Execute o Codex Security no GitHub Actions

Execute o Codex Security no GitHub Actions para revisar alterações em pull requests ou analisar seu repositório periodicamente. A ação instala a CLI, salva relatórios estruturados e adiciona um resumo do job e anotações no código-fonte. Comece usando os resultados apenas como orientação. Depois de avaliar a cobertura e a qualidade da análise, configure as regras de bloqueio.

Prepare o fluxo de trabalho

Para executar as análises, você precisa ter acesso ao Codex Security. Para adicionar sua chave de API da OpenAI:

1. No repositório do GitHub, abra Settings → Secrets and variables → Actions.
2. Selecione New repository secret.
3. Use CODEX_SECURITY_API_KEY como nome e cole sua chave de API da OpenAI no campo de valor. Salve o segredo.

Os exemplos de fluxo de trabalho abaixo passam esse segredo automaticamente para a ação do Codex Security. Você não precisa inserir a chave de API no arquivo do fluxo de trabalho.

Execute o fluxo de trabalho apenas em repositórios e pull requests nos quais você confia. As análises usam as permissões locais do runner e não param para pedir aprovação. Mantenha as credenciais que não são usadas na análise e as etapas de implantação em jobs separados.

Adicione o fluxo de trabalho do GitHub Actions

Agende a análise do repositório

O fluxo de trabalho abaixo analisa a branch padrão toda segunda-feira às 07h23 UTC. Você também pode executá-lo manualmente pela aba Actions do GitHub. Ele usa um runner x64 com Ubuntu 24.04 hospedado pelo GitHub e configura automaticamente o sandbox necessário.

1. No repositório, selecione Add file → Create new file.
2. Dê ao arquivo o nome .github/workflows/codex-security-repository.yml.
3. Cole o fluxo de trabalho abaixo e faça commit do arquivo na branch padrão.

name: Codex Security repository

on:
  workflow_dispatch:
  schedule:
    - cron: "23 7 * * 1" # Mondays at 07:23 UTC

permissions:
  contents: read

jobs:
  security:
    runs-on: ubuntu-24.04
    timeout-minutes: 120
    steps:
      - name: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

      - name: Check out the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Scan the repository
        id: security
        uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
        with:
          scope: repository
          model: gpt-6-sol
          # For approved Daybreak Blue access, uncomment the next input.
          # cyber-access-program: daybreak_blue
          effort: high
          fail-on-severity: none
          upload-artifacts: "true"
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

Adaptação do runner: A ação requer Node.js 24 e Python 3.11 ou posterior, ambos disponíveis nesse runner. A etapa de configuração do sandbox instala o pacote bubblewrap e carrega o perfil do AppArmor fornecido antes da análise. Nesse runner, só instalar o pacote não basta.

Para executar o fluxo de trabalho manualmente, abra Actions → Codex Security repository → Run workflow. Abra uma execução concluída para consultar o resumo, as anotações e os relatórios disponíveis para download.

Os problemas encontrados aparecem apenas nos relatórios porque fail-on-severity está definido como none. O job ainda falha se houver erros no analisador ou na geração dos relatórios obrigatórios.

Para analisar apenas algumas pastas, adicione os caminhos literais, um por linha, ao bloco with da etapa de análise:

paths: |
  src/api
  src/auth

Para usar caminhos, é necessário definir scope: repository. Padrões glob não são expandidos. Para analisar um diff, omita paths. Mantenha persist-credentials: false e execute a análise imediatamente após o checkout.

Analise as alterações de um pull request

Usando o mesmo segredo, crie o arquivo .github/workflows/codex-security-pr.yml:

name: Codex Security PR

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read

concurrency:
  group: codex-security-pr-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  security:
    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
    name: Codex Security
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    steps:
      - name: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

      - name: Check out the pull request
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Scan PR changes
        id: security
        uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
        with:
          scope: diff
          model: gpt-6-sol
          # For approved Daybreak Blue access, uncomment the next input.
          # cyber-access-program: daybreak_blue
          effort: high
          fail-on-severity: none
          upload-artifacts: "true"
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

Abra ou atualize um PR a partir de uma branch do mesmo repositório. A ação usa o histórico completo para identificar o commit exato que serve de base para o merge e analisa as alterações até o commit de ponta do PR selecionado no checkout. Consulte a verificação Codex Security na aba Checks do PR. Comece usando os resultados apenas como orientação. Quando quiser bloquear alterações com base nesses resultados, escolha uma política de severidade.

Este exemplo ignora PRs de forks e PRs abertos por dependabot[bot]. Um job ignorado não comprova que houve revisão de segurança. Para incluir os PRs desse bot, remova a condição que exclui o autor e configure também CODEX_SECURITY_API_KEY como um segredo para dependabot[bot]. A ação não oferece suporte a pull_request_target nem a workflow_run.

O analisador lê as orientações aplicáveis do arquivo SECURITY.md na cópia obtida pelo checkout, inclusive as alterações de política feitas no PR. Revise essas alterações junto com o código.

Configure o acesso opcional ao Daybreak

O Daybreak é opcional. Os dois exemplos de fluxo de trabalho usam gpt-6-sol. Se sua organização recebeu aprovação para o programa Trusted Access for Cyber, remova o # antes de cyber-access-program no bloco with da etapa de análise:

model: gpt-6-sol
cyber-access-program: daybreak_blue

Use uma chave de API de um projeto habilitado para o Daybreak Blue que tenha acesso a gpt-6-sol.

O parâmetro do programa também aceita standard. Se você não tiver acesso ao Daybreak, use um modelo que sua chave de API possa acessar com as proteções padrão e omita cyber-access-program ou defina o parâmetro como standard. Selecionar um modelo ou programa não concede acesso. Consulte as orientações da ação sobre o acesso ao Daybreak.

Se uma recusa ou um bloqueio de segurança interromper a análise, a ação falhará, mesmo que fail-on-severity esteja definido como none. Esse parâmetro determina como tratar os problemas encontrados e não se aplica a erros do analisador.

Defina um orçamento opcional para a análise

Os dois exemplos de fluxo de trabalho omitem max-cost, portanto a análise não para com base no custo estimado. Para definir um limite, informe um valor positivo em dólares americanos no parâmetro max-cost. Para análises executadas diretamente pela CLI, use --max-cost.

Para aplicar o limite de custo, a CLI precisa oferecer suporte aos preços do modelo selecionado. O limite se baseia em uma estimativa. Solicitações já em andamento podem fazer com que o gasto final ultrapasse esse valor. Se a análise parar ao atingir o limite, revise os problemas encontrados e o arquivo coverage.json. Consulte as opções de saída e de política para saber como funciona o limite de custo.

Salve relatórios e envie arquivos SARIF

Os exemplos definem upload-artifacts: "true" para salvar os relatórios e disponibilizá-los para download por sete dias. Os relatórios podem conter trechos de código-fonte, evidências de vulnerabilidades e detalhes sobre como corrigi-las. Escolha um período de retenção e permissões de acesso ao repositório adequados ao seu código. A ação envia apenas relatórios validados que constam da lista de permissões. Não envie recursivamente o conteúdo do diretório indicado na saída results-directory.

O envio de arquivos SARIF é opcional. Para repositórios privados ou internos, habilite o GitHub Code Security antes do envio. Substitua o bloco permissions do fluxo de trabalho pelo seguinte:

permissions:
  contents: read
  security-events: write
  actions: read # Required for private repositories

Em seguida, adicione esta etapa após a análise em qualquer um dos fluxos de trabalho:

- name: Upload security findings
  if: ${{ always() && steps.security.outputs.sarif-upload-ready == 'true' }}
  uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
  with:
    sarif_file: ${{ steps.security.outputs.sarif-path }}
    sha: ${{ steps.security.outputs.scanned-sha }}
    ref: ${{ steps.security.outputs.analysis-ref }}
    category: codex-security-repository

No fluxo de trabalho de PRs, use category: codex-security-pr para que cada escopo tenha uma categoria própria. Mantenha id: security na etapa de análise. Os relatórios completos e validados continuam disponíveis para envio mesmo quando os problemas encontrados violam a política de severidade. A ação não envia arquivos SARIF quando a análise falha ou é interrompida, quando o diff está vazio ou quando a execução é simulada.

Consulte a referência de entradas e saídas da ação para ver todas as configurações, os campos de status e os caminhos dos relatórios.

Escolha uma política de severidade

Os fluxos de trabalho do GitHub usam inicialmente fail-on-severity: none. Para que a etapa de análise falhe quando uma análise concluída encontrar problemas de severidade alta ou crítica, altere o parâmetro da etapa:

fail-on-severity: high

