Preguntas frecuentes sobre la CLI de Codex Security

Encuentra respuestas a preguntas frecuentes sobre cómo analizar repositorios y gestionar hallazgos de seguridad desde la terminal. Para instalar la CLI y ejecutar tu primer análisis, sigue la guía de inicio rápido de la CLI.

Análisis de repositorios

¿Por qué se usa una clave de API para el análisis después de iniciar sesión?

Si tu entorno incluye OPENAI_API_KEY o CODEX_API_KEY, los análisis sin terminal interactiva y los análisis con salida en JSON o JSONL usan de forma predeterminada la clave de API del entorno, incluso si ya iniciaste sesión con ChatGPT o con un token de acceso. En los análisis interactivos con salida de texto, la CLI te pide que elijas qué credenciales usar si también hay una sesión de ChatGPT disponible. Las ejecuciones de prueba no solicitan datos ni cargan credenciales.

Para usar tus credenciales guardadas en un análisis, selecciónalas de forma explícita:

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

Para exigir una clave de API de OPENAI_API_KEY o CODEX_API_KEY:

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

Para que la CLI use tus credenciales guardadas de forma predeterminada, ejecuta unset OPENAI_API_KEY CODEX_API_KEY. Consulta todos los modos de autenticación disponibles en la referencia de la CLI.

¿Se puede reanudar un análisis por lotes interrumpido?

Sí. Ejecuta el mismo comando de análisis por lotes con el archivo CSV y el directorio de salida originales. Codex Security omite los repositorios cuyo análisis ya terminó.

Agrega --max-attempts 3 para volver a intentarlo si se producen errores temporales en el repositorio o durante el análisis:

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

Los análisis completados conservan sus resultados y no se repiten, incluso si quedan áreas sin cubrir. Las brechas de cobertura no hacen que la campaña termine con el código 2.

Hallazgos y cobertura

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

Consulta la lista de análisis guardados de tu repositorio:

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

Usa el ID de uno de los análisis de la lista para revisar sus hallazgos:

npx @openai/codex-security scans show SCAN_ID

Cada análisis completado guarda en un mismo lugar el informe, los hallazgos, el archivo de manifiesto y los artefactos de respaldo. Consulta la estructura completa en Artefactos del análisis.

Para revisar los eventos guardados del análisis y de sus procesos de trabajo, ejecuta scans logs SCAN_ID. Estos registros no ocultan los datos sensibles y pueden contener código fuente o credenciales.

¿Qué pasa si la CLI no puede guardar el historial de análisis?

Codex Security guarda el historial de análisis en una base de datos del entorno de trabajo. Si la CLI no 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 los hallazgos nuevos de los conocidos?

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

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

La lista indica qué hallazgos confirmó el último análisis y cuáles de los hallazgos abiertos de análisis anteriores quedaron sin confirmar.

Compara los hallazgos de los dos análisis:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

La comparación vincula automáticamente los hallazgos por su causa raíz, reutiliza las coincidencias guardadas y clasifica los hallazgos como nuevos, persistentes, reabiertos, no observados, resueltos o de estado desconocido. Si un análisis posterior no detecta un hallazgo anterior en el código que revisó, el hallazgo se considera no observado. Solo se considera resuelto cuando se cierra de forma explícita porque ya se corrigió. El estado sigue siendo desconocido si la ruta se excluyó o la coincidencia es incierta.

¿Cómo se usa la información sobre falsos positivos?

Revisa el análisis guardado para encontrar el ID de la aparición del hallazgo:

npx @openai/codex-security scans show SCAN_ID

Registra por qué ese hallazgo no aplica:

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

Los análisis posteriores del mismo repositorio reciben esa explicación como contexto. Cada análisis comprueba por su cuenta el código fuente actual, los controles y si es posible llegar al código afectado. Descartar un hallazgo no excluye ninguna regla, ruta ni clase de vulnerabilidad.

Para obtener más información sobre el comando, consulta la referencia de hallazgos.

¿Por qué pueden variar los hallazgos al repetir un análisis?

