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

Inicio rápido de Codex Security CLI

Configure Codex Security, ejecute un análisis local y revise el informe, los hallazgos y la cobertura.

Codex Security ayuda a los equipos de seguridad e ingeniería a encontrar, confirmar y corregir vulnerabilidades. Use su interfaz de línea de comandos (CLI) para analizar repositorios que sean de su propiedad o para cuya evaluación tenga permiso, revisar los hallazgos a lo largo del tiempo y comprobar los cambios antes de que se incorporen.

Comprobar los requisitos previos

La CLI requiere Node.js 22 (22.13.0 o posterior), 24 o 26. Los análisis, análisis masivos, exportaciones, el historial de análisis y los hallazgos guardados también requieren Python 3.10 o posterior. Para obtener más detalles, consulte Autenticación y requisitos previos.

Configurar y verificar la CLI

Ejecute la CLI con npx y compruebe su versión:

npx @openai/codex-security --version

Para ver tanto la versión del paquete como la versión del plugin incluido, ejecute:

npx @openai/codex-security info --json

Consulte las versiones de la CLI y el SDK para conocer los cambios del paquete.

Enumere los comandos disponibles:

npx @openai/codex-security --help

Consulte también la referencia de la CLI.

Iniciar sesión

Para uso local, inicie sesión con su cuenta de ChatGPT:

npx @openai/codex-security login

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

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

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

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

Para las credenciales de AWS, consulte la configuración de Amazon Bedrock. Para OpenRouter o Fireworks, configure la API key del proveedor y seleccione un modelo con --provider y --model.

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

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

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

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

Según su cuenta y repositorio, los análisis de repositorios completos también pueden requerir Trusted Access for Cyber.

Preparar un análisis

Elija un repositorio de confianza que tenga permiso para evaluar. Los análisis usan sus permisos locales del sistema operativo y no se detienen para solicitar aprobación. Los procesos de análisis pueden heredar su entorno, así que elimine las credenciales no relacionadas antes de comenzar. Consulte Permisos de análisis locales.

Elija un directorio fuera del repositorio para los resultados del análisis:

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

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

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

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

Compruebe 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, incluidas las rutas --knowledge-base, sin iniciar Codex, cargar credenciales ni sondear el intérprete de Python del plugin.

Ejecutar su primer análisis

Ejecute un análisis estándar y conserve sus resultados en el directorio seleccionado:

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

Los terminales interactivos muestran un panel de análisis en tiempo real. Añada --headless para mostrar líneas de progreso en texto sin formato. CI y los terminales sin una sesión interactiva usan automáticamente el progreso en texto sin formato.

El panel también muestra detalles de la sesión en tiempo real. Estos pueden contener código fuente o credenciales, así que revíselos antes de compartirlos.

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 finalizado imprime un resumen como este:

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  COVERAGE  complete
  ELAPSED   42s
  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, solicite explícitamente una salida estructurada:

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

Los análisis solo generan informes de forma predeterminada, por lo que los hallazgos siguen disponibles para su revisión local. Puede añadir un umbral de gravedad cuando esté listo para ejecutar análisis en CI.

Elegir un modelo y el esfuerzo de razonamiento

Los análisis usan gpt-5.6-sol con un esfuerzo de razonamiento xhigh de forma predeterminada. Seleccione un modelo y esfuerzo distintos cuando la tarea lo requiera:

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

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

Revisar los resultados

Abra report.md para ver 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. Lea las áreas aplazadas o las preguntas abiertas antes de tratar el análisis como prueba de una revisión. La referencia de la CLI describe el contrato completo de los artefactos y la salida.

Revisar y corregir hallazgos

Después de un análisis interactivo completo con hallazgos, la CLI ofrece un explorador de hallazgos. Revise las pruebas y elija qué hallazgos corregir. Puede encontrar las tareas guardadas en la aplicación de escritorio Codex.

Para corregir hallazgos de gravedad alta y crítica sin el explorador:

npx @openai/codex-security scan "$REPOSITORY" \
  --patch --patch-severity high --json

Añada --create-pr para confirmar mediante commit las correcciones verificadas y abrir una solicitud de incorporación de cambios en GitHub.

También puede corregir hallazgos guardados o importar incidencias de Linear. Consulte la referencia de validate y patch.

Elegir el siguiente análisis

Use un análisis de ruta cuando un repositorio contenga servicios o paquetes independientes:

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

Revise los cambios confirmados mediante commit entre la revisión base y HEAD:

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

