Preguntas frecuentes sobre Codex Security CLI

Encuentra respuestas a preguntas comunes sobre cómo analizar repositorios y gestionar hallazgos de seguridad desde la terminal. Para realizar la instalación y un primer análisis, comienza con la guía de inicio rápido de CLI.

Análisis de repositorios

Quién puede usar la CLI

El paquete @openai/codex-security es público. Instala la CLI y el SDK:

npm install @openai/codex-security

Para ejecutar análisis, se requiere acceso a Codex Security. Para obtener los mejores resultados, usa una cuenta verificada para el acceso de confianza para ciberseguridad.

Por qué un análisis usa una API key después de iniciar sesión

Cuando tu entorno incluye OPENAI_API_KEY o CODEX_API_KEY, los análisis sin una terminal interactiva y los análisis JSON y JSONL usan de forma predeterminada la API key del entorno, incluso después de iniciar sesión correctamente con ChatGPT o un token de acceso. Los análisis interactivos con salida de texto te piden elegir cuando también está disponible el inicio de sesión con ChatGPT. Las ejecuciones de prueba no solicitan ni cargan credenciales.

Para usar tus credenciales almacenadas en un análisis, selecciónalas explícitamente:

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

Para exigir una API key de OPENAI_API_KEY o CODEX_API_KEY:

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

Para que tus credenciales almacenadas sean el valor predeterminado automático, ejecuta unset OPENAI_API_KEY CODEX_API_KEY. Para consultar todos los modos de autenticación compatibles, consulta la referencia de CLI.

Cómo funciona el análisis masivo de repositorios

Inicia sesión con GitHub CLI:

gh auth login

Descubre y selecciona repositorios de una cuenta u organización de GitHub:

npx @openai/codex-security bulk-scan

Para usar una lista preparada, proporciona un CSV de repositorios y un directorio de salida:

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

Consulta Ejecutar análisis de seguridad masivos para obtener información sobre la detección en GitHub, el formato CSV, los resultados de las campañas y las opciones disponibles.

Puede reanudarse un análisis masivo interrumpido

Sí. Ejecuta el mismo comando de análisis masivo con el CSV y el directorio de salida originales. Codex Security omite los repositorios completados cuando sus artefactos de análisis registrados permanecen intactos.

Añade --max-attempts 3 para reintentar tras errores temporales del repositorio o del análisis:

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

Cómo puede un análisis usar políticas de arquitectura y seguridad

Proporciona documentos de arquitectura, modelos de amenazas o políticas de seguridad con --knowledge-base:

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

Codex Security usa estos documentos como contexto para el análisis actual. Para consultar los tipos de archivo compatibles y el comportamiento de los directorios, consulta Añadir contexto de seguridad.

Hallazgos y cobertura

Dónde pueden encontrar los equipos los resultados de análisis anteriores

Enumera los análisis guardados de tu repositorio:

npx @openai/codex-security scans list /path/to/repository

Usa un ID de análisis de los resultados para inspeccionar sus hallazgos:

npx @openai/codex-security scans show SCAN_ID

Cada análisis completado conserva juntos su informe, hallazgos, cobertura y artefactos de respaldo. Consulta Artefactos del análisis para conocer la estructura completa.

Qué hacer si la CLI no puede guardar el historial de análisis

Codex Security conserva el historial de análisis en una base de datos del banco de trabajo. Si no se puede escribir en el directorio de estado predeterminado, elige un directorio privado fuera del repositorio:

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

Cómo distinguen los análisis entre hallazgos nuevos y conocidos

Relaciona los hallazgos que comparten una causa raíz entre los dos análisis:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Compara los hallazgos relacionados:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

La comparación identifica hallazgos nuevos, persistentes, reabiertos, resueltos y desconocidos. Un hallazgo solo se considera resuelto cuando el análisis posterior cubre su objetivo original y la ruta afectada sin brechas de cobertura.

