Ejecutar análisis de seguridad masivos

Usa npx @openai/codex-security bulk-scan para revisar repositorios en una sola campaña. Descubre repositorios de tu cuenta personal de GitHub o de una organización, o proporciona un CSV que fije cada repositorio en una revisión de Git exacta.

Elegir un origen de repositorios

Ambos flujos de trabajo guardan el progreso, conservan los resultados de cada repositorio y permiten reanudar una campaña después de una interrupción.

Descubrir repositorios de GitHub

Inicia sesión con GitHub CLI:

gh auth login

Inicia un análisis masivo interactivo:

npx @openai/codex-security bulk-scan

La CLI te guía por estos pasos:

1. Elige tu cuenta personal de GitHub o una organización.
2. Revisa los repositorios activos durante los últimos 90 días.
3. Busca en la lista de repositorios y selecciona los que quieras analizar.
4. Elige un directorio para los resultados del análisis.
5. Revisa los repositorios seleccionados y confirma la campaña.

El descubrimiento excluye los repositorios archivados y las bifurcaciones. La CLI registra el commit exacto de la rama predeterminada de cada repositorio seleccionado en <output-directory>/repositories.csv. No se inicia ningún análisis hasta que confirmes la selección.

Para usar GitHub Enterprise Server, primero inicia sesión en tu host de GitHub:

gh auth login --hostname github.example.com

Establece GH_HOST cuando inicies el descubrimiento de repositorios:

GH_HOST=github.example.com npx @openai/codex-security bulk-scan

El descubrimiento interactivo requiere una terminal. Para CI, contenedores o una lista de repositorios preparada, usa un inventario CSV.

Crear un CSV de repositorios

Crea un CSV con una fila por cada repositorio y revisión fijada:

id,repository,revision,scope,mode,prompt
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard,Review payment authorization and refunds.
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep,Review session and identity boundaries.

El CSV admite estas columnas:

Para encontrar el SHA completo del commit de un repositorio local, ejecuta:

git -C /path/to/repository rev-parse HEAD

Ejecutar una campaña desde un CSV

Pasa el CSV y un directorio de salida privado situado fuera de los repositorios:

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

--workers controla los análisis simultáneos de repositorios y su valor predeterminado es 4. No establece el número de procesos de análisis estándar independientes dentro de cada análisis profundo; configura esos límites mediante [deep_scan]. Usa --mode deep para seleccionar el análisis profundo en las filas que no tengan su propio mode. Cada fila del CSV puede seguir eligiendo su propio modo y alcance de análisis del repositorio.

Establece [deep_scan].max_time_hours para limitar la ejecución de procesos en cada análisis profundo de la campaña. La marca --max-time-hours funciona con scan, no con bulk-scan.

La CLI extrae cada revisión fijada, analiza el objetivo seleccionado, registra el resultado y elimina la copia temporal del repositorio. Un repositorio solo se considera completado cuando su análisis tiene una cobertura completa y existen todos los artefactos de resultados necesarios.

Compartir contexto e instrucciones de seguridad

Añade documentos de arquitectura, modelos de amenazas o políticas de seguridad a cada análisis con --knowledge-base. Repite la marca para añadir más archivos o directorios:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Para añadir instrucciones de análisis compartidas o ejecutar una tarea de seguimiento después de cada análisis, proporciona archivos de indicaciones:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --scan-prompt-file scan-instructions.md \
  --post-scan-prompt-file follow-up.md

La CLI añade el valor CSV prompt de cada repositorio después de las instrucciones de análisis compartidas. Las instrucciones de seguimiento se ejecutan en la misma sesión autenticada después de análisis correctos y de análisis con cobertura incompleta o errores, pero no después de una cancelación ni de un análisis que alcance su límite de coste. Las rutas de los archivos de indicaciones se resuelven desde tu directorio actual.

Elegir un modelo y un nivel de razonamiento

