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.

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 bulk-scan con el CSV y el directorio de salida originales. Codex Security omite los repositorios completados.

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

Un análisis completado con cobertura partial o unknown conserva sus resultados y hace que la campaña finalice con el código 2. No se vuelve a intentar, ni siquiera con --max-attempts.

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.

Para inspeccionar los eventos guardados del análisis y de sus procesos de trabajo, ejecuta scans logs SCAN_ID. Estos registros no están censurados y pueden contener código fuente o credenciales.

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

Enumera los hallazgos abiertos de todos los análisis de un repositorio:

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

La lista identifica los hallazgos confirmados en el análisis más reciente y los hallazgos abiertos anteriores que el análisis no confirmó.

Compara los hallazgos de los dos análisis:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

La comparación relaciona automáticamente los hallazgos por causa raíz, reutiliza las correspondencias guardadas e identifica hallazgos nuevos, persistentes, reabiertos, resueltos y desconocidos. Un hallazgo solo se considera resuelto cuando el análisis posterior abarca 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

La repetición del análisis conserva la configuración del análisis original y requiere la misma versión del plugin. Si el plugin instalado ha cambiado, el comando se detiene.

Compara el análisis de referencia con el nuevo análisis:

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

Compara los hallazgos originales con el nuevo análisis:

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 tiempo de los análisis profundos

Establece un plazo para los procesos de trabajo al iniciar un análisis profundo:

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

El valor predeterminado es de 96 horas. Usa cualquier valor positivo hasta 96, incluidas fracciones. Cuando vence el plazo, Codex Security detiene los procesos de trabajo sin finalizar, conserva los resultados de los análisis estándar finalizados y los agrega al informe final. Si ningún proceso de trabajo termina la revisión del código fuente, el informe registra una cobertura parcial y la CLI devuelve el código de salida 2.

Para configurar opciones persistentes o campañas masivas, establece max_time_hours en [deep_scan] dentro de la configuración de análisis profundos.

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 de él. Si un análisis profundo alcanza el límite después de que Codex Security agregue los resultados finalizados de los procesos de trabajo, la CLI guarda el informe finalizado con cobertura parcial y termina con el código 2. De lo contrario, conserva cualquier salida parcial disponible.

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.