For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal

Revisar alterações no código quanto à segurança

Revise pull requests e alterações locais manualmente ou no CI/CD para detectar regressões de segurança.

Execute uma revisão de segurança das alterações para encontrar regressões em um único conjunto de alterações versionado pelo Git. O Codex revisa cada arquivo alterado com características de código-fonte e o código que lhe dá suporte direto. A revisão não se estende a uma auditoria completa do repositório.

Para verificar um repositório inteiro em vez de uma alteração específica, consulte Executar uma verificação de segurança.

Executar uma revisão manual

No aplicativo para desktop, abra Segurança, selecione Verificações e, depois, + Verificação. Escolha o repositório e selecione Alterações. Revise alterações sem commit, um único commit ou revisões base e head. Verificação aprofundada não está disponível para uma verificação de alterações.

Você também pode pedir ao Codex que revise alterações sem commit em uma conversa:

Use $codex-security:security-diff-scan to review my current uncommitted changes for security regressions.

Para um intervalo de commits ou de branches, especifique as duas revisões quando necessário:

Use $codex-security:security-diff-scan to review the changes from origin/main to HEAD for security regressions. Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.

Você também pode indicar um pull request quando as revisões base e head estiverem disponíveis no checkout local.

Confirmar a alteração na configuração

  1. Selecione Alterações.
  2. Confirme o repositório em checkout, a branch atual e o commit mais recente.
  3. Em Alterações para revisão, escolha:
    • Uncommitted changes para a árvore de trabalho atual.
    • O commit mais recente para uma revisão de um único commit.
    • As revisões base e head para um intervalo de branch ou pull request.
  4. Confirme se o resumo descreve a alteração que você pretendia revisar.
  5. Selecione Iniciar verificação.

O Codex não faz checkout de outra branch nem muda a árvore de trabalho selecionada. Se uma revisão solicitada não estiver disponível localmente, faça o fetch antes da revisão ou forneça revisões base e head disponíveis localmente.

Tratar as descobertas

Depois de revisar os resultados, corrija e verifique uma descoberta aceita ou exporte e acompanhe as descobertas.

Automatizar revisões no CI/CD

Se você tiver acesso à CLI independente em versão beta, consulte Executar o Codex Security no CI para obter JSON estruturado, uma política de gravidade e o upload de SARIF. Continue nesta seção para invocar a habilidade do plug-in instalado por meio de codex exec.

Execute $codex-security:security-diff-scan no CI quando o runner puder invocar a Codex CLI sem interação. Primeiro, instale a CLI sem expor a credencial da verificação:

npm install --global @openai/codex

Instale o Plugin Codex Security na CLI:

codex plugin add codex-security@openai-curated

O comando de instalação usa o Marketplace público de plug-ins da Codex CLI. Consulte o registro de alterações do plug-in antes de depender de uma versão ou funcionalidade específica do plug-in no CI.

Em seguida, forneça uma chave de API da OpenAI armazenada no cofre de segredos do CI como CODEX_SECURITY_API_KEY. Exponha a credencial somente para a verificação:

CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
  --sandbox workspace-write \
  "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

O Sandbox gravável permite que a verificação crie artefatos temporários. O prompt ainda exige que o Codex mantenha inalterado o checkout do código-fonte.

A verificação grava a saída em $TMPDIR/codex-security-scans/<repository>/<scan-id>/:

ArquivoConteúdo
report.mdPrincipal ponto de entrada legível para todo o diretório da verificação.
findings/<slug>/Relatórios detalhados de vulnerabilidades e arquivos complementares de prova de conceito, quando solicitados.
hardening/Orientações para reforço estrutural e propostas complementares, quando solicitadas.
findings.jsonDescobertas com identificadores estáveis, gravidade, confiança, locais no código-fonte e remediação. Use-as para alimentar fluxos de trabalho internos de segurança aprovados ou ferramentas subsequentes.
scan-manifest.jsonRecibo selado da verificação com o alvo revisado, as revisões e os hashes dos artefatos.
coverage.jsonSuperfícies revisadas, superfícies com revisão adiada, exclusões e completude da cobertura.