Los análisis masivos usan gpt-5.6-sol con el nivel de razonamiento xhigh de forma predeterminada. Para elegir otro modelo y nivel en una campaña CSV:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --model gpt-5.6-terra \
  --effort high

Las mismas opciones funcionan durante el descubrimiento interactivo de repositorios:

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

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

Para usar OpenRouter o Fireworks, establece OPENROUTER_API_KEY o FIREWORKS_API_KEY, respectivamente, y especifica --provider y --model. Para obtener información sobre credenciales y ejemplos, consulta la configuración de OpenRouter o Fireworks o la configuración de Amazon Bedrock.

Revisar los resultados de la campaña

El directorio de salida contiene la campaña fijada, un registro de resultados de solo adición y artefactos separados para cada repositorio e intento:

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    ├── payments/
    │   └── attempt-1/
    │       ├── scan-manifest.json
    │       ├── findings.json
    │       ├── coverage.json
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            ├── coverage.json
            └── report.md

• manifest.json registra los repositorios, las revisiones fijadas, los alcances, los modos de análisis y las instrucciones compartidas o específicas de cada repositorio de la campaña.
• results.jsonl registra cada intento por repositorio, su estado, el directorio de artefactos y cualquier detalle disponible sobre costes o errores.
• report.md proporciona un informe legible de un intento en un repositorio.
• findings.json y coverage.json registran los hallazgos y el alcance revisado de ese intento.

Exporta un análisis de repositorio completado cuando necesites un resultado portátil:

npx @openai/codex-security export \
  /path/outside/repositories/security-scans/artifacts/payments/attempt-1 \
  --export-format sarif \
  --output /path/outside/repositories/payments.sarif

Los resultados pueden contener fragmentos de código fuente y detalles de vulnerabilidades. Mantén el directorio de salida privado, fuera de los repositorios analizados y sujeto a una política de retención adecuada.

Reanudar una campaña

Ejecuta el comando original con el mismo CSV y directorio de salida:

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

La CLI reanuda los análisis de repositorios sin terminar y omite los completados. Los análisis con cobertura incompleta no se vuelven a intentar. Sus resultados siguen disponibles y el comando finaliza con el código 2.

No cambies el inventario de repositorios ni las instrucciones de análisis y seguimiento de un directorio de salida existente. La CLI comprueba el manifiesto fijado y rechaza una campaña diferente. Usa un nuevo directorio de salida cuando cambies los repositorios, las revisiones, los alcances, los modos de análisis o las instrucciones compartidas o específicas de cada repositorio.

Reintentar errores de repositorios

Usa --max-attempts para volver a intentar un repositorio después de un error temporal de extracción o de análisis:

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

El valor predeterminado es un intento por repositorio. Cada intento recibe su propio comprobante y directorio de artefactos. Los reintentos abarcan errores de extracción, fallos de análisis y la ausencia de artefactos necesarios. Los análisis completados con cobertura incompleta no se vuelven a intentar.

Los análisis masivos usan estos códigos de salida:

Ejecutar análisis masivos en Docker

El repositorio de Codex Security incluye una configuración de Compose reforzada para campañas CSV automatizadas en un host de Docker con Linux. El host debe permitir la creación de espacios de nombres de usuario sin privilegios.

Mantén el CSV de repositorios, los resultados de análisis y el estado de inicio de sesión montados en directorios persistentes. Proporciona las credenciales de OpenAI mediante el entorno o un gestor de secretos. Para repositorios privados de GitHub, proporciona GH_TOKEN o GITHUB_TOKEN del mismo modo.

Ejecuta la imagen con el CSV y el directorio de salida montados:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

Usa el mismo CSV y directorio de salida montados para reanudar la campaña. Para GitHub Enterprise Server, establece CODEX_SECURITY_GIT_HOST en tu host de GitHub.

Para consultar todas las marcas disponibles, consulta la referencia del comando de análisis masivo. Para ver preguntas frecuentes sobre la cobertura y los hallazgos de los análisis, consulta las preguntas frecuentes de la CLI.