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

Início rápido da CLI do Codex Security

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 que tenha autorização para avaliar, rever conclusões ao longo do tempo e verificar alterações antes de serem integradas.

Verificar os pré-requisitos

A CLI requer Node.js 22 ou posterior. A execução de uma análise ou a exportação de conclusões também requer Python 3.10 ou posterior. Para obter mais detalhes, consulte Autenticação e pré-requisitos.

Configurar e verificar a CLI

Instale o pacote publicado:

npm install @openai/codex-security

Liste os comandos disponíveis:

npx @openai/codex-security --help

Consulte também a referência da 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 de 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 AWS, consulte a configuração do Amazon Bedrock.

Para utilizar o seu início de sessão do 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 completas do repositório também podem requerer Trusted Access for Cyber.

Preparar uma análise

Escolha um repositório para analisar e um diretório onde escrever os resultados.

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 persistente de estado. Os resultados podem incluir excertos do código-fonte e detalhes de vulnerabilidades, por isso escolha 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 com permissões de escrita 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 as entradas locais sem iniciar o Codex, carregar credenciais ou sondar o interpretador Python do plugin.

Executar a primeira análise

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

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

Por predefinição, a 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 imprime um resumo semelhante a este:

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: Results: /path/outside/repository/codex-security-results

A utilização de tokens e o custo estimado são apresentados quando estão 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. Poderá querer adicionar um limiar de gravidade quando estiver preparado para executar análises em CI.

Escolher um modelo e o esforço de raciocínio

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

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

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

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 evidências e a correção de cada conclusão.
  • coverage.json regista as superfícies revistas, as exclusões, o trabalho adiado, as questões em aberto e a completude 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 evidência de revisão. A referência da CLI descreve o contrato completo dos artefactos e da saída.

Escolher a análise seguinte

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

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

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

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

Reveja as alterações preparadas e não preparadas 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

O modo aprofundado suporta alvos de repositório e caminho, mas não análises de diferenças ou da árvore de trabalho.

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

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 acima do limite. O Codex Security conserva os resultados disponíveis quando uma análise é interrompida.

Analisar alterações antes de cada consolidação

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 preparadas e não preparadas antes de cada consolidação. 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 de repositórios preparada, 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. Os repositórios concluídos com artefactos de resultados intactos não são novamente analisados. Adicione --max-attempts 3 quando pretender repetir a operação após erros temporários de repositório ou análise.

Para a procura no GitHub, a preparação do CSV, os resultados da campanha 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 deve 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 credenciais através do seu 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 de interação. Utilize a CLI fora do Docker quando pretender procurar repositórios interativamente. Para repositórios privados, forneça GH_TOKEN ou GITHUB_TOKEN através do seu ambiente ou gestor de segredos. Os requisitos de início de sessão, incluindo o acesso à conta e ao repositório, também se aplicam às análises em contentores.

Voltar a consultar uma análise guardada

Liste as análises guardadas para o 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 marcar uma conclusão revista 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 conta, mas voltam a verificar o código atual.

Execute a mesma análise na versão atualmente extraída utilizando a configuração original:

npx @openai/codex-security scans rerun SCAN_ID

Para comparar duas análises, comece por fazer corresponder as conclusões que partilham a mesma causa principal:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Em seguida, verifique quais são as conclusões novas, persistentes, reabertas, resolvidas ou desconhecidas:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Para conhecer 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 da CLI.

Continue com o fluxo de trabalho adequado ao seu objetivo: