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

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

Configure o Codex Security, execute uma análise local e reveja o relatório, as conclusões e a cobertura.

O Codex Security ajuda as equipas de segurança e engenharia a encontrar, confirmar e corrigir vulnerabilidades. Utilize a respetiva interface de linha de comandos (CLI) para analisar repositórios que possua ou tenha autorização para avaliar, rever conclusões ao longo do tempo e verificar alterações antes de serem integradas.

Verificar os pré-requisitos

O CLI requer o Node.js 22 (22.13.0 ou posterior), 24 ou 26. As análises, análises em massa, exportações, histórico de análises e conclusões guardadas também requerem o Python 3.10 ou posterior. Para obter mais informações, consulte Autenticação e pré-requisitos.

Configurar e verificar o CLI

Execute o CLI com npx e verifique a respetiva versão:

npx @openai/codex-security --version

Para ver tanto a versão do pacote como a versão do plugin incluído, execute:

npx @openai/codex-security info --json

Consulte as versões do CLI e SDK para conhecer as alterações ao pacote.

Liste os comandos disponíveis:

npx @openai/codex-security --help

Consulte também a referência do CLI.

Iniciar sessão

Para utilização local, inicie sessão com a sua conta ChatGPT:

npx @openai/codex-security login

Numa máquina remota ou sem interface gráfica, utilize a autenticação do dispositivo:

npx @openai/codex-security login --device-auth

Para CI e outros fluxos de trabalho automatizados, defina uma OpenAI API key:

export OPENAI_API_KEY="<your-api-key>"

Para credenciais da AWS, consulte a configuração do Amazon Bedrock. Para OpenRouter ou Fireworks, defina a API key do fornecedor e selecione um modelo com --provider e --model.

Para utilizar o seu início de sessão no ChatGPT quando também estiver definida uma API key, selecione-o explicitamente:

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

Para exigir a API key do ambiente, selecione a autenticação por API key:

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

Consoante a sua conta e o repositório, as análises de repositórios completos também podem requerer Trusted Access for Cyber.

Preparar uma análise

Escolha um repositório fidedigno que tenha autorização para avaliar. As análises utilizam as suas permissões locais do sistema operativo e não são interrompidas para 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álises locais.

Escolha um diretório fora do repositório para os resultados da análise:

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

Se omitir --output-dir, o Codex Security guarda os resultados no seu próprio diretório de estado persistente. Os resultados podem incluir excertos de código-fonte e detalhes de vulnerabilidades, pelo que deve escolher uma localização privada e uma política de retenção adequada.

Se não for possível escrever no diretório de estado predefinido, selecione um diretório gravável fora do repositório analisado:

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

Verifique o repositório, o alvo e o diretório de saída antes de iniciar uma análise:

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

A simulação verifica os dados de entrada locais, incluindo quaisquer caminhos --knowledge-base, sem iniciar o Codex, carregar credenciais ou sondar o interpretador Python do plugin.

Executar a sua primeira análise

Execute uma análise padrão e conserve os resultados no diretório selecionado:

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

Os terminais interativos apresentam um painel de análise em tempo real. Adicione --headless para apresentar linhas simples de progresso. A CI e os terminais sem uma sessão interativa utilizam automaticamente o progresso simples.

O painel também apresenta detalhes da sessão em tempo real. Estes podem conter código-fonte ou credenciais, pelo que deve analisá-los antes de os partilhar.

Por predefinição, o CLI escreve o progresso da análise e o respetivo resumo de conclusão em stderr. Não imprime o resultado completo da análise em stdout. Uma análise concluída apresenta um resumo semelhante a este:

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

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

A utilização de tokens e o custo estimado são apresentados quando disponíveis. Para imprimir o resultado completo como JSON legível por máquina, solicite explicitamente uma saída estruturada:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

Por predefinição, as análises apenas produzem relatórios, pelo que as conclusões permanecem disponíveis para revisão local. Pode adicionar um limiar de gravidade quando estiver preparado para executar análises em CI.

Escolher um modelo e o nível de raciocínio

Por predefinição, as análises utilizam gpt-5.6-sol com o nível de raciocínio xhigh. Selecione um modelo e nível diferentes quando a tarefa assim o exigir:

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

Os níveis suportados são minimal, low, medium, high, xhigh e max.

Rever os resultados

Abra report.md para consultar o resultado legível. O diretório da análise também contém os ficheiros estruturados utilizados pela automatização:

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json regista o alvo, o âmbito, o produtor e os artefactos selados.
  • findings.json regista a gravidade, a confiança, as localizações, as provas e a correção de cada conclusão.
  • coverage.json regista as superfícies analisadas, exclusões, trabalho adiado, questões em aberto e a integridade da cobertura.

A cobertura pode ser complete, partial ou unknown. Leia todas as áreas adiadas ou questões em aberto antes de tratar a análise como prova de revisão. A referência do CLI descreve o contrato completo dos artefactos e da saída.

Rever e corrigir conclusões

Após uma análise interativa completa com conclusões, o CLI disponibiliza um navegador de conclusões. Analise as provas e escolha as conclusões que pretende corrigir. Pode encontrar as tarefas guardadas na aplicação Codex para computador.

Para corrigir conclusões de gravidade elevada e crítica sem o navegador:

npx @openai/codex-security scan "$REPOSITORY" \
  --patch --patch-severity high --json

Adicione --create-pr para fazer commit das correções verificadas e abrir um pull request no GitHub.

Também pode corrigir conclusões guardadas ou importar problemas do Linear. Consulte a referência de validate e patch.

Escolher a análise seguinte

Utilize uma análise de caminho quando um repositório contiver serviços ou pacotes distintos:

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

