Referencia de Codex Security CLI

Utilice esta referencia para consultar los comandos, indicadores, formatos de salida y comportamientos de salida compatibles con codex-security. Para realizar un primer análisis guiado, comience con el inicio rápido de la CLI.

Ejecute la CLI con npx @openai/codex-security.

Descripción general de los comandos

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

La CLI proporciona estos comandos:

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

Enumere todos los comandos disponibles:

npx @openai/codex-security --help

Añada --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 informa de las versiones del SDK y del plugin incluido. Ninguno de estos comandos requiere Python.

Detectar comandos y conectar agentes

Muestre el manifiesto de comandos legible por agentes:

npx @openai/codex-security --llms

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

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

Genere el autocompletado del shell para Bash:

npx @openai/codex-security completions bash

Sustituya bash por zsh o fish para esos shells.

Los resultados de análisis admiten --format toon|json|yaml|jsonl y --full-output. Este --format del framework 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 enumera md, pero los resultados de análisis no admiten salida Markdown.

Registre la CLI como MCP server:

npx @openai/codex-security mcp add

Sincronice las habilidades de Codex Security con sus 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 correcciones siguen estando disponibles únicamente en la CLI.

codex-security scan

Ejecute un análisis en 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] [--scan-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-hours HOURS]
                           [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh,max}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--dry-run] [--headless] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

El valor predeterminado de repository es el directorio actual.

Seleccionar la autenticación del análisis

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

Para utilizar sus credenciales almacenadas, pase --auth chatgpt:

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

Para utilizar una API key del entorno, pase --auth api-key:

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

Para establecer las credenciales almacenadas como opción automática predeterminada, ejecute unset OPENAI_API_KEY CODEX_API_KEY.

Utilizar OpenRouter o Fireworks

Seleccione OpenRouter con su API key y un modelo explícito:

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

Seleccione Fireworks con su API key y un modelo explícito:

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.

Utilizar Amazon Bedrock

Utilice --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 utilizan credenciales de AWS sin --auth, un inicio de sesión de OpenAI ni una API key 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íe la solicitud de acceso empresarial o contacte con su equipo de cuentas de OpenAI. Tras la aprobación, trabaje con su equipo de cuentas de AWS para habilitar el acceso al modelo en Amazon Bedrock.

La aprobación de Daybreak Red no incluye acceso a GPT-5.6-Cyber. GPT-5.6-Cyber requiere una aprobación independiente del Gobierno de Estados Unidos (USG). Pida a su equipo de cuentas de OpenAI que solicite esta aprobación adicional antes de habilitar GPT-5.6-Cyber en Amazon Bedrock. Consulte los requisitos de acceso a Daybreak.

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

Para realizar un análisis con Daybreak Blue, sustituya <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 realizar un análisis con Daybreak Red, elija un perfil de AWS con acceso a GPT-5.6-Cyber. Este puede ser distinto del perfil que utiliza 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 puede autenticarse con AWS_BEARER_TOKEN_BEDROCK o con la cadena estándar de credenciales de AWS. Las claves de acceso temporales requieren AWS_SESSION_TOKEN. Configure las credenciales y AWS_REGION en la misma sesión de shell o tarea de CI que el análisis.

Resultados locales y comprobaciones de acceso

Los informes locales guardados, scans show y export funcionan sin credenciales de la nube. Para subir hallazgos a Codex Security Cloud, se requiere iniciar sesión por separado en ChatGPT y tener acceso al destino.

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

Estado de la versión para Bedrock

@openai/codex-security@0.1.31 admite análisis con Amazon Bedrock. Esta versión no proporciona estimaciones de costos ni admite --max-cost para los ID de los modelos Daybreak Blue y Daybreak Red indicados anteriormente.

Compruebe las versiones del paquete instalado y de Codex incluido en él:

npx @openai/codex-security --version
npx @openai/codex-security info --json

Utilice npx @openai/codex-security scan --help para consultar las opciones disponibles en la versión que tiene instalada.

Seleccionar el objetivo del análisis

Elija 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.

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 ese checkout.

Analice todo el repositorio:

npx @openai/codex-security scan .

Analice rutas seleccionadas:

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

Analice cambios confirmados:

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

Analice cambios preparados y no preparados:

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

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

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

Configurar análisis profundos

Utilice estas opciones con --mode deep para controlar la concurrencia de los procesos de trabajo y el tiempo de ejecución:

