Perguntas frequentes sobre a CLI do Codex Security

Encontre respostas a perguntas frequentes sobre a análise de repositórios e a gestão de resultados de segurança a partir do terminal. Para obter instruções de instalação e realizar uma primeira análise, comece pelo início rápido da CLI.

Análises de repositórios

Por que motivo uma análise utiliza uma API key após o início de sessão

Quando o seu ambiente inclui OPENAI_API_KEY ou CODEX_API_KEY, as análises sem um terminal interativo e as análises JSON e JSONL utilizam, por predefinição, a API key do ambiente, mesmo após um início de sessão bem-sucedido com o ChatGPT ou um token de acesso. As análises interativas com saída de texto pedem-lhe que escolha quando também está disponível um início de sessão com o ChatGPT. As simulações não apresentam pedidos nem carregam credenciais.

Para utilizar as credenciais guardadas numa análise, selecione-as explicitamente:

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

Para exigir uma API key de OPENAI_API_KEY ou CODEX_API_KEY:

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

Para tornar as credenciais guardadas a opção automática predefinida, execute unset OPENAI_API_KEY CODEX_API_KEY. Para conhecer todos os modos de autenticação suportados, consulte a referência da CLI.

É possível retomar uma análise em massa interrompida

Sim. Execute o mesmo comando de análise em massa com o CSV e o diretório de saída originais. O Codex Security ignora os repositórios concluídos.

Adicione --max-attempts 3 para tentar novamente após erros temporários do repositório ou da análise:

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

As análises concluídas conservam os resultados e não são repetidas, mesmo quando subsistem lacunas de cobertura. As lacunas de cobertura não fazem com que a campanha termine com o código 2.

Resultados e cobertura

Onde podem as equipas encontrar resultados de análises anteriores

Liste as análises guardadas para o seu repositório:

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

Utilize um ID de análise dos resultados para inspecionar os respetivos resultados de segurança:

npx @openai/codex-security scans show SCAN_ID

Cada análise concluída mantém em conjunto o respetivo relatório, resultados, cobertura e artefactos de suporte. Consulte Artefactos da análise para conhecer a estrutura completa.

Para inspecionar os eventos guardados da análise e dos processos de trabalho, execute scans logs SCAN_ID. Estes registos não são expurgados e podem conter código-fonte ou credenciais.

O que fazer se a CLI não conseguir guardar o histórico de análises

O Codex Security mantém o histórico de análises numa base de dados do workbench. Se não for possível escrever no diretório de estado predefinido, escolha um diretório privado fora do repositório:

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

Como distinguem as análises os resultados novos dos já conhecidos

Liste as conclusões em aberto de todas as análises de um repositório:

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

A lista identifica as conclusões confirmadas na análise mais recente e as conclusões anteriores em aberto que a análise não confirmou.

Compare as ocorrências entre as duas análises:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

A comparação associa automaticamente as constatações pela causa raiz, reutiliza associações guardadas e identifica constatações novas, persistentes, reabertas, não observadas, resolvidas e desconhecidas. Quando uma análise posterior não encontra uma constatação anterior no código que analisou, a constatação é considerada não observada. Só é considerada resolvida depois de ser explicitamente encerrada como já corrigida. Os caminhos excluídos e as associações incertas permanecem com estado desconhecido.

Como funciona o feedback sobre falsos positivos

Inspecione a análise guardada para encontrar o ID da ocorrência:

npx @openai/codex-security scans show SCAN_ID

Registe o motivo pelo qual esse resultado 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 análises futuras do mesmo repositório recebem essa explicação como contexto. Ainda assim, verificam de forma independente o código-fonte, os controlos e a acessibilidade atuais. Uma rejeição não suprime uma regra, um caminho nem uma classe de vulnerabilidade.

Para obter detalhes sobre os comandos, consulte a referência de resultados.

Por que motivo podem análises repetidas devolver resultados diferentes

As análises assistidas por IA podem variar, mesmo com a mesma configuração de análise. Comece por executar novamente a sua análise de referência:

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

A repetição da análise mantém a configuração da análise original e requer a mesma versão do plugin. Se o plugin instalado tiver sido alterado, o comando para.

Compare a análise de referência com a nova análise:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Forneça orientações comuns de arquitetura e segurança quando a falta de contexto puder contribuir para a variação. A correspondência pode identificar o mesmo resultado subjacente em diferentes execuções, mas não torna as análises determinísticas. Volte a verificar diretamente qualquer resultado importante que desapareça.

Como pode uma equipa confirmar que uma correção funcionou

Volte a verificar a constatação original na cópia de trabalho alterada. A partir dessa cópia de trabalho, forneça o respetivo relatório e o problema que pretende validar:

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

Reveja as evidências de que o percurso vulnerável foi eliminado e de que o comportamento legítimo continua a funcionar. Execute o procedimento original de reprodução ou o teste de regressão, quando disponível. Se não for possível executar a verificação, registe no resultado a incerteza que subsiste.

Uma comparação de análises pode mostrar como as constatações mudaram, mas a ausência de uma constatação, por si só, não comprova uma correção.

O que significa uma cobertura incompleta

Consulte coverage.json para ver caminhos excluídos, áreas adiadas e questões em aberto. Os novos resultados não incluem um campo de completude da cobertura. Consulte scan.status em scan-manifest.json para ver o estado da execução.

As lacunas de cobertura não alteram o código de saída de uma análise concluída. O código de saída 0 não significa que todos os ficheiros tenham sido revistos. Uma análise posterior não pode comprovar que uma constatação anterior já não existe se não abranger o caminho original dessa constatação.

Automatização e custos

Como funcionam os limites de tempo das análises aprofundadas

Defina um prazo para os workers ao iniciar uma análise aprofundada:

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

O valor predefinido é de 96 horas. Utilize qualquer valor positivo até 96, incluindo frações. Ao atingir o prazo, o Codex Security interrompe os processos de trabalho por concluir, conserva os resultados das análises padrão concluídas e agrega-os no relatório final. Consulte o relatório para ver 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 da execução e da política de gravidade.

Para definições persistentes ou campanhas em massa, defina max_time_hours em [deep_scan] na configuração de análises aprofundadas.

Como funcionam os limites de custos das análises

Defina um limite de custo estimado em USD antes de iniciar a análise:

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

O limite é uma estimativa, não um teto rígido de despesas. Os pedidos já em curso podem terminar acima desse valor. Se uma análise aprofundada atingir o limite depois de o Codex Security agregar os resultados dos processos de trabalho concluídos, a CLI pode guardar um relatório concluído com um aviso de orçamento. Devolve 0, ou 1 se as constatações atingirem o limiar de gravidade configurado. Se não conseguir produzir um resultado concluído válido, devolve 2 e preserva todos os dados de saída disponíveis.

Para verificações de pull requests do GitHub e análises agendadas de repositórios, utilize a Codex Security GitHub Action. Com action-v0.3.0, uma análise concluída significa que a análise configurada produziu um resultado válido. As exclusões de âmbito e as investigações adiadas não contornam a política de gravidade. Reveja coverage.json para avaliar o âmbito e as limitações da análise. Para também rejeitar diffs vazios e execuções de simulação, exija que a saída scan-status da Action seja completed; consulte Escolher uma política de gravidade.

Para outros fornecedores, consulte a descrição geral de CI/CD. Para efetuar uma verificação antes de cada commit, utilize install-hook.