Documentação do ChatGPT
Português
Contacto goolvyouyou@gmail.com

Executar o Codex Security no GitHub Actions

Analise pull requests e repositórios com a Codex Security Action, guarde relatórios, carregue SARIF e configure a aplicação de políticas.

Execute o Codex Security no GitHub Actions para rever alterações de pull requests ou analisar o seu repositório de forma agendada. A Action instala a CLI, guarda relatórios estruturados e adiciona um resumo da tarefa e anotações no código-fonte. Comece com deteções de caráter informativo e configure depois a aplicação de políticas após rever a cobertura e a qualidade das análises.

Preparar o fluxo de trabalho

A execução de análises requer acesso ao Codex Security. Para adicionar a sua API key da OpenAI:

  1. No seu repositório do GitHub, abra Definições → Segredos e variáveis → Actions.
  2. Selecione Novo segredo do repositório.
  3. Introduza CODEX_SECURITY_API_KEY como nome e cole a sua API key da OpenAI como valor. Guarde o segredo.

Os exemplos de fluxo de trabalho abaixo passam este segredo à Codex Security Action automaticamente. Não precisa de colocar a sua API key no ficheiro do fluxo de trabalho.

Execute o fluxo de trabalho apenas em repositórios e pull requests em que confia. As análises utilizam as permissões locais do runner e não param para pedir aprovação. Mantenha as credenciais não relacionadas e os passos de colocação em produção em tarefas separadas.

Adicionar o fluxo de trabalho do GitHub Actions

Analisar o repositório de forma agendada

O fluxo de trabalho abaixo analisa o seu ramo predefinido todas as segundas-feiras às 07:23 UTC. Também pode executá-lo manualmente no separador Actions do GitHub. Utiliza um runner x64 Ubuntu 24.04 alojado pelo GitHub e configura automaticamente o sandbox necessário.

  1. No seu repositório, selecione Adicionar ficheiro → Criar novo ficheiro.
  2. Dê ao ficheiro o nome .github/workflows/codex-security-repository.yml.
  3. Cole o fluxo de trabalho abaixo e faça commit no seu ramo predefinido.
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 Action precisa de Node.js 24 e Python 3.11 ou posterior, que este runner disponibiliza. A configuração do sandbox instala o pacote bubblewrap e carrega o perfil AppArmor fornecido antes da análise. Instalar apenas o pacote não é suficiente neste runner.

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

As deteções são apenas informativas porque fail-on-severity está definido como none. Os erros do analisador e da geração obrigatória de relatórios continuam a fazer a tarefa falhar.

Para analisar pastas selecionadas, adicione caminhos literais separados por quebras de linha ao bloco with do passo de análise:

paths: |
  src/api
  src/auth

Os caminhos requerem scope: repository e não expandem padrões glob. Para análises de diferenças, omita paths. Mantenha persist-credentials: false e execute a análise imediatamente após o checkout.

Analisar alterações de pull requests

Utilizando o mesmo segredo, crie .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 um ramo do mesmo repositório. A Action utiliza o histórico completo para encontrar a base de integração exata e analisa as alterações até à revisão de topo do PR obtida no checkout. Veja a verificação Codex Security em Verificações no PR. Comece com deteções de caráter informativo e depois escolha uma política de gravidade quando estiver pronto para condicionar as alterações.

Este exemplo ignora PRs de forks e PRs abertos por dependabot[bot]. Uma tarefa ignorada não constitui prova de uma revisão de segurança. Para incluir estes PRs de bots, remova a exclusão do autor e também configure CODEX_SECURITY_API_KEY como um segredo para dependabot[bot]. A Action não suporta pull_request_target nem workflow_run.

O analisador lê as orientações SECURITY.md aplicáveis a partir do checkout, incluindo alterações de políticas no PR. Reveja essas alterações juntamente com o código.

Configurar o acesso opcional ao Daybreak

O Daybreak é opcional. Ambos os exemplos de fluxo de trabalho utilizam gpt-6-sol. Se a sua organização tiver sido aprovada para o Trusted Access for Cyber, remova o # antes de cyber-access-program no bloco with do passo de análise:

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

Utilize uma API key de um projeto com o Daybreak Blue ativado e acesso a gpt-6-sol.

O parâmetro de entrada do programa também aceita standard. Sem acesso ao Daybreak, utilize um modelo a que a sua API key tenha acesso com as salvaguardas padrão e omita cyber-access-program ou defina-o como standard. Selecionar um modelo ou programa não concede acesso. Consulte as orientações de acesso ao Daybreak da Action.

Uma recusa ou um bloqueio de segurança que interrompa a análise faz a Action falhar, incluindo quando fail-on-severity está definido como none. Esse parâmetro de entrada controla a política relativa às deteções, não os erros do analisador.

Definir um orçamento opcional para a análise

Ambos os exemplos de fluxo de trabalho omitem max-cost, pelo que não têm um limiar de paragem baseado no custo estimado. Para definir um, adicione um montante positivo em USD através do parâmetro de entrada max-cost. Para análises diretas pela CLI, utilize --max-cost.

O limite de custo requer suporte de preços na CLI para o modelo selecionado. O limiar estimado não é um limite rígido de despesa: o custo dos pedidos já em curso pode ultrapassá-lo. Reveja as deteções e coverage.json se uma análise parar ao atingir o limiar. Consulte opções de saída e de políticas para conhecer o comportamento do limite de custo.

