Referência da CLI do Codex Security

Consulte os comandos, as opções e os formatos de saída de codex-security e veja como a CLI encerra a execução. Para executar sua primeira varredura, siga o guia de início rápido da CLI.

Execute a CLI com npx @openai/codex-security. O pacote instalado também disponibiliza o alias cs.

Visão geral dos comandos

usage: codex-security [--version] <command> [options]

A CLI oferece os seguintes comandos:

A CLI também oferece os seguintes comandos de integração:

Liste todos os comandos disponíveis:

npx @openai/codex-security --help

Acrescente --help a um comando para consultar seus argumentos e opções:

npx @openai/codex-security scan --help

codex-security --version exibe a versão instalada e encerra a execução. codex-security info --json informa as versões do SDK e do plugin incluído no pacote. Nenhum dos dois comandos exige Python. Use codex-security --update para atualizar a CLI instalada.

Descobrir comandos e conectar agentes

Exiba o manifesto de comandos em um formato que os agentes possam ler:

npx @openai/codex-security --llms

Consulte o schema dos argumentos da varredura em JSON:

npx @openai/codex-security scan --schema --format json

Gere o script de preenchimento automático para Bash:

npx @openai/codex-security completions bash

Substitua bash por zsh ou fish se usar um desses shells.

Para a saída dos resultados da varredura, você pode usar --format toon|json|yaml|jsonl e --full-output. Já --export-format seleciona o formato de um artefato exportado de uma varredura concluída. A ajuda global dos comandos também lista md, mas os resultados da varredura não admitem saída em Markdown.

Registre a CLI como servidor MCP:

npx @openai/codex-security mcp add

Sincronize as habilidades do Codex Security com seus agentes:

npx @openai/codex-security skills add

A CLI disponibiliza pelo servidor MCP apenas o comando info, que permite consultar metadados em modo somente leitura. Varreduras, exportação, publicação, autenticação, validação e aplicação de correções estão disponíveis apenas pela CLI.

codex-security scan

Execute uma varredura em um repositório, em caminhos selecionados, nas alterações registradas em commits ou na árvore de trabalho.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--config FILE]
                           [--cyber-access-program PROGRAM]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH] [--scan-prompt-file FILE]
                           [--validation-prompt-file FILE]
                           [--post-scan-prompt-file FILE]
                           [--mode {standard,deep}] [--workers N]
                           [--subagents N] [--stop-after-no-new N]
                           [--max-discovery-runs N] [--max-time MINUTES]
                           [--model MODEL]
                           [--effort EFFORT]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--validate] [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--show-cost] [--dry-run] [--mock]
                           [--workflow-id ID] [--safety-identifier ID]
                           [--headless] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

Por padrão, repository corresponde ao diretório atual.

Carregar a configuração do projeto

Crie uma configuração inicial e selecione-a explicitamente:

npx @openai/codex-security init codex-security.yaml
npx @openai/codex-security scan . --config codex-security.yaml

init não sobrescreve arquivos existentes. Use -c FILE como forma abreviada de --config FILE ou defina CODEX_SECURITY_PROJECT_CONFIG. Uma opção explícita tem precedência sobre a variável de ambiente. A CLI não procura automaticamente um arquivo de configuração do projeto.

Selecione apenas configurações sob seu controle. Elas têm a mesma autoridade que as opções da CLI. As configurações nativas do Codex podem iniciar processos de servidores MCP e definir os destinos das solicitações a serviços de modelos. Não selecione arquivos controlados por um repositório ou pull request que não seja de confiança. Em CI, mantenha a configuração da ferramenta de varredura fora da cópia de trabalho avaliada. Consulte o guia de configuração do projeto para conhecer as opções e sua ordem de precedência.

Selecionar a autenticação da varredura

Use --auth auto, a opção padrão, para selecionar as credenciais automaticamente. Quando há tanto um login no ChatGPT quanto uma chave em OPENAI_API_KEY ou CODEX_API_KEY, as varreduras interativas com saída de texto perguntam qual credencial usar. Varreduras em CI, varreduras com saída JSON ou JSONL e outras varreduras sem terminal interativo usam a chave de API do ambiente. As simulações não solicitam nem carregam credenciais.

Para usar suas credenciais armazenadas, passe --auth chatgpt:

npx @openai/codex-security scan . --auth chatgpt

Para usar uma chave de API do ambiente, passe --auth api-key:

npx @openai/codex-security scan . --auth api-key

Para executar uma varredura com o Daybreak Blue, use uma chave de um projeto em que o Blue esteja habilitado e acrescente --model gpt-6-sol --cyber-access-program daybreak_blue ao comando. Para outros modelos, consulte a tabela de modelos e programas de acesso.

Para que a seleção automática use as credenciais armazenadas por padrão, execute unset OPENAI_API_KEY CODEX_API_KEY.

Atribuir varreduras a usuários finais

Ao executar varreduras em nome de usuários com autenticação por chave de API, --safety-identifier ID aceita um identificador estável gerado por hash. Use de 1 a 64 caracteres, sem caracteres NUL nem dados pessoais, como endereços de e-mail.

Para encaminhar o identificador, use CODEX_CLI_PATH para selecionar uma compilação do Codex compatível com a opção e use um plugin que repasse o identificador aos processos de varredura. O ambiente de execução do Codex incluído no pacote não oferece esse suporte.

Usar OpenRouter ou Fireworks

Para usar o OpenRouter, informe a chave de API do provedor e selecione explicitamente um modelo:

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
  --provider openrouter \
  --model anthropic/claude-sonnet-4.5

Para usar o Fireworks, informe a chave de API do provedor e selecione explicitamente um modelo:

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
  --provider fireworks \
  --model accounts/fireworks/models/qwen3-235b-a22b

Os dois provedores também oferecem suporte a bulk-scan.

Usar o Amazon Bedrock

Use --provider amazon-bedrock e um ID de modelo do Bedrock com scan ou bulk-scan. As varreduras com o Bedrock usam credenciais da AWS e dispensam --auth, login na OpenAI e chave de API da OpenAI.

Daybreak Blue e Daybreak Red

Solicite acesso ao Daybreak à equipe responsável pela sua conta na OpenAI ou pelo formulário de acesso empresarial. A aprovação para o Daybreak Red inclui acesso ao GPT-5.6 Cyber. Depois que a OpenAI aprovar sua solicitação, peça à equipe responsável pela sua conta na AWS que provisione o modelo na conta que você usa para as varreduras.

