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 chatgptPara exigir una API key de OPENAI_API_KEY o CODEX_API_KEY:
npx @openai/codex-security scan . --auth api-keyPara 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 3Los 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/repositoryUsa un ID de análisis de los resultados para inspeccionar sus hallazgos:
npx @openai/codex-security scans show SCAN_IDCada 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-stateCó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/repositoryLa 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_IDLa 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_IDRegistra 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_IDLa 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_IDProporciona 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.5El 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 5El 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.