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 servidor MCP:

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

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

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

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

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 workers 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 workers, permita hasta diez ejecuciones y detenga la ejecución de los workers 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 workers sin finalizar, conserva los resultados de los análisis completados y los agrega al informe final. Si ningún worker termina la revisión del código fuente, el análisis registra una cobertura parcial y devuelve el código de salida 2.

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 workers 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. Utilice --post-scan-prompt-file para ejecutar instrucciones de seguimiento en la misma sesión autenticada después de análisis correctos y de análisis con cobertura incompleta o errores:

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

Por ejemplo, utilice la indicación 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 límite de gasto estricto. Las solicitudes ya en curso pueden finalizar ligeramente por encima del límite. Si un análisis profundo alcanza el límite después de que Codex Security agregue los resultados completados de los workers, la CLI sella los resultados disponibles, marca la cobertura como partial y devuelve el código de salida 2. De lo contrario, devuelve 2 y deja en el disco cualquier salida parcial 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 distintos sin escribir TOML:

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

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-5.6-terra"'

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

Detecte y analice repositorios de GitHub o ejecute un análisis reanudable desde 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 la detección interactiva:

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

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.

Utilice --knowledge-base PATH para compartir documentos de seguridad entre todos los repositorios. Utilice --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 esa indicación compartida. --post-scan-prompt-file FILE ejecuta instrucciones de seguimiento después de cada análisis, incluidos los análisis con cobertura incompleta o errores. 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. El valor predeterminado de --mode es standard y el de --max-attempts es 1. Establezca --max-attempts para reintentar errores de repositorio o análisis. Los análisis completados con cobertura incompleta no se vuelven a intentar. Sus resultados siguen disponibles y el comando devuelve el código de salida 2.

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

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 workers. Estos registros no están censurados 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 un resultado con formato legible por máquinas que contenga toda la información.

Relacionar y comparar hallazgos

Compare dos análisis para encontrar hallazgos nuevos, persistentes, reabiertos, 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 el análisis posterior tiene una cobertura incompleta o no abarca la ubicación original del hallazgo. Añada --force a match cuando necesite volver a calcular una relación 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.

Tenga en cuenta que los hallazgos anteriores permanecen abiertos hasta que se resuelven o descartan (su ausencia en el análisis más reciente no se interpreta como prueba de 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 confirmar únicamente 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 servidor MCP, 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 están censurados 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 censurados 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, 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:

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  COVERAGE  complete
  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 mostrando 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 mantiene 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 del alcance seleccionado.
• partial: El análisis registra trabajo aplazado u otros límites de cobertura.
• unknown: El análisis informa de que la exhaustividad de la cobertura es desconocida.

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

Códigos de salida y señales

La CLI utiliza estos códigos de salida:

Cualquier análisis con cobertura partial o unknown devuelve 2, incluso sin una política de gravedad. Cuando se 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 después de una interrupción o un error del entorno 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 tokens de API y credenciales de nube no relacionados. Analice únicamente repositorios en los que confíe y que tenga permiso para evaluar, y proporcione solo las credenciales que requiera el 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 22 (22.13.0 o posterior), 24 o 26. 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. Utilice --python con scan, bulk-scan o export, o establezca 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|-