Referencia de la CLI de Codex Security

Consulta los comandos y las opciones de codex-security, los formatos de salida y los códigos que devuelve al finalizar. Para ejecutar tu primer análisis, sigue la guía de inicio rápido de la CLI.

Ejecuta la CLI con npx @openai/codex-security. El paquete instalado también proporciona el alias cs.

Resumen de comandos

usage: codex-security [--version] <command> [options]

La CLI ofrece los siguientes comandos:

La CLI también ofrece estos comandos de integración:

Lista todos los comandos disponibles:

npx @openai/codex-security --help

Agrega --help a un comando para consultar sus argumentos y opciones:

npx @openai/codex-security scan --help

codex-security --version muestra la versión instalada y finaliza. codex-security info --json muestra las versiones del SDK y del complemento incluido. Ninguno de los dos comandos requiere Python. Usa codex-security --update para actualizar la CLI instalada.

Consultar comandos y conectar agentes

Muestra el archivo de manifiesto de comandos que pueden leer los agentes:

npx @openai/codex-security --llms

Consulta el esquema de argumentos del análisis en formato JSON:

npx @openai/codex-security scan --schema --format json

Genera el script de autocompletado para Bash:

npx @openai/codex-security completions bash

Reemplaza bash por zsh o fish si usas uno de esos shells.

Los resultados de los análisis admiten --format toon|json|yaml|jsonl y --full-output. --export-format selecciona el formato de un artefacto que se exporta de un análisis completado. La ayuda global de los comandos también incluye md, pero los resultados de los análisis no admiten la salida en Markdown.

Registra la CLI como servidor MCP:

npx @openai/codex-security mcp add

Sincroniza las habilidades de Codex Security con tus agentes:

npx @openai/codex-security skills add

La CLI solo ofrece el comando de metadatos de solo lectura info a través de su servidor MCP. Los análisis, las exportaciones, la publicación, la autenticación, la validación y la aplicación de parches solo están disponibles desde la CLI.

codex-security scan

Analiza un repositorio, rutas seleccionadas, cambios incluidos en commits o el árbol de trabajo.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--config FILE]
                           [--cyber-access-program PROGRAM]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH] [--scan-prompt-file FILE]
                           [--validation-prompt-file FILE]
                           [--post-scan-prompt-file FILE]
                           [--mode {standard,deep}] [--workers N]
                           [--subagents N] [--stop-after-no-new N]
                           [--max-discovery-runs N] [--max-time MINUTES]
                           [--model MODEL]
                           [--effort EFFORT]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--validate] [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--show-cost] [--dry-run] [--mock]
                           [--workflow-id ID] [--safety-identifier ID]
                           [--headless] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

El valor predeterminado de repository es el directorio actual.

Cargar la configuración del proyecto

Crea una configuración inicial y selecciónala explícitamente:

npx @openai/codex-security init codex-security.yaml
npx @openai/codex-security scan . --config codex-security.yaml

init no sobrescribe archivos existentes. Usa -c FILE como abreviatura de --config FILE o define CODEX_SECURITY_PROJECT_CONFIG. Una opción explícita tiene prioridad sobre la variable de entorno. La CLI no busca automáticamente un archivo de configuración del proyecto.

Selecciona únicamente configuraciones que controles. Tienen la misma autoridad que las opciones de la CLI: los ajustes nativos de Codex pueden iniciar procesos de servidores MCP y elegir a qué servicios de modelos se envían las solicitudes. No selecciones un archivo controlado por un repositorio o un pull request que no sea de confianza. En CI, mantén la configuración del analizador fuera de la copia de trabajo que vas a evaluar. Consulta la guía de configuración del proyecto para conocer los ajustes y su orden de prioridad.

Seleccionar la autenticación del análisis

Usa --auth auto, la opción predeterminada, para seleccionar las credenciales automáticamente. Si tienes una sesión de ChatGPT y también una clave en OPENAI_API_KEY o CODEX_API_KEY, los análisis interactivos con salida de texto te preguntan qué credencial usar. Los análisis en CI, los que generan JSON o JSONL y los demás análisis sin terminal interactiva usan la clave de API del entorno. Las simulaciones no solicitan ni cargan credenciales.

Para usar tus credenciales almacenadas, pasa --auth chatgpt:

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

Para usar una clave de API del entorno, pasa --auth api-key:

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

Para que la selección automática use de forma predeterminada las credenciales almacenadas, ejecuta unset OPENAI_API_KEY CODEX_API_KEY.

Usa --auth api-key con --cyber-access-program standard|daybreak_blue|daybreak_red para seleccionar un programa de acceso de ciberseguridad para las solicitudes a modelos de OpenAI. Si omites la opción, se conservan los valores predeterminados de Codex. Con standard seleccionas explícitamente el programa estándar. Seleccionar un programa no otorga acceso. Tu proyecto de API debe contar con la aprobación para ese programa. Consulta la guía de programas de acceso para conocer los requisitos de credenciales.

Atribuir análisis a usuarios finales

Cuando ejecutas análisis en nombre de usuarios, --safety-identifier ID acepta un identificador estable generado mediante hash si usas autenticación con clave de API. Usa entre 1 y 64 caracteres, sin caracteres NUL ni datos personales, como direcciones de correo electrónico.

Para transmitir el identificador, usa CODEX_CLI_PATH para seleccionar una compilación de Codex compatible con esta opción y usa un complemento que pase el identificador a los procesos de análisis. El entorno de ejecución de Codex incluido no admite esta opción.

Usar OpenRouter o Fireworks

Selecciona OpenRouter con su clave de API y especifica un modelo:

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
  --provider openrouter \
  --model anthropic/claude-sonnet-4.5

Selecciona Fireworks con su clave de API y especifica un modelo:

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
  --provider fireworks \
  --model accounts/fireworks/models/qwen3-235b-a22b

Ambos proveedores también admiten bulk-scan.

Usar Amazon Bedrock

Usa --provider amazon-bedrock y un ID de modelo de Bedrock con scan o bulk-scan. Una vez que AWS habilita el acceso al modelo, los análisis usan credenciales de AWS sin necesidad de --auth, una sesión de OpenAI ni una clave de API de OpenAI.

Daybreak Blue y Daybreak Red

Daybreak Blue y Daybreak Red requieren la aprobación de Trusted Access for Cyber. Para solicitar acceso, envía la solicitud de acceso empresarial o ponte en contacto con el equipo de OpenAI que administra tu cuenta. Una vez que obtengas la aprobación, coordina con el equipo de AWS que administra tu cuenta para habilitar el acceso al modelo en Amazon Bedrock.

La aprobación de Daybreak Red no incluye el acceso a GPT-5.6-Cyber. GPT-5.6-Cyber requiere una aprobación independiente del gobierno de Estados Unidos (USG). Pide al equipo de OpenAI que administra tu cuenta que solicite esta aprobación adicional antes de habilitar GPT-5.6-Cyber en Amazon Bedrock. Consulta los requisitos de acceso a Daybreak.

Para consultar la disponibilidad, revisa las tarjetas de los modelos de AWS para Daybreak Blue y Daybreak Red.

Para ejecutar un análisis con Daybreak Blue, reemplaza <aws-profile-name> por un perfil de AWS que tenga acceso al modelo Daybreak Blue:

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-daybreak-blue-5.6-sol --effort high

Para ejecutar un análisis con Daybreak Red, elige un perfil de AWS con acceso a GPT-5.6-Cyber. Puede ser distinto del que usas para Daybreak Blue:

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-cyber --effort high

También puedes autenticarte con AWS_BEARER_TOKEN_BEDROCK o con la cadena estándar de credenciales de AWS. Las claves de acceso temporales requieren AWS_SESSION_TOKEN. Configura las credenciales y AWS_REGION en el mismo shell o trabajo de CI donde se ejecuta el análisis.

Resultados locales y comprobaciones de acceso

Los informes locales guardados, scans show y export funcionan sin credenciales de la nube.

info y scan --dry-run no comprueban las credenciales de AWS ni el acceso al modelo. Ejecuta un análisis para comprobar el acceso. Si recibes errores de autenticación de AWS o de acceso denegado, revisa tus credenciales, la región y los permisos del modelo.

Estimaciones de costos de Bedrock

La CLI admite estimaciones de costos y --max-cost para los ID de modelo de Daybreak Blue y Daybreak Red indicados arriba. Las estimaciones usan las tarifas comerciales estándar de AWS dentro de la región e incluyen la comisión de AWS. El límite de costo se basa en estimatedUsd, la estimación de referencia para contextos cortos. Las solicitudes en curso pueden hacer que la estimación supere el límite. Las tarifas de contexto largo pueden hacer que el valor reportado en estimatedUsdRange también lo supere. Este límite no establece un tope de facturación.

Seleccionar el objetivo del análisis

Elige un tipo de objetivo para cada análisis.

--path, --diff y --working-tree son mutuamente excluyentes. --head requiere --diff y --base requiere --working-tree. El modo profundo admite repositorios y rutas como objetivos.

Para los análisis de diferencias y del árbol de trabajo, el argumento del repositorio debe ser la raíz del worktree de Git. Las referencias seleccionadas deben existir en esa copia de trabajo.

Analiza todo el repositorio:

npx @openai/codex-security scan .

Analiza rutas seleccionadas:

npx @openai/codex-security scan . --path src --path tests

Analiza cambios incluidos en commits:

npx @openai/codex-security scan . --diff origin/main --head HEAD

Analiza cambios preparados y sin preparar:

npx @openai/codex-security scan . --working-tree --base HEAD

Ejecuta una revisión más profunda del repositorio:

npx @openai/codex-security scan . --mode deep

Configurar análisis profundos

Usa estas opciones con --mode deep para controlar la búsqueda de hallazgos:

Por ejemplo, usa dos procesos, permite hasta diez ejecuciones y detén la búsqueda después de 90 minutos:

npx @openai/codex-security scan . \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time 90

Cuando se agota el tiempo, el análisis detiene los procesos que siguen activos y reúne en su informe los hallazgos de los procesos completados. Para un análisis estándar, --max-time indica un tiempo orientativo de investigación. La generación del informe puede terminar más tarde. La validación personalizada y las instrucciones posteriores al análisis se ejecutan fuera de ese plazo.

Para reutilizar estos límites, guárdalos en un archivo de configuración del proyecto:

scan:
  mode: deep
  max_time_minutes: 90
  deep:
    workers: 2
    subagents_per_worker: 0
    stop_after_no_new: 3
    max_discovery_runs: 10

Las opciones de la línea de comandos tienen prioridad sobre la configuración del proyecto. Usa scan.deep.stop_after_consecutive_errors para cambiar cuántos errores consecutivos de los procesos de análisis detienen la búsqueda. El valor predeterminado es 3. Para bulk-scan, --workers controla el número de repositorios que se analizan en paralelo.

Agregar contexto de seguridad

Usa --knowledge-base PATH para proporcionar documentos de arquitectura, modelos de amenazas o políticas de seguridad. Repite la opción para agregar más archivos o directorios:

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

Se admiten archivos de texto UTF-8 (incluidos JSON y SARIF), PDF y DOCX. La CLI recorre los directorios de forma recursiva, rechaza las rutas de entrada con enlaces y omite las entradas de directorio que son enlaces. Guarda los documentos extraídos junto a los artefactos del análisis en el archivo privado de continuación .scan-knowledge.json para poder reanudar el análisis. Conserva este archivo con el directorio del análisis. Los informes canónicos no incluyen el texto de los documentos.

Agregar instrucciones de análisis

Para agregar instrucciones de análisis, proporciona un archivo de texto o Markdown con --scan-prompt-file. Usa --post-scan-prompt-file para ejecutar instrucciones de seguimiento en la misma sesión autenticada después de los análisis que se completan correctamente o devuelven errores:

npx @openai/codex-security scan . \
  --scan-prompt-file security-focus.md \
  --post-scan-prompt-file follow-up.md

Por ejemplo, usa el prompt de análisis para centrar la revisión en los límites de autorización y pide en las instrucciones de seguimiento que se escriba un nuevo archivo post-scan-summary.md en el directorio del análisis. Si falla el seguimiento, la CLI muestra una advertencia y conserva el análisis completado. El seguimiento no se ejecuta si se cancela el análisis o si este alcanza su límite de costo. Cuando se ejecuta, su costo queda fuera del seguimiento de costos del análisis y del límite de --max-cost.

Validar hallazgos en tu entorno

Usa --validation-prompt-file FILE para reemplazar el paso final de validación por tu propio procedimiento de prueba. Codex revisa primero el código fuente y omite la validación si no encuentra posibles hallazgos. Guarda el prompt y el script de prueba en un directorio que controles fuera de la copia de trabajo:

npx @openai/codex-security scan . \
  --validation-prompt-file /path/to/security-tests/validation.md

Por ejemplo, si tu servidor de pruebas local está en ejecución, incluye estas instrucciones en validation.md:

Run /path/to/security-tests/validate.sh against http://localhost:3000.
Report which findings reproduce and include the relevant test output.

Usa esta opción con análisis estándar de repositorios, rutas, diferencias o árboles de trabajo. Para los análisis estándar de componentes, define scan.validation_file en la configuración del proyecto. Los análisis profundos no admiten la validación personalizada.

