GitHub Actions: como usar vulnerability-alerts para ler o Dependabot com menor privilégio

O GitHub Actions ganhou em 3 de setembro de 2026 uma permissão específica para um caso que antes costumava empurrar workflows para credenciais mais amplas: vulnerability-alerts. Com vulnerability-alerts: read, o GITHUB_TOKEN pode listar e consultar alertas do Dependabot do próprio repositório sem receber permissões de escrita e sem depender de um token pessoal apenas para essa leitura. A mudança foi anunciada no changelog oficial do GitHub.

O ponto mais importante é que a nova permissão é deliberadamente estreita: ela aceita apenas read ou none. Isso a torna adequada para jobs de inventário, triagem, geração de relatórios e gates que só precisam observar alertas. Ela não transforma o GITHUB_TOKEN em uma credencial capaz de dispensar, reabrir ou alterar alertas.

O que mudou com vulnerability-alerts

A referência de sintaxe do GitHub Actions passou a listar vulnerability-alerts entre as permissões configuráveis do GITHUB_TOKEN. Segundo a documentação de workflow syntax, vulnerability-alerts: read permite que uma ação liste alertas do Dependabot do repositório; write não é um valor válido. A mesma documentação informa que read-all e write-all incluem essa permissão como leitura, mas isso é mais amplo do que o necessário para um job cuja única função é consultar alertas.

Há outra regra que ajuda a aplicar menor privilégio: quando você declara acesso para qualquer permissão dentro de permissions, as permissões não declaradas passam a none. Portanto, um job com apenas vulnerability-alerts: read não recebe automaticamente contents: read, issues: write ou outros acessos. Se o mesmo job também fizer checkout do repositório, adicione apenas o acesso que essa etapa realmente precisa.

Configuração mínima para apenas ler alertas

Se o job não precisa baixar o código, a configuração pode ser mínima. O exemplo abaixo usa a GitHub CLI para chamar o endpoint de alertas do repositório atual e expõe o token somente ao comando que faz a consulta.

Nesse caso, não há motivo para conceder contents: read: o job não faz checkout nem lê arquivos do repositório pela API. Se você precisa combinar os alertas com dados do código, acrescente somente o escopo necessário:

Para documentar explicitamente que outro job não deve acessar alertas, vulnerability-alerts: none também é válido. Na prática, ele é mais útil quando você quer tornar a fronteira de segurança evidente no YAML; se outras permissões já foram declaradas e vulnerability-alerts foi omitido, ele já ficará em none.

Quais chamadas a nova permissão cobre

A API REST de alertas do Dependabot oferece operações de leitura e atualização. Para automações com o novo GITHUB_TOKEN, a divisão prática é esta:

O endpoint de atualização exige permissão de escrita para “Dependabot alerts” em credenciais que oferecem esse nível. Como vulnerability-alerts no GITHUB_TOKEN suporta somente read e none, um workflow configurado com essa nova permissão deve ser tratado como consumidor de dados, não como ferramenta de administração de alertas. Se o processo realmente precisa alterar alertas, use uma credencial apropriada, como um GitHub App com permissão granular de escrita, e mantenha esse fluxo separado do job de leitura.

O que você consegue extrair sem dar acesso de escrita

A resposta da API inclui dados suficientes para muitos fluxos de triagem: número e estado do alerta, pacote e ecossistema, caminho do manifesto, relação da dependência quando disponível, identificadores GHSA e CVE, severidade, versões vulneráveis, primeira versão corrigida quando conhecida, CVSS e EPSS quando fornecidos. Isso permite gerar relatórios, abrir gates internos ou alimentar observabilidade sem dar ao job autoridade para modificar o repositório ou o próprio alerta.

Um cuidado útil é não confundir “ler alerta” com “ler o código”. O acesso a alertas é uma permissão própria. Se um script precisa inspecionar package-lock.json, requirements.txt ou outro arquivo depois de consultar a API, ele precisará de contents: read ou de outra forma segura de receber esse conteúdo.

Menor privilégio por job é melhor do que por workflow inteiro

A chave permissions pode aparecer no topo do workflow ou dentro de um job. Para este caso, o nível do job costuma ser mais seguro. Assim, apenas o job de segurança recebe vulnerability-alerts: read, enquanto build, testes e publicação continuam sem acesso aos alertas.

Essa separação também reduz o impacto de uma ação de terceiros comprometida. O guia de autenticação com GITHUB_TOKEN recomenda limitar o token ao mínimo necessário porque ações podem acessar github.token mesmo quando o workflow não passa o segredo explicitamente como entrada.

Reusable workflows: o chamador define o teto