Para verificar a disponibilidade, consulte na AWS os cartões dos modelos Daybreak Blue e Daybreak Red.

Escolha um perfil da AWS com acesso ao modelo. Para o Daybreak Blue, execute:

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-daybreak-blue-5.6-sol --effort high

Para o Daybreak Red, execute:

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-cyber --effort high

Você também pode se autenticar com AWS_BEARER_TOKEN_BEDROCK ou com a cadeia padrão de credenciais da AWS. Chaves de acesso temporárias exigem AWS_SESSION_TOKEN. Defina as credenciais e AWS_REGION no mesmo shell ou na mesma tarefa de CI em que a varredura será executada.

Resultados locais e verificação de acesso

Os relatórios salvos localmente, scans show e export funcionam sem credenciais de nuvem.

info e scan --dry-run não testam as credenciais da AWS nem o acesso ao modelo. Execute uma varredura para verificar o acesso. Em caso de erro de autenticação da AWS ou de acesso negado, verifique suas credenciais, a região e as permissões de acesso ao modelo.

Estimativas de custo do Bedrock

A CLI oferece estimativas de custo e suporte a --max-cost para os IDs de modelo do Daybreak Blue e do Daybreak Red listados acima. As estimativas usam os preços comerciais da modalidade Standard da AWS para uso dentro da região, incluindo a taxa da AWS. O limite de custo usa estimatedUsd, a estimativa de referência para contexto curto. Solicitações já em andamento podem fazer essa estimativa ultrapassar o limite. Os preços para contexto longo podem elevar o valor informado em estimatedUsdRange acima do limite. Esse limite não estabelece um teto para a cobrança.

Selecionar o alvo da varredura

Escolha um tipo de alvo para cada varredura.

As opções --path, --diff e --working-tree são mutuamente exclusivas. --head exige --diff, e --base exige --working-tree. O modo profundo aceita repositórios e caminhos como alvos.

Nas varreduras de diferenças e da árvore de trabalho, o argumento de repositório precisa apontar para a raiz da árvore de trabalho do Git. As referências selecionadas precisam existir nessa cópia de trabalho.

Examine todo o repositório:

npx @openai/codex-security scan .

Examine os caminhos selecionados:

npx @openai/codex-security scan . --path src --path tests

Examine as alterações registradas em commits:

npx @openai/codex-security scan . --diff origin/main --head HEAD

Examine as alterações preparadas e não preparadas para commit:

npx @openai/codex-security scan . --working-tree --base HEAD

Faça uma revisão mais profunda do repositório:

npx @openai/codex-security scan . --mode deep

Configurar varreduras profundas

Use estas opções com --mode deep para controlar a descoberta de problemas:

Por exemplo, use dois processos, permita até dez execuções e encerre a descoberta após 90 minutos:

npx @openai/codex-security scan . \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time 90

Quando o tempo se esgota, a varredura interrompe os processos ainda em execução e reúne no relatório os achados das varreduras concluídas. Em uma varredura padrão, --max-time define um tempo indicativo para a investigação. A geração do relatório pode terminar depois. A validação personalizada e as instruções pós-varredura são executadas fora desse prazo.

Para reutilizar esses limites, salve-os em um arquivo de configuração do projeto:

scan:
  mode: deep
  max_time_minutes: 90
  deep:
    workers: 2
    subagents_per_worker: 0
    stop_after_no_new: 3
    max_discovery_runs: 10

As opções da linha de comando têm precedência sobre a configuração do projeto. Use scan.deep.stop_after_consecutive_errors para definir após quantos erros consecutivos nos processos de varredura a descoberta deve parar. O padrão é 3. No comando bulk-scan, --workers controla quantos repositórios podem ser examinados simultaneamente.

Adicionar contexto de segurança

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

npx @openai/codex-security scan . \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Os formatos compatíveis incluem arquivos de texto UTF-8 (inclusive JSON e SARIF), PDF e DOCX. A CLI percorre os diretórios recursivamente, rejeita caminhos de entrada que passam por links e ignora entradas de diretório que sejam links. Para permitir a retomada da varredura, ela salva os documentos extraídos no arquivo privado de continuação .scan-knowledge.json, junto aos artefatos da varredura. Mantenha esse arquivo no diretório da varredura. Os relatórios canônicos não incluem o texto dos documentos.

Adicionar instruções de varredura

Para adicionar instruções de varredura, forneça um arquivo de texto ou Markdown com --scan-prompt-file. Use --post-scan-prompt-file para executar instruções complementares na mesma sessão autenticada após varreduras bem-sucedidas ou que retornem erros:

npx @openai/codex-security scan . \
  --scan-prompt-file security-focus.md \
  --post-scan-prompt-file follow-up.md

Por exemplo, use o prompt de varredura para concentrar a análise nos limites de autorização e peça nas instruções complementares que seja criado um arquivo post-scan-summary.md no diretório da varredura. Se a execução dessas instruções falhar, a CLI emitirá um aviso e preservará a varredura concluída. As instruções complementares não são executadas após um cancelamento nem quando a varredura atinge seu limite de custo. Quando executadas, ficam fora do cálculo de custo da varredura e do limite --max-cost.

Validar achados no seu ambiente

Use --validation-prompt-file FILE para substituir a etapa final de validação pelo seu próprio procedimento de teste. O Codex primeiro revisa o código-fonte e pula a validação se não encontrar possíveis achados. Mantenha o prompt e o script de teste em um diretório sob seu controle, fora da cópia de trabalho:

npx @openai/codex-security scan . \
  --validation-prompt-file /path/to/security-tests/validation.md

Por exemplo, se o servidor de teste local estiver em execução, coloque estas instruções em validation.md:

Execute /path/to/security-tests/validate.sh no servidor http://localhost:3000.
Informe quais achados foi possível reproduzir e inclua a saída de teste relevante.

Use essa opção em varreduras padrão de repositórios, caminhos, diferenças ou árvores de trabalho. Para varreduras padrão de componentes, defina scan.validation_file na configuração do projeto. Varreduras profundas não aceitam validação personalizada.

Adicione --validate ao comando de uma nova varredura para avaliar separadamente cada achado relatado, usando apenas o código-fonte. Se a varredura relatar achados, a CLI gravará as avaliações em um relatório no diretório da varredura. As avaliações não alteram os achados nem a decisão da política de gravidade. Não é possível combinar --validate com --dry-run, --mock ou um limite de custo da varredura definido na linha de comando ou na configuração do projeto.

Definir opções de saída e de política

Use estas opções para armazenar artefatos, preservar resultados anteriores ou gerar um resultado legível por máquina.

O modo de dados sintéticos aceita varreduras padrão de repositórios, caminhos e diferenças. Não é possível combiná-lo com --dry-run, --patch, modo profundo, validação personalizada ou prompts pós-varredura. Prompts de varredura e bases de conhecimento não alteram seus achados sintéticos. Use um CODEX_SECURITY_STATE_DIR separado para manter os resultados sintéticos fora do histórico de varreduras.

O limite de custo usa estimatedUsd, a estimativa de referência para contexto curto. Solicitações já em andamento podem fazer essa estimativa ultrapassar o limite. Os preços para contexto longo podem elevar estimatedUsdRange acima do limite. Esse limite não estabelece um teto para a cobrança.

Se uma varredura profunda atingir o limite após o Codex Security reunir os resultados dos processos concluídos, a CLI poderá selar o resultado como concluído e emitir o aviso de orçamento. Nesse caso, retornará 0, ou 1 se houver achados que atinjam o nível de gravidade configurado. Se não conseguir produzir um resultado concluído válido, retornará 2 e manterá em disco toda a saída disponível.

Se você omitir --output-dir, os resultados serão armazenados em $CODEX_HOME/state/plugins/codex-security/scans/<repository>. O valor padrão de CODEX_HOME é ~/.codex. Defina CODEX_SECURITY_STATE_DIR para armazenar os resultados em $CODEX_SECURITY_STATE_DIR/scans/<repository>. Esses diretórios podem conter trechos de código-fonte e detalhes de vulnerabilidades. Leve isso em conta ao definir permissões e prazos de retenção.

A bancada de análise mantém o histórico de varreduras em $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Definir CODEX_SECURITY_STATE_DIR também muda a localização do banco de dados da bancada.

O diretório de saída precisa ficar fora do diretório examinado e de qualquer árvore de trabalho do Git que o contenha. Use --archive-existing para preservar os resultados anteriores antes de reutilizar um diretório de saída:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

Por padrão, as varreduras apenas relatam os resultados. Adicione --fail-on-severity para avaliar uma política de gravidade em CI:

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

Uma simulação verifica as entradas locais, inclusive os documentos da base de conhecimento, sem carregar credenciais, iniciar o Codex ou testar o interpretador Python do plugin:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

Configurar o ambiente de execução

Use as opções do ambiente de execução para selecionar um modelo, um interpretador, um plugin ou um valor de configuração do Codex.

O Codex Security aceita IDs de modelo e valores de esforço de raciocínio como strings. As combinações compatíveis dependem do modelo, do provedor, da versão do Codex e das suas credenciais.

Se a configuração isolada do Codex para a varredura selecionar um perfil, os valores de model e model_reasoning_effort desse perfil terão precedência sobre --model e --effort. Sua configuração habitual do Codex não é carregada. Adicione --dry-run --verbose ao comando de varredura para consultar o modelo e o esforço efetivamente selecionados antes de iniciar a varredura.

Para escolher um modelo e um esforço de raciocínio, selecione um modelo do Codex disponível para sua conta:

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

Coloque entre aspas os valores de string passados por --codex para que o analisador TOML os receba como strings:

npx @openai/codex-security scan . --codex 'model="gpt-6.1-sol"'

Os valores de modelo e esforço são repassados ao Codex sem alterações. Combinações incompatíveis retornam erros do Codex ou do provedor. Não há substituição automática do modelo nem do esforço.

codex-security scan import

Salve achados existentes como uma varredura concluída no histórico local, sem executar uma análise de segurança nem fazer chamadas a modelos. A importação não exige autenticação para uso de modelos.

usage: codex-security scan import (--csv FILE | --json FILE)
                                  [--output-dir DIR] [--archive-existing]
                                  [--dry-run] [--format json]

Forneça exatamente uma entrada. O CSV usa as colunas de exportação do Codex Security. Para JSON, o comando aceita um documento codex-security.findings completo ou um objeto com um array findings compatível com o schema de achados. Arquivos JSON de outras ferramentas de varredura com estrutura arbitrária e arrays brutos de alertas do GitHub não são aceitos como achados salvos.

Salve este exemplo sintético como findings.csv:

occurrence_id,finding_id,title,summary,severity,confidence,status,close_reason,note,remediation,path,start_line,end_line
occ_000000000000000000000001,csf_000000000000000000000001,Missing authorization check,The route reads a record without checking ownership,high,high,open,,,Check record ownership before returning data,src/routes.ts,18,18

Valide o arquivo e depois importe-o:

npx @openai/codex-security scan import --csv findings.csv --dry-run --format json
npx @openai/codex-security scan import --csv findings.csv --format json

A simulação informa dryRun: true e findingCount: 1 sem salvar uma varredura. A importação retorna o ID da varredura salva e os caminhos dos resultados. Para importar um arquivo JSON:

npx @openai/codex-security scan import --json findings.json --format json

Nesse comando, --json FILE seleciona o arquivo de entrada. Use --format json para obter a saída em JSON.

Use como entrada um arquivo comum cujo caminho não contenha links simbólicos nem junções de diretórios. Cada importação preserva todas as ocorrências dos achados, inclusive as duplicadas, e mantém a entrada em artifacts/import/. Os identificadores originais ficam em extensions.import. O status de conclusão indica apenas que a importação terminou, sem atestar a revisão do código-fonte. scans rerun SCAN_ID importa novamente a entrada armazenada.

Para examinar um repositório chamado import, use scan ./import.

codex-security import github

Leia alertas de varredura de código do GitHub sem alterar dados no GitHub nem fazer checkout do código:

npx @openai/codex-security import github example/repository --format json > /path/outside/repository/alerts.json
npx @openai/codex-security import github example/repository \
  --github-alert 12 --github-alert 18 --format json

Substitua example/repository pelo seu repositório. Autentique-se com credenciais da CLI do GitHub que tenham permissão de leitura para a varredura de código. Por padrão, a importação lê os alertas abertos da branch padrão, inclusive os provenientes de arquivos SARIF enviados por terceiros.

Não combine números específicos de alerta com um estado diferente de open. O comando retorna um array de alertas provenientes do GitHub, sem salvar uma varredura. No repositório local correspondente, execute codex-security validate /path/outside/repository/alerts.json para avaliá-los. Ao salvar entradas para validação, mantenha o JSON completo, sem filtros de saída nem limites de tokens. Use scan import para achados que já estejam no schema do Codex Security. Para importar alertas do Dependabot, use publish findings.

codex-security install-hook

Instale a CLI fora do repositório, inspecione o hook de pre-commit existente no repositório e execute a CLI instalada a partir de um local fora da cópia de trabalho:

git -C /path/to/repository rev-parse --git-path hooks/pre-commit
codex-security install-hook /path/to/repository

Antes de cada commit, a verificação examina as alterações preparadas e não preparadas. Ela bloqueia o commit se encontrar achados de gravidade alta ou crítica ou se a varredura apresentar erros. Os hooks locais são opcionais. Para impor a verificação, torne-a obrigatória em CI. Deixe a cargo dos respectivos responsáveis os hooks e diretórios de hooks personalizados, vinculados por links ou compartilhados. O instalador não substitui scripts de pre-commit sem relação com a varredura. Se necessário, defina outro limite de gravidade:

codex-security install-hook /path/to/repository --fail-on-severity medium

codex-security policy

Elabore uma política SECURITY.md que descreva os limites de segurança do projeto e o que deve ser considerado um achado:

npx @openai/codex-security policy .
npx @openai/codex-security policy . --headless --json

O comando salva um rascunho fora do repositório e preserva os arquivos existentes. Revise o rascunho, as diferenças e as notas de revisão. Em seguida, copie apenas o SECURITY.md revisado para o destino indicado para a política. No modo sem interface interativa, as perguntas não respondidas ficam nas notas de revisão. A geração da política é opcional. As varreduras podem usar uma política existente ou ser executadas sem uma. Consulte o guia de políticas para conhecer as opções e saber a quais caminhos elas se aplicam.

codex-security scan-components

Use scan-components para examinar separadamente serviços ou pacotes de um mesmo repositório. Cada execução, mesmo que seja apenas para gerar um plano, exige um diretório de saída novo ou vazio fora da árvore de trabalho do Git que contém o repositório. Defina o diretório com --output-dir ou com output.directory na configuração do projeto.

Por exemplo, examine dois serviços em paralelo:

npx @openai/codex-security scan-components . \
  --component apps/api --component apps/web \
  --output-dir /path/outside/repository/manual-components

Ao contrário de scan --path, esse comando executa uma varredura por componente e depois reúne os achados e identifica as correspondências entre eles. Por padrão, até quatro varreduras de componentes podem ser executadas simultaneamente. Defina --workers N para alterar esse limite. --max-cost USD limita o custo de cada varredura de componente. O limite não inclui o planejamento automático nem a identificação de correspondências entre componentes.

Para que o Codex proponha uma divisão, salve um plano para revisão antes de iniciar a varredura:

npx @openai/codex-security scan-components . --auto --plan-only \
  --output-dir /path/outside/repository/component-plan

Revise os nomes e caminhos dos componentes em components.json. Depois, execute o plano salvo usando um novo diretório de saída:

npx @openai/codex-security scan-components . \
  --components-file /path/outside/repository/component-plan/components.json \
  --output-dir /path/outside/repository/components

Abra report.md no diretório de saída para revisar os achados consolidados. Se a varredura de um componente falhar, use o plano de nova tentativa salvo para examinar novamente apenas os componentes cuja varredura falhou:

npx @openai/codex-security scan-components . \
  --components-file /path/outside/repository/components/retry-components.json \
  --output-dir /path/outside/repository/retry-results

O relatório da nova tentativa cobre apenas os componentes reexaminados. Mantenha o relatório original para revisar os achados dos componentes cuja varredura terminou na primeira execução.

Falhas na varredura ou na identificação de correspondências retornam 2. Violações da política de gravidade retornam 1. Consulte o guia de varredura de componentes para saber mais sobre a sintaxe do plano e as novas tentativas.

codex-security bulk-scan

Descubra e examine repositórios do GitHub ou execute uma varredura que pode ser retomada a partir de um CSV de repositórios.

Para saber mais sobre descoberta no GitHub, inventários em CSV, resultados de campanhas e varreduras em contêineres, consulte Executar varreduras de segurança em lote.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort EFFORT]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Execute npx @openai/codex-security bulk-scan sem argumentos para selecionar os repositórios interativamente. Esse fluxo exige login na CLI do GitHub.

Para a descoberta interativa, selecione um modelo do Codex disponível para sua conta:

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

Se você já preparou uma lista de repositórios, forneça o CSV e --output-dir:

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

O CSV precisa conter as colunas id, repository e revision. As revisões precisam ser hashes completos de commits. As colunas opcionais scope, mode e prompt configuram cada repositório individualmente:

id,repository,revision,scope,mode,prompt
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Revise os limites de autorização.

Use --knowledge-base PATH para compartilhar documentos de segurança entre todos os repositórios. Use --scan-prompt-file FILE para adicionar instruções de varredura compartilhadas. A coluna prompt do CSV acrescenta as instruções específicas do repositório após o prompt compartilhado. --post-scan-prompt-file FILE executa instruções complementares após cada varredura, inclusive as que retornam erros. Essas instruções não são executadas após um cancelamento nem quando uma varredura atinge seu limite de custo.

--workers limita o número de varreduras simultâneas de repositórios e tem o valor padrão 4. O padrão de --mode é standard, e o de --max-attempts é 1. Defina --max-attempts para tentar novamente em caso de erro no repositório ou na varredura. Exclusões e notas de acompanhamento não acionam novas tentativas de varreduras concluídas. Falhas de execução que persistem retornam 2. Varreduras concluídas que violam a política de gravidade retornam 1.

Execute o mesmo comando novamente para retomar a campanha a partir de um diretório de saída existente. A CLI pula as varreduras concluídas. Use --recover para repetir tentativas que falharam ou foram interrompidas na campanha correspondente.

Para campanhas em contêineres, consulte Executar varreduras em lote no Docker.

codex-security scans

Localizar varreduras salvas

Liste as varreduras salvas para o diretório atual:

npx @openai/codex-security scans

Liste as varreduras de outro repositório:

npx @openai/codex-security scans list /path/to/repository

Localize varreduras armazenadas em um diretório de saída específico:

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

