Referência da CLI do Codex Security

Utilize esta referência para verificar os comandos codex-security suportados, os parâmetros, os formatos de saída e o comportamento de saída. Para efetuar uma primeira análise guiada, comece pelo início rápido da CLI.

Instale o pacote publicado no seu projeto:

npm install @openai/codex-security

Invoque o pacote instalado como npx @openai/codex-security. Pode utilizar codex-security diretamente quando o executável estiver disponível no seu PATH.

Visão geral dos comandos

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

A CLI disponibiliza estes comandos:

A CLI também disponibiliza estes comandos de integração:

Liste todos os comandos disponíveis:

npx @openai/codex-security --help

Adicione --help a um comando para inspecionar os respetivos argumentos e opções:

npx @openai/codex-security scan --help

codex-security --version imprime a versão instalada e termina. codex-security info --json comunica as versões do SDK e do plugin incluído. Nenhum dos comandos requer Python.

Descobrir comandos e ligar agentes

Imprima o manifesto de comandos legível por agentes:

npx @openai/codex-security --llms

Inspecione o esquema dos argumentos de análise como JSON:

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

Gere conclusões da shell para Bash:

npx @openai/codex-security completions bash

Substitua bash por zsh ou fish para essas shells.

Os resultados da análise suportam --format toon|json|yaml|jsonl e --full-output. Este --format ao nível da plataforma é distinto de --export-format, que seleciona o formato de um artefacto exportado de uma análise concluída. A ajuda global dos comandos também apresenta md, mas os resultados das análises não suportam saída Markdown.

Registe a CLI como servidor MCP:

npx @openai/codex-security mcp add

Sincronize as competências do Codex Security com os seus agentes:

npx @openai/codex-security skills add

O MCP expõe apenas o comando de metadados só de leitura info. As análises, exportações, autenticação, validação e correção permanecem exclusivas da CLI.

codex-security scan

Execute uma análise num repositório, em caminhos selecionados, em alterações consolidadas ou na árvore de trabalho.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository utiliza por predefinição o diretório atual.

Selecionar a autenticação da análise

Utilize --auth auto, a predefinição, para selecionar automaticamente as credenciais. Quando estão disponíveis um início de sessão do ChatGPT e OPENAI_API_KEY ou CODEX_API_KEY, as análises interativas com saída de texto perguntam qual credencial deve ser utilizada. As análises de CI, JSON e JSONL, bem como outras análises sem terminal interativo, utilizam a API key do ambiente. As simulações não apresentam pedidos nem carregam credenciais.

Para utilizar as credenciais guardadas, transmita --auth chatgpt:

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

Para utilizar uma API key do ambiente, transmita --auth api-key:

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

Para tornar as credenciais guardadas na predefinição automática, execute unset OPENAI_API_KEY CODEX_API_KEY.

Utilizar o Amazon Bedrock

Selecione o Amazon Bedrock com --provider amazon-bedrock e especifique explicitamente um modelo Bedrock com --model:

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

Defina AWS_REGION e autentique-se com AWS_BEARER_TOKEN_BEDROCK, chaves de acesso AWS padrão, um perfil AWS, identidade Web, credenciais de contentor ou a cadeia de credenciais AWS predefinida. As análises Bedrock utilizam credenciais AWS em vez de --auth, um início de sessão do ChatGPT ou uma OpenAI API key. Tanto scan como bulk-scan suportam --provider.

Selecionar o alvo da análise

Escolha um tipo de alvo para cada análise.

--path, --diff e --working-tree são mutuamente exclusivos. --head requer --diff e --base requer --working-tree. O modo aprofundado suporta alvos de repositório e caminho.

As análises de diferenças e da árvore de trabalho exigem que o argumento do repositório seja a raiz da árvore de trabalho Git. As referências selecionadas devem existir nessa versão extraída.

Analise todo o repositório:

npx @openai/codex-security scan .

Analise caminhos selecionados:

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

Analise alterações consolidadas:

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

Analise alterações preparadas e não preparadas:

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

Execute uma revisão mais aprofundada do repositório:

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

Adicionar contexto de segurança

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

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

Os documentos suportados incluem ficheiros .md, .markdown, .txt, .pdf e .docx. A CLI pesquisa diretórios recursivamente, rejeita caminhos de entrada ligados, ignora entradas de diretório ligadas e mantém o conteúdo extraído dos documentos fora dos resultados de análise guardados.

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

Utilize estas opções para conservar artefactos, preservar resultados anteriores ou criar um resultado legível por máquina.

O limite de custo é uma estimativa, não um limite rígido de despesas. Os pedidos já em curso podem terminar acima do limite e os resultados parciais da análise permanecem disponíveis.

Quando omite --output-dir, os resultados são conservados em $CODEX_HOME/state/plugins/codex-security/scans/<repository>. CODEX_HOME utiliza ~/.codex por predefinição. Defina CODEX_SECURITY_STATE_DIR para manter os resultados em $CODEX_SECURITY_STATE_DIR/scans/<repository>. Estes diretórios podem conter excertos do código-fonte e detalhes de vulnerabilidades, por isso administre as respetivas permissões e retenção em conformidade.

