Execute varreduras de segurança em lote

Use npx @openai/codex-security bulk-scan para analisar vários repositórios em uma única campanha. Encontre repositórios na sua conta pessoal do GitHub ou em uma organização, ou forneça um CSV que especifique a revisão exata do Git para cada repositório.

Escolha a origem dos repositórios

As duas opções salvam o progresso, preservam os resultados de cada repositório e permitem retomar a campanha após uma interrupção.

Encontre repositórios no GitHub

Entre na sua conta usando a CLI do GitHub:

gh auth login

Inicie uma varredura interativa em lote:

npx @openai/codex-security bulk-scan

A CLI orienta você nas seguintes etapas:

1. Escolha sua conta pessoal do GitHub ou uma organização.
2. Confira os repositórios que tiveram atividade nos últimos 90 dias.
3. Pesquise na lista de repositórios e selecione os que deseja analisar.
4. Escolha um diretório para os resultados das varreduras.
5. Confira os repositórios selecionados e confirme a campanha.

A busca exclui repositórios arquivados e forks. A CLI registra o commit exato da branch padrão de cada repositório selecionado em <output-directory>/repositories.csv. As varreduras só começam depois que você confirma a seleção.

Para usar o GitHub Enterprise Server, primeiro faça login no seu host do GitHub:

gh auth login --hostname github.example.com

Defina GH_HOST ao iniciar a busca por repositórios:

GH_HOST=github.example.com npx @openai/codex-security bulk-scan

A busca interativa exige um terminal. Em ambientes de CI ou contêineres, ou se você já tiver uma lista de repositórios, use um inventário em CSV.

Crie um CSV de repositórios

Crie um CSV com uma linha para cada repositório e sua respectiva revisão fixa:

id,repository,revision,scope,mode,prompt
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard,Review payment authorization and refunds.
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep,Review session and identity boundaries.

O CSV aceita as seguintes colunas:

Para obter o SHA completo do commit atual de um repositório local, execute:

git -C /path/to/repository rev-parse HEAD

Execute uma campanha a partir de um CSV

Informe o CSV e um diretório de saída privado que fique fora dos repositórios:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

--workers define quantos repositórios podem ser analisados ao mesmo tempo. O valor padrão é 4. Para limitar o número de processos independentes que executam varreduras padrão dentro de cada varredura profunda, configure os limites em [deep_scan]. Use --mode deep para selecionar a varredura profunda nas linhas sem valor próprio para mode. Cada linha do CSV pode definir seu próprio modo de varredura e o escopo da análise no repositório.

Defina [deep_scan].max_time_hours para limitar o tempo de execução dos processos de cada varredura profunda da campanha. A opção --max-time-hours funciona com scan, mas não com bulk-scan.

A CLI faz o checkout de cada revisão especificada, analisa o alvo selecionado, registra o resultado e remove a cópia temporária do repositório. A CLI considera a análise do repositório concluída quando a varredura tem o status completed no manifesto e todos os artefatos de resultado obrigatórios são válidos. Lacunas na cobertura não fazem a varredura falhar.

Compartilhe o contexto de segurança e as instruções

Use --knowledge-base para incluir documentos de arquitetura, modelos de ameaças ou políticas de segurança em todas as varreduras. Repita a opção para incluir outros arquivos ou diretórios:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Para adicionar instruções comuns às varreduras ou executar uma etapa adicional após cada uma, forneça arquivos de prompt:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --scan-prompt-file scan-instructions.md \
  --post-scan-prompt-file follow-up.md

A CLI acrescenta o conteúdo da coluna prompt de cada repositório ao final das instruções comuns de varredura. A CLI executa as instruções da etapa adicional na mesma sessão autenticada, tanto após varreduras bem-sucedidas quanto após erros de varredura. Essa etapa não é executada se a varredura for cancelada ou atingir o limite de custo. Os caminhos dos arquivos de prompt têm como base o diretório atual.

Escolha o modelo e o esforço de raciocínio

Por padrão, as varreduras em lote usam gpt-5.6-sol com esforço de raciocínio xhigh. Para escolher outro modelo e outro nível de esforço em uma campanha com CSV, use um modelo ao qual suas credenciais deem acesso. Se você faz login com o ChatGPT, verifique a disponibilidade do GPT-6.1 Sol antes de usar este exemplo:

1
2
3
4
5npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--workers 4 \
--model gpt-6.1-sol \
--effort medium

As mesmas opções funcionam na busca interativa por repositórios:

npx @openai/codex-security bulk-scan --model gpt-6.1-sol --effort medium

Use um valor de --effort compatível com seu modelo, seu provedor e sua versão do Codex.

Para usar o OpenRouter ou o Fireworks, defina OPENROUTER_API_KEY ou FIREWORKS_API_KEY, respectivamente, e especifique --provider e --model. Para consultar as credenciais necessárias e ver exemplos, confira a configuração do OpenRouter ou do Fireworks ou a configuração do Amazon Bedrock.

Confira os resultados da campanha

O diretório de saída armazena a configuração da campanha, o registro de cada tentativa e os resultados separados por repositório:

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    ├── payments/
    │   └── attempt-1/
    │       ├── scan-manifest.json
    │       ├── findings.json
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            └── report.md

• manifest.json registra os repositórios, as revisões fixadas, os escopos, os modos de varredura e as instruções da campanha, tanto as comuns quanto as específicas de cada repositório.
• results.jsonl registra cada tentativa de varredura de um repositório, seu status, o diretório de artefatos e os detalhes disponíveis sobre custos ou erros.
• report.md apresenta os resultados de uma tentativa de varredura de um repositório em formato de relatório.
• Abra findings.json para consultar os problemas identificados na tentativa e scan-manifest.json para conferir o escopo configurado e as exclusões da análise.

Quando precisar de um resultado portátil, exporte uma varredura concluída de um repositório:

npx @openai/codex-security export \
  /path/outside/repositories/security-scans/artifacts/payments/attempt-1 \
  --export-format sarif \
  --output /path/outside/repositories/payments.sarif

Os resultados podem conter trechos de código-fonte e detalhes de vulnerabilidades. Mantenha o diretório de saída privado e fora dos repositórios analisados. Defina por quanto tempo os resultados serão mantidos.

Retome uma campanha

Execute o comando original com o mesmo CSV e o mesmo diretório de saída:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

A CLI retoma a campanha e inicia novas tentativas nos repositórios cuja análise está pendente e que atendem aos critérios para uma nova tentativa. Ela pula as varreduras concluídas, inclusive aquelas com lacunas na cobertura. Os resultados dessas varreduras continuam disponíveis.

Ao usar um diretório de saída existente, mantenha o mesmo inventário de repositórios e as mesmas instruções de varredura e da etapa adicional. A CLI verifica o manifesto fixado para esse diretório e rejeita campanhas diferentes. Use um novo diretório de saída se alterar os repositórios, as revisões, os escopos, os modos de varredura ou as instruções comuns ou específicas de um repositório.

Repita a varredura de repositórios com erros

Use --max-attempts para tentar analisar o repositório novamente após um erro temporário de checkout ou de varredura:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --max-attempts 3

Por padrão, a CLI faz uma tentativa por repositório. Cada tentativa tem seu próprio registro de resultado e diretório de artefatos. A CLI pode repetir a tentativa quando ocorrem erros de checkout ou falhas na varredura, ou quando faltam artefatos obrigatórios ou eles são inválidos. Lacunas na cobertura ou violações da política de severidade não geram novas tentativas em varreduras já concluídas.

As varreduras em lote usam os seguintes códigos de saída:

Execute varreduras em lote no Docker

O repositório do Codex Security inclui uma configuração do Compose com segurança reforçada para automatizar campanhas com CSV em um host Linux com Docker. O host precisa permitir que usuários sem privilégios criem namespaces de usuário.

Mantenha o CSV de repositórios, os resultados das varreduras e o estado de autenticação em diretórios persistentes montados no contêiner. Forneça as credenciais da OpenAI por meio de variáveis de ambiente ou de um gerenciador de segredos. Para repositórios privados do GitHub, forneça GH_TOKEN ou GITHUB_TOKEN da mesma forma.

Execute a imagem com o CSV e o diretório de saída montados:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

Para retomar a campanha, use o mesmo CSV e o mesmo diretório de saída montados. Para usar o GitHub Enterprise Server, defina CODEX_SECURITY_GIT_HOST com o nome do seu host do GitHub.

Para ver todas as opções disponíveis, consulte a referência do comando bulk-scan. Para dúvidas comuns sobre a cobertura das varreduras e os problemas identificados, consulte as perguntas frequentes sobre a CLI.