Executar análises de segurança em massa

Utilize npx @openai/codex-security bulk-scan para analisar repositórios numa única campanha. Descubra repositórios a partir da sua conta pessoal do GitHub ou de uma organização, ou forneça um CSV que fixe cada repositório numa revisão Git exata.

Escolher uma origem de repositórios

Ambos os fluxos de trabalho guardam o progresso, preservam os resultados de cada repositório e permitem-lhe retomar uma campanha após uma interrupção.

Descobrir repositórios do GitHub

Inicie sessão com a GitHub CLI:

gh auth login

Inicie uma análise em massa interativa:

npx @openai/codex-security bulk-scan

A CLI orienta-o através destes passos:

1. Escolha a sua conta pessoal do GitHub ou uma organização.
2. Consulte os repositórios ativos nos últimos 90 dias.
3. Pesquise na lista de repositórios e selecione os repositórios a analisar.
4. Escolha um diretório para os resultados das análises.
5. Reveja os repositórios selecionados e confirme a campanha.

A descoberta exclui repositórios arquivados e forks. A CLI regista o commit exato do ramo predefinido de cada repositório selecionado em <output-directory>/repositories.csv. Nenhuma análise é iniciada até confirmar a seleção.

Para utilizar o GitHub Enterprise Server, comece por iniciar sessão no seu anfitrião do GitHub:

gh auth login --hostname github.example.com

Defina GH_HOST quando iniciar a descoberta de repositórios:

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

A descoberta interativa requer um terminal. Para CI, contentores ou uma lista de repositórios preparada, utilize antes um inventário CSV.

Criar um CSV de repositórios

Crie um CSV com uma linha para cada repositório e 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 suporta estas colunas:

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

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

Executar uma campanha a partir de um CSV

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

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

--workers controla as análises simultâneas de repositórios e tem como predefinição 4. Não define o número de workers independentes de análise padrão em cada análise aprofundada; configure esses limites através de [deep_scan]. Utilize --mode deep para selecionar a análise aprofundada nas linhas sem um mode próprio. Cada linha do CSV pode continuar a escolher o seu próprio modo de análise e âmbito do repositório.

Defina [deep_scan].max_time_hours para limitar a execução de workers em cada análise aprofundada da campanha. O sinalizador --max-time-hours funciona com scan, não com bulk-scan.

A CLI obtém cada revisão fixa, analisa o alvo selecionado, regista o resultado e remove a cópia de trabalho temporária do repositório. Um repositório só é considerado concluído quando a respetiva análise tem cobertura completa e existem todos os artefactos de resultado necessários.

Partilhar contexto e instruções de segurança

Adicione documentos de arquitetura, modelos de ameaças ou políticas de segurança a todas as análises com --knowledge-base. Repita o sinalizador para adicionar mais ficheiros 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 de análise partilhadas ou executar um seguimento após cada análise, forneça ficheiros 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 prompt do CSV de cada repositório após as instruções de análise partilhadas. As instruções de seguimento são executadas na mesma sessão autenticada após análises bem-sucedidas e análises com cobertura incompleta ou erros, mas não após um cancelamento ou uma análise que atinja o respetivo limite de custos. Os caminhos dos ficheiros de prompt são resolvidos a partir do diretório atual.

Escolher um modelo e o esforço de raciocínio

As análises em massa utilizam gpt-5.6-sol com o esforço de raciocínio xhigh por predefinição. Para escolher outro modelo e esforço para uma campanha CSV:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --model gpt-5.6-terra \
  --effort high

As mesmas opções funcionam durante a descoberta interativa de repositórios:

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

Os níveis de esforço suportados são minimal, low, medium, high e xhigh.

Para utilizar o OpenRouter ou o Fireworks, defina OPENROUTER_API_KEY ou FIREWORKS_API_KEY, respetivamente, e especifique --provider e --model. Para obter credenciais e exemplos, consulte a configuração do OpenRouter ou do Fireworks ou a configuração do Amazon Bedrock.

Rever os resultados da campanha

O diretório de saída contém a campanha fixa, um registo de resultados apenas de acréscimo e artefactos separados para cada repositório e tentativa:

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

• manifest.json regista os repositórios, as revisões fixas, os âmbitos, os modos de análise e as instruções partilhadas ou específicas de cada repositório na campanha.
• results.jsonl regista cada tentativa do repositório, o respetivo estado, o diretório de artefactos e quaisquer detalhes disponíveis sobre custos ou erros.
• report.md fornece um relatório legível de uma tentativa de repositório.
• findings.json e coverage.json registam as descobertas e o âmbito revisto dessa tentativa.

Exporte uma análise concluída de um repositório quando precisar de um resultado portátil:

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 excertos do código-fonte e detalhes de vulnerabilidades. Mantenha o diretório de saída privado, fora dos repositórios analisados e sujeito a uma política de retenção adequada.

Retomar uma campanha

Execute o comando original com o mesmo CSV e 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 as análises de repositórios não concluídas e ignora as concluídas. As análises com cobertura incompleta não são repetidas. Os respetivos resultados permanecem disponíveis e o comando termina com o código 2.

Não altere o inventário de repositórios nem as instruções de análise e seguimento de um diretório de saída existente. A CLI verifica o manifesto fixo e rejeita uma campanha diferente. Utilize um novo diretório de saída quando alterar repositórios, revisões, âmbitos, modos de análise ou instruções partilhadas ou específicas dos repositórios.

Repetir após erros de repositório

Utilize --max-attempts para repetir a operação num repositório após um erro temporário de obtenção ou análise:

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

A predefinição é uma tentativa por repositório. Cada tentativa recebe o seu próprio comprovativo e diretório de artefactos. As repetições abrangem erros de obtenção, falhas de análise e artefactos obrigatórios em falta. As análises concluídas com cobertura incompleta não são repetidas.

As análises em massa utilizam estes códigos de saída:

Executar análises em massa no Docker

O repositório do Codex Security inclui uma configuração reforçada do Compose para campanhas CSV automatizadas num anfitrião Docker Linux. O anfitrião tem de suportar a criação de espaços de nomes de utilizador sem privilégios.

Mantenha o CSV de repositórios, os resultados das análises e o estado de início de sessão montados em diretórios persistentes. Forneça as credenciais da OpenAI através do ambiente ou de um gestor 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

Utilize o mesmo CSV e diretório de saída montados para retomar a campanha. Para o GitHub Enterprise Server, defina CODEX_SECURITY_GIT_HOST como o seu anfitrião do GitHub.

Para consultar todos os sinalizadores disponíveis, consulte a referência do comando bulk-scan . Para perguntas comuns sobre a cobertura e as descobertas das análises, consulte as Perguntas frequentes da CLI.