Uso seguro de pull_request_target

Este guia ajuda você a avaliar se o fluxo de trabalho deve usar o pull_request_target evento e entender os riscos de segurança envolvidos. Ele também explica que a proteção GitHub se aplica à actions/checkout v7 e posterior para reduzir esses riscos por padrão e quando recusar essa proteção, se necessário.

Leia pull_request_target antes de extrair o código da pull request de um destes fluxos de trabalho ou antes de definir a entrada allow-unsafe-pr-checkout em actions/checkout.

Os riscos do evento pull_request_target

Fluxos de trabalho disparados por pull_request_target são executados com privilégios elevados: o trabalho recebe o GITHUB_TOKEN do repositório base, acesso aos segredos do repositório e da organização e acesso de gravação ao cache do branch padrão. Essa é a mesma confiança dada a eventos como push, que apenas colaboradores podem disparar, e é isso que torna pull_request_target útil para automações que respondem a pull requests de forks, como rotulagem, triagem ou a publicação de verificações de status autenticadas.

Para entender por que isso é seguro por padrão e como essa segurança geralmente é comprometida, analise pull_request_target em relação a pull_request.

O evento pull_request (assim como pull_request_review e pull_request_review_comment) é incomum: ele executa o arquivo do fluxo de trabalho a partir do commit de mesclagem do pull request. Para um pull request aberto a partir de um fork, esse commit é controlado por alguém sem acesso de gravação ao repositório base. Para executar com segurança código de fluxo de trabalho não confiável, GitHub restringe esses eventos a um GITHUB_TOKENsomente leitura, bloqueia o acesso a outros segredos e aplica políticas de aprovação para forks para evitar abuso de recursos computacionais. Para obter mais informações, consulte Eventos que disparam fluxos de trabalho. Por padrão, actions/checkout em um pull_request fluxo de trabalho também verifica a confirmação de mesclagem da solicitação de pull, de modo que o código verificado e o fluxo de trabalho executado são consistentes.

pull_request_target faz uma mudança crítica e sutil: o fluxo de trabalho e qualquer chamada subsequente actions/checkout que não especifique um ref são obtidos do branch padrão do repositório base, e não do pull request. Como apenas o código confiável do branch padrão é executado, é seguro conceder segredos e um token de leitura/gravação. Nenhum código da bifurcação é executado por padrão.

Você gera um risco quando o autor do fluxo de trabalho substitui essa configuração padrão para executar o código do fork. Os desenvolvedores geralmente escolhem pull_request_target porque desejam executar a solicitação de pull de uma bifurcação por meio da CI e têm acesso a segredos, por exemplo, para executar testes que precisam de um registro privado. Para fazer isso, eles apontam actions/checkout para o cabeçalho da solicitação de pull em vez do branch padrão, que é inseguro:

# INSECURE. Provided as an example only.
on:
  pull_request_target:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - name: Test
        run: make test

A etapa de check-out por si só não executa código não confiável. O arquivo de fluxo de trabalho em si ainda vem da ramificação padrão. A vulnerabilidade é concluída pela próxima etapa que executa o check-out de código no diretório de trabalho atual. Aqui, make test executa uma Makefile obtida do head do pull request. Um invasor só precisa abrir um pull request a partir de um fork em que Makefile (ou script de build, comando de teste, dependência ou arquivo de configuração) contenha comandos maliciosos. Esses comandos são executados com os segredos e o token do repositório base.

Esse padrão é conhecido como "pwn request" e tem sido a causa raiz de vários comprometimentos na cadeia de suprimentos. Para obter mais informações, consulte Como evitar solicitações pwn no GitHub Security Lab. Formas vulneráveis comuns incluem:

• Verificando a cabeça de uma solicitação de pull ou a confirmação de mesclagem em (actions/checkout, ref: ${{ github.event.pull_request.head.sha }}) e, em ref: refs/pull/${{ github.event.pull_request.number }}/merge seguida, compilando, testando ou executando o resultado.
• Definindo repository: para o fork (repository: ${{ github.event.pull_request.head.repo.full_name }}) para fazer pull da branch do fork diretamente.
• Buscando o código do pull request fora de actions/checkout (por exemplo, com git fetch, gh pr checkout ou baixando um artefato de uma execução de pull_request de um fork) e executando-o em seguida.

As solicitações pwn também não são exclusivas para pull_request_target. Qualquer evento que seja executado com segredos pode introduzir um pwn request se fizer checkout ou baixar e executar código não confiável. Por exemplo, um fluxo de trabalho issue_comment ou workflow_run que busca e executa o código de uma pull request de um fork é vulnerável da mesma forma. Um workflow_run fluxo de trabalho deve tratar artefatos carregados por outros fluxos de trabalho como dados não confiáveis, pois seu conteúdo pode vir de uma bifurcação.

Decidir se deve usar pull_request_target

