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 uma cópia de trabalho de cada revisão fixada, analisa o alvo selecionado, regista o resultado e remove a cópia de trabalho temporária do repositório. Um repositório é considerado concluído quando a sua análise tem o estado completed no manifesto e os artefactos de resultados obrigatórios são válidos. As lacunas de cobertura não fazem a análise falhar.

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 erros de análise, mas não após um cancelamento ou uma análise que atinja o seu limite de custo. Os caminhos dos ficheiros de instruções 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, utilize um modelo ao qual as suas credenciais permitam aceder. Se iniciar sessão com o ChatGPT, consulte a disponibilidade do GPT-6.1 Sol antes de utilizar este exemplo:

npx @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 durante a descoberta interativa de repositórios:

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

Os níveis de esforço disponíveis dependem do modelo selecionado. As análises em massa suportam minimal, low, medium, high, xhigh e max; o GPT-6.1 Sol exige, no mínimo, low.

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 mantém a configuração da campanha, um registo de cada tentativa e resultados separados para cada repositório:

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 de código-fonte e detalhes de vulnerabilidades. Mantenha o diretório de saída privado e fora dos repositórios analisados. Defina durante quanto tempo os resultados devem ser conservados.

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 a campanha, iniciando novas tentativas para os repositórios elegíveis ainda não concluídos e ignorando as análises concluídas, incluindo as que têm lacunas de cobertura. Os respetivos resultados continuam disponíveis.

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

Por predefinição, é efetuada uma tentativa por repositório. Cada tentativa tem o seu próprio registo de resultados e diretório de artefactos. As novas tentativas abrangem erros de obtenção da cópia de trabalho, falhas de análise e artefactos obrigatórios em falta ou inválidos. As análises concluídas não são repetidas por terem lacunas de cobertura ou violações da política de gravidade.

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

Executar análises em massa no Docker

O repositório Codex Security inclui uma configuração Compose reforçada para campanhas CSV automatizadas num anfitrião Docker em Linux. O anfitrião tem de permitir 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.