--subagents acepta cero o un entero positivo. --max-time-hours acepta un número positivo no superior a 96. Las demás opciones requieren un entero positivo. Estas opciones no están disponibles para los análisis estándar.

Por ejemplo, utilice dos procesos de trabajo, permita hasta diez ejecuciones y detenga la ejecución de los procesos de trabajo después de 1,5 horas:

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

Cuando vence el límite de tiempo, el análisis detiene los procesos de trabajo sin terminar, conserva los resultados de análisis completados y los combina en el informe final. Consulte el informe para ver las áreas revisadas y el trabajo pendiente. El plazo por sí solo no determina el código de salida; lo determinan el estado de ejecución y la política de gravedad.

Establezca valores predeterminados persistentes en ~/.codex/codex-security/config.toml o en $CODEX_HOME/codex-security/config.toml cuando configure CODEX_HOME:

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5

Las opciones de la línea de comandos anulan estos valores predeterminados. scan --workers controla los procesos de trabajo independientes de análisis estándar dentro de un análisis profundo; bulk-scan --workers controla los análisis simultáneos de repositorios. Establezca stop_after_consecutive_errors únicamente en el archivo TOML; su valor predeterminado es 3.

Añadir contexto de seguridad

Utilice --knowledge-base PATH para proporcionar documentos de arquitectura, modelos de amenazas o políticas de seguridad. Repita 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 compatibles incluyen archivos .md, .markdown, .txt, .pdf y .docx. La CLI busca recursivamente en los directorios, rechaza las rutas de entrada enlazadas, omite las entradas enlazadas de los directorios y mantiene el contenido extraído de los documentos fuera de los resultados de análisis guardados.

Añadir instrucciones de análisis

Para añadir instrucciones de análisis, proporcione un archivo de texto o Markdown con --scan-prompt-file. Use --post-scan-prompt-file para ejecutar instrucciones de seguimiento en la misma sesión autenticada después de los análisis satisfactorios y de los errores de análisis:

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

Por ejemplo, utilice el prompt del análisis para centrarse en los límites de autorización y solicite que el seguimiento escriba un nuevo post-scan-summary.md en el directorio del análisis. Si el seguimiento falla, la CLI informa de una advertencia y conserva el análisis completado. El seguimiento no se ejecuta después de una cancelación ni cuando el análisis alcanza su límite de costo.

Establecer opciones de salida y políticas

Utilice estas opciones para conservar artefactos y resultados anteriores o crear un resultado legible por máquinas.

El límite de costo es una estimación, no un tope de gasto estricto. 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 combine los resultados completados de los procesos de trabajo, la CLI puede sellar un resultado completado e informar de la advertencia de presupuesto. Devuelve 0, o 1 si los hallazgos alcanzan el umbral de gravedad configurado. Si no puede generar un resultado completado válido, devuelve 2 y deja en disco cualquier salida disponible.

Cuando se omite --output-dir, los resultados persisten en $CODEX_HOME/state/plugins/codex-security/scans/<repository>. El valor predeterminado de CODEX_HOME es ~/.codex. Establezca CODEX_SECURITY_STATE_DIR para conservar los resultados en $CODEX_SECURITY_STATE_DIR/scans/<repository>. Estos directorios pueden contener extractos de código fuente y detalles de vulnerabilidades, por lo que debe gestionar sus permisos y su retención de forma adecuada.

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 que lo contenga. Un análisis puede sustituir 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

Los análisis solo generan informes de forma predeterminada. Añada --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, incluidos los documentos de la base de conocimientos, sin cargar credenciales, iniciar Codex ni sondear el intérprete de Python del plugin:

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

Configurar el entorno de ejecución

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

Para seleccionar un modelo y un esfuerzo de razonamiento diferentes sin escribir TOML, elija un modelo al que sus credenciales permitan acceder. Si inicia sesión con ChatGPT, consulte la disponibilidad de GPT-6.1 Sol antes de usar estos ejemplos:

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

Ponga entre comillas los valores de cadena que se pasen mediante --codex para que el analizador TOML reciba una cadena:

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

codex-security install-hook

Instale una comprobación de seguridad Git previa al commit para el repositorio actual:

npx @openai/codex-security install-hook

La comprobación analiza los cambios preparados y no preparados antes de cada commit y bloquea los hallazgos de gravedad alta o los errores de análisis. Respeta core.hooksPath y no sustituye un script previo al commit existente. Establezca un umbral de gravedad distinto cuando sea necesario:

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

codex-security bulk-scan

Descubra y analice repositorios de GitHub, o ejecute 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, consulte Ejecutar análisis de seguridad masivos.

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}]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Ejecute npx @openai/codex-security bulk-scan sin argumentos para seleccionar repositorios de forma interactiva. Este flujo requiere una sesión iniciada en GitHub CLI.

Para elegir un modelo y un esfuerzo de razonamiento durante el descubrimiento interactivo, use un modelo al que sus credenciales permitan acceder. Consulte la disponibilidad de GPT-6.1 Sol al iniciar sesión con ChatGPT:

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

Para una lista de repositorios preparada, proporcione 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 de commit completos. Las columnas opcionales scope, mode y prompt configuran repositorios individuales:

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

Use --knowledge-base PATH para compartir documentos de seguridad entre todos los repositorios. Use --scan-prompt-file FILE para añadir instrucciones de análisis compartidas; la columna prompt del CSV añade instrucciones específicas del repositorio después de esas instrucciones compartidas. --post-scan-prompt-file FILE ejecuta instrucciones de seguimiento después de cada análisis, incluidos los errores de análisis. No se ejecuta después de una cancelación ni cuando un análisis alcanza su límite de costo.

--workers limita los análisis simultáneos de repositorios y su valor predeterminado es 4. --mode tiene el valor predeterminado standard, y el de --max-attempts es 1. Configure --max-attempts para reintentar tras errores del repositorio o del análisis. Los análisis completados no se reintentan por lagunas de cobertura ni por incumplimientos de la política de gravedad. Sus resultados siguen disponibles.

Vuelva a ejecutar el mismo comando para reanudar desde un directorio de salida existente. La CLI omite los análisis completados, incluidos aquellos con lagunas de cobertura.

Para campañas en contenedores, consulte Ejecutar análisis masivos en Docker.

codex-security scans

Buscar análisis guardados

Enumere los análisis guardados del directorio actual:

npx @openai/codex-security scans

Enumere los análisis de otro repositorio:

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

Busque los análisis almacenados 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

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

npx @openai/codex-security scans show SCAN_ID

Añada --show-linked-findings para incluir enlaces a hallazgos de análisis anteriores.

Vuelva a ejecutar el análisis en el checkout actual con su configuración original:

npx @openai/codex-security scans rerun SCAN_ID

La nueva ejecución requiere la versión del plugin registrada por el análisis original. Si la versión instalada es distinta, el comando se detiene en lugar de ejecutarse con un plugin diferente.

Inspeccionar registros de análisis guardados

Lea todos los eventos de sesión guardados de un análisis y sus procesos de trabajo. Estos registros no ocultan información confidencial y pueden contener código fuente o credenciales, así que revíselos antes de compartirlos:

npx @openai/codex-security scans logs SCAN_ID

Añada --json para obtener una salida estructurada.

Relacionar y comparar hallazgos

Compare dos análisis para identificar hallazgos nuevos, persistentes, reabiertos, no observados, resueltos y desconocidos:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

La comparación relaciona automáticamente los hallazgos que comparten la misma causa raíz y reutiliza las relaciones guardadas. Para guardar relaciones explícitamente, utilice scans match:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Un hallazgo es desconocido cuando su ruta está excluida o su coincidencia es incierta. Si el análisis posterior no lo encuentra en el código que analizó, se considera no observado. Solo se considera resuelto un hallazgo cerrado explícitamente como ya corregido. Añada --force a match cuando necesite recalcular una coincidencia existente.

Para relacionar todos los análisis completados del repositorio actual, incluidos los análisis de otros checkouts:

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

Los resultados pueden variar incluso si vuelve a ejecutar la misma configuración. La relación y la comparación permiten hacer un seguimiento de los cambios; no hacen que los resultados sean deterministas ni demuestran que una vulnerabilidad ya no existe. Utilice validate para volver a comprobar un hallazgo crítico para la seguridad con el código actual.

codex-security findings

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

npx @openai/codex-security findings list

Pase una ruta de repositorio para inspeccionar otro checkout:

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

Añada --json para obtener una salida estructurada. La lista identifica los hallazgos observados en el análisis más reciente y los hallazgos anteriores que no se confirmaron en ese análisis.

Los hallazgos anteriores permanecen abiertos hasta que se resuelven o 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

Inspeccione el análisis guardado para identificar la aparición del hallazgo:

npx @openai/codex-security scans show SCAN_ID

Registre una explicación específica para el 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, los controles y la accesibilidad actuales. Una decisión anterior no omite una regla, una ruta ni una clase de vulnerabilidad.

codex-security export

Exporte 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 ni las credenciales de Codex.

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 portátiles de hallazgos 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 en el directorio de trabajo actual. Las exportaciones pueden contener extractos de código fuente y detalles de vulnerabilidades. Ejecute el comando fuera del repositorio o pase --output con una ruta privada fuera del checkout analizado.

Escriba 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

Escriba SARIF en stdout:

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

Exporte los hallazgos como JSON:

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

Exporte los hallazgos como CSV:

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

codex-security publish scan

Publique en Linear todos los hallazgos de un análisis completado:

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ítalo en una terminal interactiva para seleccionar un análisis completado del historial local. La creación de incidencias también requiere que el análisis y sus hallazgos existan en el historial local. Una ejecución de prueba valida los artefactos sellados sin esta comprobación de persistencia.

Cada invocación que no sea de prueba intenta crear una incidencia nueva por cada hallazgo. Volver a publicar el mismo análisis no relaciona, actualiza ni reutiliza las incidencias existentes. Si algunos hallazgos fallan, el comando conserva las incidencias creadas correctamente y devuelve el código de salida 2. Con --json, revise los resultados created y failed antes de volver a intentarlo para evitar duplicados.

Obtenga una vista previa de las cargas útiles de las incidencias antes de publicarlas:

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

Publicar con la aplicación de Linear conectada

Sin una API key de Linear, el comando inicia Codex con su configuración existente y la aplicación de Linear conectada. Inicie sesión y conecte Linear con su 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 API key de Linear

Proporcionar --linear-api-key o CODEX_SECURITY_LINEAR_API_KEY publica directamente mediante la API de Linear y no inicia Codex. La publicación directa deja las incidencias sin asignar, salvo que seleccione 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 anulan sus variables de entorno correspondientes. Para las API keys, prefiera CODEX_SECURITY_LINEAR_API_KEY a --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.

codex-security validate y codex-security patch

Compruebe si un posible hallazgo es válido:

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

Genere 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 utilizan el directorio actual. Utilice validate para volver a comprobar un hallazgo después de una corrección o cuando un análisis posterior deje de informarlo. Comparar análisis por sí solo no demuestra que una corrección haya funcionado.

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

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

Corregir hallazgos después de un análisis

Utilice scan --patch para corregir hallazgos después de un análisis completo. Esto requiere @openai/codex-security 0.1.15 o posterior. 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 verificados y ya corregidos no activan --fail-on-severity.

Corregir hallazgos guardados

Pase un ID de hallazgo o aparición para corregir su repositorio original, o seleccione 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. Los comandos de hallazgos guardados admiten --json; las entradas de texto literal y de archivos no.

Añada --create-pr para crear un commit únicamente con los archivos de corrección verificados y abrir una solicitud de incorporación de cambios con GitHub CLI:

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

Si falla el envío o la solicitud de incorporación de cambios, ejecute el comando patch --resume-pr BRANCH mostrado desde el mismo repositorio para volver a intentarlo.

Corregir incidencias de Linear

Establezca CODEX_SECURITY_LINEAR_API_KEY o LINEAR_API_KEY para usar una API key personal, o LINEAR_ACCESS_TOKEN para usar un token de OAuth. Prefiera una variable de entorno a --linear-api-key KEY para mantener la clave fuera del historial del shell.

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

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

Utilice --linear-project para seleccionar las incidencias abiertas de un proyecto. Añada --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, salvo que el filtro establezca state. No modifica las incidencias de Linear.

codex-security login, logout y info

Inicie sesión de forma interactiva:

npx @openai/codex-security login

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

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

Compruebe la sesión actual:

npx @openai/codex-security login status

Elimine la sesión almacenada:

npx @openai/codex-security logout

Almacene una API key pasándola por stdin:

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

Almacene un token de acceso empresarial:

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

Inspeccione los metadatos de solo lectura del SDK y del plugin incluido:

npx @openai/codex-security info --json

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

