Documentación de ChatGPT
Español
Contacto goolvyouyou@gmail.com

Inicio rápido de Codex Security CLI

Configura Codex Security, ejecuta un análisis local y revisa el informe, los hallazgos y la cobertura.

Codex Security ayuda a los equipos de seguridad e ingeniería a encontrar, confirmar y corregir vulnerabilidades. Usa su interfaz de línea de comandos (CLI) para analizar repositorios que poseas o tengas permiso para evaluar, revisar los hallazgos a lo largo del tiempo y comprobar los cambios antes de que se incorporen.

Comprueba los requisitos previos

La CLI requiere Node.js 22 o posterior. Para ejecutar un análisis o exportar hallazgos también se requiere Python 3.10 o posterior. Para obtener más información, consulta Autenticación y requisitos previos.

Configura y verifica la CLI

Instala el paquete publicado:

npm install @openai/codex-security

Enumera los comandos disponibles:

npx @openai/codex-security --help

Consulta también la referencia de la CLI.

Inicia sesión

Para uso local, inicia sesión con tu cuenta de ChatGPT:

npx @openai/codex-security login

En una máquina remota o sin interfaz gráfica, usa la autenticación de dispositivo:

npx @openai/codex-security login --device-auth

Para CI y otros flujos de trabajo automatizados, configura una OpenAI API key:

export OPENAI_API_KEY="<your-api-key>"

Para las credenciales de AWS, consulta la configuración de Amazon Bedrock.

Para usar tu inicio de sesión de ChatGPT cuando también haya una API key configurada, selecciónalo explícitamente:

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

Para exigir la API key del entorno, selecciona la autenticación mediante API key:

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

Según tu cuenta y repositorio, los análisis del repositorio completo también pueden requerir Trusted Access for Cyber.

Prepara un análisis

Elige un repositorio que quieras analizar y un directorio donde escribir los resultados.

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

Si omites --output-dir, Codex Security guarda los resultados en su propio directorio persistente de estado. Los resultados pueden incluir fragmentos del código fuente y detalles de vulnerabilidades, así que elige una ubicación privada y una política de retención adecuada.

Si no se puede escribir en el directorio de estado predeterminado, selecciona un directorio con permisos de escritura fuera del repositorio analizado:

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

Comprueba el repositorio, el objetivo y el directorio de salida antes de iniciar un análisis:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

La ejecución de prueba comprueba las entradas locales sin iniciar Codex, cargar credenciales ni examinar el intérprete de Python del plugin.

Ejecuta tu primer análisis

Ejecuta un análisis estándar y conserva sus resultados en el directorio seleccionado:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

De forma predeterminada, la CLI escribe el progreso del análisis y su resumen de finalización en stderr. No imprime el resultado completo del análisis en stdout. Un análisis completado imprime un resumen como este:

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: Results: /path/outside/repository/codex-security-results

El uso de tokens y el costo estimado aparecen cuando están disponibles. Para imprimir el resultado completo como JSON legible por máquinas, solicita explícitamente una salida estructurada:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

De forma predeterminada, los análisis solo generan informes, por lo que los hallazgos permanecen disponibles para su revisión local. Cuando estés listo para ejecutar análisis en CI, quizá quieras añadir un umbral de gravedad.

Elige un modelo y un nivel de razonamiento

De forma predeterminada, los análisis usan gpt-5.6-sol con un nivel de razonamiento xhigh. Selecciona un modelo y un nivel diferentes cuando la tarea lo requiera:

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

Los niveles admitidos son minimal, low, medium, high y xhigh.

Revisa los resultados

Abre report.md para consultar el resultado legible. El directorio del análisis también contiene los archivos estructurados utilizados por la automatización:

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json registra el objetivo, el alcance, el productor y los artefactos sellados.
  • findings.json registra la gravedad, la confianza, las ubicaciones, las pruebas y la corrección de cada hallazgo.
  • coverage.json registra las superficies revisadas, las exclusiones, el trabajo aplazado, las preguntas abiertas y la exhaustividad de la cobertura.

La cobertura puede ser complete, partial o unknown. Lee todas las áreas aplazadas o preguntas abiertas antes de tratar el análisis como evidencia de una revisión. La referencia de la CLI describe el contrato completo de los artefactos y la salida.

Elige el siguiente análisis