Reveja as alterações confirmadas entre a revisão de base e HEAD:

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

Reveja as alterações em staging e fora de staging em relação a HEAD:

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

As análises de diferenças e da árvore de trabalho esperam que o argumento do repositório seja a raiz da árvore de trabalho Git. Obtenha as revisões selecionadas antes de iniciar uma análise de diferenças.

Utilize o modo aprofundado quando um repositório ou caminho necessitar de uma revisão mais abrangente:

npx @openai/codex-security scan "$REPOSITORY" --mode deep

Para controlar os workers, os subagentes e o momento em que a análise termina:

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

Estas opções requerem o modo aprofundado, que suporta alvos de repositório e caminho, mas não análises de diferenças nem da árvore de trabalho. Aqui, --workers controla workers independentes de análises padrão dentro de uma análise; bulk-scan --workers controla análises de repositórios em simultâneo. --max-time-hours aceita um número positivo até 96, incluindo frações de hora. Quando o limite é atingido, a análise interrompe os workers inacabados, preserva os resultados das análises concluídas e agrega-os no relatório final.

Adicionar contexto de arquitetura e segurança

Forneça documentos de arquitetura, modelos de ameaças ou políticas de segurança como contexto da análise. Isto ajuda o Codex Security a avaliar as conclusões em função do funcionamento real do seu sistema:

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

Adicionar instruções de análise personalizadas

Adicione instruções que direcionem a análise para as suas prioridades de segurança. Utilize um segundo ficheiro para instruções de seguimento:

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

O seguimento é executado na mesma sessão autenticada após análises bem-sucedidas e análises com cobertura incompleta ou erros. Se o seguimento falhar, o CLI apresenta um aviso e conserva a análise concluída. Não é executado após o cancelamento ou uma análise que atinja o respetivo limite de custo. Ambas as opções também funcionam com bulk-scan; uma coluna CSV prompt adiciona instruções específicas do repositório.

Definir um orçamento para a análise

Utilize --max-cost para interromper uma análise quando o custo estimado do modelo exceder um limite em USD:

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

Os pedidos já em curso podem terminar ligeiramente acima do limite. Se uma análise aprofundada atingir o limite depois de o Codex Security agregar os resultados dos workers concluídos, o CLI guarda o relatório concluído, marca a cobertura como partial e devolve o código de saída 2. Se a análise não conseguir produzir um relatório concluído, qualquer saída parcial disponível permanece no disco.

Analisar alterações antes de cada commit

Instale uma verificação de segurança Git pre-commit no seu repositório:

npx @openai/codex-security install-hook

A verificação analisa as alterações em staging e fora de staging antes de cada commit. Bloqueia conclusões de gravidade elevada e erros de análise sem substituir um script pre-commit existente.

Analisar repositórios em massa

Inicie sessão no GitHub antes de procurar repositórios:

gh auth login

Procure e selecione repositórios da sua conta ou organização GitHub:

npx @openai/codex-security bulk-scan

O fluxo interativo exclui repositórios arquivados e forks. Solicita-lhe que confirme os repositórios selecionados antes da análise.

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

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

Execute novamente o mesmo comando para retomar uma análise em massa existente. O Codex Security ignora os repositórios concluídos. Adicione --max-attempts 3 quando pretender tentar novamente erros temporários do repositório ou da análise.

Para obter informações sobre a pesquisa no GitHub, a preparação do CSV, os resultados de campanhas e a configuração do Docker, consulte Executar análises de segurança em massa.

Executar análises em massa no Docker

Se o seu acesso incluir a imagem Docker do Codex Security, utilize a configuração Compose reforçada e o perfil de segurança fornecidos num anfitrião Docker Linux. O anfitrião tem de suportar a criação de espaços de nomes de utilizador sem privilégios. Forneça um CSV de repositórios, mantenha os resultados e o estado de início de sessão em diretórios montados persistentes e forneça as credenciais através do ambiente ou de um gestor de segredos:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

O contentor executa análises em massa sem pedidos interativos. Utilize o CLI fora do Docker quando pretender procurar repositórios interativamente. Para repositórios privados, forneça GH_TOKEN ou GITHUB_TOKEN através do ambiente ou do gestor de segredos. Os requisitos de início de sessão, incluindo o acesso à conta e aos repositórios, também se aplicam às análises em contentores.

Voltar a consultar uma análise guardada

Liste as análises guardadas do seu repositório:

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

Copie um ID de análise dos resultados para inspecionar as respetivas conclusões e configuração:

npx @openai/codex-security scans show SCAN_ID

Para inspecionar os eventos guardados de uma análise e dos respetivos workers:

npx @openai/codex-security scans logs SCAN_ID

Os registos guardados não são expurgados e podem conter código-fonte ou credenciais. Analise-os antes de os partilhar.

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

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

Uma conclusão anterior permanece aberta quando a análise mais recente não a confirma.

Para marcar uma conclusão analisada como falso positivo, explique por que motivo a conclusão não se aplica:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

As análises posteriores têm essa explicação em consideração, mas voltam a verificar o código atual.

Execute a mesma análise na versão atual do repositório utilizando a configuração original:

npx @openai/codex-security scans rerun SCAN_ID

Compare duas análises para encontrar conclusões novas, persistentes, reabertas, resolvidas ou desconhecidas:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

A comparação estabelece automaticamente a correspondência entre conclusões com base na causa principal e reutiliza correspondências guardadas.

Para obter informações sobre o formato CSV das análises em massa, os filtros do histórico de análises e as opções dos comandos, consulte a referência do CLI.

Continue com o fluxo de trabalho adequado ao seu objetivo: