Ejecutar Codex Security en GitHub Actions

Ejecuta Codex Security en GitHub Actions para revisar los cambios de los pull requests o analizar tu repositorio de forma periódica. La acción instala la CLI, guarda informes estructurados y agrega un resumen del trabajo y anotaciones en el código fuente. Empieza con resultados informativos y, después de revisar la cobertura y la calidad del análisis, configura las políticas de bloqueo.

Preparar el flujo de trabajo

Para ejecutar análisis, necesitas acceso a Codex Security. Sigue estos pasos para agregar tu clave de API de OpenAI:

1. En tu repositorio de GitHub, abre Settings → Secrets and variables → Actions.
2. Selecciona New repository secret.
3. Ingresa CODEX_SECURITY_API_KEY como nombre y pega tu clave de API de OpenAI como valor. Guarda el secreto.

Los siguientes ejemplos de flujos de trabajo pasan este secreto automáticamente a la acción de Codex Security. No necesitas incluir tu clave de API en el archivo del flujo de trabajo.

Ejecuta el flujo de trabajo solo en repositorios y pull requests de confianza. Los análisis usan los permisos locales del runner y no se detienen para solicitar aprobación. Mantén las credenciales y los pasos de despliegue ajenos al análisis en trabajos separados.

Agregar el flujo de trabajo de GitHub Actions

Programar el análisis del repositorio

El siguiente flujo de trabajo analiza tu rama predeterminada todos los lunes a las 07:23 UTC. También puedes ejecutarlo manualmente desde la pestaña Actions de GitHub. Usa un runner x64 con Ubuntu 24.04 alojado en GitHub y configura automáticamente el sandbox necesario.

1. En tu repositorio, selecciona Add file → Create new file.
2. Asigna al archivo el nombre .github/workflows/codex-security-repository.yml.
3. Pega el siguiente flujo de trabajo y haz commit en tu rama predeterminada.

name: Codex Security repository

on:
  workflow_dispatch:
  schedule:
    - cron: "23 7 * * 1" # Mondays at 07:23 UTC

permissions:
  contents: read

jobs:
  security:
    runs-on: ubuntu-24.04
    timeout-minutes: 120
    steps:
      - name: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

      - name: Check out the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Scan the repository
        id: security
        uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
        with:
          scope: repository
          model: gpt-6-sol
          # For approved Daybreak Blue access, uncomment the next input.
          # cyber-access-program: daybreak_blue
          effort: high
          fail-on-severity: none
          upload-artifacts: "true"
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

Adaptar el runner: la acción necesita Node.js 24 y Python 3.11 o posterior, ambos disponibles en este runner. Durante la configuración del sandbox, se instala el paquete bubblewrap y se carga el perfil de AppArmor incluido antes del análisis. En este runner, no basta con instalar el paquete.

Para ejecutar el flujo de trabajo manualmente, abre Actions → Codex Security repository → Run workflow. Abre una ejecución finalizada para revisar el resumen, las anotaciones y los informes descargables.

Los hallazgos solo se incluyen en el informe porque fail-on-severity tiene el valor none. Si se produce un error en el analizador o en la generación de los informes obligatorios, el trabajo falla de todos modos.

Para analizar carpetas específicas, agrega sus rutas literales, una por línea, al bloque with del paso de análisis:

paths: |
  src/api
  src/auth

Para usar rutas, se requiere scope: repository. Los patrones glob no se expanden. Para analizar diferencias, omite paths. Conserva persist-credentials: false y ejecuta el análisis inmediatamente después del checkout.

Analizar los cambios de un pull request

Usa el mismo secreto y crea .github/workflows/codex-security-pr.yml:

name: Codex Security PR

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read

concurrency:
  group: codex-security-pr-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  security:
    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
    name: Codex Security
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    steps:
      - name: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

      - name: Check out the pull request
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Scan PR changes
        id: security
        uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
        with:
          scope: diff
          model: gpt-6-sol
          # For approved Daybreak Blue access, uncomment the next input.
          # cyber-access-program: daybreak_blue
          effort: high
          fail-on-severity: none
          upload-artifacts: "true"
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

Abre o actualiza un pull request desde una rama del mismo repositorio. La acción usa el historial completo para identificar el commit base exacto de la fusión y analiza los cambios desde esa base hasta el commit del pull request que se obtuvo en el checkout. Consulta la verificación Codex Security en la pestaña Checks del pull request. Empieza con hallazgos informativos y elige una política de gravedad cuando quieras bloquear cambios según los hallazgos.