Inspecionar ou repetir uma varredura

Exiba os resultados e a configuração de uma varredura salva:

npx @openai/codex-security scans show SCAN_ID

Adicione --show-linked-findings para incluir vínculos com achados de varreduras anteriores.

Execute novamente uma varredura salva:

npx @openai/codex-security scans rerun SCAN_ID

A nova execução cria uma varredura usando as configurações e o método de autenticação salvos, a cópia de trabalho atual e os arquivos de contexto atuais. Ela não recarrega os arquivos de configuração do projeto nem reutiliza credenciais salvas. Se a execução original usou prompts de varredura ou de validação personalizada, forneça esses arquivos novamente com --scan-prompt-file e --validation-prompt-file.

A nova execução exige a versão do plugin registrada na varredura original e é interrompida se a versão instalada for diferente.

Inspecionar logs de varreduras salvas

Leia o registro completo dos eventos de sessão salvos para uma varredura e seus processos. Esses logs não ocultam dados sensíveis e podem conter código-fonte ou credenciais. Revise-os antes de compartilhá-los:

npx @openai/codex-security scans logs SCAN_ID

Adicione --json para obter uma saída estruturada.

Associar e comparar achados

Compare duas varreduras para identificar achados novos, persistentes, reabertos, não observados, resolvidos e de estado desconhecido:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

A comparação associa automaticamente os achados que têm a mesma causa raiz e reutiliza as correspondências salvas. Para salvar correspondências explicitamente, use scans match:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

O estado de um achado é desconhecido quando seu caminho foi excluído ou sua correspondência é incerta. Se a varredura posterior não o encontrar no código examinado, ele será classificado como não observado. Um achado só é considerado resolvido quando é explicitamente encerrado como já corrigido. Adicione --force a match quando precisar recalcular uma correspondência existente.

Para associar achados de todas as varreduras concluídas do repositório atual, inclusive as executadas em outras cópias de trabalho:

npx @openai/codex-security scans match --all

Os resultados podem variar mesmo que você repita a varredura com a mesma configuração. A associação e a comparação acompanham as mudanças, mas não tornam os resultados determinísticos nem comprovam que uma vulnerabilidade deixou de existir. Use validate para verificar novamente, no código atual, um achado crítico para a segurança.

codex-security findings

Liste os achados em aberto nas varreduras do repositório atual:

npx @openai/codex-security findings list

Passe o caminho de um repositório para inspecionar outra cópia de trabalho:

npx @openai/codex-security findings list /path/to/repository

Adicione --json para obter uma saída estruturada. A lista identifica os achados observados na varredura mais recente e os achados anteriores que essa varredura não confirmou.

Os achados anteriores permanecem em aberto até serem resolvidos ou descartados. Sua ausência na varredura mais recente não comprova que foram corrigidos.

Para registrar um achado revisado como falso positivo:

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

Inspecione a varredura salva para identificar a ocorrência do achado:

npx @openai/codex-security scans show SCAN_ID

Registre uma explicação específica para o falso positivo:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

A justificativa não pode ficar vazia. O Codex Security salva a decisão para o repositório e a fornece como contexto para varreduras futuras. Cada varredura reavalia de forma independente o código-fonte atual, os controles e a possibilidade de alcançar o código afetado. Uma decisão anterior não exclui regras, caminhos ou classes de vulnerabilidade das varreduras.

codex-security export

Exporte achados salvos ou um modelo de ameaças sem iniciar o Codex nem carregar credenciais. A exportação de achados em CSV, JSON, SARIF ou CSV do ServiceNow AVIT exige uma varredura concluída e selada. Modelos de ameaças usam Markdown.

usage: codex-security export [scan_dir | --scan SCAN_ID]
                             [--artifact {findings,threat-model}]
                             [--export-format {csv,json,sarif,md,servicenow-avit}]
                             [--avit-template FILE]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH]

Omita scan_dir e --scan para usar a varredura concluída mais recente do repositório atual. Caso contrário, forneça um diretório de resultados salvos ou selecione uma varredura pelo ID ou por um prefixo único de pelo menos oito caracteres com --scan. Não é possível combinar esses seletores.

--source-root funciona apenas na exportação de achados em SARIF. O JSON preserva o documento selado de achados. O CSV contém colunas portáveis de achados e não inclui o estado da triagem local na bancada de análise.

Sem --output, a CLI grava o SARIF em results.sarif, o JSON em findings.json, o CSV em findings.csv, o CSV do ServiceNow AVIT em servicenow-avit.csv e o Markdown em threatmodel.md, todos no diretório de trabalho atual. As exportações podem conter trechos de código-fonte e detalhes de vulnerabilidades. Passe --output com um caminho privado fora da cópia de trabalho. Ao executar o comando fora do repositório, especifique também um diretório de resultados ou --scan.

Exportar achados

Grave a saída SARIF em um arquivo:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

Envie a saída SARIF para stdout:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

Exporte os achados em JSON:

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

Exporte os achados em CSV:

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

Exportar achados para o ServiceNow

O ServiceNow exige a função Ethical Hacker (sn_vul.app_pen_tester). Acesse All > Manual AVIT Ingestion > Upload File UI e baixe o modelo de CSV. Mantenha os cabeçalhos originais e exatamente uma linha de dados. Use o nome exato do aplicativo no ServiceNow. Preencha a finalidade, os tipos de dados sensíveis, os programas de conformidade, as tecnologias usadas, a equipe do aplicativo e as URLs a testar. Preencha Requested by, Assigned to e Assignment group. Deixe em branco os campos dos achados. Salve o modelo como app.csv em um diretório privado fora do repositório examinado. Reutilize-o nas varreduras do mesmo aplicativo.

No repositório examinado, exporte os achados mais recentes usando esse modelo. Mantenha o arquivo de saída no diretório privado também:

npx @openai/codex-security export --scan latest \
  --export-format servicenow-avit \
  --avit-template /path/outside/repository/exports/app.csv \
  --output /path/outside/repository/exports/findings-avit.csv

A CLI grava uma linha por achado e preenche Steps to reproduce com o caminho de ataque registrado, quando disponível. Revise essas etapas e preencha os campos em branco no CSV exportado. Volte a Upload File UI, selecione Import File, envie o CSV e selecione Submit. Cada envio cria um novo formulário de teste de penetração para o aplicativo. Consulte as instruções de envio do ServiceNow.

Exportar um modelo de ameaças salvo

Exporte para stdout o modelo de ameaças salvo na varredura concluída mais recente sem fazer outra chamada ao modelo:

npx @openai/codex-security export --artifact threat-model --output -

Ou selecione uma varredura e salve seu modelo de ameaças em um arquivo:

npx @openai/codex-security export --scan SCAN_ID \
  --artifact threat-model \
  --output /path/outside/repository/exports/threatmodel.md

Se você selecionar uma varredura pelo ID ou pelo diretório, também poderá exportar um modelo salvo de uma varredura inacabada ou que tenha falhado. Se nenhum modelo tiver sido salvo, o comando retornará um erro. Revise todo conteúdo identificado no documento como provisório ou recuperado antes de reutilizá-lo.

Para usar o modelo exportado como contexto em outra varredura, passe o caminho dele para --knowledge-base.

codex-security publish scan

Publique achados selecionados de uma varredura concluída no Linear ou em um serviço personalizado de achados. As opções a seguir se aplicam à publicação no Linear:

usage: codex-security publish scan [SCAN_DIR] --to linear
                                   [--linear-team TEAM_ID]
                                   [--project PROJECT_ID]
                                   [--linear-api-key KEY]
                                   [--linear-assignee EMAIL_OR_USER_ID]
                                   [--dry-run] [--json]

SCAN_DIR precisa conter uma varredura concluída e selada. Em um terminal interativo, omita esse argumento para selecionar uma varredura concluída no histórico local. Para criar issues, a varredura e seus achados também precisam constar no histórico local de varreduras. A simulação valida os artefatos selados sem verificar se estão nesse histórico.

Use --scan SCAN_ID ou --scan latest no lugar de um diretório para selecionar uma varredura salva. Repita --finding-id ID para selecionar um subconjunto de achados para o Linear. Use publish check SCAN_DIR com as opções de destino do Linear para verificar os artefatos e as publicações registradas. Com uma chave de API, o comando também verifica a autenticação e o acesso ao destino. Para o aplicativo conectado, o acesso é informado como not-checked.

Cada execução fora do modo de simulação tenta criar uma nova issue para cada achado selecionado, a menos que --skip-existing encontre um registro de publicação bem-sucedida para essa ocorrência, equipe e projeto. A opção não inspeciona issues remotas nem abrange publicações sem registro ou simultâneas. Se a publicação de alguns achados falhar, o comando preservará as issues criadas com sucesso e retornará o código de saída 2. Com --json, revise os resultados created e failed antes de tentar novamente para evitar duplicatas.

Confira os dados das issues antes de publicar:

npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --dry-run \
  --json

Publicar com o aplicativo conectado do Linear

Sem uma chave de API do Linear, o comando inicia o Codex usando a configuração existente e o aplicativo conectado do Linear. Faça login e conecte o Linear à sua conta do Codex antes de publicar:

npx @openai/codex-security login
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --project PROJECT_ID

Publicar com uma chave de API do Linear

Ao fornecer --linear-api-key ou CODEX_SECURITY_LINEAR_API_KEY, você publica diretamente pela API do Linear sem iniciar o Codex. Na publicação direta, as issues ficam sem responsável, a menos que você indique alguém:

export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --linear-assignee teammate@example.com

Os valores da linha de comando têm precedência sobre as variáveis de ambiente correspondentes. Para chaves de API, prefira CODEX_SECURITY_LINEAR_API_KEY a --linear-api-key, pois argumentos da linha de comando podem aparecer no histórico do shell e nas listas de processos.

Publicar em um serviço personalizado de achados

Para usar um serviço de achados existente, selecione explicitamente a URL dele:

npx @openai/codex-security publish scan --scan latest \
  --to custom --findings-url http://localhost:3000

A publicação envia os achados selados completos e o ID do repositório alvo. Os achados podem incluir trechos de código-fonte, evidências e detalhes de vulnerabilidades. Use HTTPS para serviços fora da sua máquina local e adicione --dry-run --json para inspecionar os dados antes de enviá-los.

A CLI não envia credenciais de modelos para serviços personalizados. Faça a autenticação necessária fora da CLI. Consulte o guia do serviço de achados para obter detalhes sobre a implantação e o protocolo.

codex-security publish findings

Use --to local para salvar os achados importados na sua máquina. Com --to cloud, até a prévia entra em contato com o serviço. Esse destino exige um login do ChatGPT armazenado em arquivo e o ID ou a URL de um repositório autorizado que já tenha um ambiente de nuvem. A importação para a Nuvem pode retornar um resultado parcial se o serviço rejeitar registros individuais. Consulte o guia de importação do GitHub para conhecer os dois fluxos.

Para importar alertas do Dependabot para uma cópia de trabalho local, você precisa de uma exportação salva do mesmo repositório do GitHub. Siga o guia de exportação do Dependabot para salvar todas as páginas fora da cópia de trabalho usando um token com permissão de leitura dos alertas do Dependabot.

Acrescente echo "$out/dependabot.jsonl" ao final do script de exportação antes de executá-lo. Em um novo shell, use o caminho exibido pelo script para visualizar a prévia do arquivo. Substitua ./project pelo caminho da sua cópia de trabalho e OWNER/REPO pelo seu repositório. Se a cópia de trabalho tiver repositórios remotos acessíveis pela rede, um deles deverá corresponder ao repositório dos alertas. Caso contrário, verifique se a exportação pertence à cópia de trabalho.

export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
npx @openai/codex-security publish findings /path/to/dependabot.jsonl \
  --to local --repository ./project --provider github \
  --source-key github.com/OWNER/REPO/dependabot --dry-run --format json

Verifique o destino e as exclusões na prévia. A simulação retorna 0 mesmo que liste alertas excluídos. Para salvar os alertas aceitos, execute o comando novamente sem --dry-run e confirme, ou substitua --dry-run por --yes. Se a importação excluir algum alerta, ela salvará os alertas aceitos e retornará 1. Consulte os alertas armazenados no mesmo shell.

npx @openai/codex-security findings imported ./project --format json

Os alertas importados começam com o status de avaliação not_assessed. Uma nova importação com a mesma chave de origem atualiza os registros armazenados dos alertas presentes no arquivo. Os alertas omitidos mantêm o estado da última importação. Alertas associados ao mesmo aviso de segurança permanecem em registros separados.

Comandos de revisão de achados

