Ejecutar Codex Security en GitLab CI/CD

Ejecute Codex Security en GitLab CI/CD para analizar cambios confirmados y ramas protegidas, publicar hallazgos en GitLab Security y, opcionalmente, proponer correcciones verificadas en solicitudes de fusión en borrador.

El flujo de trabajo mantiene las credenciales de análisis separadas del acceso de escritura al repositorio. Los cambios generados siempre requieren revisión humana antes de la fusión.

Comience con informes dedicados únicamente al análisis. Habilite la remediación solo después de comprobar los límites del ejecutor, los hallazgos y las credenciales de su proyecto.

Antes de comenzar

Necesita:

• Un proyecto de GitLab con un ejecutor de confianza compatible con el espacio de nombres de usuario del entorno aislado de Codex.
• El rol de Maintainer u Owner en el proyecto de GitLab para poder configurar variables de CI/CD del proyecto y recursos protegidos.
• Una API key de OpenAI con acceso a Codex Security. Las organizaciones que usan claves de Platform API pueden solicitar Trusted Access para Cyber. Las personas que usan la autenticación de ChatGPT pueden utilizar el flujo personal de Trusted Access. Algunas cuentas o repositorios requieren este acceso para los análisis de repositorios completos.
• GitLab Ultimate 19.2 o una versión posterior para la ingesta de SARIF 2.1.0.
• El historial completo de Git para que los trabajos de solicitudes de fusión puedan calcular la base de fusión.

La imagen de la canalización instala Node.js 26, Python 3, Git, rg y la versión fijada de Codex Security CLI. La remediación automatizada también requiere una prueba de regresión existente y un ejecutor capaz de ejecutar comandos controlados por el repositorio sin credenciales protegidas.

Comenzar con una canalización dedicada únicamente al análisis

Cree una variable de GitLab CI/CD protegida, enmascarada y oculta denominada CODEX_SECURITY_API_KEY. Use una API key de OpenAI Platform con acceso a Codex Security y establezca su ámbito de entorno en codex-security/openai. Consulte variables de CI/CD con ámbito de entorno.

Añada primero esta canalización mínima a un proyecto de prueba. Analiza los cambios confirmados en solicitudes de fusión protegidas aptas, publica SARIF desde un trabajo de informe correcto y restaura el resultado del analizador en una puerta independiente:

stages:
  - security_scan
  - security_gate

.codex-security-merge-request:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID && $CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED == "true" && $CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED == "true"'

codex-security:
  extends: .codex-security-merge-request
  stage: security_scan
  image: node:26-bookworm-slim
  environment:
    name: codex-security/openai
    action: access
  variables:
    GIT_DEPTH: "0"
  before_script:
    - npm install --prefix /tmp/codex-security-cli --ignore-scripts --no-audit --no-fund @openai/codex-security@0.1.20
  script:
    - |
      set -eu
      test -n "${CODEX_SECURITY_API_KEY:-}"

      CODEX_SECURITY_BIN="/tmp/codex-security-cli/node_modules/.bin/codex-security"
      RESULTS_DIR="/tmp/codex-security-results-$CI_JOB_ID"
      ARTIFACT_DIR="codex-security-artifacts"
      BASE_REVISION="$(git merge-base \
        "$CI_MERGE_REQUEST_DIFF_BASE_SHA" "$CI_COMMIT_SHA")"
      install -d -m 700 "$RESULTS_DIR" "$ARTIFACT_DIR/results"

      codex_security_api_key="$CODEX_SECURITY_API_KEY"
      unset CODEX_SECURITY_API_KEY
      set +e
      OPENAI_API_KEY="$codex_security_api_key" \
        "$CODEX_SECURITY_BIN" scan . \
          --diff "$BASE_REVISION" \
          --head "$CI_COMMIT_SHA" \
          --auth api-key \
          --output-dir "$RESULTS_DIR" \
          --json
      scan_exit="$?"
      set -e
      unset codex_security_api_key

      case "$scan_exit" in
        0|1|2) ;;
        *) exit "$scan_exit" ;;
      esac

      "$CODEX_SECURITY_BIN" export "$RESULTS_DIR" \
        --export-format sarif \
        --source-root "$CI_PROJECT_DIR" \
        --output "$ARTIFACT_DIR/results.sarif"
      test -s "$ARTIFACT_DIR/results.sarif"
      cp -R "$RESULTS_DIR"/. "$ARTIFACT_DIR/results/"
      printf '%s\n' "$scan_exit" > "$ARTIFACT_DIR/scan-exit-code.txt"
      exit 0
  artifacts:
    when: always
    access: maintainer
    expire_in: 7 days
    paths:
      - codex-security-artifacts/
    reports:
      sarif: codex-security-artifacts/results.sarif

