For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegación principal
Theme

Revisar la seguridad de los cambios en el código

Revisa pull requests y cambios locales para detectar regresiones de seguridad, ya sea manualmente o en CI/CD.

Ejecuta una revisión de seguridad para detectar regresiones en un conjunto de cambios de Git. Codex revisa cada archivo modificado que contiene código fuente o contenido similar, junto con el código que le da soporte directo. La revisión se limita a ese alcance y no abarca una auditoría de todo el repositorio.

Para analizar un repositorio completo en lugar de un cambio específico, consulta Ejecutar un análisis de seguridad.

Ejecutar una revisión manual

En la aplicación de escritorio, abre Seguridad, selecciona Análisis y luego + Análisis. Elige el repositorio y selecciona Cambios. Puedes revisar los cambios sin commit, un solo commit o los cambios entre una revisión base y una revisión final. La opción Análisis profundo no está disponible para el análisis de cambios.

También puedes pedirle a Codex en una conversación que revise los cambios sin commit:

Use $codex-security:security-diff-scan to review my current uncommitted changes for security regressions.

Para revisar un rango de commits o los cambios de una rama, especifica ambas revisiones cuando sea necesario:

Use $codex-security:security-diff-scan to review the changes from origin/main to HEAD for security regressions. Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.

También puedes indicar qué pull request quieres revisar si tanto la revisión base como la final están disponibles en la copia local del repositorio.

Confirmar el cambio durante la configuración

  1. Selecciona Cambios.
  2. Confirma el repositorio que tienes abierto en tu copia local, la rama actual y el último commit.
  3. En Cambios para revisar, elige una de estas opciones:
    • Uncommitted changes para revisar los cambios del árbol de trabajo actual.
    • El último commit para revisar solo ese commit.
    • Una revisión base y una revisión final para revisar un rango de cambios de una rama o un pull request.
  4. Confirma que el resumen describa el cambio que quieres revisar.
  5. Selecciona Iniciar análisis.

Codex no cambia de rama ni de árbol de trabajo. Si una revisión solicitada no está disponible localmente, tráela del repositorio remoto antes de la revisión o indica una revisión base y una revisión final que estén disponibles en tu copia local.

Tomar medidas sobre los hallazgos

Después de revisar los resultados, puedes corregir y verificar un hallazgo aceptado o exportar los hallazgos y darles seguimiento.

Automatizar las revisiones en CI/CD

Si usas la CLI independiente, consulta Ejecutar Codex Security en CI para obtener resultados en JSON estructurado, aplicar una política de gravedad y cargar resultados en formato SARIF. Sigue los pasos de esta sección para ejecutar la habilidad del complemento instalado mediante codex exec.

Ejecuta $codex-security:security-diff-scan en CI cuando el runner pueda ejecutar la CLI de Codex sin intervención. Primero, instala la CLI sin exponer la credencial del análisis:

npm install --global @openai/codex

Instala el complemento Codex Security en la CLI:

codex plugin add codex-security@openai-curated

El comando de instalación usa el marketplace público de complementos de la CLI de Codex. Consulta el historial de cambios del complemento para conocer los requisitos de cada versión.

Luego, proporciona una clave de API de OpenAI desde el almacén de secretos de tu sistema de CI mediante CODEX_SECURITY_API_KEY. Expón la credencial solo durante el análisis:

CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
  --sandbox workspace-write \
  "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

El permiso de escritura en el sandbox permite que el análisis genere artefactos temporales. El prompt le exige a Codex que deje intacta la copia local del código fuente.

El análisis guarda sus resultados en $TMPDIR/codex-security-scans/<repository>/<scan-id>/:

Archivo Contenido
report.md Informe principal que sirve de punto de partida para consultar todo el directorio del análisis.
findings/<slug>/ Informes detallados de vulnerabilidades y archivos de prueba de concepto que los respaldan, cuando se solicitan.
hardening/ Recomendaciones para reforzar la seguridad de la estructura del código y propuestas que las respaldan, cuando se solicitan.
findings.json Hallazgos con identificadores estables, nivel de gravedad, nivel de confianza, ubicaciones en el código fuente y medidas de corrección. Usa estos campos en flujos de trabajo de seguridad o en herramientas que procesen los resultados.
scan-manifest.json Comprobante sellado del análisis que incluye el objetivo revisado, las revisiones y los hashes de los artefactos.
coverage.json Áreas revisadas y áreas cuya revisión se pospuso, exclusiones y grado de cobertura alcanzado.

Para conocer las definiciones de los campos, consulta el esquema de los hallazgos. Usa findingId para identificar el hallazgo y occurrenceId para identificar la instancia de ese hallazgo en este análisis.

Por ejemplo, este comando imprime una fila por hallazgo con los campos separados por tabulaciones:

jq -r '
  .findings[] |
  [.findingId, .severity.level, .confidence.level, .locations[0].path, .locations[0].startLine, .title] |
  @tsv
' findings.json

Estos ejemplos suponen que usas un runner Linux de confianza con Node.js y npm, Git, Python 3, jq y las herramientas de línea de comandos del proveedor. Debes tener permisos de escritura en el directorio que npm usa como prefijo para los paquetes globales.

Los resultados del análisis pueden incluir información sensible sobre las vulnerabilidades. Mantén los artefactos privados y revisa el destino y el contenido antes de publicar los hallazgos. Elige el ejemplo de tu proveedor de CI:

Choose an option
name: Codex Security review

on:
  pull_request:

jobs:
  security-review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Install Codex Security
        env:
          CODEX_HOME: ${{ runner.temp }}/codex-home
        run: |
          npm install --global @openai/codex
          codex plugin add codex-security@openai-curated

      - name: Review code changes
        env:
          CODEX_SECURITY_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
          CODEX_HOME: ${{ runner.temp }}/codex-home
          TMPDIR: ${{ runner.temp }}/codex-security
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_REVISION: ${{ github.event.pull_request.head.sha }}
        run: |
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_REVISION")"
          CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
            --sandbox workspace-write \
            "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: codex-security-review
          path: ${{ runner.temp }}/codex-security/codex-security-scans

Los ejemplos omiten los pull requests que provienen de forks. Ejecuta los trabajos que usan credenciales solo desde una definición de pipeline protegida y únicamente para colaboradores a quienes confiarías la credencial del análisis. Archiva codex-security-scans para conservar juntos los hallazgos estructurados, el archivo de manifiesto, los datos de cobertura y report.md, además de los resultados de findings/ o hardening/ que hayas solicitado. Al principio, usa los resultados como referencia y revisa la cobertura y el tiempo de ejecución antes de convertir el trabajo en una verificación obligatoria.

Para saber cómo manejar las claves de API y los controles del sandbox, consulta Modo no interactivo. Si tu organización permite usar la GitHub Action de Codex, esta puede instalar la CLI durante la ejecución. Aun así, primero debes instalar el complemento y configurar el parámetro de entrada codex-home de la acción para que apunte al mismo CODEX_HOME.