Inicio rápido de Codex Security CLI

Ejecute un análisis estándar de un repositorio local con la CLI independiente de Codex Security. Esta guía de inicio rápido termina con un informe guardado que puede revisar y volver a consultar. Para realizar análisis dentro de una conversación de Codex, use el plugin de Codex Security .

Comprobar los requisitos previos

Use Node.js 24 o 26, o Node.js 22 a partir de la versión 22.13.0. También necesita Python 3.10 o posterior. Python 3.10 también necesita tomli. Los análisis que usan inferencia de OpenAI requieren acceso a Codex Security. Según su cuenta y repositorio, los análisis de todo el repositorio también pueden requerir Trusted Access for Cyber.

La CLI se ejecuta con los permisos de su sistema operativo y no se detiene para solicitar aprobación. Los procesos de análisis pueden heredar su entorno, así que elimine las credenciales no relacionadas antes de comenzar. Consulte Permisos de los análisis locales.

Configurar y verificar la CLI

Ejecute el paquete público con npx:

npx @openai/codex-security --version

El comando muestra la versión del paquete instalado. Use info --json para comprobar la versión del plugin incluido, o --help para enumerar los comandos. Los cambios del paquete se indican en las versiones de la CLI y el SDK.

Iniciar sesión

Inicie sesión con su cuenta de ChatGPT:

npx @openai/codex-security login

En un equipo sin navegador, añada --device-auth y siga las instrucciones de inicio de sesión que se muestran. Use --auth chatgpt en los comandos de análisis siguientes para seleccionar ese inicio de sesión incluso si su entorno también contiene una API key.

Para API keys y otros proveedores, consulte Seleccionar la autenticación del análisis. Para Amazon Bedrock, use Credenciales de AWS y acceso a modelos en lugar de un inicio de sesión de ChatGPT o una API key de OpenAI.

Preparar un análisis

Sustituya estas rutas por la de su repositorio y la de un nuevo directorio de resultados fuera de su árbol de trabajo de Git:

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

Los resultados pueden incluir fragmentos del código fuente y detalles de vulnerabilidades. Elija una ubicación privada. Si omite --output-dir, la CLI usa su directorio de estado persistente.

Compruebe el destino y la ubicación de salida:

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

Una ejecución de prueba correcta confirma las entradas locales. No inicia un análisis, carga credenciales ni comprueba el intérprete de Python del plugin, por lo que no garantiza que la autenticación y la configuración del entorno de ejecución funcionen.

Ejecutar su primer análisis

Elimine --dry-run para iniciar el análisis:

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

Una terminal interactiva muestra un panel en tiempo real. Las terminales no interactivas muestran líneas de progreso. Añada --headless para usar líneas de progreso también en una terminal interactiva. El panel y los registros guardados pueden contener código fuente o credenciales. Revíselos antes de compartirlos.

Cuando finaliza el análisis, stderr incluye la ruta del informe, el número de hallazgos y el tiempo transcurrido. Por ejemplo:

  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

De forma predeterminada, la gravedad de un hallazgo no provoca que un análisis falle. Para obtener stdout en un formato legible por máquinas, añada --json. Para que los hallazgos hagan fallar una comprobación de CI, establezca una política de gravedad.

Revisar los resultados

Abra report.md desde el directorio indicado. Confirme el destino y la revisión, y después lea la cobertura antes de revisar los hallazgos individuales.

Compruebe scan.status en scan-manifest.json para confirmar que el análisis se completó. Revise coverage.json para consultar las áreas revisadas, las rutas excluidas, el trabajo pendiente y las preguntas abiertas.

Un análisis completado devuelve 0, salvo que los hallazgos alcancen un umbral de gravedad configurado, en cuyo caso devuelve 1. Las lagunas de cobertura no cambian el código de salida, por lo que el código de salida 0 no significa que se hayan revisado todos los archivos. Los errores de entrada, ejecución, integridad de los resultados o generación de las salidas obligatorias devuelven 2. La referencia de la CLI explica los códigos de salida.

Para cada hallazgo, compruebe el código afectado, los requisitos previos para el atacante, las pruebas de validación y la incertidumbre restante. Un hallazgo basado en el código fuente no necesariamente incluye una reproducción satisfactoria en tiempo de ejecución. Seleccione un hallazgo para corregirlo solo cuando sus pruebas respalden el problema señalado.

Mantenga unido el directorio del análisis al compartirlo o archivarlo. Contiene scan-manifest.json, findings.json y coverage.json junto con el informe y los artefactos de respaldo. Consulte Artefactos del análisis para ver la estructura completa.

Volver a consultar un análisis guardado

Enumere los análisis del repositorio:

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

Copie un ID de análisis de los resultados:

npx @openai/codex-security scans show SCAN_ID

Tras un análisis interactivo completo con hallazgos, la CLI también ofrece un explorador de hallazgos. Revise allí las pruebas antes de elegir una corrección. Para los hallazgos guardados, use los comandos de validación y aplicación de parches.

Elija el siguiente análisis

Para problemas de autenticación, diferencias entre análisis repetidos o comentarios sobre falsos positivos, consulte las preguntas frecuentes de la CLI.