Guia rápido da CLI do Codex Security

Execute uma varredura padrão em um repositório local com a CLI independente do Codex Security. Ao concluir este guia, você terá um relatório salvo para revisar e consultar novamente. Para executar varreduras em uma conversa do Codex, use o plugin do Codex Security.

Confira os pré-requisitos

Use o Node.js 24 ou 26. Se usar o Node.js 22, a versão mínima é a 22.13.0. Você também precisa do Python 3.10 ou posterior. Se usar o Python 3.10, instale tomli. Algumas solicitações de cibersegurança e alguns achados protegidos exigem Trusted Access for Cyber.

A CLI é executada com as suas permissões no sistema operacional e não pausa para pedir aprovação. Os processos de varredura podem herdar seu ambiente. Antes de começar, remova as credenciais que não serão usadas na varredura. Consulte Permissões para varreduras locais.

Configure e verifique a CLI

Instale o pacote público globalmente e confira a versão.

npm install -g @openai/codex-security
codex-security --version

O pacote fornece o comando codex-security e seu alias cs. Verifique se o diretório de executáveis globais do npm está no seu PATH.

Para executar a CLI sem instalá-la globalmente, use npx.

npx @openai/codex-security --version

Os exemplos a seguir usam npx @openai/codex-security. Depois da instalação global, você pode usar codex-security no lugar desse comando.

O comando exibe a versão instalada do pacote. Use info --json para conferir a versão do plugin incluído no pacote ou --help para listar os comandos.

Faça login

Faça login com sua conta do ChatGPT.

npx @openai/codex-security login

Em uma máquina sem navegador, adicione --device-auth se o seu espaço de trabalho permitir e siga as instruções de login exibidas. Se a autenticação por dispositivo estiver desativada, siga as instruções de login via SSH. Use --auth chatgpt nos comandos de varredura a seguir para selecionar esse login mesmo que seu ambiente também contenha uma chave de API.

Para usar chaves de API ou outros provedores, consulte Como selecionar a autenticação da varredura. Para o Amazon Bedrock, use credenciais da AWS e acesso ao modelo em vez de um login do ChatGPT ou de uma chave da API da OpenAI.

Prepare uma varredura

Substitua os caminhos abaixo pelo caminho do seu repositório e pelo de um novo diretório de resultados fora da árvore de trabalho do Git desse repositório.

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

Os resultados podem incluir trechos de código-fonte e detalhes de vulnerabilidades. Escolha um local privado. Se você omitir --output-dir, a CLI usará o diretório em que mantém seu estado persistente.

Confira o alvo da varredura e o local de saída.

npx @openai/codex-security scan "$REPOSITORY" \
  --auth chatgpt --output-dir "$SCAN_DIR" --dry-run

Uma simulação bem-sucedida confirma os parâmetros locais. A simulação não inicia uma varredura, não carrega credenciais nem verifica o interpretador Python do plugin. Portanto, ela não garante que a autenticação e a configuração do ambiente de execução funcionarão.

Execute sua primeira varredura

Remova --dry-run para iniciar a varredura.

npx @openai/codex-security scan "$REPOSITORY" \
  --auth chatgpt --output-dir "$SCAN_DIR"

Se você tiver acesso ao Daybreak Blue no seu espaço de trabalho do ChatGPT, adicione --model gpt-6-sol --cyber-access-program daybreak_blue ao comando de varredura.

Em um terminal interativo, a CLI exibe um painel atualizado em tempo real. Em terminais não interativos, ela exibe linhas de progresso. Adicione --headless para exibir linhas de progresso também em um terminal interativo. O painel e os logs salvos podem conter código-fonte ou credenciais. Revise o conteúdo antes de compartilhá-lo.

Ao concluir a varredura, a CLI exibe em stderr o caminho do relatório, o número de achados e o tempo decorrido, como neste exemplo.

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  SCOPE     repository: .
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

Por padrão, a gravidade de um achado não faz a varredura falhar. Para obter em stdout uma saída que possa ser processada automaticamente, adicione --json. Para que achados de determinada gravidade façam uma verificação de CI falhar, defina uma política de gravidade.

Revise os resultados

Abra report.md no diretório de resultados. Confirme o alvo e a revisão do código e, em seguida, analise os achados. Para conferir o status e o escopo registrados, consulte scan.status e scan.scope em scan-manifest.json.

Uma varredura concluída retorna 0, a menos que algum achado atinja o limite de gravidade configurado. Nesse caso, ela retorna 1. O código de saída 0 não garante que todos os arquivos tenham sido analisados. Falhas nos dados de entrada, na execução, na integridade dos resultados ou na geração das saídas obrigatórias retornam 2. A referência da CLI explica os códigos de saída.

Para cada achado, confira o código afetado, as condições necessárias para um ataque, as evidências de validação e o que ainda é incerto. Um achado identificado pela análise do código-fonte nem sempre inclui uma reprodução bem-sucedida do problema em tempo de execução. Selecione um achado para correção somente quando as evidências sustentarem o problema apontado.

Ao compartilhar ou arquivar o diretório da varredura, mantenha todo o conteúdo junto. Além do relatório e dos artefatos de apoio, o diretório contém scan-manifest.json e findings.json. Consulte Artefatos da varredura para ver a estrutura completa.

Exporte o modelo de ameaças salvo

As varreduras padrão, profundas e de diferenças salvam o modelo de ameaças junto com os resultados. Exporte o modelo em Markdown sem fazer login nem realizar outra chamada ao modelo de IA.

npx @openai/codex-security export "$SCAN_DIR" \
  --artifact threat-model --output "$SCAN_DIR/exports/threatmodel.md"

Se nenhum modelo de ameaças tiver sido salvo, export retornará um erro. Consulte a referência de exportação para selecionar varreduras salvas e outros formatos de saída.

Consulte novamente uma varredura salva

Liste as varreduras do repositório.

npx @openai/codex-security scans list "$REPOSITORY"

Copie o ID de uma varredura da lista de resultados e use-o no comando a seguir.

npx @openai/codex-security scans show SCAN_ID

Ao concluir uma varredura interativa com achados, a CLI também permite navegar pelos achados. Examine as evidências ali antes de escolher uma correção. Para achados salvos, use os comandos de validação e aplicação de correções.

Escolha a próxima varredura

Para resolver problemas de autenticação, entender diferenças entre varreduras repetidas ou enviar comentários sobre falsos positivos, consulte as perguntas frequentes sobre a CLI.