Alguns fluxos de trabalho precisam obter o código de pull request de um fork com um nível elevado de confiança, e foi por isso que pull_request_target foi criado desde o início. Por exemplo, gerar relatórios de cobertura que exigem um registro privado de artefatos ou gerar e executar verificações autenticadas nas alterações introduzidas pelo pull request. Considere as perguntas abaixo antes de usar pull_request_target ou ativar a flag allow-unsafe-pr-checkout em actions/checkout.

• Você pode usar pull_request em vez disso? pull_request é acionado pelos mesmos eventos que pull_request_target e executa o código do fluxo de trabalho do branch de mesclagem pull_request. Ele faz isso com segurança em pull requests de forks com as proteções detalhadas acima. Se o acesso ao segredo adicional não for necessário, use pull_request. Fluxos de trabalho mais complexos podem ser reestruturados para separar o tratamento potencialmente perigoso do código de solicitação de pull do acesso a segredos. Para obter mais informações, consulte Como evitar solicitações pwn no GitHub Security Lab.

• O código de check-out já foi executado? Essa é a falha que apresenta vulnerabilidades de solicitação pwn. Isso é mais comumente introduzido com actions/checkout ao fazer checkout da referência head de uma pull request no diretório de trabalho e, em seguida, executá-la. A menos que a path entrada seja definida, actions/checkout grava o código no $GITHUB_WORKSPACE diretório, que normalmente é o diretório de trabalho em que os comandos subsequentes são executados. A execução não está limitada às suas próprias etapas: comandos de compilação e teste, como npm install e npm run build, além de arquivos de configuração e dependências que o código traz com ele, podem executar código controlado pelo invasor. A execução não requer uma etapa de build óbvia. Você deve garantir que o código extraído seja inspecionado apenas como dados e nunca executado antes de usar um evento pull_request_target.

Reforço da segurança de um fluxo de trabalho pull_request_target

Se você tiver confirmado que precisa pull_request_target, aplique esses controles para limitar o impacto desse evento de alto risco. Elas se aplicam se o fluxo de trabalho verifica ou não o código da solicitação de pull.

• Restringir segredos. Confirme se as permissões definidas em GITHUB_TOKEN têm os privilégios mínimos e se somente os segredos necessários do repositório e da organização são usados para o fluxo de trabalho. Para obter mais informações, consulte Usar GITHUB_TOKEN para autenticação em fluxos de trabalho.

• Entenda o impacto no cache. Além de GITHUB_TOKEN e dos segredos configurados, os fluxos de trabalho executados em pull_request_target também têm acesso de gravação ao cache compartilhado com outros fluxos de trabalho na branch padrão. Alterações mal-intencionadas nesse cache de pull_request_target eventos podem afetar a execução de outros fluxos de trabalho não relacionados.

• Verifique se a computação subjacente é isolada e efêmera. Se os executores auto-hospedados forem usados, você deverá confirmar se o ambiente do executor está devidamente restrito dos recursos internos e não é reutilizado entre GitHub Actions execuções. Para obter mais informações, consulte Referência de uso seguro.

• O Portão é executado atrás da aprovação. pull_request_target os fluxos de trabalho podem ser condicionados a um label obrigatório que apenas usuários com acesso de escrita podem adicionar. Isso é detalhado nas GitHub Security Lab evitar solicitações pwn.

• Impor práticas recomendadas de GitHub Actions segurança. Além dos riscos específicos de solicitações pwn, outras vulnerabilidades comuns, como injeção de comando, podem existir e afetar o código executado neste evento privilegiado. Para obter mais informações, consulte Como manter seus GitHub Actions e fluxos de trabalho seguros: entrada não confiável no GitHub Security Lab. Para identificar e proteger proativamente contra vulnerabilidades comuns GitHub Actions , habilite CodeQL para GitHub Actions. Para obter mais informações, consulte Como definir a configuração padrão da verificação de código.

Recusar proteções internas

Se você analisou as perguntas acima e confirmou que seu fluxo de trabalho requer pull_request_target e o usa com segurança, pode desativar a proteção actions/checkout. Definir allow-unsafe-pr-checkout: true como um parâmetro de entrada actions/checkout permite fazer checkout de refs de head de pull requests de forks. Faça isso somente após confirmar que o código extraído nunca é executado. A entrada é nomeada intencionalmente para ser fácil de detectar na revisão de código e na análise estática.

Essa proteção abrange somente refs de pull requests de forks. Verificar outro código não confiável, como um repositório de terceiros não relacionado, buscar código com git fetch ou gh pr checkoutexecutar um artefato baixado, não é coberto pelas actions/checkout verificações.

Restringindo o uso de pull_request_target

Os administradores do repositório, da organização e da empresa podem usar proteções de execução de fluxo de trabalho para controlar quais eventos e atores podem disparar fluxos de trabalho. Se um repositório não tiver nenhum uso legítimo para pull_request_target, restringi-lo remove o risco, independentemente de como os fluxos de trabalho individuais são definidos.