Leer 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 en stdout. Solicite --json, --format o --full-output para enviar resultados de análisis estructurados a stdout.

Las terminales interactivas muestran un panel en tiempo real con la fase actual del análisis, los archivos revisados, la actividad, el uso de tokens y el costo estimado. CI y la salida redirigida utilizan progreso en texto sin formato. Añada --headless para usar progreso en texto sin formato en una terminal interactiva:

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

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

Diagnósticos detallados

Añada --verbose para mostrar en stderr diagnósticos con información confidencial ocultada del ciclo de vida, la autenticación, el progreso y el costo:

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

Establezca CODEX_SECURITY_LOG_LEVEL=debug para habilitar los mismos diagnósticos sin el indicador. LOG_LEVEL=debug también habilita los diagnósticos cuando CODEX_SECURITY_LOG_LEVEL no está configurado.

Resumen de finalización

Un análisis completado escribe en stderr el número de hallazgos abiertos del repositorio, el desglose por gravedad, 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. Por ejemplo:

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  ELAPSED   1s
  TOKENS    1,250 input, 200 cached, 30 output
  RESULTS   /path/to/scan

Los hallazgos informativos cuentan para el total del resumen. Las políticas de gravedad evalúan únicamente los hallazgos critical, high, medium y low del análisis actual, no los hallazgos anteriores que se muestran en el total del repositorio.

Salida JSON

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

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

Al aplicar correcciones, la salida JSON también incluye los resultados de las correcciones y cualquier solicitud de incorporación de cambios creada.

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.

Artefactos del análisis

Un análisis completado conserva juntos el informe legible y los artefactos estructurados. El manifiesto sellado registra los hashes de los artefactos para que quienes los consulten después puedan comprobar que esos archivos no han cambiado:

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

Los archivos estructurados cumplen funciones diferentes:

Consulte scan.status en scan-manifest.json para conocer el estado de ejecución: completed, failed, canceled o interrupted. Los resultados nuevos no incluyen coverage.completeness. Revise las superficies aplazadas, las exclusiones explícitas y las preguntas abiertas en coverage.json para comprender qué revisó el análisis.

Códigos de salida y señales

La CLI utiliza estos códigos de salida:

Las lagunas de cobertura no cambian el código de salida de un análisis completado ni eluden su política de gravedad. El código de salida 0 no significa que se hayan revisado todos los archivos. Cuando solicita una salida estructurada, los análisis completados y las publicaciones parciales siguen escribiendo los resultados disponibles en stdout. La CLI muestra la ubicación de cualquier salida parcial tras una interrupción o un error de ejecución.

Permisos de análisis local

Los análisis de la CLI y el SDK se ejecutan con sus permisos locales del sistema operativo. Cada análisis utiliza el perfil del sistema de archivos codex_security_scan y establece approvalPolicy en "never". El perfil permite leer el sistema de archivos local y escribir en las raíces del espacio de trabajo y en el directorio de estado del análisis seleccionado. Los análisis no se detienen para solicitar aprobación interactiva.

La configuración proporcionada mediante --codex de la CLI o codexOverrides del SDK, incluidos approval_policy, sandbox_mode y los permisos del sistema de archivos, no puede sustituir ni restringir estos controles de análisis. Las restricciones del host y de red siguen aplicándose.

Los procesos de análisis y del entorno de trabajo pueden heredar su entorno, incluidos los tokens de API y las credenciales de la nube que no estén relacionados. Elimine las credenciales no relacionadas antes de iniciar un análisis.

Autenticación y requisitos previos

Establezca OPENAI_API_KEY o CODEX_API_KEY, inicie sesión con npx @openai/codex-security login o utilice una sesión existente de Codex respaldada por archivos. Para OpenRouter o Fireworks, establezca la API key del proveedor y seleccione un modelo. Para Amazon Bedrock, utilice una API key de Bedrock o la cadena estándar de credenciales de AWS.

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

Para CI, limite el alcance de la API key al paso del análisis y utilice un flujo de trabajo de confianza.

La CLI requiere Node.js 24 o 26, o Node.js 22 a partir de 22.13.0. Los análisis, los análisis masivos, 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. Use --python con scan, bulk-scan o export, o configure PYTHON para cualquier comando basado en Python.

Continúe con el inicio rápido de la CLI, la guía de análisis masivos, 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|-