Referência da CLI do Codex Security

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

Execute a CLI com npx @openai/codex-security.

Descriçã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 apresenta 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.

Detetar comandos e ligar agentes

Apresente o manifesto de comandos legível por agentes:

npx @openai/codex-security --llms

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

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

Gere sugestões de preenchimento automático da shell para Bash:

npx @openai/codex-security completions bash

Substitua bash por zsh ou fish para essas shells.

Os resultados das análises suportam --format toon|json|yaml|jsonl e --full-output. Este --format ao nível da estrutura é 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 indica md, mas os resultados das análises não suportam saída Markdown.

Registe a CLI como MCP server:

npx @openai/codex-security mcp add

Sincronize as skills 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 continuam disponíveis apenas na CLI.

codex-security scan

Execute uma análise num repositório, em caminhos selecionados, em alterações confirmadas 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] [--scan-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-hours HOURS]
                           [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh,max}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--dry-run] [--headless] [--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 as credenciais automaticamente. 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 que credencial deve ser utilizada. As análises de CI, JSON e JSONL, bem como outras análises sem um terminal interativo, utilizam a API key do ambiente. As simulações não apresentam pedidos nem carregam credenciais.

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

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

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

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

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

Utilizar OpenRouter ou Fireworks

Selecione o OpenRouter com a respetiva API key e um modelo explícito:

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

Selecione o Fireworks com a respetiva API key e um modelo explícito:

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

Ambos os fornecedores também suportam bulk-scan.

Utilizar Amazon Bedrock

Utilize --provider amazon-bedrock e um ID de modelo Bedrock com scan ou bulk-scan. Depois de a AWS disponibilizar o acesso ao modelo, as análises utilizam credenciais AWS sem --auth, um início de sessão na OpenAI ou uma API key da OpenAI.

Daybreak Blue e Daybreak Red

Daybreak Blue e Daybreak Red requerem aprovação do Trusted Access for Cyber. Para solicitar acesso, submeta o pedido de acesso empresarial ou contacte a equipa responsável pela sua conta OpenAI. Após a aprovação, trabalhe com a equipa responsável pela sua conta AWS para disponibilizar o acesso ao modelo no Amazon Bedrock.

A aprovação do Daybreak Red não inclui acesso ao GPT-5.6-Cyber. O GPT-5.6-Cyber requer uma aprovação separada do governo dos Estados Unidos (USG). Peça à equipa responsável pela sua conta OpenAI que solicite esta aprovação adicional antes de disponibilizar o GPT-5.6-Cyber no Amazon Bedrock. Consulte os requisitos de acesso ao Daybreak.

Para verificar a disponibilidade, consulte as fichas de modelo da AWS para Daybreak Blue e Daybreak Red.

Para executar uma análise com Daybreak Blue, substitua <aws-profile-name> por um perfil AWS que tenha acesso ao modelo Daybreak Blue:

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 executar uma análise com Daybreak Red, escolha um perfil AWS com acesso ao GPT-5.6-Cyber. Este pode ser diferente do perfil que utiliza para Daybreak Blue:

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

Também pode autenticar-se com AWS_BEARER_TOKEN_BEDROCK ou com a cadeia padrão de credenciais da AWS. As chaves de acesso temporárias requerem AWS_SESSION_TOKEN. Defina as credenciais e AWS_REGION na mesma shell ou tarefa de CI em que executa a análise.

Resultados locais e verificações de acesso

Os relatórios locais guardados, scans show e export funcionam sem credenciais da nuvem. O carregamento de resultados para o Codex Security Cloud requer um início de sessão separado no ChatGPT e acesso ao destino.

info e scan --dry-run não testam as credenciais da AWS nem o acesso aos modelos. Execute uma análise para verificar o acesso. Em caso de erros de autenticação da AWS ou de acesso negado, verifique as suas credenciais, a região e as permissões do modelo.

Estado da versão para Bedrock

@openai/codex-security@0.1.31 permite executar análises no Amazon Bedrock. Esta versão não fornece estimativas de custos nem suporta --max-cost para os IDs dos modelos Daybreak Blue e Daybreak Red indicados acima.

Verifique as versões do pacote instalado e do Codex incluído:

npx @openai/codex-security --version
npx @openai/codex-security info --json

Utilize npx @openai/codex-security scan --help para verificar as opções disponíveis na versão instalada.

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 profundo suporta alvos de repositório e de caminho.

As análises de diferenças e da árvore de trabalho requerem que o argumento do repositório seja a raiz da árvore de trabalho Git. As referências selecionadas têm de existir nessa cópia de trabalho.

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 confirmadas:

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 profunda do repositório:

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

Configurar análises profundas

Utilize estas opções com --mode deep para controlar a simultaneidade dos processos de trabalho e o tempo de execução:

--subagents aceita zero ou um número inteiro positivo. --max-time-hours aceita um número positivo não superior a 96. As restantes opções requerem um número inteiro positivo. Estas opções não estão disponíveis para análises padrão.

Por exemplo, utilize dois processos de trabalho, permita até dez execuções e interrompa a execução dos processos de trabalho após 1,5 horas:

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

Quando o limite de tempo expira, a análise para os processos de trabalho ainda não concluídos, conserva os resultados das análises concluídas e agrega-os no relatório final. Consulte o relatório para conhecer as áreas revistas e o trabalho adiado. O prazo, por si só, não determina o código de saída; este depende do estado de execução e da política de gravidade.

Defina predefinições persistentes em ~/.codex/codex-security/config.toml, ou em $CODEX_HOME/codex-security/config.toml quando definir CODEX_HOME:

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5

As opções da linha de comandos substituem estas predefinições. scan --workers controla os processos de trabalho independentes de análise padrão numa análise profunda; bulk-scan --workers controla as análises simultâneas de repositórios. Defina stop_after_consecutive_errors apenas no ficheiro TOML; a respetiva predefinição é 3.

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 os 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 guardados da análise.

Adicionar instruções de análise

Para adicionar instruções de análise, forneça um ficheiro de texto ou Markdown com --scan-prompt-file. Utilize --post-scan-prompt-file para executar instruções de seguimento na mesma sessão autenticada após análises bem-sucedidas e erros de análise:

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

Por exemplo, utilize o pedido da análise para se concentrar nos limites de autorização e peça às instruções de seguimento que escrevam um novo post-scan-summary.md no diretório da análise. Se o seguimento falhar, a CLI comunica um aviso e conserva a análise concluída. O seguimento não é executado após um cancelamento nem quando a análise atinge o respetivo limite de custos.

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 teto rígido de despesa. Os pedidos já em curso podem terminar ligeiramente acima do limite. Se uma análise aprofundada atingir o limite após o Codex Security agregar os resultados concluídos dos processos de trabalho, a CLI pode selar um resultado concluído e comunicar o aviso de orçamento. Devolve 0, ou 1 se os problemas detetados atingirem o limiar de gravidade configurado. Se não conseguir produzir um resultado concluído válido, devolve 2 e deixa no disco qualquer saída disponível.

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

O ambiente de trabalho conserva 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 do ambiente de trabalho.

O diretório de saída tem de ficar 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, incluindo documentos da base de conhecimentos, 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 opções do ambiente de execução quando precisar de um modelo, interpretador, plugin ou valor de configuração do Codex explícito.

Para selecionar um modelo e um esforço de raciocínio diferentes sem escrever TOML, escolha 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 estes exemplos:

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

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

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

codex-security install-hook

Instale uma verificação de segurança Git pré-confirmação no repositório atual:

npx @openai/codex-security install-hook

A verificação analisa alterações preparadas e não preparadas antes de cada confirmação e bloqueia resultados de gravidade elevada ou erros da análise. Respeita core.hooksPath e não substitui um script pré-confirmação existente. Defina um limiar de gravidade diferente quando necessário:

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

codex-security bulk-scan

Descubra e analise repositórios GitHub ou execute uma análise que pode ser retomada a partir de um CSV de repositórios.

Para obter um guia completo sobre deteção no GitHub, inventários CSV, resultados de campanhas e 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}]
                                [--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 repositórios interativamente. Este fluxo requer um início de sessão na GitHub CLI.

Para escolher um modelo e um esforço de raciocínio durante a descoberta interativa, utilize um modelo ao qual as suas credenciais permitam aceder. Consulte a disponibilidade do GPT-6.1 Sol ao iniciar sessão com o ChatGPT :

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

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 têm de ser hashes de confirmação completos. As colunas opcionais scope, mode e prompt configuram repositórios individuais:

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

Utilize --knowledge-base PATH para partilhar documentos de segurança entre todos os repositórios. Utilize --scan-prompt-file FILE para adicionar instruções de análise partilhadas; a coluna prompt do CSV acrescenta instruções específicas de cada repositório após esse prompt partilhado. --post-scan-prompt-file FILE executa instruções de seguimento após cada análise, incluindo erros de análise. Não é executado após um cancelamento ou quando uma análise atinge o seu limite de custo.

--workers limita as análises simultâneas de repositórios e tem o valor predefinido 4. --mode tem o valor predefinido standard e --max-attempts tem o valor predefinido 1. Defina --max-attempts para repetir tentativas após erros de repositório ou de análise. As análises concluídas não são repetidas por terem lacunas de cobertura ou violações da política de gravidade. Os respetivos resultados continuam disponíveis.

Execute novamente o mesmo comando para retomar a partir de um diretório de saída existente. A CLI ignora as análises concluídas, incluindo as que têm lacunas de cobertura.

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

codex-security scans

Encontrar análises guardadas

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

npx @openai/codex-security scans

Liste as análises de outro repositório:

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

Encontre 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

Adicione --show-linked-findings para incluir ligações de resultados de análises anteriores.

Execute novamente a análise na cópia de trabalho atual utilizando a configuração original:

npx @openai/codex-security scans rerun SCAN_ID

A nova execução requer a versão do plugin registada pela análise original. Se a versão instalada for diferente, o comando para em vez de executar com um plugin diferente.

Inspecionar registos de análises guardados

Leia todos os eventos de sessão guardados de uma análise e dos respetivos processos de trabalho. Estes registos não são expurgados e podem conter código-fonte ou credenciais, pelo que deve revê-los antes de os partilhar:

npx @openai/codex-security scans logs SCAN_ID

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

Fazer correspondência e comparar resultados

Compare duas análises para identificar problemas novos, persistentes, reabertos, não observados, resolvidos e desconhecidos:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

A comparação faz corresponder automaticamente resultados que partilham a mesma causa principal e reutiliza correspondências guardadas. Para guardar correspondências explicitamente, utilize scans match:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Um problema é desconhecido quando o seu caminho é excluído ou a correspondência é incerta. Se a análise posterior não o encontrar no código que analisou, é considerado não observado. Só é considerado resolvido um problema explicitamente encerrado como já corrigido. Adicione --force a match quando precisar de recalcular uma correspondência existente.

Para fazer corresponder todas as análises concluídas do repositório atual, incluindo análises de outras cópias de trabalho:

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

Os resultados das análises podem variar mesmo quando volta a executar 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 um resultado crítico para a segurança no código atual.

codex-security findings

Liste os resultados em aberto nas análises do repositório atual:

npx @openai/codex-security findings list

Passe um caminho de 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 resultados observados na análise mais recente e resultados anteriores que não foram confirmados nessa análise.

Os problemas detetados anteriormente permanecem em aberto até serem resolvidos ou descartados. A sua ausência na análise mais recente não demonstra que foram corrigidos.

Para registar como falso positivo um resultado revisto:

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

Inspecione a análise guardada para identificar a ocorrência do resultado:

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"

A justificação não pode estar vazia. 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, um caminho ou uma 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 interfere no ambiente de execução do Codex nem nas 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 de resultados selado. O CSV contém colunas de resultados portáteis e não inclui o estado de triagem do ambiente de trabalho local.

Sem --output, a CLI escreve SARIF em results.sarif, JSON em findings.json e 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 passe --output com um caminho privado fora da cópia de trabalho analisada.

Escreva 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 SARIF no stdout:

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

Exporte os resultados como JSON:

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

Exporte os resultados como CSV:

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

codex-security publish scan

Publique no Linear todos os resultados de uma análise concluída:

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 tem de conter uma análise concluída e selada. Omita-o num terminal interativo para selecionar uma análise concluída no histórico de análises local. A criação de problemas também requer que a análise e os respetivos resultados existam no histórico de análises local. Uma simulação valida os artefactos selados sem esta verificação de persistência.

Cada invocação que não seja uma simulação tenta criar um novo problema para cada resultado. Voltar a publicar a mesma análise não faz corresponder, atualizar nem reutilizar problemas existentes. Se alguns resultados falharem, o comando preserva os problemas criados com êxito e devolve o código de saída 2. Com --json, reveja os resultados created e failed antes de repetir a tentativa para evitar duplicados.

Pré-visualize os conteúdos dos problemas antes da publicação:

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

Publicar com a aplicação Linear ligada

Sem uma API key do Linear, o comando inicia o Codex utilizando a sua configuração existente e a aplicação Linear ligada. Inicie sessão e ligue o Linear à sua conta 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 API key do Linear

Fornecer --linear-api-key ou CODEX_SECURITY_LINEAR_API_KEY publica diretamente através da API do Linear e não inicia o Codex. A publicação direta deixa os problemas sem atribuição, a menos que selecione um responsável:

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 comandos substituem as variáveis de ambiente correspondentes. Para API keys, prefira CODEX_SECURITY_LINEAR_API_KEY a --linear-api-key, porque os argumentos da linha de comandos podem aparecer no histórico da shell e nas listas de processos.

codex-security validate e codex-security patch

Verifique se um resultado candidato é válido:

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

Gere uma correção com a skill de remediação incluída:

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

Cada argumento posicional aceita texto literal ou um caminho de ficheiro. Estas entradas utilizam o diretório atual. Utilize validate para voltar a verificar um resultado após uma correção ou quando uma análise posterior deixar de o comunicar. A simples comparação de análises não prova que uma correção funcionou.

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

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

Corrigir resultados após uma análise

Utilize scan --patch para corrigir resultados após uma análise completa. Isto requer @openai/codex-security 0.1.15 ou posterior. O limiar de gravidade predefinido é low. Este comando seleciona resultados elevados e críticos:

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

Os resultados verificados e já corrigidos não acionam --fail-on-severity.

Corrigir resultados guardados

Passe um ID de resultado ou ocorrência para corrigir o respetivo repositório original, ou selecione resultados de uma análise guardada:

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 análise concluída mais recente do repositório atual. Os comandos de resultados guardados suportam --json; as entradas de texto literal e de ficheiro não.

Adicione --create-pr para confirmar apenas os ficheiros de correção verificados e abrir um pedido de integração com a GitHub CLI:

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

Se o envio ou o pedido de integração falhar, execute o comando patch --resume-pr BRANCH apresentado no mesmo repositório para repetir a tentativa.

Corrigir problemas do Linear

Defina CODEX_SECURITY_LINEAR_API_KEY ou LINEAR_API_KEY para uma API key pessoal, ou LINEAR_ACCESS_TOKEN para um token OAuth. Prefira uma variável de ambiente a --linear-api-key KEY para manter a chave fora do histórico da shell.

Importe um problema por ID ou URL. Repita --linear-issue para selecionar mais do que um problema:

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

Utilize --linear-project para selecionar os problemas em aberto 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 problemas concluídos e cancelados, salvo se o filtro definir state. Não altera os problemas do Linear.

codex-security login, logout e info

Inicie sessão interativamente:

npx @openai/codex-security login

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

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

Verifique a sessão atual:

npx @openai/codex-security login status

Remova a sessão guardada:

npx @openai/codex-security logout

Guarde uma API key passando-a pelo 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 MCP server, info é o único comando disponível. As análises, exportações, publicações, inícios de sessão, validações e correções continuam disponíveis apenas na 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 o stderr sem escrever o resultado completo da análise no stdout. Solicite --json, --format ou --full-output para enviar resultados estruturados da análise para o stdout.

Os terminais interativos mostram um painel em direto com a fase atual da análise, os ficheiros revistos, a atividade, a utilização de tokens e o custo estimado. A CI e a saída redirecionada utilizam progresso em texto simples. Adicione --headless para utilizar progresso em texto simples num terminal interativo:

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

O painel também mostra detalhes da sessão em direto. Estes não são expurgados e podem conter código-fonte ou credenciais. Reveja-os antes de os partilhar.

Diagnósticos detalhados

Adicione --verbose para apresentar no stderr diagnósticos expurgados do ciclo de vida, autenticação, progresso e custos:

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

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

Resumo de conclusão

Uma análise concluída escreve em stderr o número de problemas em aberto no repositório, a distribuição por gravidade, o tempo decorrido, o caminho do relatório e o diretório de resultados. Inclui a utilização de tokens e o custo estimado quando disponíveis. Por exemplo:

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  ELAPSED   1s
  TOKENS    1,250 input, 200 cached, 30 output
  RESULTS   /path/to/scan

Os resultados informativos contam para o total do resumo. As políticas de gravidade avaliam apenas os resultados critical, high, medium e low da análise atual, não os resultados anteriores mostrados no total do repositório.

Saída JSON

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

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

Durante a correção, a saída JSON também inclui os resultados das correções e qualquer pedido de integração criado.

O progresso, os resumos de conclusão, os avisos de arquivamento e os erros continuam a ser enviados para stderr. Uma análise concluída continua a apresentar o resultado JSON completo quando uma política de gravidade devolve o código de saída 1.

Artefactos da análise

Uma análise concluída mantém o relatório legível e os artefactos estruturados juntos. O manifesto selado regista os hashes dos artefactos para que os leitores possam verificar posteriormente que esses ficheiros não foram alterados:

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

Os ficheiros estruturados têm finalidades diferentes:

Consulte scan.status em scan-manifest.json para obter o estado de execução: completed, failed, canceled ou interrupted. Os novos resultados não incluem coverage.completeness. Reveja as superfícies adiadas, as exclusões explícitas e as questões em aberto em coverage.json para compreender o que a análise reviu.

Códigos e sinais de saída

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

As lacunas de cobertura não alteram o código de saída de uma análise concluída nem contornam a sua política de gravidade. O código de saída 0 não significa que todos os ficheiros tenham sido revistos. Quando solicita saída estruturada, as análises concluídas e as publicações parciais continuam a escrever os resultados disponíveis em stdout. A CLI apresenta a localização de qualquer saída parcial após uma interrupção ou um erro de execução.

Permissões de análise local

As análises da CLI e do SDK são executadas com as suas permissões locais do sistema operativo. Cada análise utiliza o perfil do sistema de ficheiros codex_security_scan e define approvalPolicy como "never". O perfil permite ler o sistema de ficheiros local e escrever nas raízes da área de trabalho e no diretório de estado da análise selecionado. As análises não param para solicitar aprovação interativa.

As definições fornecidas através de --codex da CLI ou codexOverrides do SDK, incluindo approval_policy, sandbox_mode e as permissões do sistema de ficheiros, não podem substituir nem restringir estes controlos de análise. As restrições do anfitrião e da rede continuam a aplicar-se.

Os processos de análise e do workbench podem herdar o seu ambiente, incluindo tokens de API não relacionados e credenciais de serviços na nuvem. Remova as credenciais não relacionadas antes de iniciar uma análise.

Autenticação e pré-requisitos

Defina OPENAI_API_KEY ou CODEX_API_KEY, inicie sessão com npx @openai/codex-security login ou utilize uma sessão Codex existente armazenada num ficheiro. Para OpenRouter ou Fireworks, defina a API key do fornecedor e selecione um modelo. Para Amazon Bedrock, utilize uma API key do Bedrock ou a cadeia de credenciais AWS padrão.

Para obter informações sobre a seleção de credenciais, consulte Selecionar a autenticação da análise.

Para CI, limite a API key ao passo da análise e utilize um fluxo de trabalho de confiança.

A CLI requer Node.js 24 ou 26, ou Node.js 22 a partir da versão 22.13.0. As análises, as análises em lote, as exportações, o histórico de análises e as ocorrências guardadas também requerem Python 3.10 ou posterior. O Python 3.10 também requer tomli. Utilize --python com scan, bulk-scan ou export, ou defina PYTHON para qualquer comando baseado em Python.

Prossiga para 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|-