A bancada de trabalho mantém o histórico de análises em $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Definir CODEX_SECURITY_STATE_DIR também move a base de dados da bancada de trabalho.

O diretório de saída deve estar fora do diretório analisado e de qualquer árvore de trabalho Git envolvente. Uma análise pode substituir um diretório de resultados existente com --archive-existing.

Para preservar 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 predefinição, as análises apenas produzem relatórios. 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 sem carregar credenciais, iniciar o Codex ou sondar o interpretador Python do plugin:

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

Configurar o ambiente de execução

Utilize as opções do ambiente de execução quando necessitar de um modelo, interpretador, plugin ou valor de configuração do Codex explícito.

Para selecionar um modelo e esforço de raciocínio diferentes sem escrever TOML:

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

Coloque entre aspas os valores de cadeia transmitidos através de --codex para que o analisador TOML receba uma cadeia:

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

codex-security install-hook

Instale uma verificação de segurança Git pre-commit no repositório atual:

npx @openai/codex-security install-hook

A verificação analisa as alterações preparadas e não preparadas antes de cada consolidação e bloqueia conclusões de gravidade elevada ou erros de análise. Respeita core.hooksPath e não substitui um script pre-commit existente. Defina um limiar de gravidade diferente quando necessário:

npx @openai/codex-security install-hook . --fail-on-severity medium

codex-security bulk-scan

Procure e analise repositórios GitHub ou execute uma análise retomável a partir de um CSV de repositórios:

Para obter um guia completo sobre a procura no GitHub, os inventários CSV, os resultados de campanhas e as análises em contentores, consulte Executar análises de segurança em massa.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Execute npx @openai/codex-security bulk-scan sem argumentos para selecionar repositórios interativamente. Este fluxo requer um início de sessão na GitHub CLI.

Para escolher um modelo e esforço de raciocínio durante a procura interativa:

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

Para uma lista de repositórios preparada, forneça um CSV e --output-dir:

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

O CSV requer as colunas id, repository e revision. As revisões devem ser hashes completos de consolidações. As colunas opcionais scope e mode configuram repositórios individuais:

id,repository,revision,scope,mode
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard

--workers limita as análises simultâneas e utiliza 4 por predefinição. --mode utiliza standard por predefinição e --max-attempts utiliza 1 por predefinição. Defina --max-attempts quando pretender repetir a operação num repositório após um erro. Execute novamente o mesmo comando para retomar uma análise em massa a partir do respetivo diretório de saída existente. A CLI apenas ignora repositórios concluídos quando os respetivos artefactos de resultados registados ainda estão presentes.

Para campanhas em contentores, consulte Executar análises em massa no Docker.

codex-security scans

Localizar análises guardadas

Liste as análises guardadas para o diretório atual:

npx @openai/codex-security scans

Liste as análises para um repositório diferente:

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

Localize análises armazenadas num diretório de saída específico:

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

Inspecionar ou repetir uma análise

Mostre os resultados e a configuração de uma análise guardada:

npx @openai/codex-security scans show SCAN_ID

Repita a análise na versão atualmente extraída utilizando a configuração original:

npx @openai/codex-security scans rerun SCAN_ID

Fazer corresponder e comparar conclusões

Faça corresponder as conclusões que partilham a mesma causa principal entre duas análises:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Compare as análises correspondentes para encontrar conclusões novas, persistentes, reabertas, resolvidas e desconhecidas:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Uma conclusão é desconhecida quando a análise posterior tem cobertura incompleta ou não abrange a localização original da conclusão. Adicione --force a match quando necessitar de recalcular uma correspondência existente.

Para fazer corresponder todas as análises concluídas do repositório atual, incluindo análises de outras versões extraídas:

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

Os resultados das análises podem variar mesmo quando repete a mesma configuração. A correspondência e a comparação acompanham as alterações; não tornam os resultados determinísticos nem provam que uma vulnerabilidade deixou de existir. Utilize validate para voltar a verificar uma conclusão crítica para a segurança no código atual.

codex-security findings

Registe uma conclusão revista como falso positivo:

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

Inspecione a análise guardada para identificar a ocorrência da conclusão:

npx @openai/codex-security scans show SCAN_ID

Registe 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"

O motivo não pode estar vazio. O Codex Security guarda a decisão para o repositório e fornece-a como contexto a análises futuras. Cada análise volta a verificar de forma independente o código-fonte, os controlos e a acessibilidade atuais. Uma decisão anterior não suprime uma regra, caminho ou classe de vulnerabilidade.

codex-security export

Exporte CSV, JSON ou SARIF de uma análise concluída e selada. A exportação valida os artefactos da análise antes de escrever a saída e não altera o ambiente de execução do Codex nem as credenciais.

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir é o diretório da análise concluída.

--source-root funciona apenas com --export-format sarif. O JSON preserva o documento selado de conclusões. O CSV contém colunas portáteis de conclusões e não inclui o estado local de triagem da bancada de trabalho.