Cómo funciona la retroalimentación sobre falsos positivos

Inspecciona el análisis guardado para encontrar el ID de la incidencia:

npx @openai/codex-security scans show SCAN_ID

Registra por qué ese hallazgo no es aplicable:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

Los análisis futuros del mismo repositorio reciben esa explicación como contexto. Aun así, comprueban de manera independiente el código fuente, los controles y la accesibilidad actuales. Un descarte no suprime una regla, ruta ni clase de vulnerabilidad.

Para obtener detalles sobre los comandos, consulta la referencia de hallazgos.

Por qué los análisis repetidos pueden devolver hallazgos diferentes

Los análisis asistidos por IA pueden variar, incluso con la misma configuración de análisis. Comienza por volver a ejecutar el análisis de referencia:

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

Relaciona los hallazgos de referencia con el nuevo análisis:

npx @openai/codex-security scans match BASELINE_SCAN_ID REPEAT_SCAN_ID

Compara los resultados relacionados:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Proporciona directrices compartidas de arquitectura y seguridad cuando la falta de contexto pueda contribuir a la variación. La asociación puede identificar el mismo hallazgo subyacente entre ejecuciones, pero no hace que los análisis sean deterministas. Vuelve a comprobar directamente cualquier hallazgo importante que desaparezca.

Cómo puede un equipo confirmar que una corrección funcionó

Después de aplicar una corrección, vuelve a ejecutar el análisis original:

npx @openai/codex-security scans rerun BEFORE_SCAN_ID

Relaciona los hallazgos originales con el nuevo análisis:

npx @openai/codex-security scans match BEFORE_SCAN_ID AFTER_SCAN_ID

Compara los hallazgos relacionados:

npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

Confirma que el nuevo análisis cubra el objetivo original y la ruta afectada sin brechas de cobertura. Después, vuelve a comprobar directamente el hallazgo original en la versión actual del repositorio:

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

La ausencia de un hallazgo o una comparación de análisis por sí solas no demuestran que una corrección haya funcionado.

Qué significa una cobertura incompleta

La cobertura puede ser complete, partial o unknown. Revisa coverage.json para conocer las rutas excluidas, las superficies aplazadas y las preguntas pendientes antes de considerar un análisis como evidencia de una revisión.

Los análisis con cobertura parcial o desconocida devuelven el código de salida 2, incluso sin una política de gravedad. Aun así, conservan los hallazgos y la cobertura disponibles. Un análisis posterior no puede demostrar que un hallazgo anterior ya no existe cuando no cubre la ruta original de ese hallazgo.

Automatización y costo

Cómo funcionan los límites de costo de los análisis

Establece un límite de costo estimado en USD antes de iniciar el análisis:

npx @openai/codex-security scan . --max-cost 5

El límite es una estimación, no un tope de gasto estricto. Las solicitudes que ya están en curso pueden finalizar por encima del límite. Codex Security conserva los resultados disponibles cuando el análisis se detiene.

Pueden los análisis comprobar commits y pull requests

Instala una comprobación de seguridad previa al commit para los cambios preparados y no preparados:

npx @openai/codex-security install-hook

Para las comprobaciones de pull requests, analiza los cambios incluidos en commits y establece un umbral de gravedad:

npx @openai/codex-security scan . \
  --diff origin/main \
  --fail-on-severity high

Un análisis completo devuelve el código de salida 1 cuando encuentra un problema con una gravedad igual o superior a la seleccionada. Consulta Ejecutar análisis en CI para conocer el flujo de trabajo completo de GitHub Actions, la gestión de artefactos y la exportación SARIF.

Puede otra aplicación ejecutar análisis directamente

Sí. Usa el SDK de TypeScript para iniciar análisis, seleccionar objetivos, inspeccionar hallazgos y cobertura, hacer un seguimiento del progreso y aplicar controles de costos desde una aplicación o herramienta para desarrolladores.