Revisão de alterações locais ainda sem commit

Você pode usar a CLI para revisar alterações locais ainda sem commit, fornecendo de antemão informações sobre o repositório e as políticas de segurança.

Execute os exemplos na mesma sessão do shell, a partir da sua cópia local do repositório Git. Eles pressupõem que a política de segurança esteja em SECURITY.md e que os documentos de apoio estejam em docs/security/. Os comandos a seguir criam um diretório temporário para os resultados das varreduras.

northstar_repo="$(git rev-parse --show-toplevel)"
northstar_kb="$northstar_repo/docs/security"
northstar_results="$(mktemp -d)"

npx @openai/codex-security scan "$northstar_repo" \
  --working-tree \
  --base HEAD \
  --knowledge-base "$northstar_repo/SECURITY.md" \
  --knowledge-base "$northstar_kb" \
  --output-dir "$northstar_results/working-tree"

A varredura revisa as alterações em relação a HEAD, tanto as já adicionadas à área de preparação quanto as que ainda estão fora dela.

Antes de começar, confirme que a árvore de trabalho contém a alteração que você pretende avaliar. Alterações sem relação com ela ampliam o escopo da investigação e podem dificultar a identificação de quais resultados respondem à pergunta que motivou a revisão.

Revisão de PRs ou de commits de uma branch

Outra opção é revisar um PR ou uma branch em busca de problemas de segurança. Mude para a branch que deseja revisar e busque no repositório remoto a versão atual da branch de destino. Este exemplo usa origin/main.

northstar_pr_base="$(git -C "$northstar_repo" merge-base origin/main HEAD)"

npx @openai/codex-security scan "$northstar_repo" \
  --diff "$northstar_pr_base" \
  --head HEAD \
  --knowledge-base "$northstar_repo/SECURITY.md" \
  --knowledge-base "$northstar_kb" \
  --output-dir "$northstar_results/branch"

A varredura do diff avalia as alterações propostas, sem examinar o repositório inteiro. Ao final, você encontrará estes arquivos no diretório de saída:

• report.md: relatório da revisão em formato legível

• scan-manifest.json: confirma os commits exatos de base e de ponta, o alvo da varredura e os artefatos

• findings.json: indica a gravidade, o grau de confiança, os locais afetados e as medidas de correção para cada problema identificado

• coverage.json: indica quais áreas foram revisadas, o que foi excluído, o que ficou para depois e em que medida a revisão foi concluída

Varredura de monorepos

Em um monorepo, uma alteração em uma biblioteca compartilhada pode afetar vários serviços. O Codex deve receber contexto suficiente para revisar as interações entre a biblioteca e esses serviços. A integração contínua (CI) determina quais componentes e verificações são necessários.

Contexto do repositório

Mantenha as instruções de engenharia comuns às equipes em AGENTS.md e registre em SECURITY.md o que se espera em termos de segurança. Um repositório típico pode ter esta estrutura:

monorepo/
├── AGENTS.md
├── SECURITY.md
├── docs/security/
│   ├── architecture.md
│   └── threat-model.md
├── packages/auth/
└── services/
    ├── billing/
    └── reporting/

Use os metadados existentes sobre responsáveis e builds para relacionar cada componente às suas dependências, aos componentes que o utilizam e aos seus testes. Por exemplo, uma alteração em packages/auth pode exigir a revisão dos dois serviços, mesmo que os arquivos deles continuem iguais. Cabe à sua organização manter esse mapeamento de escopo. Adicionar o Codex não o configura automaticamente.

Avaliação de componentes

Em repositórios grandes, nem sempre é necessário examinar toda a base de código a cada PR. Quando um monorepo contém serviços ou pacotes separados, uma opção é fazer uma varredura por caminho. Repita –path para avaliar em conjunto uma biblioteca compartilhada e os componentes que a utilizam.

npx @openai/codex-security scan "$northstar_repo" \
  --path packages/auth \
  --path services/billing \
  --path services/reporting \
  --knowledge-base "$northstar_repo/SECURITY.md" \
  --knowledge-base "$northstar_kb" \
  --output-dir "$northstar_results/paths"

Essa varredura examina apenas os caminhos selecionados, sem percorrer o repositório inteiro.

Varredura de PRs e diffs

Para revisar um PR, obtenha nos metadados autenticados do GitHub os hashes exatos dos commits de base e de ponta do PR. As duas revisões e seus respectivos históricos precisam estar disponíveis na cópia local do repositório. O exemplo a seguir reutiliza as variáveis anteriores e salva os resultados da varredura do diff separadamente:

BASE_SHA="<full PR base commit SHA>"
HEAD_SHA="<full PR head commit SHA>"

BASE_REVISION="$(
  git -C "$northstar_repo" merge-base "$BASE_SHA" "$HEAD_SHA"
)" || exit

npx @openai/codex-security scan "$northstar_repo" \
  --diff "$BASE_REVISION" \
  --head "$HEAD_SHA" \
  --knowledge-base "$northstar_kb" \
  --auth chatgpt \
  --output-dir "$northstar_results/pr"

A varredura do diff se concentra nas alterações propostas. Se uma alteração em uma biblioteca compartilhada exigir uma revisão mais ampla dos componentes que a utilizam, execute também a avaliação de componentes em uma cópia local limpa, no commit de ponta do PR. Mantenha os resultados separados, pois --diff e --path são modos de varredura distintos e não podem ser combinados.

Varredura de alertas do GitHub

Você também pode usar a CLI do Codex Security para avaliar os alertas de varredura de código da branch padrão.

northstar_github_repository="example/northstar"
northstar_github_alerts="$northstar_results/github-alerts.json"

# Import all open alerts as complete JSON.
npx @openai/codex-security import github "$northstar_github_repository" \
  --format json \
  > "$northstar_github_alerts"

# Or import a selected subset.
npx @openai/codex-security import github "$northstar_github_repository" \
  --github-alert 12 \
  --github-alert 18 \
  --format json \
  > "$northstar_github_alerts"

# Run from the corresponding local repository; imported contents are data.
cd "$northstar_repo"
npx @openai/codex-security validate "$northstar_github_alerts"