codex-security-gate:
  extends: .codex-security-merge-request
  stage: security_gate
  image: alpine:3.20
  needs:
    - job: codex-security
      artifacts: true
  script:
    - exit "$(cat codex-security-artifacts/scan-exit-code.txt)"

Revise cada cambio en .gitlab-ci.yml antes de ejecutar un trabajo que contenga secretos. El ejemplo mínimo omite intencionadamente los análisis completos y la remediación.

Adoptar la canalización de producción

1. Descargue la canalización completa de GitLab y guárdela como .gitlab-ci.yml en la raíz del repositorio. Si su repositorio ya tiene una canalización, integre en el archivo existente las etapas, plantillas ocultas y trabajos del ejemplo.
2. Conserve las etapas de compilación, prueba e implementación existentes. Si el proyecto usa workflow: rules, confirme que permite los eventos de canalización que desea analizar.

El ejemplo añade las etapas security_scan, security_remediation, security_publish y security_gate. Los informes dedicados únicamente al análisis solo requieren CODEX_SECURITY_API_KEY.

De forma predeterminada, el trabajo de análisis solo se ejecuta para solicitudes de fusión del mismo proyecto entre ramas protegidas. Establezca CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH=true para analizar los envíos a la rama predeterminada protegida y las canalizaciones manuales. Establezca CODEX_SECURITY_SCHEDULED_DEEP_SCAN=true y configure presupuestos explícitos de tiempo y coste para habilitar análisis profundos programados en la rama predeterminada protegida.

Una canalización de solicitud de fusión puede acceder a variables y ejecutores protegidos solo cuando:

• Protege las ramas de origen y destino en el mismo proyecto.
• El proyecto permite que las canalizaciones de solicitudes de fusión accedan a variables y ejecutores protegidos.
• El usuario que inicia la canalización puede enviar cambios o fusionarlos en la rama de destino.

Las canalizaciones de bifurcaciones y las solicitudes de fusión no protegidas no reciben la credencial de análisis. Revise cada cambio en .gitlab-ci.yml antes de ejecutar un trabajo que contenga secretos. Enmascarar y ocultar una variable no hace que el código de CI no confiable sea seguro.

Ejecutar un análisis y revisar los hallazgos

Cree una solicitud de fusión protegida apta o ejecute la canalización en la rama predeterminada protegida. Comience con una diferencia pequeña antes de ejecutar un análisis de pago del repositorio completo.

Abra el trabajo codex-security y confirme que sus artefactos incluyen:

• scan-manifest.json
• findings.json
• coverage.json
• results.sarif
• scan-exit-code.txt

A continuación, abra la pestaña Security de la canalización, revise las advertencias de ingesta y confirme los identificadores de los hallazgos, los niveles de gravedad y las ubicaciones en el código fuente. Los análisis de la rama predeterminada también crean registros de vulnerabilidades del proyecto. Los hallazgos de solicitudes de fusión aparecen en la pestaña Security de la canalización o en el widget de seguridad de la solicitud de fusión, pero no crean registros de vulnerabilidades para todo el proyecto.