Revise los cambios preparados y no preparados 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. Obtenga las revisiones seleccionadas antes de iniciar un análisis de diferencias.

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

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

Para controlar los procesos de trabajo, los subagentes y cuándo se detiene el análisis:

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

Estas opciones requieren el modo profundo, que admite objetivos de repositorio y ruta, pero no análisis de diferencias ni del árbol de trabajo. Aquí, --workers controla los procesos de trabajo de análisis estándar independientes dentro de un análisis; bulk-scan --workers controla los análisis de repositorios simultáneos. --max-time-hours acepta un número positivo hasta 96, incluidas horas fraccionarias. Al alcanzar el límite, el análisis detiene los procesos de trabajo sin terminar, conserva los resultados de análisis finalizados y los agrega al informe final.

Añadir contexto de arquitectura y seguridad

Proporcione 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 su sistema:

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

Añadir instrucciones de análisis personalizadas

Añada instrucciones que centren el análisis en sus prioridades de seguridad. Use un segundo archivo para las instrucciones de seguimiento:

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

El seguimiento se ejecuta en la misma sesión autenticada después de los análisis correctos y de los análisis con cobertura incompleta o errores. Si el seguimiento falla, la CLI muestra una advertencia y conserva el análisis finalizado. No se ejecuta después de una cancelación ni de un análisis que alcance su límite de costo. Ambas opciones también funcionan con bulk-scan; una columna CSV prompt añade instrucciones específicas del repositorio.

Establecer un presupuesto de análisis

Use --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 ligeramente por encima del límite. 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, marca su cobertura como partial y devuelve el código de salida 2. Si el análisis no puede generar un informe finalizado, cualquier salida parcial disponible permanece en el disco.

Analizar los cambios antes de cada commit

Instale una comprobación de seguridad de pre-commit de Git para su repositorio:

npx @openai/codex-security install-hook

La comprobación analiza los cambios preparados y no preparados antes de cada commit. Bloquea los hallazgos de gravedad alta y los errores de análisis sin sustituir un script de pre-commit existente.

Analizar repositorios de forma masiva

Inicie sesión en GitHub antes de descubrir repositorios:

gh auth login

Descubra y seleccione repositorios de su cuenta u organización de GitHub:

npx @openai/codex-security bulk-scan

El flujo interactivo excluye los repositorios archivados y las bifurcaciones. Le solicita que confirme los repositorios seleccionados antes de analizarlos.

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

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

Vuelva a ejecutar el mismo comando para reanudar un análisis masivo existente. Codex Security omite los repositorios finalizados. Añada --max-attempts 3 cuando desee reintentar errores temporales del repositorio o del análisis.

Para obtener información sobre el descubrimiento en GitHub, la preparación del CSV, los resultados de campañas y la configuración de Docker, consulte Ejecutar análisis de seguridad masivos.

Ejecutar análisis masivos en Docker

Si su acceso incluye la imagen de Docker de Codex Security, use 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. Proporcione un CSV de repositorios, conserve los resultados y el estado de inicio de sesión en directorios montados persistentes y proporcione las credenciales mediante su 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 masivos sin indicaciones interactivas. Use la CLI fuera de Docker cuando quiera descubrir repositorios de forma interactiva. Para repositorios privados, proporcione GH_TOKEN o GITHUB_TOKEN mediante su entorno o gestor de secretos. También se aplican a los análisis en contenedores los requisitos de inicio de sesión, incluido el acceso a la cuenta y al repositorio.

Volver a consultar un análisis guardado

Enumere los análisis guardados de su repositorio:

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

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

npx @openai/codex-security scans show SCAN_ID

Para inspeccionar los eventos guardados de un análisis y sus procesos de trabajo:

npx @openai/codex-security scans logs SCAN_ID

Los registros guardados no están redactados y pueden contener código fuente o credenciales. Revíselos antes de compartirlos.

Enumere los hallazgos abiertos de todos los análisis del repositorio:

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

Un hallazgo anterior permanece abierto cuando el análisis más reciente no lo confirma.

Para marcar un hallazgo revisado como falso positivo, explique por qué el hallazgo no es aplicable:

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.

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

npx @openai/codex-security scans rerun SCAN_ID

Compare dos análisis para encontrar hallazgos nuevos, persistentes, reabiertos, resueltos o desconocidos:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

La comparación empareja automáticamente los hallazgos según la causa raíz y reutiliza las coincidencias guardadas.

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

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