Português

Rever alterações de código quanto à segurança

Reveja pull requests e alterações locais quanto a regressões de segurança, manualmente ou em CI/CD.

Execute uma revisão de segurança de alterações para encontrar regressões num conjunto de alterações gerido por Git. O Codex revê cada ficheiro alterado semelhante a código-fonte e o respetivo código de suporte direto. Não expande a revisão para uma auditoria completa do repositório.

Se pretender analisar um repositório completo em vez de uma alteração específica, consulte Executar uma análise de segurança.

Executar uma revisão manual

Na aplicação para computador, abra Security, selecione Scans e selecione + Scan. Escolha o repositório e, em seguida, selecione Changes. Reveja alterações por confirmar, um único commit ou uma revisão de base e de destino. Deep scan não está disponível para uma análise de alterações.

Também pode pedir ao Codex para rever alterações por confirmar numa conversa:

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

Para um intervalo de commits ou branches, identifique ambas as extremidades 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.

Também pode indicar um pull request quando as respetivas revisões de base e de destino estiverem disponíveis no checkout local.

Confirmar a alteração na configuração

  1. Selecione Changes.
  2. Confirme o repositório com checkout efetuado, a branch atual e o commit mais recente.
  3. Em Changes to review, escolha:
    • Uncommitted changes para a árvore de trabalho atual.
    • O commit mais recente para uma revisão de um único commit.
    • Uma revisão de base e de destino para um intervalo de branch ou pull request.
  4. Confirme que o resumo descreve a alteração que pretendia rever.
  5. Selecione Start scan.

O fluxo de trabalho não efetua o checkout de outra branch nem altera a árvore de trabalho selecionada. Se uma revisão solicitada não estiver disponível localmente, obtenha-a antes da revisão ou forneça uma base e um destino disponíveis localmente.

Atuar sobre as conclusões

Depois de rever os resultados, corrija e verifique uma conclusão aceite ou exporte e acompanhe as conclusões.

Automatizar revisões em CI/CD

Execute a mesma capacidade $codex-security:security-diff-scan a partir de CI quando o executor puder invocar a CLI do Codex sem interação. Primeiro, instale a CLI e o plugin sem expor a credencial de análise:

npm install --global @openai/codex

Instale o plugin Codex Security na CLI:

codex plugin add codex-security@openai-curated

O comando de instalação utiliza o marketplace público de plugins da CLI do Codex, que pode disponibilizar uma versão diferente da apresentada no catálogo da aplicação para computador alojada. Consulte o registo de alterações do plugin antes de depender de uma versão ou funcionalidade específica do plugin em CI.

Em seguida, disponibilize uma OpenAI API key a partir do repositório de segredos de CI como CODEX_SECURITY_API_KEY apenas para a análise:

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."

A análise escreve os resultados em $TMPDIR/codex-security-scans/<repository>/<scan-id>/:

Ficheiro Conteúdo
report.md Ponto de entrada principal e legível para o diretório completo da análise.
findings/<slug>/ Um relatório detalhado de vulnerabilidade por cada conclusão comunicável, com ficheiros de prova de conceito de suporte quando disponíveis.
hardening/ Portefólio de reforço estrutural e propostas ou diagramas de suporte quando a análise contém conclusões comunicáveis.
findings.json Conclusões com identificadores estáveis, gravidade, confiança, localizações no código-fonte e correção. Fornece dados a fluxos de trabalho internos de segurança aprovados ou a ferramentas subsequentes.
scan-manifest.json Recibo selado da análise com o alvo revisto, as revisões e os hashes dos artefactos.
coverage.json Superfícies revistas e adiadas, exclusões e integralidade da cobertura.

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

Campo Tipo Descrição
documentType String Identifica o documento como codex-security.findings.
schemaVersion String Identifica a versão do esquema de conclusões.
scanId String Identifica a análise que produziu as conclusões.
findings Array Contém zero ou mais objetos de conclusão.
findings[].findingId String Identificador estável da conclusão derivado da respetiva impressão digital.
findings[].occurrenceId String Identifica esta ocorrência da conclusão numa análise específica.
findings[].ruleId String Identifica a família da vulnerabilidade.
findings[].identity Object Contém a âncora semântica e um identificador opcional da instância relacionada.
findings[].fingerprints Object Contém o algoritmo de impressão digital e a impressão digital principal.
findings[].title String Fornece o título abreviado da conclusão.
findings[].summary String Resume a vulnerabilidade e o respetivo impacto.
findings[].severity Object Contém o nível de gravidade e detalhes opcionais da pontuação.
findings[].confidence Object Contém o nível de confiança e a respetiva justificação.
findings[].taxonomy Object Contém a categoria da vulnerabilidade e os identificadores CWE.
findings[].locations Array Lista os ficheiros afetados, os números de linha e as funções das localizações.
findings[].remediation String Descreve a correção recomendada.
findings[].provenance Object Identifica a origem da conclusão.

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

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

Estes exemplos pressupõem um executor Linux fidedigno com Node.js e npm, Git, Python 3, jq e as ferramentas de linha de comandos do fornecedor. O prefixo global de pacotes npm tem de permitir escrita.

Escolha o exemplo correspondente ao seu fornecedor de CI. Os resultados da análise podem incluir detalhes confidenciais sobre vulnerabilidades. Mantenha os artefactos privados e publique as conclusões apenas depois de rever o público, o conteúdo e as aprovações necessárias.

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 provenientes de forks. Execute tarefas com credenciais apenas a partir de uma definição de pipeline protegida e apenas para colaboradores de confiança a quem possa ser facultada a credencial de análise. Arquive codex-security-scans para manter juntos as conclusões estruturadas, o manifesto, os artefactos de cobertura, report.md e os respetivos resultados associados findings/ e hardening/. Comece com resultados consultivos e reveja a cobertura e o ambiente de execução antes de tornar a tarefa numa verificação obrigatória.

Para obter informações sobre o tratamento da API key e os controlos da sandbox, consulte o Modo não interativo. Se a sua organização permitir a Codex GitHub Action, esta pode instalar a CLI durante a execução, mas ainda terá de instalar primeiro o plugin e direcionar a entrada codex-home da ação para o mesmo CODEX_HOME.