Este ejemplo omite los pull requests provenientes de forks y los que abre dependabot[bot]. Que se omita un trabajo no demuestra que se haya realizado una revisión de seguridad. Para incluir los pull requests de este bot, elimina la condición que excluye al actor y configura también CODEX_SECURITY_API_KEY como secreto para dependabot[bot]. La acción no admite pull_request_target ni workflow_run.

El analizador lee las directrices aplicables de SECURITY.md en la copia local, incluidos los cambios de política del pull request. Revisa esos cambios junto con el código.

Configurar el acceso opcional a Daybreak

Daybreak es opcional. Ambos ejemplos de flujos de trabajo usan gpt-6-sol. Si tu organización recibió aprobación para el programa Trusted Access for Cyber, elimina el # que precede a cyber-access-program en el bloque with del paso de análisis:

model: gpt-6-sol
cyber-access-program: daybreak_blue

Usa una clave de API de un proyecto habilitado para Daybreak Blue que tenga acceso a gpt-6-sol.

El parámetro del programa también admite standard. Si no tienes acceso a Daybreak, usa un modelo al que tu clave de API tenga acceso con las medidas de seguridad estándar y omite cyber-access-program o asígnale el valor standard. Seleccionar un modelo o programa no otorga acceso. Consulta las directrices de la acción sobre el acceso a Daybreak.

Si un rechazo o un bloqueo de seguridad interrumpe el análisis, la acción falla incluso cuando fail-on-severity tiene el valor none. Ese parámetro controla la política aplicable a los hallazgos y no afecta el tratamiento de los errores del analizador.

Establecer un presupuesto opcional para el análisis

Ambos ejemplos omiten max-cost, por lo que no hay un umbral de costo estimado que detenga el análisis. Para establecer un umbral, asigna un monto positivo en USD al parámetro max-cost. Para los análisis que ejecutes directamente con la CLI, usa --max-cost.

Para aplicar el límite de costo, la CLI debe admitir los precios del modelo seleccionado. El umbral se basa en una estimación y no es un límite estricto de gasto, ya que el costo de las solicitudes en curso puede superarlo. Si el análisis se detiene al alcanzar el umbral, revisa los hallazgos y coverage.json. Consulta las opciones de salida y de política para saber cómo funciona el límite de costo.

Guardar informes y subir archivos SARIF

Los ejemplos usan upload-artifacts: "true" para guardar informes descargables durante siete días. Los informes pueden contener fragmentos de código fuente, evidencias de vulnerabilidades y detalles sobre cómo corregirlas. Elige un período de retención y permisos de acceso al repositorio adecuados para tu código. La acción solo sube los informes validados que figuran en su lista de informes permitidos. No subas de forma recursiva el contenido del directorio indicado en la salida results-directory.

La carga de archivos SARIF es opcional. Para repositorios privados o internos, habilita GitHub Code Security antes de subir el archivo. Reemplaza el bloque permissions del flujo de trabajo por el siguiente:

permissions:
  contents: read
  security-events: write
  actions: read # Required for private repositories

Luego, en cualquiera de los dos flujos de trabajo, agrega este paso después del análisis:

- name: Upload security findings
  if: ${{ always() && steps.security.outputs.sarif-upload-ready == 'true' }}
  uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
  with:
    sarif_file: ${{ steps.security.outputs.sarif-path }}
    sha: ${{ steps.security.outputs.scanned-sha }}
    ref: ${{ steps.security.outputs.analysis-ref }}
    category: codex-security-repository

Para el flujo de trabajo de pull requests, usa category: codex-security-pr para que cada alcance tenga su propia categoría. Conserva id: security en el paso de análisis. Los informes completos y validados siguen disponibles para su carga aunque los hallazgos incumplan la política de gravedad. No se suben archivos SARIF si el análisis falla o se interrumpe, si no hay diferencias o si la ejecución es de prueba.

Consulta la referencia de entradas y salidas de la acción para ver todas las opciones de configuración, los campos de estado y las rutas de los informes.

Elegir una política de gravedad

Los flujos de trabajo de GitHub usan inicialmente fail-on-severity: none. Para que el paso falle si al finalizar el análisis hay hallazgos de gravedad alta o crítica, cambia el parámetro del paso de análisis:

fail-on-severity: high

En las reglas de tu repositorio, establece Codex Security como verificación de estado obligatoria para bloquear la fusión si falla el trabajo del pull request. GitHub considera que un trabajo omitido por una condición tiene un resultado exitoso, incluso cuando la verificación es obligatoria. Los pull requests provenientes de forks y los de dependabot[bot] pasan esta verificación sin que se ejecute el análisis. Para bloquear la fusión en esos casos, exige que el análisis finalice con éxito.

La acción refleja el resultado de la CLI:

• Con el código de salida 0, la acción establece scan-status: completed y policy-status: passed.
• Con el código de salida 1, la acción establece scan-status: completed y policy-status: failed. El paso falla si hay hallazgos de gravedad igual o superior al nivel configurado.
• Si el código de salida es 2 o se interrumpe el proceso, la acción establece scan-status: failed y policy-status: not-evaluated. El paso falla.
• El paso también falla si falta un informe obligatorio o no es válido, si cambia la copia local del código, si falla la carga de los artefactos solicitados o si falla la limpieza del entorno de ejecución.

Cuando el análisis finaliza, significa que se ejecutó con la configuración indicada y produjo un resultado válido. Las exclusiones de alcance, las investigaciones pospuestas y las demás notas de coverage.json no generan un resultado de análisis independiente ni permiten eludir la política de gravedad. Que el análisis finalice no garantiza que se hayan detectado todas las vulnerabilidades. Revisa coverage.json al evaluar el resultado.

Exigir que el análisis finalice con éxito

Para aplicar una política más estricta, agrega una verificación independiente que se ejecute incluso si el trabajo de análisis falla o si GitHub lo omite. Si GitHub omite el trabajo de análisis, ninguno de sus pasos se ejecuta, por lo que no puedes verificar el resultado desde un paso de ese mismo trabajo.

En el flujo de trabajo de pull requests, agrega el siguiente bloque outputs al trabajo security existente, con la misma sangría que runs-on y steps:

outputs:
  scan-status: ${{ steps.security.outputs.scan-status }}

Luego agrega este trabajo dentro de jobs, al mismo nivel que el trabajo security existente:

security-gate:
  name: Codex Security gate
  needs: security
  if: ${{ always() }}
  runs-on: ubuntu-24.04
  steps:
    - name: Require a successful, completed scan
      env:
        SCAN_RESULT: ${{ needs.security.result }}
        SCAN_STATUS: ${{ needs.security.outputs.scan-status }}
      run: test "$SCAN_RESULT" = success && test "$SCAN_STATUS" = completed

Establece Codex Security gate como verificación de estado obligatoria para esta política. La verificación exige que el trabajo de análisis se ejecute con éxito y que el estado sea scan-status: completed. Al comprobar ambas condiciones, la verificación falla si se incumple la política de gravedad o si hay errores en la generación de informes o en la limpieza, incluso cuando el análisis en sí haya finalizado.

Con las exclusiones del ejemplo, esta verificación bloquea los pull requests provenientes de forks y los de dependabot[bot]. También bloquea los casos sin diferencias y las ejecuciones de prueba, que la acción marca como skipped. La verificación no analiza los pull requests excluidos. Elige esta política solo si estos casos deben impedir la fusión.

Solucionar problemas de un análisis

• Referencia de Git desconocida o diferencias inesperadas: haz checkout del último commit de la rama del pull request con fetch-depth: 0.
• Error al iniciar el sandbox: en Ubuntu 24.04, instala el paquete bubblewrap y carga el perfil de AppArmor antes de ejecutar la acción. La instalación del paquete por sí sola no carga el perfil necesario.
• Faltan credenciales: verifica que el flujo de trabajo de confianza tenga acceso a CODEX_SECURITY_API_KEY y que este secreto esté asignado a la variable de entorno OPENAI_API_KEY del paso de análisis.
• Error de configuración de Python: la acción requiere Python 3.11 o posterior.
• Notas de cobertura: revisa las exclusiones de alcance y las investigaciones pospuestas en coverage.json. Estas notas no provocan fallos de ejecución ni permiten eludir la política de gravedad.
• Falta el archivo SARIF: revisa scan-status, report-status y sarif-upload-ready. Si falta el archivo SARIF opcional, la acción emite una advertencia sin cambiar el resultado del análisis. Si falla la carga de los artefactos solicitados, el trabajo falla de todos modos.
• Error al subir el archivo SARIF: verifica que tu organización haya habilitado GitHub Code Security para el repositorio y que el flujo de trabajo otorgue los permisos actions: read, contents: read y security-events: write.

Para conocer todos los comandos, las opciones, los artefactos y los campos de salida, consulta la referencia de la CLI. Para otros proveedores, consulta la descripción general de CI/CD.