Guardar relatórios e carregar SARIF

Os exemplos definem upload-artifacts: "true" para guardar relatórios disponíveis para transferência com um período de retenção de sete dias. Os relatórios podem conter excertos de código-fonte, provas de vulnerabilidades e detalhes de correção. Escolha um período de retenção e um nível de acesso ao repositório adequados ao seu código. A Action carrega apenas relatórios validados presentes na sua lista de permissões; não carregue recursivamente a respetiva saída results-directory.

O carregamento de SARIF é opcional. Para repositórios privados ou internos, ative o GitHub Code Security antes de carregar. Substitua o bloco permissions do fluxo de trabalho por:

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

Em seguida, adicione este passo 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

Para o fluxo de trabalho de PRs, utilize category: codex-security-pr para que cada âmbito tenha uma categoria distinta. Mantenha id: security no passo de análise. Os relatórios completos e validados continuam disponíveis para carregamento quando as deteções fazem falhar a política de gravidade. O SARIF não é carregado para análises falhadas ou interrompidas, diferenças vazias ou execuções de simulação.

Consulte a referência de parâmetros de entrada e de saída da Action para conhecer todas as definições, os campos de estado e os caminhos dos relatórios.

Escolher uma política de gravidade

Os fluxos de trabalho do GitHub começam com fail-on-severity: none. Para falhar perante deteções de gravidade alta ou crítica de uma análise concluída, altere o parâmetro de entrada do passo de análise:

fail-on-severity: high

Defina Codex Security como uma verificação de estado obrigatória nas regras do seu repositório para bloquear integrações quando a tarefa do PR falhar. O GitHub considera uma tarefa ignorada condicionalmente como bem-sucedida, mesmo para verificações obrigatórias. Os PRs de forks e os PRs de dependabot[bot] passam esta verificação sem uma análise. Para bloquear esses casos, exija uma análise concluída com êxito.

A Action segue 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; o passo falha perante deteções com gravidade igual ou superior à configurada.
  • O código de saída 2 ou um processo interrompido define scan-status: failed e policy-status: not-evaluated; o passo falha.
  • Relatórios obrigatórios inválidos ou em falta, um checkout alterado, falhas no carregamento dos artefactos solicitados e falhas de limpeza do ambiente de execução também fazem o passo falhar.

Uma análise concluída significa que a análise configurada produziu um resultado válido. As exclusões de âmbito, as investigações adiadas e outras notas em coverage.json não criam um resultado de análise separado nem contornam a política de gravidade. A conclusão não certifica que todas as vulnerabilidades foram encontradas. Reveja coverage.json ao avaliar o resultado.

Exigir uma análise concluída com êxito

Para uma política mais rigorosa, adicione uma verificação de bloqueio separada que seja executada mesmo que a tarefa de análise falhe ou o GitHub a ignore. Um passo dentro da tarefa de análise não pode verificar uma tarefa ignorada porque nenhum dos seus passos é executado.

No fluxo de trabalho de PRs, adicione este mapeamento outputs à tarefa security existente, com a mesma indentação de runs-on e steps:

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

Em seguida, adicione esta tarefa em jobs, ao lado da tarefa 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 estado obrigatória para esta política. Esta exige uma tarefa de análise bem-sucedida e scan-status: completed. Verificar ambas as condições preserva as falhas da política de gravidade, da geração de relatórios e da limpeza, mesmo quando a análise em si foi concluída.

Com as exclusões do exemplo, esta verificação bloqueia PRs de forks e PRs de dependabot[bot]. Também bloqueia diferenças vazias e execuções de simulação, que a Action marca como skipped. A verificação não analisa os PRs excluídos. Escolha esta política apenas se estes casos deverem impedir a integração.

Resolver problemas de uma análise

  • Referência Git desconhecida ou diferenças inesperadas: Faça checkout da revisão de topo do PR com fetch-depth: 0.
  • Erro de arranque do sandbox: No Ubuntu 24.04, instale o pacote bubblewrap e carregue o perfil AppArmor antes da Action. Instalar apenas o pacote não carrega o perfil necessário.
  • Credenciais em falta: Confirme que CODEX_SECURITY_API_KEY está disponível para o fluxo de trabalho de confiança e associado à variável de ambiente OPENAI_API_KEY do passo de análise.
  • Erro de configuração do Python: A Action requer Python 3.11 ou posterior.
  • Notas de cobertura: Reveja as exclusões de âmbito e as investigações adiadas em coverage.json. Estas notas não causam falhas de execução nem contornam a política de gravidade.
  • SARIF em falta: Inspecione scan-status, report-status e sarif-upload-ready. Se o SARIF opcional estiver em falta, a Action emite um aviso sem alterar o resultado da análise; as falhas no carregamento dos artefactos solicitados continuam a fazer falhar a tarefa.
  • Erro de carregamento de SARIF: Confirme que a sua organização ativou o GitHub Code Security para o repositório e que o fluxo de trabalho concede actions: read, contents: read e security-events: write.

Para conhecer todos os comandos, opções, artefactos e campos de saída, consulte a referência da CLI. Para outros fornecedores, consulte a visão geral de CI/CD.