Preguntas frecuentes sobre Codex Security CLI

Respuestas sobre los análisis de Codex Security, los hallazgos, los falsos positivos, la cobertura, el costo y la CI.

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

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.

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

Los análisis completados conservan sus resultados y no se reintentan, aunque queden lagunas en la cobertura. Las lagunas en la 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

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, manifiesto y artefactos complementarios. Consulta Artefactos del análisis para ver 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 ocultan información confidencial 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 entorno 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 su causa raíz, reutiliza las coincidencias guardadas e identifica hallazgos nuevos, persistentes, reabiertos, no observados, resueltos y desconocidos. Cuando un análisis posterior no encuentra un hallazgo anterior en el código que analizó, el hallazgo se considera no observado. Solo se considera resuelto después de que se cierre explícitamente como ya corregido. Las rutas excluidas y las coincidencias inciertas permanecen como desconocidas.

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ó

Vuelve a comprobar el hallazgo original en la copia de trabajo modificada. Desde esa copia de trabajo, pasa tu informe 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 las pruebas de que la vía vulnerable está cerrada y de que el comportamiento legítimo sigue funcionando. Ejecuta el caso de reproducción original o la prueba de regresión cuando estén disponibles. Si no se puede ejecutar la comprobación, indique en el resultado la incertidumbre restante.

Una comparación de análisis puede mostrar cómo cambiaron los hallazgos, pero la ausencia de un hallazgo por sí sola no verifica una corrección.

Qué significa una cobertura incompleta

En scan-manifest.json, comprueba scan.status para ver si el análisis finalizó. scan.scope registra el alcance configurado. scan.review.excludedPaths enumera los patrones de rutas que el análisis excluyó de la revisión. Si un manifiesto anterior tiene scan.coverageRef, abre el archivo que indica para obtener detalles de la cobertura.

Las lagunas en la 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. Un análisis posterior no puede determinar que un hallazgo anterior ya no existe si 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. Al llegar al límite de tiempo, Codex Security detiene los procesos de trabajo sin finalizar, conserva los resultados de los análisis estándar completados y los integra en el informe final. Consulta el informe para ver las áreas revisadas y el trabajo pospuesto. El límite de tiempo por sí solo no determina el código de salida; lo determinan el estado de ejecución y la política de gravedad.

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 estricto de gasto. 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 integre los resultados completados de los procesos de trabajo, la CLI puede guardar un informe completado con una advertencia sobre el presupuesto. Devuelve 0, o 1 si los hallazgos alcanzan el umbral de gravedad configurado. Si no puede producir un resultado completado válido, devuelve 2 y conserva cualquier salida disponible.

Para las comprobaciones de pull requests de GitHub y los análisis programados de repositorios, usa la acción de GitHub de Codex Security. Con action-v0.3.0, un análisis completado significa que el análisis configurado produjo un resultado válido. Las exclusiones de alcance y las investigaciones aplazadas no eluden la política de gravedad. Revisa coverage.json para evaluar el alcance y las limitaciones del análisis. Para rechazar también los diffs vacíos y las ejecuciones de prueba, exige que la salida scan-status de la acción sea completed; consulta Elegir una política de gravedad.

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