Restrinja el acceso a los artefactos porque los resultados del análisis pueden contener fragmentos de código fuente vulnerable, pruebas y detalles de remediación.

Elegir un perfil de análisis

La canalización selecciona un perfil a partir del activador:

Los análisis de solicitudes de fusión centran los comentarios en el cambio confirmado. Los análisis de la rama predeterminada revisan el repositorio integrado. Los análisis profundos programados proporcionan una cobertura periódica más amplia. Un análisis de diferencias completado solo se aplica a ese cambio y no demuestra que todo el repositorio esté limpio.

El flujo de trabajo instala la CLI fuera del repositorio y la ejecuta mediante una ruta absoluta. Su comprobación preliminar en seco usa la API key limitada al proceso, pero no inicia un análisis de pago ni verifica la autenticación de API, el acceso a Codex Security, la cuota ni la disponibilidad del modelo.

El flujo de trabajo escribe el estado y los resultados del análisis fuera del árbol de trabajo y limita OPENAI_API_KEY al proceso de análisis. La CLI recibe un entorno pequeño y explícito en lugar de heredar todas las variables de GitLab. Para los análisis de diferencias, el flujo de trabajo calcula la base de fusión y vincula el análisis a las revisiones base y de cabecera revisadas.

El ejemplo fija @openai/codex-security en 0.1.20. Vuelva a probar la autenticación, los artefactos, la ingesta de SARIF y el control de políticas antes de cambiar la versión fijada.

Separar los informes de la aplicación de políticas

GitLab ingiere SARIF desde un trabajo de informe correcto. La canalización publica primero el informe y restaura el estado de salida del analizador en un trabajo codex-security-gate independiente.

El trabajo de informe acepta hallazgos de los códigos de salida 0 y 1. Acepta el código de salida 2 solo cuando el manifiesto del análisis demuestra que este finalizó, la cobertura es explícitamente partial y existe un informe SARIF no vacío. Los demás errores de tiempo de ejecución, configuración o exportación siguen bloqueando la canalización.

La puerta final conserva estos códigos de salida del analizador:

El ejemplo permite temporalmente la salida 2 mientras calibra la cobertura parcial. Elimine esa excepción cuando la cobertura incompleta deba bloquear la canalización.

La remediación y la publicación se ejecutan antes de la puerta final de la política. Un hallazgo apto puede generar una solicitud de fusión en borrador verificada incluso si después la puerta hace que falle la canalización.

Habilitar la remediación verificada

La remediación automatizada es opcional y solo se ejecuta en canalizaciones de la rama predeterminada protegida. El proceso de remediación de Codex y los comandos de verificación controlados por el repositorio no reciben el token de acceso al proyecto de GitLab ni credenciales inyectadas por el ejecutor.

El contrato de seguridad tiene tres partes: los comandos controlados por el repositorio nunca reciben credenciales de OpenAI o GitLab, solo el trabajo de publicación recibe acceso de escritura al repositorio y cada cambio generado permanece como borrador hasta que una persona lo revisa y fusiona.

El flujo de trabajo:

1. Requiere una cobertura completa del análisis y un hallazgo de gravedad high o critical.
2. Confirma que la prueba de regresión configurada falla antes de aplicar el parche.
3. Genera un parche específico y rechaza los cambios en archivos de CI, credenciales, binarios u otros archivos protegidos.
4. Ejecuta la prueba de regresión sin credenciales de OpenAI, GitLab, registro, implementación o token de trabajo.
5. Usa verify-fix para devolver fixed, still_vulnerable o inconclusive. El trabajo publica un parche solo cuando verify-fix devuelve fixed y el proceso de verificación no modifica el parche.

Establezca estas variables protegidas para habilitar la remediación:

• Establezca CODEX_SECURITY_ENABLE_REMEDIATION en true.
• Establezca CODEX_SECURITY_VERIFICATION_COMMAND en una prueba de regresión existente que finalice con 1 antes de la corrección y con 0 después.
• Opcionalmente, establezca CODEX_SECURITY_SETUP_COMMAND en un comando de configuración de dependencias no interactivo.

Elija una prueba de regresión que compruebe la propiedad de seguridad subyacente, no una implementación concreta. Examine con el mismo rigor los cambios generados en las pruebas y en el código fuente.

Publicar una solicitud de fusión en borrador

Cree un token de acceso al proyecto de GitLab con el rol Developer y los ámbitos api y write_repository. Guárdelo como GITLAB_REMEDIATION_TOKEN protegido, enmascarado y oculto, limitado únicamente al entorno codex-security/publish.

Establezca CODEX_SECURITY_CREATE_MR=true para habilitar la publicación. Establezca también el valor no secreto CODEX_SECURITY_MR_TEST_COMMAND en la prueba de regresión de seguridad específica del proyecto que debe superar cada rama de remediación generada. Mantenga esta variable sin proteger para que la solicitud de fusión no protegida generada pueda leer el comando. El flujo de trabajo de publicación:

• Recibe el token de escritura en el repositorio, pero ninguna credencial de OpenAI.
• Crea una rama codex-security/fix-<finding-hash>.
• Abre una solicitud de fusión en borrador y reutiliza un borrador abierto existente en lugar de crear un duplicado.
• Ejecuta la prueba de regresión de la rama de remediación no protegida como usuario sin privilegios en una copia que solo contiene archivos con seguimiento y no incluye credenciales protegidas.
• Nunca fusiona automáticamente el cambio generado.

No sustituya el token de acceso al proyecto por CI_JOB_TOKEN. No puede realizar la operación necesaria para crear la solicitud de fusión. Revise el parche propuesto, las pruebas de verificación y el hallazgo antes de fusionarlo.

Configurar variables opcionales

Configure únicamente las variables necesarias para las funciones que habilite:

GitLab proporciona las variables CI_*. La canalización administra CODEX_SECURITY_BIN, CODEX_SECURITY_EFFORT, CODEX_SECURITY_MODE, CODEX_SECURITY_STATE_DIR y CODEX_SECURITY_TARGET; no las configure como variables del proyecto. Para los análisis de diferencias, la CLI deriva la identidad canónica del destino a partir de las revisiones base y de cabecera normalizadas.

Ajustar la aplicación de políticas y el coste

Use análisis de diferencias específicos para obtener comentarios sobre las solicitudes de fusión, análisis estándar del repositorio para la rama predeterminada y análisis profundos programados para obtener una cobertura más amplia. Ambos perfiles de repositorio completo están deshabilitados de forma predeterminada. Un análisis profundo programado también requiere CODEX_SECURITY_DEEP_MAX_TIME_HOURS y CODEX_SECURITY_DEEP_MAX_COST; mantenga el presupuesto de tiempo de la CLI por debajo del tiempo de espera de ocho horas del trabajo. Mida ejecuciones representativas antes de establecer un presupuesto. Considere --max-cost como un límite de coste estimado, no como un límite máximo de facturación estricto.

Comience con análisis que solo generen informes. Añada --fail-on-severity después de que su equipo haya revisado hallazgos representativos, la cobertura, el coste y el tiempo de ejecución. Consulte Ejecutar Codex Security en CI para obtener información sobre las políticas de gravedad y los códigos de salida.

Cuando falle un trabajo:

• La ausencia de artefactos de análisis indica un problema de configuración o del ejecutor.
• Si hay artefactos con cobertura parcial, debe revisar coverage.json.
• Si faltan hallazgos de GitLab, compruebe si el trabajo del informe SARIF se completó correctamente y si GitLab aceptó el informe.
• Si se omite la remediación, compruebe la rama protegida, la cobertura completa, la gravedad del hallazgo, el comando de verificación y las variables de activación.
• Si hay errores de publicación, compruebe el rol, los ámbitos y la restricción de entorno del token del proyecto.

Para obtener información sobre cada comando, indicador y artefacto, consulte la referencia de Codex Security CLI.