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 conclusões de 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 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 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

Selecione o Amazon Bedrock com --provider amazon-bedrock e especifique um modelo Bedrock explícito 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, do início de sessão do ChatGPT ou de uma API key da OpenAI. 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 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 interrompe os processos de trabalho inacabados, conserva os resultados das análises concluídas e agrega-os no relatório final. Se nenhum processo de trabalho concluir a revisão do código-fonte, a análise regista cobertura parcial e devolve o código de saída 2.

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 análises com cobertura incompleta ou erros:

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 custos é uma estimativa, não um limite rígido de despesas. Os pedidos já em curso podem terminar ligeiramente acima do limite. Se uma análise profunda atingir o limite depois de o Codex Security agregar os resultados concluídos dos processos de trabalho, a CLI sela os resultados disponíveis, marca a cobertura como partial e devolve o código de saída 2. Caso contrário, devolve 2 e deixa no disco qualquer saída parcial 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 esforço de raciocínio diferentes sem escrever TOML:

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

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-5.6-terra"'

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

Detete 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 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 esforço de raciocínio durante a deteção 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 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 CSV prompt adiciona instruções específicas do repositório depois desse pedido partilhado. --post-scan-prompt-file FILE executa instruções de seguimento após cada análise, incluindo análises com cobertura incompleta ou erros. Não é executado após um cancelamento nem quando uma análise atinge o respetivo limite de custos.

--workers limita as análises simultâneas de repositórios e utiliza 4 por predefinição. --mode utiliza standard por predefinição, e --max-attempts utiliza 1 por predefinição. Defina --max-attempts para repetir erros de repositório ou de análise. As análises concluídas com cobertura incompleta não são repetidas. Os respetivos resultados permanecem disponíveis e o comando devolve o código de saída 2.

Execute novamente o mesmo comando para retomar a partir de um diretório de saída existente. A CLI ignora análises concluídas, incluindo análises com cobertura incompleta.

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 um resultado formatado para máquinas com informação completa.

Fazer correspondência e comparar resultados

Compare duas análises para encontrar resultados novos, persistentes, reabertos, 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 resultado é desconhecido quando a análise posterior tem cobertura incompleta ou não abrange a localização original do resultado. 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.

Tenha em atenção que os resultados anteriores permanecem abertos até serem resolvidos ou rejeitados (a ausência na análise mais recente não é interpretada como prova de 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 competência 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 servidor MCP, 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 no stderr a contagem de resultados em aberto do repositório, a discriminaçã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 disponíveis:

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  COVERAGE  complete
  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 permanecem no stderr. Uma análise concluída continua a apresentar o resultado JSON completo quando uma política de gravidade devolve a saída 1 ou quando uma cobertura incompleta devolve a saída 2.

Artefactos da análise

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

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

Os ficheiros estruturados têm finalidades diferentes:

A completude da cobertura tem três valores:

• complete: A análise regista 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 prova para uma decisão de segurança.

Códigos e sinais de saída

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 e as publicações parciais continuam a escrever os resultados disponíveis no stdout. A CLI apresenta a localização de qualquer saída parcial após uma interrupção ou erro do ambiente 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 ambiente de trabalho podem herdar o seu ambiente, incluindo tokens de API e credenciais de serviços de nuvem não relacionados. Analise apenas repositórios em que confia e que tem autorização para avaliar, e forneça apenas as credenciais necessárias à 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 22 (22.13.0 ou posterior), 24 ou 26. As análises, análises em massa, exportações, histórico de análises e resultados guardados 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|-