Em workflows reutilizáveis, a permissão disponível no workflow chamado não pode superar a que veio do chamador. A documentação de reusable workflows diz que as permissões do GITHUB_TOKEN só podem permanecer iguais ou ser reduzidas ao longo da cadeia de chamadas. Portanto, se um workflow reutilizável precisa consultar alertas, o job chamador precisa conceder vulnerability-alerts: read; o workflow chamado não consegue elevar sozinho um token que chegou com none.

Em cadeias A → B → C, trate a permissão como um teto descendente: se A não concede leitura, B e C não conseguem recuperá-la. Isso evita que um reusable workflow introduza silenciosamente mais acesso do que o repositório chamador autorizou.

Forks e pull requests: leitura também é privilégio

Pull requests vindos de forks recebem um GITHUB_TOKEN com restrições e, em geral, sem acesso a segredos. O GitHub também trata workflows disparados por pull requests do Dependabot como se viessem de um fork. Essas regras estão descritas em eventos que disparam workflows e na documentação de Dependabot no GitHub Actions.

O fato de vulnerability-alerts ser somente leitura não torna seguro entregar essa leitura a código não confiável. Alertas podem revelar pacotes, versões e vulnerabilidades presentes no repositório. Evite conceder essa permissão a um job que faz checkout e executa código controlado pelo autor de um pull request externo. Uma arquitetura mais segura é separar a consulta em um job ou workflow confiável, acionado por workflow_dispatch, schedule, push em branch protegida ou outro evento que não execute conteúdo não confiável.

Se houver motivo para usar pull_request_target, aplique as orientações específicas de segurança do GitHub: mantenha permissões mínimas e não faça checkout nem execute o head não confiável do pull request em um contexto privilegiado. A fronteira aqui não é apenas “escrever ou não escrever”; impedir vazamento de dados de segurança também faz parte do menor privilégio.

Erros comuns ao adotar a permissão

• Usar read-all por conveniência. Funciona para leitura, mas concede vários outros acessos de leitura. Prefira declarar somente vulnerability-alerts: read e os escopos adicionais realmente necessários.
• Adicionar contents: read sem precisar. Se o job apenas chama a API, esse acesso pode ser removido.
• Tentar vulnerability-alerts: write. O valor não é suportado.
• Esperar que o novo escopo permita dispensar alertas. Atualizações exigem permissão de escrita de Dependabot alerts e outra credencial adequada.
• Confiar no padrão do repositório. Defina permissions no YAML para tornar o contrato do job explícito e revisável.
• Esquecer que reusable workflows não elevam privilégios. O chamador deve conceder a leitura.
• Executar código de fork no mesmo job que lê alertas. Mesmo sem escrita, isso pode expor informação de segurança.

Como investigar 403, 404 ou uma lista vazia

O endpoint de listagem documenta respostas como 403 e 404, mas esses códigos podem ter mais de uma causa. Primeiro, confirme no log que o job realmente recebeu vulnerability-alerts: read e que está consultando repos/${{ github.repository }}/dependabot/alerts. Depois, verifique se Dependabot alerts está habilitado para o repositório e se o dependency graph está disponível.

Uma resposta 200 com [] não indica falha de permissão: pode simplesmente não haver alertas que correspondam aos filtros usados. Para depurar, remova temporariamente filtros como state ou severity e confira o JSON bruto. Já um 422 aponta para validação da requisição, como parâmetros incompatíveis ou inválidos.

Checklist de migração para menor privilégio

1. Localize workflows que usam PAT, GitHub App ou read-all apenas para consultar alertas do Dependabot.
2. Mova a leitura para um job dedicado, quando possível.
3. Defina vulnerability-alerts: read no nível desse job.
4. Adicione contents: read somente se houver checkout ou leitura de conteúdo.
5. Mantenha operações de atualização de alertas em um fluxo separado com credencial de escrita apropriada.
6. Revise reusable workflows para garantir que o chamador concede a permissão sem ampliar outras.
7. Não exponha a leitura de alertas a código de forks ou outros inputs não confiáveis.
8. Teste a chamada GET /repos/{owner}/{repo}/dependabot/alerts e trate 403, 404, 422 e lista vazia de forma distinta.

Para workflows que só precisam observar vulnerabilidades, a nova permissão fecha uma lacuna importante: agora é possível usar o token efêmero e limitado do próprio GitHub Actions para ler alertas do Dependabot com um contrato explícito de somente leitura. O ganho de segurança vem menos da nova palavra no YAML e mais de usá-la no menor escopo possível — no job certo, em gatilhos confiáveis e sem misturar leitura de alertas com capacidades de escrita desnecessárias.