Agrega --validate al comando de un nuevo análisis para evaluar por separado cada hallazgo reportado usando únicamente el código fuente. Si el análisis reporta hallazgos, la CLI escribe las evaluaciones en un informe en el directorio del análisis. Estas evaluaciones no modifican los hallazgos ni el resultado de aplicar la política de gravedad. No puedes combinar --validate con --dry-run, --mock ni con un límite de costo del análisis definido en la línea de comandos o en la configuración del proyecto.

Configurar las opciones de salida y de política

Usa estas opciones para guardar artefactos, conservar resultados anteriores o generar resultados legibles por máquina.

El modo de datos sintéticos admite análisis estándar de repositorios, rutas y diferencias. No puedes combinarlo con --dry-run, --patch, el modo profundo, la validación personalizada ni los prompts posteriores al análisis. Los prompts de análisis y las bases de conocimiento no modifican los hallazgos sintéticos. Usa un CODEX_SECURITY_STATE_DIR independiente para evitar que los resultados sintéticos aparezcan en tu historial de análisis.

El límite de costo se basa en estimatedUsd, la estimación de referencia para contextos cortos. Las solicitudes en curso pueden hacer que la estimación supere el límite. Las tarifas de contexto largo pueden hacer que estimatedUsdRange también lo supere. Este límite no establece un tope de facturación.

Si un análisis profundo alcanza el límite después de que Codex Security reúne los resultados de los procesos completados, la CLI puede sellar el resultado completo y mostrar la advertencia de presupuesto. Devuelve 0, o 1 si los hallazgos alcanzan el umbral de gravedad configurado. Si no puede generar un resultado completo válido, devuelve 2 y conserva en el disco toda la salida disponible.

Si omites --output-dir, los resultados se conservan en $CODEX_HOME/state/plugins/codex-security/scans/<repository>. El valor predeterminado de CODEX_HOME es ~/.codex. Define CODEX_SECURITY_STATE_DIR para guardar los resultados en $CODEX_SECURITY_STATE_DIR/scans/<repository>. Estos directorios pueden contener fragmentos de código fuente y detalles de vulnerabilidades. Tenlo en cuenta al administrar sus permisos y su plazo de conservación.

El entorno de trabajo guarda el historial de análisis en $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Al definir CODEX_SECURITY_STATE_DIR, también cambia la ubicación de la base de datos del entorno de trabajo.

El directorio de salida debe estar fuera del directorio analizado y de cualquier worktree de Git que lo contenga. Usa --archive-existing para conservar los resultados anteriores antes de reutilizar un directorio de salida:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

De forma predeterminada, los análisis solo generan informes. Agrega --fail-on-severity para evaluar una política de gravedad en CI:

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

Una simulación comprueba las entradas locales, incluidos los documentos de la base de conocimiento, sin cargar credenciales, iniciar Codex ni probar el intérprete de Python del complemento:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

Configurar el entorno de ejecución

Usa las opciones del entorno de ejecución para seleccionar un modelo, un intérprete, un complemento o un valor de configuración de Codex.

Codex Security acepta los ID de modelo y los valores de esfuerzo de razonamiento como cadenas de texto. Las combinaciones admitidas dependen del modelo, del proveedor, de la versión de Codex y de tus credenciales.

Si la configuración aislada de Codex para el análisis selecciona un perfil, los valores model y model_reasoning_effort de ese perfil tienen prioridad sobre --model y --effort. Tu configuración habitual de Codex no se carga. Agrega --dry-run --verbose al comando de análisis para consultar el modelo y el esfuerzo que se usarán antes de iniciar el análisis.

Para elegir un modelo y un esfuerzo de razonamiento, selecciona un modelo de Codex disponible para tu cuenta:

npx @openai/codex-security scan . --model gpt-6.1-sol --effort medium

Escribe entre comillas los valores de texto que pases mediante --codex para que el analizador TOML reciba una cadena:

npx @openai/codex-security scan . --codex 'model="gpt-6.1-sol"'

Los valores de modelo y esfuerzo se pasan a Codex sin cambios. Si la combinación no es compatible, Codex o el proveedor devuelve un error sin sustituir el modelo ni el esfuerzo por otro.

codex-security scan import

Guarda hallazgos existentes como un análisis completado en el historial local sin ejecutar un análisis de seguridad ni llamar a modelos. La importación no requiere autenticación para usar modelos.

usage: codex-security scan import (--csv FILE | --json FILE)
                                  [--output-dir DIR] [--archive-existing]
                                  [--dry-run] [--format json]

Proporciona exactamente una entrada. El formato CSV usa las columnas de exportación de Codex Security. Para JSON, se acepta un documento codex-security.findings completo o un objeto que contenga un arreglo findings que cumpla con el esquema de hallazgos. No se aceptan como hallazgos guardados archivos JSON arbitrarios de otros analizadores ni arreglos de alertas de GitHub sin procesar.

Guarda este ejemplo sintético como findings.csv:

occurrence_id,finding_id,title,summary,severity,confidence,status,close_reason,note,remediation,path,start_line,end_line
occ_000000000000000000000001,csf_000000000000000000000001,Missing authorization check,The route reads a record without checking ownership,high,high,open,,,Check record ownership before returning data,src/routes.ts,18,18

Valida el archivo y luego impórtalo:

npx @openai/codex-security scan import --csv findings.csv --dry-run --format json
npx @openai/codex-security scan import --csv findings.csv --format json

La simulación muestra dryRun: true y findingCount: 1 sin guardar un análisis. La importación devuelve el ID del análisis guardado y las rutas de los resultados. Para importar un archivo JSON:

npx @openai/codex-security scan import --json findings.json --format json

En este comando, --json FILE selecciona el archivo de entrada. Usa --format json para obtener la salida en JSON.

Usa un archivo de entrada normal cuya ruta no contenga enlaces simbólicos ni puntos de unión de directorios. Cada importación conserva todas las apariciones de los hallazgos, incluidos los duplicados, y guarda la entrada en artifacts/import/. Los identificadores originales se guardan en extensions.import. El estado completado indica que finalizó la importación, sin implicar que se haya revisado el código fuente. scans rerun SCAN_ID vuelve a importar la entrada guardada.

Para analizar un repositorio llamado import, usa scan ./import.

codex-security import github

Lee alertas de análisis de código de GitHub sin modificar GitHub ni crear una copia de trabajo del código:

npx @openai/codex-security import github example/repository --format json > /path/outside/repository/alerts.json
npx @openai/codex-security import github example/repository \
  --github-alert 12 --github-alert 18 --format json

