Guía de inicio rápido de la CLI de Codex Security

Ejecuta un análisis estándar de un repositorio local con la CLI independiente de Codex Security. Al terminar esta guía, tendrás un informe guardado que podrás revisar y volver a consultar. Para ejecutar análisis dentro de una conversación de Codex, usa el complemento de Codex Security.

Verifica los requisitos previos

Usa Node.js 24 o 26, o bien Node.js 22 a partir de la versión 22.13.0. También necesitas Python 3.10 o posterior. Si usas Python 3.10, instala tomli. Algunas solicitudes de ciberseguridad y algunos hallazgos protegidos requieren Trusted Access for Cyber.

La CLI se ejecuta con los permisos que tienes en el sistema operativo y no se detiene para solicitar aprobación. Los procesos de análisis pueden heredar tu entorno. Antes de empezar, elimina del entorno las credenciales que no tengan relación con el análisis. Consulta Permisos para análisis locales.

Configura y verifica la CLI

Instala el paquete público de forma global y comprueba su versión:

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

El paquete incluye el comando codex-security y su alias cs. Asegúrate de que el directorio de ejecutables globales de npm esté en tu PATH.

Para ejecutar la CLI sin instalarla de forma global, usa npx:

npx @openai/codex-security --version

Los siguientes ejemplos usan npx @openai/codex-security. Si instalaste el paquete de forma global, puedes usar codex-security en su lugar.

El comando muestra la versión instalada del paquete. Usa info --json para comprobar la versión del complemento incluido o --help para ver la lista de comandos.

Inicia sesión

Inicia sesión con tu cuenta de ChatGPT:

npx @openai/codex-security login

En un equipo sin navegador, agrega --device-auth si tu Espacio de trabajo lo permite y sigue las instrucciones de inicio de sesión que aparecen en pantalla. Si la autenticación por dispositivo está deshabilitada, sigue las instrucciones para iniciar sesión mediante SSH. Agrega --auth chatgpt a los comandos de análisis que aparecen a continuación para usar esa sesión incluso si tu entorno también contiene una clave de API.

Para usar claves de API u otros proveedores, consulta Selecciona el método de autenticación para el análisis. Para Amazon Bedrock, usa las credenciales de AWS y el acceso a modelos en lugar de iniciar sesión con ChatGPT o usar una clave de la API de OpenAI.

Prepara un análisis

Reemplaza la primera ruta por la de tu repositorio y la segunda por la de un nuevo directorio de resultados fuera del Worktree de Git de ese repositorio:

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

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

Comprueba qué se va a analizar y dónde se guardarán los resultados:

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

Si la ejecución de prueba se completa correctamente, la CLI confirma los datos de entrada locales. La prueba no inicia un análisis, no carga credenciales ni comprueba el intérprete de Python del complemento. Por lo tanto, no confirma que la autenticación y la configuración del entorno de ejecución vayan a funcionar.

Ejecuta tu primer análisis

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

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

En una terminal interactiva, verás un panel que se actualiza en tiempo real. Las terminales no interactivas muestran el progreso línea por línea. Agrega --headless para ver el progreso línea por línea también en una terminal interactiva. El panel y los registros guardados pueden contener código fuente o credenciales. Revísalos antes de compartirlos.

Cuando termina el análisis, stderr muestra la ruta del informe, la cantidad 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)
  SCOPE     repository: .
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

De forma predeterminada, la gravedad de un hallazgo no hace que el análisis falle. Para obtener los resultados en stdout en un formato que puedas procesar automáticamente, agrega --json. Para que una comprobación de CI falle cuando haya hallazgos de determinada gravedad, configura una política de gravedad.

Revisa los resultados

Abre report.md en el directorio de resultados. Confirma el objetivo y la revisión del repositorio, y luego revisa los hallazgos. Para consultar el estado y el alcance registrados, revisa scan.status y scan.scope en scan-manifest.json.

Al completarse el análisis, la CLI devuelve el código de salida 0, salvo que algún hallazgo alcance el umbral de gravedad configurado, en cuyo caso devuelve 1. El código de salida 0 no confirma que se hayan revisado todos los archivos. Los errores en los datos de entrada, en la ejecución, en la integridad de los resultados o en la generación de la salida requerida dan lugar al código 2. La referencia de la CLI explica los códigos de salida.

Para cada hallazgo, revisa el código afectado, las condiciones que debe cumplir un atacante, las pruebas de validación y las dudas que aún queden. Un hallazgo basado en el código fuente no siempre incluye una reproducción exitosa del problema durante la ejecución. Selecciona un hallazgo para corregirlo solo después de comprobar que las pruebas respaldan el problema señalado.

Si compartes o archivas el directorio del análisis, conserva todo su contenido. Contiene scan-manifest.json y findings.json, junto con el informe y los artefactos de respaldo. Consulta Artefactos del análisis para ver la estructura completa del directorio.

Exporta el modelo de amenazas guardado

Los análisis estándar, los análisis profundos y los análisis de diferencias guardan su modelo de amenazas junto con los resultados. Expórtalo en formato Markdown sin iniciar sesión ni hacer otra llamada al modelo:

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

Si no se guardó ningún modelo de amenazas, export devuelve un error. Consulta la referencia del comando de exportación para seleccionar análisis guardados y otros formatos de salida.

Vuelve a consultar un análisis guardado

Muestra la lista de análisis del repositorio:

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

Copia un ID de análisis de los resultados y úsalo en el siguiente comando:

npx @openai/codex-security scans show SCAN_ID

Cuando se completa un análisis interactivo con hallazgos, la CLI también ofrece un explorador de hallazgos. Revisa las pruebas allí antes de elegir una corrección. Para los hallazgos guardados, usa los comandos de validación y aplicación de parches.

Elige el siguiente análisis

Si tienes problemas de autenticación, encuentras diferencias al repetir un análisis o quieres enviar comentarios sobre falsos positivos, consulta las preguntas frecuentes sobre la CLI.