Documentação do ChatGPT
Português
Contacto goolvyouyou@gmail.com

Perguntas frequentes sobre a CLI do Codex Security

Respostas sobre análises do Codex Security, resultados, falsos positivos, cobertura, custos e CI.

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

Quem pode utilizar a CLI

O pacote @openai/codex-security é público. Instale a CLI e o SDK:

npm install @openai/codex-security

A execução de análises requer acesso ao Codex Security. Para obter os melhores resultados, utilize uma conta verificada para Trusted Access for Cyber.

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.

Como funciona a análise de repositórios em massa

Inicie sessão com a GitHub CLI:

gh auth login

Detete e selecione repositórios de uma conta ou organização do GitHub:

npx @openai/codex-security bulk-scan

Para uma lista preparada, forneça um CSV de repositórios e um diretório de saída:

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

Consulte Executar análises de segurança em massa para obter informações sobre a deteção no GitHub, o formato CSV, os resultados da campanha e as opções disponíveis.

É 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 quando os artefactos de análise registados permanecem intactos.

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

Como pode uma análise utilizar políticas de arquitetura e segurança

Forneça documentos de arquitetura, modelos de ameaças ou políticas de segurança com --knowledge-base:

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

O Codex Security utiliza estes documentos como contexto para a análise atual. Para conhecer os tipos de ficheiro suportados e o comportamento dos diretórios, consulte Adicionar contexto de segurança.

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.

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

Faça corresponder os resultados que partilham uma causa principal entre as duas análises:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Compare os resultados correspondentes:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

A comparação identifica resultados novos, persistentes, reabertos, resolvidos e desconhecidos. Um resultado só é considerado resolvido quando a análise posterior abrange o respetivo alvo original e caminho afetado sem lacunas de cobertura.

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

Faça corresponder os resultados de referência à nova análise:

npx @openai/codex-security scans match BASELINE_SCAN_ID REPEAT_SCAN_ID

Compare os resultados correspondentes:

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

Depois de aplicar uma correção, execute novamente a análise original:

npx @openai/codex-security scans rerun BEFORE_SCAN_ID

Faça corresponder os resultados originais à nova análise:

npx @openai/codex-security scans match BEFORE_SCAN_ID AFTER_SCAN_ID

Compare os resultados correspondentes:

npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

Confirme que a nova análise abrange o alvo original e o caminho afetado sem lacunas de cobertura. Em seguida, volte a verificar diretamente o resultado original na versão atualmente extraída:

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

A ausência de um resultado ou apenas a comparação de análises não prova que uma correção funcionou.

O que significa uma cobertura incompleta

A cobertura pode ser complete, partial ou unknown. Consulte coverage.json para verificar caminhos excluídos, superfícies adiadas e questões em aberto antes de considerar uma análise como prova de revisão.

As análises com cobertura parcial ou desconhecida devolvem o código de saída 2, mesmo sem uma política de gravidade. Continuam a conservar todos os resultados e dados de cobertura disponíveis. Uma análise posterior não pode determinar que um resultado anterior deixou de existir quando não abrange o caminho original desse resultado.

Automatização e custos

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 limite máximo rígido de despesas. Os pedidos já em curso podem terminar acima do limite. O Codex Security mantém os resultados disponíveis quando a análise é interrompida.

Podem as análises verificar commits e pull requests

Instale uma verificação de segurança pre-commit para alterações em staging e fora de staging:

npx @openai/codex-security install-hook

Para verificações de pull requests, analise as alterações incluídas em commits e defina um limiar de gravidade:

npx @openai/codex-security scan . \
  --diff origin/main \
  --fail-on-severity high

Uma análise completa devolve o código de saída 1 quando encontra um problema com gravidade igual ou superior à selecionada. Consulte Executar análises em CI para conhecer o fluxo de trabalho completo do GitHub Actions, o tratamento de artefactos e a exportação SARIF.

Pode outra aplicação executar análises diretamente

Sim. Utilize o TypeScript SDK para iniciar análises, selecionar alvos, inspecionar resultados e cobertura, acompanhar o progresso e aplicar controlos de custos a partir de uma aplicação ou ferramenta de desenvolvimento.