Estes comandos operam sobre achados existentes:

verify-fix retorna 2 se alguma verificação for inconclusiva ou falhar. Caso contrário, retorna 1 se alguma vulnerabilidade persistir ou 0 se todos os achados tiverem sido corrigidos. Consulte --help de cada comando para ver os seletores, as configurações de modelo e as opções de saída.

codex-security feedback

Envie à OpenAI a descrição de um problema e receba um ID para compartilhar com o suporte:

npx @openai/codex-security feedback SCAN_ID \
  --reason "The scan stopped before it finished" --json

Sem um ID de varredura, o comando seleciona a varredura iniciada mais recentemente no repositório atual, mesmo que ainda esteja em execução ou tenha falhado. Se não houver nenhuma, envia um relato geral. Os relatos incluem a descrição, as versões e os IDs de varredura e de sessão selecionados. Por padrão, os logs ficam de fora. Adicione --include-logs apenas se puder compartilhar com a OpenAI o código-fonte, os prompts, os achados e a saída das ferramentas presentes nos logs.

codex-security validate e codex-security patch

Avalie possíveis achados com base no código-fonte do repositório atual:

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

Gere uma correção com a habilidade de remediação incluída no pacote:

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

Cada argumento posicional aceita um texto literal ou o caminho de um arquivo. Essas entradas usam o diretório atual. validate usa um sandbox somente leitura para avaliar as evidências no código-fonte. O comando não compila o alvo, não executa código do aplicativo, testes ou provas de conceito e não contata serviços. As varreduras padrão, profundas e de diferenças mantêm seus próprios fluxos de validação. O comando patch continua corrigindo e verificando os achados.

Use validate para reavaliar um achado após uma correção ou quando uma varredura posterior deixar de relatá-lo. A comparação de varreduras por si só não comprova que a correção funcionou. Para obter evidências em tempo de execução, reproduza o problema em uma etapa separada.

O comando envia a avaliação para stdout sem salvar um relatório. Redirecione stdout para armazená-la:

npx @openai/codex-security validate findings.json > /path/outside/repository/assessment.md

Adicione --context TEXT, --context-file FILE ou repita --knowledge-base PATH para fornecer contexto de segurança. Para obter uma saída estruturada, use --output-schema FILE com um JSON Schema autocontido compatível com o modelo e o provedor. A CLI verifica se o JSON gerado está de acordo com o schema antes de gravá-lo em stdout. Se a saída for inválida, a CLI encerrará a execução com 2 sem gravar a avaliação. validate não aceita --json.

Use --effort para selecionar o esforço de raciocínio em qualquer um dos dois comandos:

npx @openai/codex-security validate "Possible SQL injection" --effort high

Corrigir achados após uma varredura

Use scan --patch para corrigir achados após a conclusão da varredura. O nível mínimo de gravidade padrão é low. Este comando seleciona achados de gravidade alta e crítica:

npx @openai/codex-security scan . --patch --patch-severity high --json

Achados cuja correção foi verificada ou que já estavam corrigidos não acionam --fail-on-severity.

Corrigir achados salvos

Passe o ID de um achado ou de uma ocorrência para aplicar a correção no repositório original, ou selecione achados de uma varredura salva:

npx @openai/codex-security patch OCCURRENCE_ID
npx @openai/codex-security patch --scan SCAN_ID --severity high --json
npx @openai/codex-security patch --scan latest --severity medium

--scan latest seleciona a varredura concluída mais recente do repositório atual. patch aceita --json para achados salvos, textos literais e arquivos de entrada.

Adicione --create-pr para criar um commit apenas com os arquivos de correção verificados e abrir um pull request no GitHub ou um merge request no GitLab como rascunho, usando a CLI correspondente:

npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr

Se o push ou a criação do pull request falhar, execute o comando patch --resume-pr BRANCH exibido, a partir do mesmo repositório, para tentar novamente.

Aplicar correções para issues do Linear

Defina CODEX_SECURITY_LINEAR_API_KEY ou LINEAR_API_KEY para usar uma chave de API pessoal, ou LINEAR_ACCESS_TOKEN para usar um token OAuth. Prefira uma variável de ambiente a --linear-api-key KEY para evitar que a chave apareça no histórico do shell.

Importe uma issue pelo ID ou pela URL. Repita --linear-issue para selecionar mais de uma issue:

npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124

Use --linear-project para selecionar as issues abertas de um projeto. Adicione --linear-filter para restringir a seleção:

npx @openai/codex-security patch --linear-project "Security backlog" \
  --linear-filter '{"labels":{"name":{"eq":"security"}}}'

A CLI exclui issues concluídas e canceladas, a menos que o filtro defina state. Ela não altera as issues no Linear.

codex-security login, logout e info

Faça login interativamente:

npx @openai/codex-security login

Use a autenticação por dispositivo em uma máquina remota ou sem interface interativa:

npx @openai/codex-security login --device-auth

Verifique o status do login atual:

npx @openai/codex-security login status

Remova as credenciais de login armazenadas:

npx @openai/codex-security logout

Armazene uma chave de API passando-a por stdin:

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

Armazene um token de acesso empresarial:

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

Consulte os metadados somente leitura do SDK e do plugin incluído no pacote:

npx @openai/codex-security info --json

Interpretar a saída da varredura

Por padrão, as varreduras enviam o progresso, os resumos de conclusão e os erros para stderr sem gravar o resultado completo em stdout. Use --json, --format ou --full-output para enviar os resultados estruturados da varredura para stdout.

Em terminais interativos, um painel mostra em tempo real a fase atual da varredura, o inventário de arquivos, a atividade, o uso de tokens e o custo estimado. Em CI e na saída redirecionada, o progresso aparece em texto simples. Adicione --headless para exibir o progresso em texto simples em um terminal interativo:

npx @openai/codex-security scan . --headless

O painel também mostra detalhes da sessão em tempo real. Esses detalhes não ocultam dados sensíveis e podem conter código-fonte ou credenciais. Revise-os antes de compartilhá-los.

Diagnósticos detalhados

Adicione --verbose para enviar diagnósticos de ciclo de vida, autenticação, progresso e custo para stderr:

npx @openai/codex-security scan . --verbose

Defina CODEX_SECURITY_LOG_LEVEL=debug para habilitar os mesmos diagnósticos sem usar a opção na linha de comando. LOG_LEVEL=debug também habilita os diagnósticos quando CODEX_SECURITY_LOG_LEVEL não está definida ou está em branco.