Reemplaza example/repository por tu repositorio. Autentícate con credenciales de la CLI de GitHub que tengan acceso de lectura al análisis de código. De forma predeterminada, la importación lee las alertas abiertas de la rama predeterminada, incluidas las de archivos SARIF cargados por terceros.

No combines números de alerta específicos con un estado distinto de open. El comando devuelve un arreglo de alertas del servicio de origen sin guardar un análisis. Desde el repositorio local correspondiente, ejecuta codex-security validate /path/outside/repository/alerts.json para evaluarlas. Al guardar las entradas de validación, conserva el JSON completo sin filtros de salida ni límites de tokens. Usa scan import para los hallazgos que ya cumplen con el esquema de Codex Security. Para importar alertas de Dependabot, usa publish findings.

codex-security install-hook

Instala la CLI fuera del repositorio, inspecciona el hook de pre-commit existente en el repositorio y ejecuta la CLI instalada desde fuera de la copia de trabajo:

git -C /path/to/repository rev-parse --git-path hooks/pre-commit
codex-security install-hook /path/to/repository

La comprobación analiza los cambios preparados y sin preparar antes de cada commit y bloquea el commit si detecta hallazgos de gravedad alta o crítica o errores de análisis. Los hooks locales son opcionales. Para exigir la comprobación, configúrala como obligatoria en CI. Deja que sus propietarios administren los hooks y directorios de hooks personalizados, enlazados o compartidos. El instalador no reemplaza scripts de pre-commit ajenos. Si es necesario, define un umbral de gravedad distinto:

codex-security install-hook /path/to/repository --fail-on-severity medium

codex-security policy

Redacta una política SECURITY.md que describa los límites de seguridad del proyecto y qué debe considerarse un hallazgo:

npx @openai/codex-security policy .
npx @openai/codex-security policy . --headless --json

El comando guarda un borrador fuera del repositorio sin modificar los archivos existentes. Revisa el borrador, las diferencias y las notas de revisión. Luego copia únicamente el archivo SECURITY.md revisado al destino que se muestra para la política. En el modo sin interfaz interactiva, las preguntas sin respuesta quedan en las notas de revisión. Generar una política es opcional. Los análisis pueden usar una política existente o ejecutarse sin ella. Consulta la guía de políticas para conocer las opciones y cómo delimitar el alcance por ruta.

codex-security scan-components

Usa scan-components para analizar por separado servicios o paquetes de un mismo repositorio. Cada ejecución, incluso si solo genera un plan, necesita un directorio de salida nuevo o vacío fuera del worktree de Git que contiene el código que vas a analizar. Defínelo con --output-dir o con output.directory en la configuración del proyecto.

Por ejemplo, analiza dos servicios en paralelo:

npx @openai/codex-security scan-components . \
  --component apps/api --component apps/web \
  --output-dir /path/outside/repository/manual-components

A diferencia de scan --path, este comando genera un análisis por componente y luego combina los hallazgos e identifica las coincidencias. De forma predeterminada, se pueden analizar cuatro componentes a la vez. Define --workers N para cambiar ese límite. --max-cost USD limita el costo de cada análisis de componente. El límite excluye la planificación automática y la búsqueda de coincidencias entre componentes.

Para que Codex proponga cómo dividir el repositorio, guarda un plan y revísalo antes del análisis:

npx @openai/codex-security scan-components . --auto --plan-only \
  --output-dir /path/outside/repository/component-plan

Revisa los nombres y las rutas de los componentes en components.json y luego ejecuta el plan guardado con un directorio de salida nuevo:

npx @openai/codex-security scan-components . \
  --components-file /path/outside/repository/component-plan/components.json \
  --output-dir /path/outside/repository/components

Abre report.md en el directorio de salida para revisar los hallazgos combinados. Si falla el análisis de algún componente, usa el plan de reintento guardado para volver a analizar solo los componentes que fallaron:

npx @openai/codex-security scan-components . \
  --components-file /path/outside/repository/components/retry-components.json \
  --output-dir /path/outside/repository/retry-results

El informe del reintento solo abarca los componentes que se volvieron a analizar. Conserva el informe original para revisar los hallazgos de los componentes cuyo análisis se completó en la primera ejecución.

Los errores de análisis o de búsqueda de coincidencias devuelven 2. Los incumplimientos de la política de gravedad devuelven 1. Consulta la guía de análisis de componentes para conocer la sintaxis del plan y cómo realizar reintentos.

codex-security bulk-scan

Detecta y analiza repositorios de GitHub o ejecuta un análisis que se puede reanudar a partir de un archivo CSV de repositorios.

Para obtener información sobre la detección de repositorios en GitHub, los inventarios CSV, los resultados de campañas y los análisis en contenedores, consulta Ejecutar análisis de seguridad por lotes.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort EFFORT]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Ejecuta npx @openai/codex-security bulk-scan sin argumentos para seleccionar repositorios de forma interactiva. Este flujo requiere que inicies sesión en la CLI de GitHub.

Para la detección interactiva, selecciona un modelo de Codex disponible para tu cuenta:

npx @openai/codex-security bulk-scan --model gpt-6.1-sol --effort medium

Si ya preparaste la lista de repositorios, proporciona un archivo CSV y --output-dir:

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

El archivo CSV requiere las columnas id, repository y revision. Las revisiones deben ser hashes completos de commits. Las columnas opcionales scope, mode y prompt permiten configurar cada repositorio:

id,repository,revision,scope,mode,prompt
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Review authorization boundaries.

Usa --knowledge-base PATH para compartir documentos de seguridad entre todos los repositorios. Usa --scan-prompt-file FILE para agregar instrucciones de análisis compartidas. La columna prompt del CSV agrega las instrucciones específicas de cada repositorio después del prompt compartido. --post-scan-prompt-file FILE ejecuta instrucciones de seguimiento después de cada análisis, incluidos los que devuelven errores. El seguimiento no se ejecuta si se cancela el análisis o si este alcanza su límite de costo.

--workers limita el número de repositorios que se analizan en paralelo y su valor predeterminado es 4. El valor predeterminado de --mode es standard y el de --max-attempts es 1. Define --max-attempts para reintentar la operación si se producen errores de repositorio o de análisis. Las exclusiones y las notas de seguimiento no activan reintentos de análisis completados. Si persisten errores de ejecución, se devuelve 2. Si un análisis completado incumple la política de gravedad, se devuelve 1.

Ejecuta de nuevo el mismo comando para reanudar la campaña desde un directorio de salida existente. La CLI omite los análisis completados. Usa --recover para reintentar las ejecuciones fallidas o interrumpidas de la campaña correspondiente.

Para las campañas en contenedores, consulta Ejecutar análisis por lotes en Docker.

codex-security scans

Buscar análisis guardados

Lista los análisis guardados del directorio actual:

npx @openai/codex-security scans

Lista los análisis de otro repositorio:

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

Busca los análisis guardados en un directorio de salida específico:

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

Inspeccionar o repetir un análisis

Muestra los resultados y la configuración de un análisis guardado:

npx @openai/codex-security scans show SCAN_ID

Agrega --show-linked-findings para incluir enlaces a hallazgos de análisis anteriores.

Vuelve a ejecutar un análisis guardado:

npx @openai/codex-security scans rerun SCAN_ID

Al repetir la ejecución se crea un nuevo análisis con los ajustes y el método de autenticación guardados, la copia de trabajo actual y los archivos de contexto actuales. No se vuelven a cargar los archivos de configuración del proyecto ni se reutilizan las credenciales guardadas. Si el análisis original usó prompts de análisis o de validación personalizada, vuelve a proporcionar esos archivos con --scan-prompt-file y --validation-prompt-file.

Para repetir un análisis se requiere la versión del complemento registrada en la ejecución original. Si la versión instalada es distinta, la ejecución se detiene.

Inspeccionar registros de análisis guardados

Consulta todos los eventos de sesión guardados de un análisis y de sus procesos. Estos registros no ocultan información sensible y pueden contener código fuente o credenciales. Revísalos antes de compartirlos:

npx @openai/codex-security scans logs SCAN_ID

Agrega --json para obtener una salida estructurada.

Identificar coincidencias y comparar hallazgos

Compara dos análisis para identificar hallazgos nuevos, persistentes, reabiertos, no observados, resueltos y de estado desconocido:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

La comparación identifica automáticamente los hallazgos que comparten la misma causa raíz y reutiliza las coincidencias guardadas. Para guardar las coincidencias de forma explícita, usa scans match:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

El estado de un hallazgo es desconocido cuando su ruta está excluida o la coincidencia es incierta. Si el análisis posterior no lo encuentra en el código que analizó, el hallazgo se considera no observado. Solo se considera resuelto un hallazgo que se cerró explícitamente por estar ya corregido. Agrega --force a match cuando necesites volver a calcular una coincidencia existente.

Para identificar coincidencias entre todos los análisis completados del repositorio actual, incluidos los de otras copias de trabajo:

npx @openai/codex-security scans match --all

Los resultados pueden variar incluso si repites el análisis con la misma configuración. La búsqueda de coincidencias y la comparación permiten seguir los cambios, pero no hacen que los resultados sean deterministas ni demuestran que una vulnerabilidad haya dejado de existir. Usa validate para volver a comprobar un hallazgo crítico para la seguridad en el código actual.

codex-security findings

Lista los hallazgos abiertos de todos los análisis del repositorio actual:

npx @openai/codex-security findings list

Pasa la ruta de un repositorio para inspeccionar otra copia de trabajo:

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

Agrega --json para obtener una salida estructurada. La lista identifica los hallazgos observados en el análisis más reciente y los hallazgos anteriores que ese análisis no confirmó.

Los hallazgos anteriores permanecen abiertos hasta que se resuelven o se descartan. Su ausencia en el análisis más reciente no demuestra que se hayan corregido.

Para registrar un hallazgo revisado como falso positivo:

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

Inspecciona el análisis guardado para identificar la aparición específica del hallazgo:

npx @openai/codex-security scans show SCAN_ID

Registra una explicación específica de por qué se trata de un falso positivo:

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

El motivo no puede estar vacío. Codex Security guarda la decisión para el repositorio y la proporciona como contexto para análisis futuros. Cada análisis vuelve a comprobar de forma independiente el código fuente actual, los controles y si es posible alcanzar el código afectado. Una decisión previa no excluye ninguna regla, ruta ni clase de vulnerabilidad.

codex-security export

Exporta hallazgos guardados o un modelo de amenazas sin iniciar Codex ni cargar credenciales. Solo puedes exportar hallazgos como CSV, JSON, SARIF o CSV de ServiceNow AVIT desde un análisis completado y sellado. Los modelos de amenazas usan Markdown.

usage: codex-security export [scan_dir | --scan SCAN_ID]
                             [--artifact {findings,threat-model}]
                             [--export-format {csv,json,sarif,md,servicenow-avit}]
                             [--avit-template FILE]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH]

Omite scan_dir y --scan para usar el último análisis completado del repositorio actual. También puedes proporcionar un directorio de resultados guardados o seleccionar un análisis por su ID o un prefijo único de al menos ocho caracteres con --scan. No puedes combinar estos selectores.

--source-root solo funciona con exportaciones de hallazgos en SARIF. El formato JSON conserva el documento sellado de hallazgos. El CSV contiene columnas de hallazgos que se pueden usar en otros sistemas y no incluye el estado de clasificación del entorno de trabajo local.

Sin --output, la CLI escribe la salida SARIF en results.sarif, JSON en findings.json, CSV en findings.csv, CSV de ServiceNow AVIT en servicenow-avit.csv y Markdown en threatmodel.md, en el directorio de trabajo actual. Las exportaciones pueden contener fragmentos de código fuente y detalles de vulnerabilidades. Pasa --output con una ruta privada fuera de la copia de trabajo. Si ejecutas el comando fuera del repositorio, especifica también un directorio de resultados o --scan.

Exportar hallazgos

Escribe la salida SARIF en un archivo:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

Escribe la salida SARIF en stdout:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

Exporta los hallazgos en formato JSON:

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

Exporta los hallazgos en formato CSV:

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

Exportar hallazgos para ServiceNow

ServiceNow requiere el rol Ethical Hacker (sn_vul.app_pen_tester). Abre All > Manual AVIT Ingestion > Upload File UI y descarga la plantilla CSV. Conserva los encabezados originales y exactamente una fila de datos. Usa el nombre exacto de la aplicación en ServiceNow. Indica el propósito, los tipos de datos sensibles, los programas de cumplimiento, las tecnologías utilizadas, el equipo responsable de la aplicación y las URL que se probarán. Completa Requested by, Assigned to y Assignment group. Deja en blanco los campos del hallazgo. Guarda la plantilla como app.csv en un directorio privado fuera del repositorio analizado. Reutilízala para los análisis de la misma aplicación.

Desde el repositorio analizado, exporta los hallazgos más recientes con esa plantilla. Guarda también la salida en el directorio privado:

npx @openai/codex-security export --scan latest \
  --export-format servicenow-avit \
  --avit-template /path/outside/repository/exports/app.csv \
  --output /path/outside/repository/exports/findings-avit.csv

La CLI escribe una fila por hallazgo y completa Steps to reproduce a partir de la ruta de ataque registrada, si está disponible. Revisa esos pasos y completa los campos vacíos del CSV exportado. Vuelve a Upload File UI, selecciona Import File, carga el CSV y selecciona Submit. Cada carga crea un nuevo formulario de pruebas de penetración para la aplicación. Consulta las instrucciones de carga de ServiceNow.

Exportar un modelo de amenazas guardado

Exporta a stdout el modelo de amenazas guardado del último análisis completado sin volver a llamar al modelo:

npx @openai/codex-security export --artifact threat-model --output -

También puedes seleccionar un análisis y guardar su modelo en un archivo:

npx @openai/codex-security export --scan SCAN_ID \
  --artifact threat-model \
  --output /path/outside/repository/exports/threatmodel.md

Si seleccionas un análisis por ID o directorio, también puedes exportar un modelo guardado de un análisis inconcluso o fallido. Si no se guardó ningún modelo, el comando devuelve un error. Antes de reutilizar el documento, revisa el contenido que se identifique como provisional o recuperado.

Para proporcionar el modelo exportado como contexto para otro análisis, pasa su ruta a --knowledge-base.

codex-security publish scan

Publica hallazgos seleccionados de un análisis completado en Linear o en un servicio personalizado de hallazgos. Las siguientes opciones corresponden a la publicación en Linear:

usage: codex-security publish scan [SCAN_DIR] --to linear
                                   [--linear-team TEAM_ID]
                                   [--project PROJECT_ID]
                                   [--linear-api-key KEY]
                                   [--linear-assignee EMAIL_OR_USER_ID]
                                   [--dry-run] [--json]

SCAN_DIR debe contener un análisis completado y sellado. Omítelo en una terminal interactiva para seleccionar un análisis completado del historial local. Para crear incidencias, el análisis y sus hallazgos también deben estar en el historial local. Una simulación valida los artefactos sellados sin comprobar si se guardaron en el historial.

Usa --scan SCAN_ID o --scan latest en lugar de un directorio para seleccionar un análisis guardado. Repite --finding-id ID para seleccionar un subconjunto de hallazgos para Linear. Usa publish check SCAN_DIR con las opciones de destino de Linear para verificar los artefactos y las publicaciones registradas. Si usas una clave de API, también se comprueban la autenticación y el acceso al destino. El acceso mediante la app conectada se indica como not-checked.

Cada ejecución que no sea una simulación intenta crear una incidencia nueva para cada hallazgo seleccionado, salvo que --skip-existing encuentre una publicación correcta registrada para esa aparición, equipo y proyecto. Esta opción no inspecciona incidencias remotas ni cubre publicaciones sin registrar o simultáneas. Si falla la publicación de algunos hallazgos, el comando conserva las incidencias creadas correctamente y devuelve el código de salida 2. Con --json, revisa los resultados created y failed antes de reintentar para evitar duplicados.

Revisa los datos de las incidencias antes de publicar:

npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --dry-run \
  --json

Publicar con la app de Linear conectada

Sin una clave de API de Linear, el comando inicia Codex con tu configuración existente y la app de Linear conectada. Inicia sesión y conecta Linear a tu cuenta de Codex antes de publicar:

npx @openai/codex-security login
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --project PROJECT_ID

Publicar con una clave de API de Linear

Si proporcionas --linear-api-key o CODEX_SECURITY_LINEAR_API_KEY, el comando publica directamente mediante la API de Linear sin iniciar Codex. La publicación directa deja las incidencias sin asignar a menos que selecciones un responsable:

export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --linear-assignee teammate@example.com

Los valores de la línea de comandos tienen prioridad sobre las variables de entorno correspondientes. Para las claves de API, es preferible usar CODEX_SECURITY_LINEAR_API_KEY en lugar de --linear-api-key, ya que los argumentos de la línea de comandos pueden aparecer en el historial del shell y en las listas de procesos.

Publicar en un servicio personalizado de hallazgos

Si ya tienes un servicio de hallazgos, selecciona su URL explícitamente:

npx @openai/codex-security publish scan --scan latest \
  --to custom --findings-url http://localhost:3000

La publicación envía los hallazgos sellados completos y el ID del repositorio objetivo. Los hallazgos pueden incluir fragmentos de código fuente, evidencia y detalles de vulnerabilidades. Usa HTTPS para servicios fuera de tu equipo local y agrega --dry-run --json para inspeccionar los datos antes de enviarlos.

La CLI no envía credenciales de modelos a servicios personalizados. Gestiona fuera de la CLI cualquier autenticación necesaria. Consulta la guía del servicio de hallazgos para conocer los detalles del despliegue y del protocolo.

codex-security publish findings

Usa --to local para guardar los hallazgos importados en tu equipo. Con --to cloud, la CLI se conecta al servicio incluso para generar una vista previa. Necesitas credenciales de inicio de sesión de ChatGPT guardadas en un archivo y el ID o la URL de un repositorio autorizado que ya tenga un entorno en la nube. La importación en la nube puede devolver un resultado parcial si el servicio rechaza algunos registros. Consulta la guía de importación desde GitHub para conocer ambos procedimientos.

Para importar alertas de Dependabot en una copia de trabajo local, necesitas una exportación guardada del mismo repositorio de GitHub. Sigue la guía de exportación de Dependabot para guardar todas las páginas fuera de la copia de trabajo con un token que tenga acceso de lectura a las alertas de Dependabot.

Agrega echo "$out/dependabot.jsonl" al final del script de exportación antes de ejecutarlo. En un shell nuevo, usa la ruta que mostró el script para obtener una vista previa del archivo. Reemplaza ./project por la ruta de tu copia de trabajo y OWNER/REPO por el propietario y el nombre de tu repositorio. Si la copia de trabajo tiene repositorios remotos configurados con acceso por red, uno de ellos debe coincidir con el repositorio de las alertas. De lo contrario, verifica que la exportación corresponda a la copia de trabajo.

export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
npx @openai/codex-security publish findings /path/to/dependabot.jsonl \
  --to local --repository ./project --provider github \
  --source-key github.com/OWNER/REPO/dependabot --dry-run --format json

Comprueba el destino y las exclusiones en la vista previa. La simulación finaliza con el código 0 aunque muestre alertas excluidas. Para guardar las alertas aceptadas, vuelve a ejecutar el comando sin --dry-run y confirma la importación, o reemplaza --dry-run por --yes. Si la importación excluye alguna alerta, guarda las aceptadas y finaliza con el código 1. Consulta las alertas guardadas en el mismo shell.

npx @openai/codex-security findings imported ./project --format json

El estado de evaluación inicial de las alertas importadas es not_assessed. Si usas la misma clave de origen en una importación posterior, se actualizan los registros guardados de las alertas incluidas en el archivo. Las alertas omitidas conservan el estado de su última importación. Las alertas que comparten un aviso de seguridad se mantienen en registros separados.

Comandos de revisión de hallazgos

Estos comandos trabajan con hallazgos existentes:

verify-fix devuelve 2 si alguna comprobación falla o no es concluyente. En los demás casos, devuelve 1 si persiste alguna vulnerabilidad o 0 si todos los hallazgos se corrigieron. Consulta --help de cada comando para ver los selectores, los ajustes del modelo y las opciones de salida.

codex-security feedback

Envía a OpenAI la descripción de un problema y recibe un ID que puedes compartir con soporte:

npx @openai/codex-security feedback SCAN_ID \
  --reason "The scan stopped before it finished" --json

Si omites el ID del análisis, el comando selecciona el análisis que se inició más recientemente en el repositorio actual, incluidos los análisis activos o fallidos. Si no existe ninguno, envía un informe general. Los informes incluyen la descripción, las versiones y los ID de análisis y sesión seleccionados. Los registros se excluyen de forma predeterminada. Agrega --include-logs solo si puedes compartir con OpenAI el código fuente, los prompts, los hallazgos y la salida de las herramientas que contienen los registros.

codex-security validate y codex-security patch

Evalúa posibles hallazgos en el código fuente del repositorio actual:

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

Genera una corrección con la habilidad de remediación incluida:

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

Cada argumento posicional acepta texto literal o una ruta de archivo. Estas entradas usan el directorio actual. validate usa un sandbox de solo lectura para evaluar la evidencia en el código fuente. No compila el objetivo ni ejecuta código de la aplicación. Tampoco ejecuta pruebas o pruebas de concepto ni se conecta a servicios. Los análisis estándar, profundos y de diferencias conservan sus propios flujos de validación. patch sigue corrigiendo y verificando los hallazgos.

Usa validate para volver a evaluar un hallazgo después de corregirlo o cuando deje de aparecer en un análisis posterior. La comparación entre análisis por sí sola no demuestra que la corrección haya funcionado. Para obtener evidencia en tiempo de ejecución, reproduce el problema en un paso independiente.

El comando escribe la evaluación en stdout sin guardar un informe. Redirige stdout para conservarla:

npx @openai/codex-security validate findings.json > /path/outside/repository/assessment.md

Agrega --context TEXT, --context-file FILE o varias opciones --knowledge-base PATH para proporcionar contexto de seguridad. Para obtener una salida estructurada, usa --output-schema FILE con un esquema JSON Schema autocontenido compatible con tu modelo y proveedor. La CLI comprueba que el JSON generado cumpla con el esquema antes de escribirlo en stdout. Si la salida no es válida, la CLI finaliza con el código 2 sin escribir la evaluación. validate no admite --json.

Usa --effort para seleccionar el esfuerzo de razonamiento de cualquiera de los dos comandos:

npx @openai/codex-security validate "Possible SQL injection" --effort high

Aplicar parches a los hallazgos después de un análisis

Usa scan --patch para corregir hallazgos después de completar un análisis. El umbral de gravedad predeterminado es low. Este comando selecciona los hallazgos de gravedad alta y crítica:

npx @openai/codex-security scan . --patch --patch-severity high --json

Los hallazgos cuya corrección se verificó y los que ya estaban corregidos no activan --fail-on-severity.

Aplicar parches a hallazgos guardados

Pasa el ID de un hallazgo o de una de sus apariciones para aplicar el parche en el repositorio original, o selecciona hallazgos de un análisis guardado:

npx @openai/codex-security patch OCCURRENCE_ID
npx @openai/codex-security patch --scan SCAN_ID --severity high --json
npx @openai/codex-security patch --scan latest --severity medium

--scan latest selecciona el último análisis completado del repositorio actual. patch admite --json para hallazgos guardados, texto literal y archivos de entrada.

Agrega --create-pr para crear un commit únicamente con los archivos de parches verificados y abrir un pull request de GitHub o un merge request de GitLab como borrador con la CLI correspondiente:

npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr

Si falla el envío de los cambios o la creación del pull request, ejecuta desde el mismo repositorio el comando patch --resume-pr BRANCH que aparece en la salida para reintentar la operación.

Aplicar parches a incidencias de Linear

Define CODEX_SECURITY_LINEAR_API_KEY o LINEAR_API_KEY para usar una clave de API personal, o LINEAR_ACCESS_TOKEN para usar un token de OAuth. Es preferible usar una variable de entorno en lugar de --linear-api-key KEY para evitar que la clave aparezca en el historial del shell.

Importa una incidencia por ID o URL. Repite --linear-issue para seleccionar más de una incidencia:

npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124

Usa --linear-project para seleccionar las incidencias abiertas de un proyecto. Agrega --linear-filter para restringir la selección:

npx @openai/codex-security patch --linear-project "Security backlog" \
  --linear-filter '{"labels":{"name":{"eq":"security"}}}'

La CLI excluye las incidencias completadas y canceladas a menos que el filtro defina state. No modifica las incidencias de Linear.

codex-security login, logout e info

Inicia sesión de forma interactiva:

npx @openai/codex-security login

Usa la autenticación de dispositivo en un equipo remoto o sin interfaz interactiva:

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

Comprueba el estado de la sesión actual:

npx @openai/codex-security login status

Elimina los datos de inicio de sesión guardados:

npx @openai/codex-security logout

Guarda una clave de API pasándola mediante stdin:

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

Guarda un token de acceso empresarial:

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

Inspecciona los metadatos de solo lectura del SDK y del complemento incluido:

npx @openai/codex-security info --json

Leer la salida del análisis

De forma predeterminada, los análisis envían el progreso, los resúmenes finales y los errores a stderr sin escribir el resultado completo en stdout. Usa --json, --format o --full-output para enviar los resultados estructurados del análisis a stdout.

Las terminales interactivas muestran un panel en tiempo real con la fase actual del análisis, el inventario de archivos, la actividad, el uso de tokens y el costo estimado. En CI o al redirigir la salida, el progreso se muestra en texto plano. Agrega --headless para ver el progreso en texto plano en una terminal interactiva:

npx @openai/codex-security scan . --headless

El panel también muestra detalles de la sesión en tiempo real. Estos detalles no ocultan información sensible y pueden contener código fuente o credenciales. Revísalos antes de compartirlos.

Diagnósticos detallados

Agrega --verbose para escribir en stderr diagnósticos del ciclo de ejecución, la autenticación, el progreso y el costo:

npx @openai/codex-security scan . --verbose

Define CODEX_SECURITY_LOG_LEVEL=debug para activar los mismos diagnósticos sin usar la opción. LOG_LEVEL=debug también activa los diagnósticos cuando CODEX_SECURITY_LOG_LEVEL no está definida o está vacía.

Codex Security conserva el texto de diagnóstico. Los diagnósticos pueden contener código fuente o credenciales, así que revísalos antes de compartirlos.

Resumen final

Al completarse, el análisis escribe en stderr la cantidad de hallazgos abiertos del repositorio, el desglose por gravedad, el tiempo transcurrido, la ruta del informe y el directorio de resultados. También muestra el uso de tokens cuando está disponible y el costo estimado si especificas --show-cost o --max-cost. Por ejemplo:

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  SCOPE     repository: .
  ELAPSED   1s
  RESULTS   /path/to/scan

El total del resumen incluye los hallazgos informativos. Las políticas de gravedad solo evalúan los hallazgos critical, high, medium y low del análisis actual. Los hallazgos anteriores que figuran en el total del repositorio quedan fuera de la evaluación.

Salida JSON

scan --json escribe un único documento JSON en stdout. Consulta manifest.scan para conocer el estado y el alcance, y findings para ver los hallazgos del análisis actual. Cuando está disponible, repositoryFindings incluye esos hallazgos y los hallazgos abiertos anteriores. review.excludedPaths enumera los patrones de ruta que el análisis registró como excluidos de la revisión. scanDir, reportPath y artifactsDir indican dónde se guardaron los resultados.

threatModel contiene el modelo de amenazas guardado como datos estructurados o en Markdown. threatModelPath indica la ruta del documento guardado. Cualquiera de los dos valores puede ser null. Aunque falle la escritura del documento, el modelo aún se puede exportar.

Al aplicar parches, la salida JSON también incluye los resultados de los parches y cualquier pull request que se haya creado.

El progreso, los resúmenes finales, los avisos de archivado y los diagnósticos se siguen escribiendo en stderr. Un análisis completado muestra el resultado JSON incluso cuando la política de gravedad devuelve el código de salida 1.

Comprueba siempre el código de salida del proceso, incluso si el JSON se puede interpretar correctamente. Si la ejecución falla sin devolver resultados de análisis, se genera un error estructurado con status, code y message cuando usas --json, --format json o --format jsonl. Si se conservan resultados válidos del análisis, la salida puede contener el resultado habitual y warnings, por ejemplo, tras un cambio en el objetivo. Con --json, --format json o --format jsonl, agrega --full-output para recibir un objeto contenedor con ok: false, el error en error y cualquier resultado sellado válido que se haya conservado en data. Los demás formatos solo reportan errores en stderr, incluso con --full-output. Estas reglas también se aplican a scans rerun y scans resume.

Artefactos del análisis

Un análisis completado guarda juntos el informe legible y los artefactos estructurados. El archivo de manifiesto sellado registra los hashes de los artefactos para que quien los consulte más adelante pueda comprobar que los archivos no han cambiado:

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── report.md
├── threatmodel.md          # when available
├── artifacts/
└── exports/
    └── results.sarif       # when produced

Cada archivo estructurado cumple una función distinta:

Finalización y cobertura de la revisión

Consulta scan.status en scan-manifest.json para comprobar si el análisis se completó. Consulta scan.scope para conocer el alcance configurado y scan.review.excludedPaths para ver las exclusiones registradas durante la revisión. Las comparaciones entre análisis también usan esas exclusiones. Incluso si el análisis se completa, pueden quedar archivos sin revisar dentro de su alcance.

Si quedan tareas pendientes, inspecciona la evidencia disponible con scans show SCAN_ID y scans logs SCAN_ID. Si un análisis profundo interrumpido admite la reanudación, puedes continuarlo con scans resume SCAN_ID. Para iniciar una nueva revisión con los ajustes guardados, usa scans rerun SCAN_ID cuando estén disponibles las instrucciones de ejecución. Es posible que los análisis de complementos no incluyan instrucciones que permitan repetir la ejecución. En ese caso, inicia un análisis nuevo con las rutas y el contexto deseados.

Códigos de salida y señales

La CLI usa los siguientes códigos de salida:

Las omisiones de cobertura no modifican el código de salida de un análisis completado ni evitan que se aplique su política de gravedad. El código de salida 0 no indica que se hayan revisado todos los archivos. Si solicitas una salida estructurada, los análisis completados y las publicaciones parciales escriben los resultados disponibles en stdout. Tras una interrupción o un error de ejecución, la CLI muestra la ubicación de cualquier salida parcial.

Permisos de los análisis locales

Los análisis de la CLI y del SDK se ejecutan con tus permisos locales del sistema operativo. El perfil de análisis permite leer el sistema de archivos local y escribir en los directorios raíz del espacio de trabajo. La revisión automática de las solicitudes de aprobación de ejecución puede conceder permisos adicionales para una operación. Usa --codex 'approval_policy="never"' o define codexOverrides.approval_policy: "never" en el SDK para denegar las solicitudes de permisos. Las restricciones del host y de la red siguen vigentes.

Los procesos de análisis y del entorno de trabajo pueden heredar tu entorno, incluidos tokens de API y credenciales de la nube ajenos al análisis. Elimina las credenciales que no correspondan antes de iniciar un análisis.

Autenticación y requisitos previos

Define OPENAI_API_KEY o CODEX_API_KEY, inicia sesión con npx @openai/codex-security login o usa credenciales de inicio de sesión de Codex ya guardadas en un archivo. Para OpenRouter o Fireworks, define la clave de API del proveedor y selecciona un modelo. Para Amazon Bedrock, usa una clave de API de Bedrock o la cadena estándar de credenciales de AWS.

Para elegir las credenciales, consulta Seleccionar la autenticación del análisis.

En CI, limita el acceso a la clave de API al paso de análisis y usa un flujo de trabajo de confianza.

La CLI requiere Node.js 24 o 26, o Node.js 22 a partir de la versión 22.13.0. Los análisis, los análisis por lotes, las exportaciones, el historial de análisis y los hallazgos guardados también requieren Python 3.10 o posterior. Python 3.10 también requiere tomli. Usa --python con scan, bulk-scan o export, o define PYTHON para cualquier comando que use Python.

Para leer o reanudar sesiones comprimidas de Codex (.jsonl.zst), usa Node.js 22.15.0 o una versión posterior de la serie 22.x, o Node.js 24 o 26. Las sesiones .jsonl sin comprimir funcionan en todas las versiones compatibles de Node.js.

Continúa con la guía de inicio rápido de la CLI, la guía de análisis por lotes, las preguntas frecuentes sobre la CLI, la guía de CI o la guía del SDK de TypeScript.