Executar análises de segurança em massa

Utilize npx @openai/codex-security bulk-scan para rever 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 retomar uma campanha após uma interrupção.

Descobrir repositórios 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. Reveja 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 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 fixada:

id,repository,revision,scope,mode
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep

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 o número de análises simultâneas de repositórios e a predefinição é 4. Utilize --mode deep para selecionar a análise aprofundada para linhas sem o respetivo mode. Cada linha do CSV pode continuar a escolher o seu próprio modo de análise e âmbito do repositório.

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

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

Por predefinição, as análises em massa utilizam gpt-5.6-sol com o esforço de raciocínio xhigh. 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.

Rever os resultados da campanha

O diretório de saída contém a campanha fixada, 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 fixadas, os âmbitos e os modos de análise da campanha.
• results.jsonl regista cada tentativa no 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 para uma tentativa num repositório.
• findings.json e coverage.json registam as descobertas e o âmbito revisto dessa tentativa.

Exporte uma análise de repositório concluída 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, 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 os repositórios que ainda precisam de processamento. Só ignora um repositório concluído quando o recibo correspondente e todos os artefactos de análise necessários ainda existem.

Não altere o inventário de repositórios de um diretório de saída existente. A CLI verifica o manifesto fixado e rejeita uma campanha diferente. Utilize um novo diretório de saída quando alterar repositórios, revisões, âmbitos ou modos de análise.

Repetir após erros nos repositórios

Utilize --max-attempts para repetir a operação num repositório após um erro temporário de obtenção ou de 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 recibo e diretório de artefactos.

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 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 da sessão montados em diretórios persistentes. Forneça as credenciais OpenAI através do ambiente ou de um gestor de segredos. Para repositórios GitHub privados, 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 GitHub.

Para consultar todas as opções disponíveis, consulte a referência do comando bulk-scan. Para perguntas frequentes sobre a cobertura das análises e as descobertas, consulte as perguntas frequentes da CLI.