O Codex Security preserva o texto dos diagnósticos. Eles podem conter código-fonte ou credenciais. Revise-os antes de compartilhá-los.

Resumo de conclusão

Ao terminar, a varredura envia para stderr o número de achados em aberto no repositório, a distribuição por gravidade, o tempo decorrido, o caminho do relatório e o diretório de resultados. Também informa o uso de tokens, quando disponível, e o custo estimado quando você define --show-cost ou --max-cost. Exemplo:

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  SCOPE     repository: .
  ELAPSED   1s
  RESULTS   /path/to/scan

Os achados informativos entram no total do resumo. As políticas de gravidade avaliam apenas os achados critical, high, medium e low da varredura atual. Os achados anteriores incluídos no total do repositório ficam fora dessa avaliação.

Saída JSON

scan --json grava um único documento JSON em stdout. Consulte manifest.scan para verificar o status e o escopo, e findings para ver os achados da varredura atual. Quando disponível, repositoryFindings inclui esses achados e os achados anteriores ainda em aberto. review.excludedPaths lista os padrões de caminho que a varredura registrou como excluídos da revisão. scanDir, reportPath e artifactsDir apontam para os resultados salvos.

threatModel contém o modelo de ameaças salvo como dados estruturados ou Markdown. threatModelPath aponta para o documento salvo. Qualquer um dos dois pode ser null. Mesmo que a gravação do documento falhe, o modelo ainda pode ser exportado.

Ao aplicar correções, a saída JSON também inclui os resultados das correções e o pull request, caso tenha sido criado.

O progresso, os resumos de conclusão, os avisos de arquivamento e os diagnósticos continuam em stderr. Uma varredura concluída exibe o resultado JSON mesmo quando a política de gravidade retorna o código de saída 1.

Sempre verifique o código de saída do processo, mesmo que o JSON seja interpretado com sucesso. Quando não há resultados de varredura para retornar, falhas de execução produzem um erro estruturado com status, code e message ao usar --json, --format json ou --format jsonl. Quando há resultados válidos preservados, a saída pode conter o resultado normal da varredura e warnings, por exemplo, após uma mudança no alvo. Com --json, --format json ou --format jsonl, adicione --full-output para receber um objeto com ok: false, o erro em error e os resultados selados válidos que tenham sido preservados em data. Os outros formatos relatam falhas apenas em stderr, mesmo com --full-output. Essas regras também se aplicam a scans rerun e scans resume.

Artefatos da varredura

Uma varredura concluída mantém o relatório para leitura e os artefatos estruturados no mesmo diretório. O manifesto selado registra os hashes dos artefatos para que seja possível verificar posteriormente se os arquivos foram alterados:

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── report.md
├── threatmodel.md          # when available
├── artifacts/
└── exports/
    └── results.sarif       # when produced

Os arquivos estruturados têm finalidades distintas:

Conclusão e cobertura da revisão

Consulte scan.status em scan-manifest.json para verificar se a varredura foi concluída. Consulte scan.scope para ver o escopo configurado e scan.review.excludedPaths para ver as exclusões que a varredura registrou durante a revisão. As comparações de varreduras também usam essas exclusões. Mesmo em uma varredura concluída, alguns arquivos dentro do escopo podem não ter sido revisados.

Se houver trabalho pendente, inspecione as evidências disponíveis com scans show SCAN_ID e scans logs SCAN_ID. Uma varredura profunda interrompida pode continuar com scans resume SCAN_ID se atender aos requisitos para retomada. Para iniciar uma nova revisão com as configurações salvas, use scans rerun SCAN_ID quando houver instruções de execução registradas. Varreduras feitas por plugins podem não ter instruções que permitam repetir a execução. Nesse caso, inicie uma nova varredura com os caminhos e o contexto desejados.

Códigos de saída e sinais

A CLI usa os seguintes códigos de saída:

Lacunas na cobertura não alteram o código de saída de uma varredura concluída nem dispensam a aplicação da política de gravidade. O código de saída 0 não indica que todos os arquivos foram revisados. Quando você solicita saída estruturada, as varreduras concluídas e as publicações parciais gravam os resultados disponíveis em stdout. Após uma interrupção ou um erro de execução, a CLI exibe o local de qualquer saída parcial.

Permissões de varredura local

As varreduras da CLI e do SDK são executadas com suas permissões locais do sistema operacional. O perfil da varredura permite ler o sistema de arquivos local e gravar nos diretórios raiz do espaço de trabalho. As solicitações de aprovação de execução passam por revisão automática, que pode conceder permissões adicionais para uma operação. Use --codex 'approval_policy="never"' ou defina codexOverrides.approval_policy: "never" no SDK para negar solicitações de permissão. As restrições do host e da rede continuam valendo.

Os processos de varredura e da bancada de análise podem herdar seu ambiente, inclusive tokens de API e credenciais de nuvem sem relação com a varredura. Remova as credenciais desnecessárias antes de iniciar a varredura.

Autenticação e pré-requisitos

Defina OPENAI_API_KEY ou CODEX_API_KEY, faça login com npx @openai/codex-security login ou use um login existente do Codex armazenado em arquivo. Para OpenRouter ou Fireworks, defina a chave de API do provedor e selecione um modelo. Para Amazon Bedrock, use uma chave de API do Bedrock ou a cadeia padrão de credenciais da AWS.

Para saber como selecionar as credenciais, consulte Selecionar a autenticação da varredura.

Em CI, restrinja a chave de API à etapa da varredura e use um fluxo de trabalho de confiança.

A CLI exige Node.js 24 ou 26, ou Node.js 22 a partir da versão 22.13.0. Varreduras, varreduras em lote, exportações, histórico de varreduras e achados salvos também exigem Python 3.10 ou posterior. O Python 3.10 também exige tomli. Use --python com scan, bulk-scan ou export, ou defina PYTHON para qualquer comando que dependa de Python.

Para ler ou retomar sessões compactadas do Codex (.jsonl.zst), use Node.js 22.15.0 ou posterior da série 22.x, ou Node.js 24 ou 26. Sessões em .jsonl sem compactação funcionam em todas as versões compatíveis do Node.js.

Continue com o guia de início rápido da CLI, o guia de varreduras em lote, as perguntas frequentes sobre a CLI, o guia de CI ou o guia do SDK para TypeScript.