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 se considera completado cuando su análisis tiene el estado completed en el manifiesto y los artefactos obligatorios de resultados son válidos. Las lagunas de cobertura no hacen que el análisis falle.

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 prompts:

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 de prompt del CSV 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 los análisis satisfactorios y de los errores de análisis, pero no después de una cancelación ni de un análisis que alcance su límite de costo. Las rutas de los archivos de instrucciones se resuelven desde el directorio actual.

Elegir un modelo y un nivel de razonamiento

Los análisis masivos usan gpt-5.6-sol con un esfuerzo de razonamiento xhigh de forma predeterminada. Para seleccionar otro modelo y esfuerzo para una campaña CSV, usa un modelo al que tus credenciales permitan acceder. Si inicias sesión con ChatGPT, consulta la disponibilidad de GPT-6.1 Sol antes de usar este ejemplo:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --model gpt-6.1-sol \
  --effort medium

Las mismas opciones funcionan durante el descubrimiento interactivo de repositorios:

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

Los niveles de esfuerzo disponibles dependen del modelo seleccionado. Los análisis masivos admiten minimal, low, medium, high, xhigh y max; GPT-6.1 Sol requiere como mínimo low.

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 conserva la configuración de la campaña, un registro de cada intento y resultados separados para cada repositorio:

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 y fuera de los repositorios analizados. Establece durante cuánto tiempo se conservarán los resultados.

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 la campaña, inicia nuevos intentos para los repositorios sin terminar que cumplan los requisitos y omite los análisis completados, incluidos aquellos con lagunas de cobertura. Sus resultados siguen disponibles.

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 tiene su propio registro de resultados y directorio de artefactos. Los reintentos abarcan errores al extraer el repositorio, fallos del análisis y artefactos obligatorios ausentes o no válidos. Los análisis completados no se reintentan por lagunas de cobertura ni por incumplimientos de la política de gravedad.

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