Documentación de ChatGPT
Español
Contacto goolvyouyou@gmail.com

Ejecutar Codex Security en GitHub Actions

Analice pull requests y repositorios con la acción de Codex Security, guarde informes, cargue SARIF y configure la aplicación de políticas.

Ejecute Codex Security en GitHub Actions para revisar los cambios de pull requests o analizar su repositorio de forma programada. La acción instala la CLI, guarda informes estructurados y añade un resumen del trabajo y anotaciones en el código fuente. Empiece con resultados informativos y configure la aplicación de políticas después de revisar la cobertura y la calidad del análisis.

Preparar el flujo de trabajo

Para ejecutar análisis se necesita acceso a Codex Security. Para añadir su API key de OpenAI:

  1. En su repositorio de GitHub, abra Settings → Secrets and variables → Actions.
  2. Seleccione New repository secret.
  3. Introduzca CODEX_SECURITY_API_KEY como nombre y pegue su API key de OpenAI como valor. Guarde el secreto.

Los ejemplos de flujo de trabajo siguientes pasan este secreto a la acción de Codex Security automáticamente. No necesita incluir su API key en el archivo del flujo de trabajo.

Ejecute el flujo de trabajo solo en repositorios y pull requests de confianza. Los análisis usan los permisos locales del ejecutor y no se detienen para solicitar aprobación. Mantenga las credenciales no relacionadas y los pasos de despliegue en trabajos separados.

Añadir el flujo de trabajo de GitHub Actions

Analizar el repositorio de forma programada

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

  1. En su repositorio, seleccione Add file → Create new file.
  2. Asigne al archivo el nombre .github/workflows/codex-security-repository.yml.
  3. Pegue el siguiente flujo de trabajo y confirme los cambios en su 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 }}

Adapte el ejecutor: La acción necesita Node.js 24 y Python 3.11 o posterior, que este ejecutor proporciona. La configuración del entorno aislado instala el paquete bubblewrap y carga el perfil de AppArmor proporcionado antes del análisis. Instalar solo el paquete no basta en este ejecutor.

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

Los hallazgos solo se incluyen en los informes porque fail-on-severity es none. Los errores del analizador y de la generación obligatoria de informes siguen haciendo que el trabajo falle.

Para analizar carpetas específicas, añada rutas literales separadas por saltos de línea al bloque with del paso de análisis:

paths: |
  src/api
  src/auth

Las rutas requieren scope: repository y no expanden patrones glob. Para los análisis de diferencias, omita paths. Mantenga persist-credentials: false y ejecute el análisis inmediatamente después de extraer el código.

Analizar los cambios de pull requests

Con el mismo secreto, cree .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 }}

Abra o actualice un PR desde una rama del mismo repositorio. La acción usa el historial completo para encontrar la base de fusión exacta y analiza los cambios hasta el HEAD del PR extraído. Consulte la comprobación Codex Security en Checks dentro del PR. Empiece con hallazgos informativos y, después, elija una política de gravedad cuando esté listo para condicionar la aceptación de cambios.

Este ejemplo omite los PR de bifurcaciones y los PR abiertos por dependabot[bot]. Un trabajo omitido no demuestra que se haya realizado una revisión de seguridad. Para incluir estos PR de bots, elimine la exclusión del actor y también configure CODEX_SECURITY_API_KEY como un secreto para dependabot[bot]. La acción no admite pull_request_target ni workflow_run.

El analizador lee las instrucciones aplicables de SECURITY.md en el código extraído, incluidos los cambios de políticas del PR. Revise esos cambios junto con el código.

Configurar el acceso opcional a Daybreak

Daybreak es opcional. Ambos ejemplos de flujo de trabajo usan gpt-6-sol. Si su organización ha recibido aprobación para Trusted Access for Cyber, elimine el # situado antes de cyber-access-program en el bloque with del paso de análisis:

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

Use una API key de un proyecto que tenga Daybreak Blue habilitado y acceso a gpt-6-sol.

La entrada del programa también acepta standard. Sin acceso a Daybreak, use un modelo al que su API key tenga acceso con las medidas de protección estándar y omita cyber-access-program o establézcalo en standard. Seleccionar un modelo o programa no concede acceso. Consulte las instrucciones de acceso a Daybreak de la acción.

Un rechazo o bloqueo de seguridad que interrumpa el análisis hace que la acción falle, incluso cuando fail-on-severity es none. Esa entrada controla la política de hallazgos, no los errores del analizador.

Establecer un presupuesto opcional para los análisis

Ambos ejemplos de flujo de trabajo omiten max-cost, por lo que no tienen un umbral de detención por costo estimado. Para establecer uno, añada un importe positivo en USD con la entrada max-cost. Para los análisis directos con la CLI, use --max-cost.

El límite de costo requiere que la CLI disponga de información de precios del modelo seleccionado. El umbral estimado no es un límite estricto de gasto: el costo de las solicitudes ya en curso puede superarlo. Revise los hallazgos y coverage.json si un análisis se detiene al alcanzar el umbral. Consulte opciones de salida y políticas para conocer el comportamiento del límite de costo.

