Hardening do GitHub Actions

Um revisor de segurança focado para fluxos de trabalho do GitHub Actions. Ele raciocina sobre o modelo de ameaças específico do Actions — onde os limites de confiança residem nos tipos de gatilho, escopos de token e interpolação de strings — em vez das vulnerabilidades de código de aplicação que um scanner de segurança geral procura. A maioria dos riscos de fluxo de trabalho são invisíveis para os linters de linguagem porque o código perigoso é o próprio YAML e a maneira como o GitHub expande expressões ${{ }} em um shell antes que seu script seja executado.

Quando Usar Esta Habilidade

Use esta habilidade quando a solicitação envolver:

• Revisar, auditar ou proteger qualquer arquivo sob .github/workflows/
• Criar um novo fluxo de trabalho e querer que ele seja seguro por padrão
• Um fluxo de trabalho que usa gatilhos pull_request_target, workflow_run ou issue_comment
• Perguntas sobre permissões GITHUB_TOKEN ou a chave permissions:
• Fixar ações em SHAs de commit vs tags vs branches
• Lidar com entrada não confiável (títulos de issues, corpos de PRs, nomes de branches, mensagens de commit) em etapas run:
• Autenticação OIDC / cloud do Actions, ou manuseio de segredos em CI
• Runners auto-hospedados em repositórios públicos
• Qualquer solicitação como "este fluxo de trabalho é seguro?", "proteja meu CI" ou "revise este GitHub Action"

A Ideia Central

Em um fluxo de trabalho, ${{ <expr> }} é expandido pelo runner para o script antes que o shell o execute. Portanto, uma etapa como:

- run: echo "Title: ${{ github.event.issue.title }}"

não está passando uma variável — está colando texto controlado pelo atacante diretamente no seu comando shell. Um título de issue "; <attacker-command> # é concatenado no script e executado. Este único mecanismo é a vulnerabilidade mais comum do Actions no mundo real, e os modelos rotineiramente a geram. Trate cada ${{ }} que contém dados que um colaborador externo pode influenciar como um sink de injeção de código.

Fluxo de Execução

Siga estas etapas em ordem para cada fluxo de trabalho revisado.

Etapa 1 — Mapear os Gatilhos e o Nível de Confiança

Leia cada gatilho on: e classifique o privilégio do fluxo de trabalho:

• push, pull_request (do mesmo repositório) → executa com a confiança do próprio colaborador
• pull_request de um fork → executa com um token somente leitura, sem segredos (seguro por design)
• pull_request_target, workflow_run, issue_comment, issues → executam no contexto do repositório base com um token de leitura/escrita e acesso total a segredos, mas podem ser acionados por colaboradores externos. Estes são os gatilhos perigosos.

Leia references/triggers-and-privilege.md para a matriz de confiança completa.

Etapa 2 — Caçar Injeção de Script

Para cada bloco run:, cada script: em actions/github-script e cada entrada para uma ação personalizada, liste as expressões ${{ }} e verifique se alguma delas se resolve para dados controláveis pelo atacante. Contextos de alto risco incluem:

• github.event.issue.title, github.event.issue.body
• github.event.pull_request.title, github.event.pull_request.body, .head.ref, .head.label
• github.event.comment.body, github.event.review.body
• github.event.pages.*.page_name, github.event.commits.*.message, github.event.head_commit.*
• github.head_ref e qualquer campo github.event.* que um autor de fork possa definir

Leia references/injection.md para a lista completa de sinks e as correções de padrão seguro.

Etapa 3 — Verificar se Gatilhos Privilegiados Não Executam Código Não Confiável

Se um fluxo de trabalho pull_request_target ou workflow_run fizer checkout do código do PR/fork (ref: ${{ github.event.pull_request.head.sha }}) e depois executá-lo (scripts de build, teste, instalação, npm install com scripts de ciclo de vida, etc.), isso é execução remota de código contra um token privilegiado. Sinalize como CRÍTICO. O padrão seguro é dividir em dois fluxos de trabalho: um fluxo de trabalho pull_request não privilegiado que executa o código não confiável, e um fluxo de trabalho workflow_run privilegiado que apenas consome seus resultados.

Etapa 4 — Auditar permissions:

• Se não houver bloco permissions:, o fluxo de trabalho herda o padrão do repositório, que pode ser leitura/escrita em tudo. Sinalize.
• Recomende um permissions: {} (negar tudo) ou contents: read de nível superior, e então conceda o mínimo por job (por exemplo, pull-requests: write apenas no job que comenta).
• Sinalize quaisquer escopos permissions: write-all ou write amplos que as etapas realmente não precisam.

Leia references/permissions-and-tokens.md para orientação por escopo e configuração de OIDC.

Etapa 5 — Auditar Referências de Ação (Cadeia de Suprimentos)

Para cada uses::

…