O esquema findings.json define a estrutura completa. O esquema inclui estes campos:

CampoTipoDescrição
documentTypeStringIdentifica o documento como codex-security.findings.
schemaVersionStringIdentifica a versão do esquema de descobertas.
scanIdStringIdentifica a verificação que gerou as descobertas.
findingsArrayContém zero ou mais objetos de descoberta.
findings[].findingIdStringIdentificador estável da descoberta, derivado de sua impressão digital.
findings[].occurrenceIdStringIdentifica esta ocorrência da descoberta em uma verificação específica.
findings[].ruleIdStringIdentifica a família da vulnerabilidade.
findings[].identityObjetoContém a âncora semântica e o identificador opcional da instância irmã.
findings[].fingerprintsObjetoContém o algoritmo de impressão digital e a impressão digital principal.
findings[].titleStringFornece o título curto da descoberta.
findings[].summaryStringResume a vulnerabilidade e seu impacto.
findings[].severityObjetoContém o nível de severidade e detalhes opcionais de pontuação.
findings[].confidenceObjetoContém o nível de confiança e a justificativa.
findings[].taxonomyObjetoContém a categoria da vulnerabilidade e os identificadores CWE.
findings[].locationsArrayLista os arquivos afetados, os números de linha e as funções de cada localização.
findings[].remediationStringDescreve a correção recomendada.
findings[].provenanceObjetoIdentifica a origem da descoberta.

Por exemplo, este comando imprime uma linha separada por tabulações para cada descoberta:

jq -r '
  .findings[] |
  [.findingId, .severity.level, .confidence.level, .locations[0].path, .locations[0].startLine, .title] |
  @tsv
' findings.json

Estes exemplos pressupõem um runner Linux confiável com Node.js e npm, Git, Python 3, jq e as ferramentas de linha de comando do provedor. O prefixo global de pacotes do npm precisa ter permissão de gravação.

Escolha o exemplo correspondente ao seu provedor de CI:

Os resultados da verificação podem incluir detalhes confidenciais sobre vulnerabilidades. Mantenha os artefatos em sigilo e só publique as descobertas depois de avaliar o público-alvo, o conteúdo e as aprovações necessárias.

Escolha uma opção
name: Codex Security review

on:
  pull_request:

jobs:
  security-review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Install Codex Security
        env:
          CODEX_HOME: ${{ runner.temp }}/codex-home
        run: |
          npm install --global @openai/codex
          codex plugin add codex-security@openai-curated

      - name: Review code changes
        env:
          CODEX_SECURITY_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
          CODEX_HOME: ${{ runner.temp }}/codex-home
          TMPDIR: ${{ runner.temp }}/codex-security
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_REVISION: ${{ github.event.pull_request.head.sha }}
        run: |
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_REVISION")"
          CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
            --sandbox workspace-write \
            "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: codex-security-review
          path: ${{ runner.temp }}/codex-security/codex-security-scans

Os exemplos ignoram pull requests originados de forks. Execute jobs com credenciais somente a partir de uma definição de pipeline protegida e apenas para colaboradores confiáveis que tenham acesso à credencial da verificação. Arquive codex-security-scans para manter em um só lugar as descobertas estruturadas, o manifesto, a cobertura e report.md, junto com quaisquer saídas solicitadas de findings/ ou hardening/. Comece com resultados informativos e analise a cobertura e o tempo de execução antes de tornar o job uma verificação obrigatória.

Para saber mais sobre o gerenciamento de chaves de API e os controles do Sandbox, consulte Modo não interativo. Se sua organização permitir o uso da Codex GitHub Action, ela poderá instalar a CLI em tempo de execução, mas você ainda precisará instalar primeiro o plug-in e fazer a entrada codex-home da ação apontar para o mesmo CODEX_HOME.