Ejecutar análisis de seguridad por lotes

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

Elegir el origen de los repositorios

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

Buscar repositorios en GitHub

Inicia sesión con GitHub CLI:

gh auth login

Inicia un análisis interactivo por lotes:

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 que tuvieron actividad en 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.

La búsqueda excluye los repositorios archivados y los forks. La CLI registra el commit exacto de la rama predeterminada de cada repositorio seleccionado en <output-directory>/repositories.csv. Los análisis comienzan solo después de 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

Configura GH_HOST al iniciar la búsqueda de repositorios:

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

La búsqueda interactiva requiere una terminal. Si trabajas en CI, usas contenedores o ya tienes una lista de repositorios preparada, usa un inventario en CSV.

Crear un archivo CSV de repositorios

Crea un archivo CSV con una fila por repositorio e indica en ella la revisión exacta que quieres analizar:

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 archivo CSV admite estas columnas:

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

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

Ejecutar una campaña a partir de un archivo CSV

Indica el archivo CSV y un directorio de salida privado que esté fuera de los repositorios:

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

--workers controla cuántos repositorios se analizan en paralelo. Su valor predeterminado es 4. La opción no establece la cantidad de procesos independientes que ejecutan análisis estándar dentro de cada análisis profundo. Configura esos límites en [deep_scan]. Usa --mode deep para seleccionar el análisis profundo en las filas que no tengan su propio valor de mode. En cada fila del archivo CSV puedes elegir el modo de análisis y la parte del repositorio que se analizará.

Configura [deep_scan].max_time_hours para limitar el tiempo de ejecución de los procesos de cada análisis profundo de la campaña. La opción --max-time-hours funciona con scan, pero no con bulk-scan.

La CLI crea una copia de trabajo de cada repositorio en la revisión especificada, analiza el contenido seleccionado, registra el resultado y elimina la copia temporal. El análisis de un repositorio se considera completo cuando su estado en el archivo de manifiesto es completed y todos los artefactos de resultados obligatorios son válidos. Las brechas de cobertura no hacen que falle el análisis.

Compartir contexto e instrucciones de seguridad

Agrega documentos de arquitectura, modelos de amenazas o políticas de seguridad a todos los análisis con --knowledge-base. Repite la opción para agregar 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 agregar 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 agrega el valor de prompt de cada repositorio en el CSV después de las instrucciones de análisis compartidas. Las instrucciones de seguimiento se ejecutan en la misma sesión autenticada tanto si el análisis termina correctamente como si ocurre un error. No se ejecutan si se cancela el análisis o si este alcanza su límite de costo. Las rutas de los archivos de prompts se resuelven a partir del directorio actual.

Elegir un modelo y un nivel de esfuerzo de razonamiento

De forma predeterminada, los análisis por lotes usan gpt-5.6-sol con un esfuerzo de razonamiento de xhigh. Para elegir otro modelo y otro nivel de esfuerzo para una campaña basada en un archivo CSV, usa un modelo al que tengas acceso con tus credenciales. Si inicias sesión con ChatGPT, consulta la disponibilidad de GPT-6.1 Sol antes de usar este ejemplo:

1
2
3
4
5npx @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 la búsqueda interactiva de repositorios:

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

Usa un valor de --effort compatible con tu modelo, tu proveedor y tu versión de Codex.

Para usar OpenRouter o Fireworks, configura OPENROUTER_API_KEY o FIREWORKS_API_KEY, respectivamente, y especifica --provider y --model. Para obtener información sobre las credenciales y ver 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 configuración de la campaña, un registro de cada intento y los resultados de cada repositorio por separado:

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    ├── payments/
    │   └── attempt-1/
    │       ├── scan-manifest.json
    │       ├── findings.json
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.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 que se usan en la campaña.
• results.jsonl registra cada intento de análisis de un repositorio, su estado, el directorio de artefactos y los detalles disponibles sobre costos o errores.
• report.md contiene un informe legible de un intento de análisis de un repositorio.
• Abre findings.json para ver los hallazgos del intento y scan-manifest.json para consultar el alcance configurado y lo que se excluyó de la revisión.

Si necesitas un resultado portátil, exporta el análisis completado de un repositorio:

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 sobre vulnerabilidades. Mantén el directorio de salida privado y fuera de los repositorios analizados. Define cuánto tiempo se conservarán los resultados.

Reanudar una campaña

Ejecuta el comando original con el mismo archivo CSV y el mismo 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 e inicia nuevos intentos para los repositorios cuyo análisis quedó pendiente y que cumplen las condiciones para otro intento. Omite los análisis completados, incluidos los que tienen brechas de cobertura. Sus resultados siguen disponibles.

Si usas un directorio de salida existente, conserva el inventario de repositorios y las instrucciones de análisis y seguimiento originales. La CLI comprueba el archivo de manifiesto fijado para la campaña y rechaza cualquier campaña diferente. Usa un directorio de salida nuevo si cambias los repositorios, las revisiones, los alcances, los modos de análisis o las instrucciones compartidas o específicas de cada repositorio.

Reintentar el análisis de un repositorio tras un error

Usa --max-attempts para volver a intentar el análisis de un repositorio si ocurre un error temporal al crear la copia de trabajo o al ejecutar el análisis:

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

De forma predeterminada, se realiza un intento por repositorio. Cada intento tiene su propio registro de resultados y directorio de artefactos. Se puede reintentar si hay errores al crear la copia de trabajo, si falla el análisis o si faltan artefactos obligatorios o estos no son válidos. Los análisis completados no se repiten por brechas de cobertura ni por incumplimientos de la política de gravedad.

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

Ejecutar análisis por lotes en Docker

El repositorio de Codex Security incluye una configuración de Compose con seguridad reforzada para automatizar campañas basadas en archivos CSV en un host de Docker con Linux. El host debe permitir que los usuarios sin privilegios creen espacios de nombres de usuario.

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

Ejecuta la imagen con el archivo 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 archivo CSV y el mismo directorio de salida montados para reanudar la campaña. Si usas GitHub Enterprise Server, asigna a CODEX_SECURITY_GIT_HOST el nombre de tu host de GitHub.

Para ver todas las opciones disponibles, consulta la referencia del comando bulk-scan. Si tienes preguntas sobre la cobertura de los análisis o los hallazgos, consulta las preguntas frecuentes sobre la CLI.