Guia de início rápido do Codex Security CLI

Execute uma análise padrão de um repositório local com a CLI autónoma do Codex Security. Este guia de início rápido termina com um relatório guardado que pode rever e voltar a consultar. Para análises numa conversa do Codex, utilize o plugin do Codex Security .

Verificar os pré-requisitos

Utilize Node.js 24 ou 26, ou Node.js 22 a partir da versão 22.13.0. Também precisa de Python 3.10 ou posterior. O Python 3.10 também precisa de tomli. As análises que utilizam inferência da OpenAI requerem acesso ao Codex Security. Consoante a sua conta e o repositório, as análises de todo o repositório também podem requerer Trusted Access for Cyber.

A CLI é executada com as permissões do seu sistema operativo e não faz pausas para obter aprovação. Os processos de análise podem herdar o seu ambiente, pelo que deve remover credenciais não relacionadas antes de começar. Consulte Permissões de análise local.

Configurar e verificar o CLI

Execute o pacote público com npx:

npx @openai/codex-security --version

O comando apresenta a versão do pacote instalado. Utilize info --json para verificar a versão do plugin incluído ou --help para listar os comandos. As alterações ao pacote estão listadas nas versões da CLI e do SDK.

Iniciar sessão

Inicie sessão com a sua conta ChatGPT:

npx @openai/codex-security login

Numa máquina sem navegador, adicione --device-auth e siga as instruções de início de sessão apresentadas. Utilize --auth chatgpt nos comandos de análise abaixo para selecionar esse início de sessão, mesmo quando o seu ambiente também contém uma API key.

Para API keys e outros fornecedores, consulte Selecionar a autenticação da análise. Para Amazon Bedrock, utilize Credenciais AWS e acesso a modelos em vez de um início de sessão no ChatGPT ou de uma API key da OpenAI.

Preparar uma análise

Substitua estes caminhos pelo seu repositório e por um novo diretório de resultados fora da respetiva árvore de trabalho do Git:

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

Os resultados podem incluir excertos do código-fonte e detalhes de vulnerabilidades. Escolha uma localização privada. Se omitir --output-dir, a CLI utiliza o respetivo diretório de estado persistente.

Verifique o destino e a localização de saída:

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

Uma execução de teste bem-sucedida confirma os dados de entrada locais. Não inicia uma análise, não carrega credenciais nem verifica o interpretador Python do plugin, pelo que não garante que a autenticação e a configuração do ambiente de execução serão bem-sucedidas.

Executar a sua primeira análise

Remova --dry-run para iniciar a análise:

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

Um terminal interativo apresenta um painel em tempo real. Os terminais não interativos apresentam linhas de progresso. Adicione --headless para utilizar linhas de progresso também num terminal interativo. O painel e os registos guardados podem conter código-fonte ou credenciais. Reveja-os antes de os partilhar.

Quando a análise termina, stderr inclui o caminho do relatório, o número de constatações e o tempo decorrido. Por exemplo:

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

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

Por predefinição, a gravidade de uma constatação não faz com que a análise falhe. Para obter stdout num formato legível por máquina, adicione --json. Para que as constatações façam falhar uma verificação de CI, defina uma política de gravidade.

Rever os resultados

Abra report.md no diretório indicado. Confirme o destino e a revisão, e depois leia a cobertura antes de rever as constatações individuais.

Verifique scan.status em scan-manifest.json para confirmar que a análise foi concluída. Consulte coverage.json para conhecer as áreas revistas, os caminhos excluídos, o trabalho adiado e as questões em aberto.

Uma análise concluída termina com 0, exceto se os problemas detetados atingirem um limiar de gravidade configurado, caso em que devolve 1. As lacunas de cobertura não alteram o código de saída, pelo que um código de saída 0 não significa que todos os ficheiros foram revistos. As falhas de entrada, execução, integridade dos resultados ou saída obrigatória devolvem 2. A referência da CLI explica os códigos de saída.

Para cada problema detetado, verifique o código afetado, os pré-requisitos do atacante, as evidências de validação e a incerteza restante. Um problema detetado com base no código-fonte não inclui necessariamente uma reprodução bem-sucedida em tempo de execução. Selecione um problema para correção apenas quando as evidências sustentarem o problema descrito.

Mantenha o diretório da análise intacto ao partilhá-lo ou arquivá-lo. Contém scan-manifest.json, findings.json e coverage.json, juntamente com o relatório e os artefactos de suporte. Consulte Artefactos da análise para conhecer a estrutura completa.

Voltar a consultar uma análise guardada

Liste as análises do repositório:

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

Copie um ID de análise dos resultados:

npx @openai/codex-security scans show SCAN_ID

Após uma análise interativa concluída com problemas detetados, a CLI também disponibiliza um explorador de problemas. Reveja aí as evidências antes de escolher uma correção. Para problemas guardados, utilize os comandos de validação e correção.

Escolher a próxima análise

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