Perguntas frequentes sobre a CLI do Codex Security

Tire suas dúvidas sobre como executar varreduras em repositórios e gerenciar achados de segurança pelo terminal. Para instalar a CLI e executar a primeira varredura, consulte o guia de início rápido da CLI.

Varreduras em repositórios

Por que a varredura usa uma chave de API mesmo depois do login?

Quando o ambiente inclui OPENAI_API_KEY ou CODEX_API_KEY, tanto as varreduras sem terminal interativo quanto as varreduras com saída em JSON ou JSONL usam a chave de API do ambiente por padrão, mesmo após um login bem-sucedido pelo ChatGPT ou com um token de acesso. Nas varreduras interativas com saída de texto, a CLI pede que você escolha o método de autenticação quando o login pelo ChatGPT também está disponível. As execuções simuladas não pedem que você faça essa escolha nem carregam credenciais.

Para usar as credenciais salvas em uma varredura, selecione-as explicitamente:

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

Para exigir uma chave de API de OPENAI_API_KEY ou CODEX_API_KEY:

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

Para que a CLI use as credenciais salvas por padrão, execute unset OPENAI_API_KEY CODEX_API_KEY. Consulte todos os modos de autenticação disponíveis na referência da CLI.

É possível retomar uma varredura em lote interrompida?

Sim. Execute novamente o mesmo comando de varredura em lote com o CSV e o diretório de saída originais. O Codex Security pula os repositórios cuja varredura já foi concluída.

Adicione --max-attempts 3 para tentar novamente em caso de erros temporários no repositório ou na varredura:

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

As varreduras concluídas mantêm seus resultados e não são repetidas, mesmo que ainda haja lacunas na cobertura. Essas lacunas não fazem a campanha terminar com o código 2.

Achados e cobertura

Onde a equipe pode consultar os resultados de varreduras anteriores?

Liste as varreduras salvas do repositório:

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

Use o ID de uma varredura da lista para examinar os achados:

npx @openai/codex-security scans show SCAN_ID

Cada varredura concluída mantém juntos o relatório, os achados, o manifesto e os artefatos de apoio. Consulte Artefatos da varredura para ver como esses arquivos estão organizados.

Para examinar os eventos registrados da varredura e dos processos de execução, execute scans logs SCAN_ID. Esses logs não ocultam dados sensíveis e podem conter código-fonte ou credenciais.

E se a CLI não conseguir salvar o histórico de varreduras?

O Codex Security armazena o histórico de varreduras no banco de dados do ambiente de trabalho. Se não for possível gravar no diretório de estado padrão, escolha um diretório privado fora do repositório:

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

Como as varreduras distinguem achados novos dos já conhecidos?

Liste os achados em aberto de todas as varreduras de um repositório:

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

A lista indica quais achados a varredura mais recente confirmou e quais achados anteriores continuam em aberto, mas não foram confirmados nessa varredura.

Compare os achados das duas varreduras:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

A comparação associa automaticamente os achados pela causa raiz, reutiliza as correspondências salvas e identifica achados novos, persistentes, reabertos, não observados, resolvidos e de situação desconhecida. Quando uma varredura posterior não detecta um achado anterior no código que examinou, o achado é classificado como não observado. Ele só é considerado resolvido quando alguém o encerra explicitamente como já corrigido. A situação permanece desconhecida quando o caminho foi excluído ou a correspondência é incerta.

Como funciona o registro de falsos positivos?

Examine a varredura salva para encontrar o ID da ocorrência:

npx @openai/codex-security scans show SCAN_ID

Registre por que o achado não se aplica:

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

As próximas varreduras do mesmo repositório recebem essa explicação como contexto. Cada uma verifica de forma independente o código-fonte atual, os controles e se é possível atingir o trecho indicado. Descartar um achado não exclui nenhuma regra, caminho ou classe de vulnerabilidade das verificações.

Para saber mais sobre os comandos, consulte a referência de achados.

Por que varreduras repetidas podem retornar achados diferentes?

Varreduras assistidas por IA podem produzir resultados diferentes, mesmo com a mesma configuração. Comece executando novamente a varredura de referência:

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

A nova execução mantém a configuração original e exige a mesma versão do plugin. Se o plugin instalado tiver mudado, o comando interrompe a execução.

Compare a varredura de referência com a nova varredura:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Se a falta de contexto puder contribuir para essa variação, forneça as mesmas orientações de arquitetura e segurança para as varreduras. A correspondência entre achados permite reconhecer o mesmo problema em execuções diferentes, mas não torna as varreduras determinísticas. Verifique diretamente qualquer achado importante que deixe de aparecer.

Como a equipe pode confirmar que uma correção funcionou?

Verifique novamente o achado original na cópia de trabalho que contém as alterações. A partir dessa cópia, informe o relatório da varredura original e o problema que você quer validar:

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

Examine as evidências de que o caminho vulnerável foi bloqueado e de que o comportamento legítimo continua funcionando. Se disponível, execute o caso de reprodução original ou o teste de regressão. Se não for possível executar a verificação, registre no resultado o que ainda é incerto.

Uma comparação de varreduras pode mostrar como os achados mudaram, mas o simples fato de um achado deixar de aparecer não confirma a correção.

O que significa ter cobertura incompleta?

Em scan-manifest.json, consulte scan.status para verificar se a varredura terminou. O campo scan.scope registra o escopo configurado. O campo scan.review.excludedPaths lista os padrões de caminho que a varredura excluiu da análise. Se um manifesto antigo contiver o campo scan.coverageRef, abra o arquivo indicado nesse campo para consultar os detalhes da cobertura.

Lacunas na cobertura não alteram o código de saída de uma varredura concluída. O código de saída 0 não significa que todos os arquivos foram examinados. Se uma varredura posterior não abranger o caminho original de um achado, ela não poderá confirmar que o problema deixou de existir.

Automação e custos

Como funcionam os limites de tempo das varreduras aprofundadas?

Ao iniciar uma varredura aprofundada, defina um prazo para os processos de execução:

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

O padrão é 96 horas. Use qualquer valor positivo até 96, inclusive valores fracionários. Quando o prazo termina, o Codex Security interrompe os processos ainda em execução, preserva os resultados das varreduras padrão concluídas e os reúne no relatório final. Consulte o relatório para saber quais áreas foram examinadas e quais análises ficaram para depois. O prazo, por si só, não determina o código de saída. Esse código depende do status da execução e da política de severidade.

Para manter essa configuração entre execuções ou aplicá-la a campanhas em lote, defina max_time_hours na seção [deep_scan] da configuração de varreduras aprofundadas.

Como funcionam os limites de custo das varreduras?

Antes de iniciar a varredura, defina um limite de custo estimado em dólares americanos:

npx @openai/codex-security scan . --max-cost 5

O limite é uma estimativa. O gasto final pode ultrapassá-lo se já houver solicitações em andamento. Se uma varredura aprofundada atingir o limite depois que o Codex Security reunir os resultados dos processos concluídos, a CLI poderá salvar um relatório concluído com um aviso sobre o orçamento. Nesse caso, ela retorna 0 ou, se houver achados que atinjam o limiar de severidade configurado, 1. Se não conseguir produzir um resultado final válido, a CLI retorna 2 e preserva toda a saída disponível.

Para verificar pull requests no GitHub e executar varreduras agendadas em repositórios, use a GitHub Action do Codex Security. Na versão action-v0.3.0, uma varredura concluída indica que a análise configurada produziu um resultado válido. A política de severidade continua valendo mesmo quando há exclusões de escopo ou investigações adiadas. Consulte coverage.json para avaliar o escopo e as limitações da varredura. Para rejeitar também diffs vazios e execuções simuladas, exija que a saída scan-status da GitHub Action tenha o valor completed. Consulte Como escolher uma política de severidade.

Para outros provedores, consulte a visão geral de CI/CD. Para executar uma verificação antes de cada commit, use install-hook.