Sem --output, a CLI escreve o SARIF em results.sarif, o JSON em findings.json e o CSV em findings.csv no diretório de trabalho atual. As exportações podem conter excertos do código-fonte e detalhes de vulnerabilidades. Execute o comando fora do repositório ou transmita --output com um caminho privado fora da versão extraída analisada.

Escreva o SARIF num ficheiro:

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

Escreva o SARIF em stdout:

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

Exporte as conclusões como JSON:

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

Exporte as conclusões como CSV:

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

codex-security validate e codex-security patch

Verifique se uma conclusão candidata é válida:

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

Gere uma correção com a competência de remediação incluída:

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

Cada argumento pode conter texto literal ou apontar para um ficheiro. Ambos os comandos funcionam no diretório atual. Utilize validate para voltar a verificar diretamente uma conclusão original após uma correção ou quando uma análise posterior deixar de a comunicar. Uma comparação de análises, por si só, não prova que uma correção funcionou. As ferramentas externas podem utilizar estes comandos sem reconstruir o analisador.

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

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

codex-security login, logout e info

Inicie sessão interativamente:

npx @openai/codex-security login

Utilize a autenticação de dispositivo numa máquina remota ou sem interface gráfica:

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

Verifique o início de sessão atual:

npx @openai/codex-security login status

Remova o início de sessão guardado:

npx @openai/codex-security logout

Guarde uma API key transmitindo-a através de stdin:

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

Guarde um token de acesso empresarial:

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

Inspecione os metadados só de leitura do SDK e do plugin incluído:

npx @openai/codex-security info --json

Quando expõe a CLI como servidor MCP, info é o único comando disponível. As análises, exportações, o início de sessão, a validação e a correção permanecem exclusivas da CLI.

Ler a saída da análise

Por predefinição, as análises enviam o progresso, os resumos de conclusão e os erros para stderr sem escrever o resultado completo da análise em stdout. Solicite --json, --format ou --full-output para enviar os resultados estruturados da análise para stdout.

Diagnósticos detalhados

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

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

Defina CODEX_SECURITY_LOG_LEVEL=debug para ativar os mesmos diagnósticos sem o parâmetro. LOG_LEVEL=debug também ativa os diagnósticos quando CODEX_SECURITY_LOG_LEVEL não está definido.

Estes controlos de registo aplicam-se apenas à CLI. As credenciais e os identificadores dos fornecedores permanecem expurgados e os resultados estruturados da análise permanecem em stdout.

Resumo de conclusão

Uma análise concluída escreve em stderr o número de conclusões, a distribuição por gravidade, a cobertura, o tempo decorrido, o caminho do relatório e o diretório dos resultados. Inclui a utilização de tokens e o custo estimado quando estão disponíveis:

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

As conclusões informativas contam para o total do resumo. As políticas de gravidade avaliam apenas as conclusões critical, high, medium e low.

Saída JSON

scan --json escreve um documento JSON completo em stdout. A sua estrutura de nível superior é:

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

O progresso, os resumos de conclusão, os avisos de arquivamento e os erros permanecem em stderr. Uma análise concluída continua a imprimir o resultado JSON completo quando uma política de gravidade devolve o código de saída 1 ou a cobertura incompleta devolve o código de saída 2.

Artefactos da análise

Uma análise concluída mantém o relatório legível e os artefactos estruturados em conjunto:

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

Os ficheiros estruturados cumprem funções diferentes:

A completude da cobertura tem três valores:

• complete: A análise regista uma cobertura completa para o âmbito selecionado.
• partial: A análise regista trabalho adiado ou outros limites de cobertura.
• unknown: A análise comunica a completude da cobertura como desconhecida.

Reveja as superfícies adiadas, as exclusões explícitas e as questões em aberto antes de utilizar a cobertura como evidência para uma decisão de segurança.

Códigos de saída e sinais

A CLI utiliza estes códigos de saída:

Qualquer análise com cobertura partial ou unknown devolve 2, mesmo sem uma política de gravidade. Quando solicita uma saída estruturada, as análises concluídas continuam a escrever os resultados disponíveis em stdout. A CLI imprime a localização de qualquer saída parcial após uma interrupção ou um erro do ambiente de execução.

Autenticação e pré-requisitos

Defina OPENAI_API_KEY ou CODEX_API_KEY, inicie sessão com npx @openai/codex-security login ou utilize um início de sessão existente do Codex baseado em ficheiros. Para o Amazon Bedrock, utilize uma API key do Bedrock ou a cadeia de credenciais AWS padrão.

Para a seleção de credenciais, consulte Selecionar a autenticação da análise.

Para CI, limite a API key à etapa de análise e utilize um fluxo de trabalho fidedigno.

A CLI requer Node.js 22 ou posterior. A execução de uma análise ou a exportação de conclusões também requer Python 3.10 ou posterior. O Python 3.10 também requer tomli. Utilize --python ou PYTHON para selecionar um interpretador quando a deteção automática não for adequada.

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

Aliases de texto simples

• --output FILE|-