Ejecutar análisis de seguridad masivos

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

Elegir una fuente 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

Configura 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 para cada repositorio y revisión fijada:

id,repository,revision,scope,mode
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep

El 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 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 el número de análisis simultáneos de repositorios y su valor predeterminado es 4. 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 de análisis y ámbito del repositorio.

La CLI obtiene 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 requeridos.

Elegir un modelo y el esfuerzo de razonamiento

De forma predeterminada, los análisis masivos usan gpt-5.6-sol con un esfuerzo de razonamiento xhigh. Para elegir otro modelo y esfuerzo 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 esfuerzo admitidos son minimal, low, medium, high y xhigh.

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 independientes 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 ámbitos y los modos de análisis de la campaña.
• results.jsonl registra cada intento del repositorio, su estado, el directorio de artefactos y cualquier detalle disponible sobre costes o errores.
• report.md proporciona un informe legible de un intento del repositorio.
• findings.json y coverage.json registran los hallazgos y el ámbito revisado de ese intento.

Exporta un análisis completado de un repositorio 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 extractos del 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 repositorios que aún necesitan procesamiento. Solo omite un repositorio completado cuando todavía existen el comprobante correspondiente y todos los artefactos de análisis requeridos.

No cambies el inventario de repositorios 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 ámbitos o los modos de análisis.

Reintentar errores de repositorios

Usa --max-attempts para volver a intentar un repositorio después de un error temporal al obtenerlo o analizarlo:

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 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 admitir 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, configura CODEX_SECURITY_GIT_HOST con tu host de GitHub.

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