Usa un análisis de ruta cuando un repositorio contenga servicios o paquetes separados:

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

Revisa los cambios confirmados entre la revisión base y HEAD:

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

Revisa los cambios preparados y no preparados con respecto a HEAD:

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

Los análisis de diferencias y del árbol de trabajo esperan que el argumento del repositorio sea la raíz del árbol de trabajo de Git. Obtén las revisiones seleccionadas antes de iniciar un análisis de diferencias.

Usa el modo profundo cuando un repositorio o una ruta necesiten una revisión más amplia:

npx @openai/codex-security scan "$REPOSITORY" --mode deep

El modo profundo admite objetivos de repositorio y de ruta, pero no análisis de diferencias ni del árbol de trabajo.

Añade contexto de arquitectura y seguridad

Proporciona documentos de arquitectura, modelos de amenazas o políticas de seguridad como contexto del análisis. Esto ayuda a Codex Security a evaluar los hallazgos según el funcionamiento real de tu sistema:

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

Establece un presupuesto de análisis

Usa --max-cost para detener un análisis cuando el costo estimado del modelo supere un límite en USD:

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

Las solicitudes que ya estén en curso pueden finalizar por encima del límite. Codex Security conserva los resultados disponibles cuando se detiene un análisis.

Analiza los cambios antes de cada confirmación

Instala una comprobación de seguridad previa a la confirmación de Git en tu repositorio:

npx @openai/codex-security install-hook

La comprobación analiza los cambios preparados y no preparados antes de cada confirmación. Bloquea los hallazgos de gravedad alta y los errores del análisis sin reemplazar ningún script previo a la confirmación existente.

Analiza repositorios en bloque

Inicia sesión en GitHub antes de detectar repositorios:

gh auth login

Detecta y selecciona repositorios de tu cuenta u organización de GitHub:

npx @openai/codex-security bulk-scan

El flujo interactivo excluye los repositorios archivados y las bifurcaciones. Te pide que confirmes los repositorios seleccionados antes de analizarlos.

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

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

Ejecuta de nuevo el mismo comando para reanudar un análisis en bloque existente. Los repositorios completados cuyos artefactos de resultados estén intactos no se vuelven a analizar. Añade --max-attempts 3 cuando quieras volver a intentar errores temporales del repositorio o del análisis.

Para la detección en GitHub, la preparación del CSV, los resultados de campañas y la configuración de Docker, consulta Ejecutar análisis de seguridad en bloque.

Ejecuta análisis en bloque en Docker

Si tu acceso incluye la imagen de Docker de Codex Security, usa la configuración reforzada de Compose y el perfil de seguridad suministrados en un host de Docker con Linux. El host debe admitir la creación de espacios de nombres de usuario sin privilegios. Proporciona un CSV de repositorios, conserva los resultados y el estado de inicio de sesión en directorios montados persistentes y proporciona las credenciales mediante tu entorno o un gestor de secretos:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

El contenedor ejecuta análisis en bloque sin solicitudes interactivas. Usa la CLI fuera de Docker cuando quieras detectar repositorios de forma interactiva. Para repositorios privados, proporciona GH_TOKEN o GITHUB_TOKEN mediante tu entorno o un gestor de secretos. Los requisitos de inicio de sesión, incluido el acceso a la cuenta y al repositorio, también se aplican a los análisis en contenedores.

Vuelve a consultar un análisis guardado

Enumera los análisis guardados de tu repositorio:

npx @openai/codex-security scans list "$REPOSITORY"

Copia un ID de análisis de los resultados para inspeccionar sus hallazgos y su configuración:

npx @openai/codex-security scans show SCAN_ID

Para marcar un hallazgo revisado como falso positivo, explica por qué no corresponde:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

Los análisis posteriores tienen en cuenta esa explicación, pero aun así vuelven a comprobar el código actual.

Ejecuta el mismo análisis en la copia de trabajo actual con su configuración original:

npx @openai/codex-security scans rerun SCAN_ID

Para comparar dos análisis, primero relaciona los hallazgos que compartan la misma causa raíz:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Después, comprueba qué hallazgos son nuevos, persisten, se han reabierto, se han resuelto o son desconocidos:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Para conocer el formato CSV del análisis en bloque, los filtros del historial de análisis y las opciones de los comandos, consulta la referencia de la CLI.

Continúa con el flujo de trabajo que se ajuste a tu objetivo: