Referencia de Codex Security CLI

Usa esta referencia para consultar los comandos codex-security admitidos, las opciones, los formatos de salida y el comportamiento de salida. Para realizar un primer análisis guiado, comienza con el inicio rápido de la CLI.

Instala el paquete publicado en tu proyecto:

npm install @openai/codex-security

Invoca el paquete instalado como npx @openai/codex-security. Puedes usar codex-security directamente cuando el ejecutable esté disponible en tu PATH.

Resumen de comandos

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

La CLI proporciona estos comandos:

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

Enumera todos los comandos disponibles:

npx @openai/codex-security --help

Añade --help a un comando para inspeccionar sus argumentos y opciones:

npx @openai/codex-security scan --help

codex-security --version imprime la versión instalada y finaliza. codex-security info --json informa de las versiones del SDK y del plugin incluido. Ninguno de los comandos requiere Python.

Descubre comandos y conecta agentes

Imprime el manifiesto de comandos legible por agentes:

npx @openai/codex-security --llms

Inspecciona el esquema de argumentos del análisis como JSON:

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

Genera finalizaciones de shell para Bash:

npx @openai/codex-security completions bash

Sustituye bash por zsh o fish para esos shells.

Los resultados del análisis admiten --format toon|json|yaml|jsonl y --full-output. Este --format del marco es independiente de --export-format, que selecciona el formato de un artefacto exportado desde un análisis completado. La ayuda global de los comandos también muestra md, pero los resultados del análisis no admiten la salida Markdown.

Registra la CLI como servidor MCP:

npx @openai/codex-security mcp add

Sincroniza las skills de Codex Security con tus agentes:

npx @openai/codex-security skills add

MCP solo expone el comando de metadatos de solo lectura info. Los análisis, las exportaciones, la autenticación, la validación y la aplicación de parches siguen estando disponibles únicamente en la CLI.

codex-security scan

Ejecuta un análisis de un repositorio, rutas seleccionadas, cambios confirmados o el árbol de trabajo.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository usa de forma predeterminada el directorio actual.

Selecciona la autenticación del análisis

Usa --auth auto, la opción predeterminada, para seleccionar las credenciales automáticamente. Cuando estén disponibles tanto un inicio de sesión de ChatGPT como OPENAI_API_KEY o CODEX_API_KEY, los análisis interactivos con salida de texto preguntan qué credencial se debe usar. Los análisis de CI, JSON y JSONL, así como otros análisis sin terminal interactivo, usan la API key del entorno. Las ejecuciones de prueba no solicitan ni cargan credenciales.

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

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

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

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

Para convertir las credenciales almacenadas en la opción automática predeterminada, ejecuta unset OPENAI_API_KEY CODEX_API_KEY.

Usa Amazon Bedrock

Selecciona Amazon Bedrock con --provider amazon-bedrock y especifica un modelo de Bedrock explícito con --model:

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

Configura AWS_REGION y autentícate con AWS_BEARER_TOKEN_BEDROCK, claves de acceso estándar de AWS, un perfil de AWS, identidad web, credenciales de contenedor o la cadena de credenciales predeterminada de AWS. Los análisis de Bedrock usan credenciales de AWS en lugar de --auth, el inicio de sesión de ChatGPT o una OpenAI API key. Tanto scan como bulk-scan admiten --provider.

Selecciona 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 objetivos de repositorio y de ruta.

Los análisis de diferencias y del árbol de trabajo requieren que el argumento del repositorio sea la raíz del árbol de trabajo 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 los cambios confirmados:

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

Analiza los cambios preparados y no preparados:

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

Añade 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 añadir más archivos o directorios:

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

Los documentos admitidos incluyen archivos .md, .markdown, .txt, .pdf y .docx. La CLI busca en los directorios de forma recursiva, rechaza las rutas de entrada enlazadas, omite las entradas de directorio enlazadas y mantiene el contenido extraído de los documentos fuera de los resultados de análisis guardados.

Configura las opciones de salida y políticas

Usa estas opciones para conservar artefactos, preservar resultados anteriores o crear un resultado legible por máquinas.

El límite de costo es una estimación, no un límite estricto de gasto. Las solicitudes que ya estén en curso pueden finalizar por encima del límite, y los resultados parciales del análisis permanecen disponibles.

Cuando omites --output-dir, los resultados se conservan en $CODEX_HOME/state/plugins/codex-security/scans/<repository>. CODEX_HOME usa ~/.codex de forma predeterminada. Configura CODEX_SECURITY_STATE_DIR para conservar los resultados en $CODEX_SECURITY_STATE_DIR/scans/<repository>. Estos directorios pueden contener fragmentos del código fuente y detalles de vulnerabilidades, así que administra sus permisos y retención según corresponda.

El entorno de trabajo conserva el historial de análisis en $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Configurar CODEX_SECURITY_STATE_DIR también mueve la base de datos del entorno de trabajo.

El directorio de salida debe estar fuera del directorio analizado y de cualquier árbol de trabajo de Git contenedor. Un análisis puede reemplazar un directorio de resultados existente con --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. Añade --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 ejecución de prueba comprueba las entradas locales sin cargar credenciales, iniciar Codex ni examinar el intérprete de Python del plugin:

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

Configura el entorno de ejecución

Usa las opciones del entorno de ejecución cuando necesites un modelo, intérprete, plugin o valor de configuración de Codex explícitos.

Para seleccionar otro modelo y nivel de razonamiento sin escribir TOML:

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

Pon entre comillas los valores de cadena pasados mediante --codex para que el analizador de TOML reciba una cadena:

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

codex-security install-hook

Instala una comprobación de seguridad previa a la confirmación de Git para el repositorio actual:

npx @openai/codex-security install-hook

La comprobación analiza los cambios preparados y no preparados antes de cada confirmación y bloquea los hallazgos de gravedad alta o los errores del análisis. Respeta core.hooksPath y no reemplaza ningún script previo a la confirmación existente. Establece otro umbral de gravedad cuando sea necesario:

npx @openai/codex-security install-hook . --fail-on-severity medium

codex-security bulk-scan

Detecta y analiza repositorios de GitHub, o ejecuta un análisis reanudable a partir de un CSV de repositorios:

Para obtener una guía completa sobre la detección en GitHub, los inventarios CSV, los resultados de campañas y los análisis en contenedores, consulta Ejecutar análisis de seguridad en bloque.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--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 un inicio de sesión en GitHub CLI.

Para elegir un modelo y un nivel de razonamiento durante la detección interactiva:

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

Para usar una lista de repositorios preparada, proporciona un CSV y --output-dir:

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

El CSV requiere las columnas id, repository y revision. Las revisiones deben ser hashes completos de confirmaciones. Las columnas opcionales scope y mode configuran repositorios individuales:

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

--workers limita los análisis simultáneos y usa 4 de forma predeterminada. --mode usa standard de forma predeterminada, y --max-attempts usa 1 de forma predeterminada. Configura --max-attempts cuando quieras volver a intentar analizar un repositorio después de un error. Ejecuta de nuevo el mismo comando para reanudar un análisis en bloque desde su directorio de salida existente. La CLI omite los repositorios completados solo cuando sus artefactos de resultados registrados siguen presentes.

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

codex-security scans

Busca análisis guardados

Enumera los análisis guardados del directorio actual:

npx @openai/codex-security scans

Enumera los análisis de otro repositorio:

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

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

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

Inspecciona o repite un análisis

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

npx @openai/codex-security scans show SCAN_ID

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

npx @openai/codex-security scans rerun SCAN_ID

Relaciona y compara hallazgos

Relaciona los hallazgos que compartan la misma causa raíz entre dos análisis:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Compara los análisis relacionados para encontrar hallazgos nuevos, persistentes, reabiertos, resueltos y desconocidos:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Un hallazgo es desconocido cuando el análisis posterior tiene una cobertura incompleta o no cubre la ubicación original del hallazgo. Añade --force a match cuando necesites volver a calcular una relación existente.

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

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

Los resultados pueden variar aunque repitas la misma configuración. La relación y la comparación permiten seguir los cambios; no hacen que los resultados sean deterministas ni demuestran que una vulnerabilidad ya no exista. Usa validate para volver a comprobar un hallazgo crítico para la seguridad con respecto al código actual.

codex-security findings

Registra 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 del hallazgo:

npx @openai/codex-security scans show SCAN_ID

Registra una explicación específica del 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 debe estar vacío. Codex Security guarda la decisión para el repositorio y la proporciona como contexto a análisis futuros. Cada análisis vuelve a comprobar de forma independiente el código fuente actual, los controles y la accesibilidad. Una decisión anterior no suprime ninguna regla, ruta ni clase de vulnerabilidad.

codex-security export

Exporta CSV, JSON o SARIF desde un análisis completado y sellado. La exportación valida los artefactos del análisis antes de escribir la salida y no modifica el entorno de ejecución de Codex ni las credenciales.

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir es el directorio del análisis completado.

--source-root solo funciona con --export-format sarif. JSON conserva el documento de hallazgos sellado. CSV contiene columnas de hallazgos portátiles y no incluye el estado de clasificación del entorno de trabajo local.

Sin --output, la CLI escribe SARIF en results.sarif, JSON en findings.json y CSV en findings.csv dentro del directorio de trabajo actual. Las exportaciones pueden contener fragmentos del código fuente y detalles de vulnerabilidades. Ejecuta el comando fuera del repositorio o pasa --output con una ruta privada fuera de la copia de trabajo analizada.

Escribe 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 SARIF en stdout:

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

Exporta los hallazgos como JSON:

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

Exporta los hallazgos como CSV:

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

codex-security validate y codex-security patch

Comprueba si un posible hallazgo es válido:

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

Genera una corrección con la skill de corrección incluida:

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

Cada argumento puede contener texto literal o apuntar a un archivo. Ambos comandos funcionan con el directorio actual. Usa validate para volver a comprobar directamente un hallazgo original después de una corrección o cuando un análisis posterior ya no lo informe. La comparación de análisis por sí sola no demuestra que una corrección haya funcionado. Las herramientas externas pueden usar estos comandos sin volver a compilar el analizador.

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

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

codex-security login, logout y info

Inicia sesión de forma interactiva:

npx @openai/codex-security login

Usa la autenticación de dispositivo en una máquina remota o sin interfaz gráfica:

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

Comprueba el inicio de sesión actual:

npx @openai/codex-security login status

Elimina el inicio de sesión almacenado:

npx @openai/codex-security logout

Almacena una API key pasándola mediante stdin:

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

Almacena 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 plugin incluido:

npx @openai/codex-security info --json

Cuando expones la CLI como servidor MCP, info es el único comando disponible. Los análisis, las exportaciones, el inicio de sesión, la validación y la aplicación de parches siguen estando disponibles únicamente en la CLI.

Lee la salida del análisis

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

Diagnósticos detallados

Añade --verbose para imprimir en stderr diagnósticos censurados del ciclo de vida, la autenticación, el progreso y el costo:

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

Configura CODEX_SECURITY_LOG_LEVEL=debug para habilitar los mismos diagnósticos sin la opción. LOG_LEVEL=debug también habilita los diagnósticos cuando CODEX_SECURITY_LOG_LEVEL no está configurado.

Estos controles de registro solo se aplican a la CLI. Las credenciales y los identificadores de proveedores permanecen censurados, y los resultados estructurados del análisis permanecen en stdout.

Resumen de finalización

Un análisis completado escribe en stderr el número de hallazgos, el desglose por gravedad, la cobertura, el tiempo transcurrido, la ruta del informe y el directorio de resultados. Incluye el uso de tokens y el costo estimado cuando están disponibles:

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

Los hallazgos informativos cuentan para el total del resumen. Las políticas de gravedad solo evalúan los hallazgos critical, high, medium y low.

Salida JSON

scan --json escribe un documento JSON completo en stdout. Su estructura de nivel superior es:

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

El progreso, los resúmenes de finalización, los avisos de archivado y los errores permanecen en stderr. Un análisis completado sigue imprimiendo el resultado JSON completo cuando una política de gravedad devuelve el código de salida 1 o una cobertura incompleta devuelve el código de salida 2.

Artefactos del análisis

Un análisis completado conserva juntos el informe legible y los artefactos estructurados:

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

Los archivos estructurados cumplen funciones diferentes:

La exhaustividad de la cobertura tiene tres valores:

• complete: El análisis registra una cobertura completa de su alcance seleccionado.
• partial: El análisis registra trabajo aplazado u otros límites de cobertura.
• unknown: El análisis informa que la exhaustividad de la cobertura es desconocida.

Revisa las superficies aplazadas, las exclusiones explícitas y las preguntas abiertas antes de usar la cobertura como evidencia para una decisión de seguridad.

Códigos de salida y señales

La CLI usa estos códigos de salida:

Cualquier análisis con cobertura partial o unknown devuelve 2, incluso sin una política de gravedad. Cuando solicitas una salida estructurada, los análisis completados siguen escribiendo los resultados disponibles en stdout. La CLI imprime la ubicación de cualquier salida parcial después de una interrupción o un error del entorno de ejecución.

Autenticación y requisitos previos

Configura OPENAI_API_KEY o CODEX_API_KEY, inicia sesión con npx @openai/codex-security login o usa un inicio de sesión existente de Codex basado en archivos. Para Amazon Bedrock, usa una API key de Bedrock o la cadena estándar de credenciales de AWS.

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

Para CI, limita la API key al paso del análisis y usa un flujo de trabajo de confianza.

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. Python 3.10 también requiere tomli. Usa --python o PYTHON para seleccionar un intérprete cuando la detección automática no sea adecuada.

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

Alias de texto sin formato

• --output FILE|-