Nas regras do repositório, defina Codex Security como uma verificação de status obrigatória para bloquear o merge quando o job do PR falhar. O GitHub considera que um job ignorado devido a uma condição foi bem-sucedido, mesmo quando a verificação é obrigatória. PRs de forks e PRs de dependabot[bot] passam por essa verificação sem análise. Para bloquear o merge nesses casos, exija que a análise seja concluída com sucesso.

A ação usa o resultado da CLI:

• O código de saída 0 define scan-status: completed e policy-status: passed.
• O código de saída 1 define scan-status: completed e policy-status: failed. A etapa falha quando encontra problemas com severidade igual ou superior à configurada.
• Se o código de saída for 2 ou o processo for interrompido, a ação define scan-status: failed e policy-status: not-evaluated. A etapa falha.
• A etapa também falha se um relatório obrigatório estiver ausente ou for inválido, se a cópia obtida pelo checkout tiver sido alterada, se o envio dos artefatos solicitados falhar ou se ocorrer um erro na limpeza do ambiente de execução.

Uma análise concluída indica que a análise configurada produziu um resultado válido. Exclusões de escopo, investigações adiadas e outras observações em coverage.json não geram um status de análise diferente nem dispensam a aplicação da política de severidade. A conclusão da análise não garante que todas as vulnerabilidades tenham sido encontradas. Consulte coverage.json ao avaliar o resultado.

Exija que a análise seja concluída com sucesso

Para aplicar uma política mais rigorosa, adicione uma verificação separada que seja executada mesmo se o job de análise falhar ou se o GitHub o ignorar. Uma etapa dentro do próprio job não consegue verificar se ele foi ignorado, pois, nesse caso, nenhuma de suas etapas é executada.

No fluxo de trabalho de PRs, adicione este mapeamento de outputs ao job security existente, no mesmo nível de recuo de runs-on e steps:

outputs:
  scan-status: ${{ steps.security.outputs.scan-status }}

Em seguida, adicione o job abaixo em jobs, no mesmo nível do job security existente:

security-gate:
  name: Codex Security gate
  needs: security
  if: ${{ always() }}
  runs-on: ubuntu-24.04
  steps:
    - name: Require a successful, completed scan
      env:
        SCAN_RESULT: ${{ needs.security.result }}
        SCAN_STATUS: ${{ needs.security.outputs.scan-status }}
      run: test "$SCAN_RESULT" = success && test "$SCAN_STATUS" = completed

Defina Codex Security gate como a verificação de status obrigatória para essa política. Ela exige que o job de análise seja bem-sucedido e que a ação indique scan-status: completed. Verificar as duas condições garante que falhas na política de severidade, nos relatórios ou na limpeza continuem bloqueando o merge mesmo quando a análise em si tiver sido concluída.

Com as exclusões do exemplo, essa verificação bloqueia PRs de forks e PRs de dependabot[bot]. Ela também bloqueia diffs vazios e execuções simuladas, que a ação marca como skipped. A verificação não analisa os PRs excluídos. Escolha essa política apenas se esses casos precisarem impedir o merge.

Solucione problemas na análise

• Referência Git desconhecida ou diff inesperado: Faça checkout do commit de ponta do PR com fetch-depth: 0.
• Erro ao iniciar o sandbox: No Ubuntu 24.04, instale o pacote bubblewrap e carregue o perfil do AppArmor antes de executar a ação. A instalação do pacote, por si só, não carrega o perfil necessário.
• Credenciais ausentes: Confirme que CODEX_SECURITY_API_KEY está disponível para o fluxo de trabalho confiável e que seu valor foi atribuído à variável de ambiente OPENAI_API_KEY da etapa de análise.
• Erro na configuração do Python: A ação requer Python 3.11 ou posterior.
• Observações sobre a cobertura: Revise as exclusões de escopo e as investigações adiadas em coverage.json. Essas observações não causam falhas de execução nem dispensam a aplicação da política de severidade.
• Arquivo SARIF ausente: Verifique scan-status, report-status e sarif-upload-ready. Se o arquivo SARIF opcional estiver ausente, a ação emitirá um aviso sem alterar o resultado da análise. O job ainda falhará se houver erro no envio de um artefato solicitado.
• Erro no envio do arquivo SARIF: Confirme que sua organização habilitou o GitHub Code Security para o repositório e que o fluxo de trabalho concede as permissões actions: read, contents: read e security-events: write.

Consulte a referência da CLI para ver todos os comandos, opções, artefatos e campos de saída. Para outros provedores, consulte a visão geral de CI/CD.