Guardar informes y cargar SARIF

Los ejemplos establecen upload-artifacts: "true" para guardar informes descargables con un período de retención de siete días. Los informes pueden contener fragmentos de código fuente, evidencias de vulnerabilidades y detalles de corrección. Elija un período de retención y un nivel de acceso al repositorio adecuados para su código. La acción solo carga informes validados incluidos en su lista de permitidos; no cargue recursivamente su salida results-directory.

La carga de SARIF es opcional. Para los repositorios privados o internos, habilite GitHub Code Security antes de cargarlo. Sustituya el bloque permissions del flujo de trabajo por:

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

Después, añada este paso tras el análisis en cualquiera de los flujos de trabajo:

- 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 PR, use category: codex-security-pr para que cada alcance tenga una categoría distinta. Mantenga id: security en el paso de análisis. Los informes completos y validados siguen disponibles para su carga cuando los hallazgos incumplen la política de gravedad. SARIF no se carga si los análisis fallan o se interrumpen, si no hay diferencias o si se realizan ejecuciones de prueba.

Consulte la referencia de entradas y salidas de la acción para conocer toda la configuración, los campos de estado y las rutas de los informes.

Elegir una política de gravedad

Los flujos de trabajo de GitHub empiezan con fail-on-severity: none. Para que fallen ante hallazgos de gravedad alta o crítica de un análisis completado, cambie la entrada del paso de análisis:

fail-on-severity: high

Establezca Codex Security como comprobación de estado obligatoria en las reglas de su repositorio para bloquear las fusiones cuando falle el trabajo del PR. GitHub considera correcto un trabajo omitido condicionalmente, incluso en las comprobaciones obligatorias. Los PR de bifurcaciones y los PR de dependabot[bot] superan esta comprobación sin un análisis. Para bloquear esas omisiones, exija un análisis completado correctamente.

La acción sigue el resultado de la CLI:

  • El código de salida 0 establece scan-status: completed y policy-status: passed.
  • El código de salida 1 establece scan-status: completed y policy-status: failed; el paso falla si hay hallazgos cuya gravedad sea igual o superior a la configurada.
  • El código de salida 2 o un proceso interrumpido establece scan-status: failed y policy-status: not-evaluated; el paso falla.
  • Los informes obligatorios no válidos o ausentes, los cambios en el código extraído, los fallos al cargar los artefactos solicitados y los fallos de limpieza del entorno de ejecución también hacen que el paso falle.

Un análisis completado significa que el análisis configurado produjo un resultado válido. Las exclusiones de alcance, las investigaciones aplazadas y otras notas de coverage.json no crean un resultado de análisis independiente ni permiten eludir la política de gravedad. La finalización no certifica que se hayan encontrado todas las vulnerabilidades. Revise coverage.json al evaluar el resultado.

Exigir un análisis completado correctamente

Para aplicar una política más estricta, añada un control independiente que se ejecute incluso si el trabajo de análisis falla o GitHub lo omite. Un paso dentro del trabajo de análisis no puede comprobar un trabajo omitido porque ninguno de sus pasos se ejecuta.

En el flujo de trabajo de PR, añada esta asignación outputs al trabajo security existente, con la misma sangría que runs-on y steps:

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

Después, añada este trabajo bajo jobs, junto al 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

Establezca Codex Security gate como comprobación de estado obligatoria para esta política. Este control requiere tanto un trabajo de análisis correcto como scan-status: completed. Comprobar ambos conserva los fallos de la política de gravedad, la generación de informes y la limpieza, incluso cuando el análisis en sí se haya completado.

Con las exclusiones del ejemplo, este control bloquea los PR de bifurcaciones y los PR de dependabot[bot]. También bloquea los casos sin diferencias y las ejecuciones de prueba, que la acción marca como skipped. El control no analiza los PR excluidos. Elija 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: Extraiga el HEAD del PR con fetch-depth: 0.
  • Error al iniciar el entorno aislado: En Ubuntu 24.04, instale el paquete bubblewrap y cargue el perfil de AppArmor antes de la acción. Instalar solo el paquete no carga el perfil necesario.
  • Faltan credenciales: Confirme que CODEX_SECURITY_API_KEY esté disponible para el flujo de trabajo de confianza y 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: Revise las exclusiones de alcance y las investigaciones aplazadas en coverage.json. Estas notas no provocan fallos de ejecución ni permiten eludir la política de gravedad.
  • Falta SARIF: Inspeccione scan-status, report-status y sarif-upload-ready. Si falta el SARIF opcional, la acción emite una advertencia sin cambiar el resultado del análisis; los fallos al cargar los artefactos solicitados siguen haciendo que el trabajo falle.
  • Error al cargar SARIF: Confirme que su organización haya habilitado GitHub Code Security para el repositorio y que el flujo de trabajo conceda actions: read, contents: read y security-events: write.

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