Los análisis asistidos por IA pueden producir resultados distintos incluso con la misma configuración. Primero, vuelve a ejecutar el análisis de referencia:

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

La nueva ejecución conserva la configuración del análisis original y requiere la misma versión del complemento. Si cambió la versión instalada del complemento, el comando se detiene.

Compara el análisis de referencia con el nuevo:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Si la falta de contexto puede contribuir a la variación, proporciona las mismas pautas de arquitectura y seguridad para los análisis. La búsqueda de coincidencias permite reconocer un mismo hallazgo en distintas 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ó?

Vuelve a comprobar el hallazgo original en la copia de trabajo que contiene los cambios. Desde esa copia, indica el informe del análisis original y el problema que quieres validar:

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

Revisa la evidencia para confirmar que ya no es posible aprovechar la ruta vulnerable y que el código sigue funcionando en los casos de uso legítimos. Si está disponible, ejecuta el caso original que reproduce el problema o la prueba de regresión. Si no puedes realizar la comprobación, indica en el resultado qué queda por confirmar.

Una comparación de análisis puede mostrar cómo cambiaron los hallazgos, pero la ausencia de un hallazgo por sí sola no confirma que se haya corregido.

¿Qué significa que la cobertura sea incompleta?

En scan-manifest.json, consulta scan.status para saber si el análisis terminó. El campo scan.scope indica el alcance configurado. En scan.review.excludedPaths figuran los patrones de las rutas que el análisis excluyó de la revisión. Si un archivo de manifiesto anterior contiene el campo scan.coverageRef, abre el archivo al que apunta ese campo para consultar los detalles de cobertura.

Las brechas de cobertura no cambian el código de salida de un análisis completado. El código de salida 0 no significa que se hayan revisado todos los archivos. Si un análisis posterior no cubre la ruta original de un hallazgo, no puede confirmar que el problema haya desaparecido.

Automatización y costo

¿Cómo funcionan los límites de tiempo de los análisis profundos?

Al iniciar un análisis profundo, establece un plazo para los procesos de trabajo:

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

El plazo predeterminado es de 96 horas. Puedes usar cualquier valor positivo de hasta 96 horas, incluidas las fracciones de hora. Cuando vence el plazo, Codex Security detiene los procesos de trabajo que siguen en curso, conserva los resultados de los análisis estándar completados y los reúne en el informe final. Consulta el informe para ver qué áreas se revisaron y qué trabajo se pospuso. El vencimiento del plazo por sí solo no determina el código de salida. Este depende del estado de ejecución y de la política de severidad.

Para guardar esta configuración de forma persistente o aplicarla a campañas por lotes, define max_time_hours en la sección [deep_scan] de la configuración de análisis profundos.

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

Antes de iniciar el análisis, establece un límite de costo estimado en USD:

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

El límite se basa en una estimación y no impone un tope estricto al gasto. Las solicitudes que ya están en curso pueden hacer que el costo final supere ese límite. Si un análisis profundo alcanza el límite después de que Codex Security reúne los resultados de los procesos de trabajo completados, la CLI puede guardar un informe completo con una advertencia sobre el presupuesto. Devuelve 0, o 1 si algún hallazgo alcanza el umbral de severidad configurado. Si no puede producir un resultado completo y válido, devuelve 2 y conserva toda la salida disponible.

Para las comprobaciones de Pull Requests en GitHub y los análisis programados de repositorios, usa la GitHub Action de Codex Security. Con action-v0.3.0, un análisis completado indica que el análisis configurado produjo un resultado válido. La política de severidad se aplica incluso si se excluyeron áreas del análisis o se pospusieron investigaciones. Revisa coverage.json para evaluar el alcance y las limitaciones del análisis. Para rechazar también las diferencias vacías y las ejecuciones de prueba, exige que la salida scan-status de la GitHub Action tenga el valor completed. Consulta Cómo elegir una política de severidad.

Para otros proveedores, consulta la descripción general de CI/CD. Para ejecutar una comprobación antes de cada commit, usa install-hook.