Español

Revisar los cambios de código para detectar problemas de seguridad

Revisa las solicitudes de incorporación de cambios y los cambios locales para detectar regresiones de seguridad manualmente o en CI/CD.

Ejecuta una revisión de seguridad de los cambios para detectar regresiones en un conjunto de cambios respaldado por Git. Codex revisa cada archivo modificado similar a código fuente y el código directamente relacionado que lo respalda. No amplía la revisión para convertirla en una auditoría completa del repositorio.

Si quieres 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 Security, selecciona Scans y selecciona + Scan. Elige el repositorio y, luego, selecciona Changes. Revisa los cambios sin confirmar, una sola confirmación o una revisión base y una revisión principal. Deep scan no está disponible para un análisis de cambios.

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

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

Para una confirmación o un intervalo de ramas, identifica ambos extremos 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 una solicitud de incorporación de cambios cuando sus revisiones base y principal estén disponibles en la copia de trabajo local.

Confirmar el cambio en la configuración

  1. Selecciona Changes.
  2. Confirma el repositorio cuya copia de trabajo está activa, la rama actual y la confirmación más reciente.
  3. En Changes to review, elige:
    • Uncommitted changes para el árbol de trabajo actual.
    • La confirmación más reciente para revisar una sola confirmación.
    • Una revisión base y una revisión principal para un intervalo de ramas o de una solicitud de incorporación de cambios.
  4. Confirma que el resumen describa el cambio que querías revisar.
  5. Selecciona Start scan.

El flujo de trabajo no cambia a otra rama ni modifica el árbol de trabajo seleccionado. Si una revisión solicitada no está disponible localmente, recupérala antes de la revisión o proporciona revisiones base y principal disponibles localmente.

Actuar sobre los hallazgos

Después de revisar los resultados, corrige y verifica un hallazgo aceptado o exporta y haz un seguimiento de los hallazgos.

Automatizar las revisiones en CI/CD

Ejecuta la misma habilidad $codex-security:security-diff-scan desde CI cuando el ejecutor pueda invocar la CLI de Codex sin interacción. Primero, instala la CLI y el plugin sin exponer la credencial del análisis:

npm install --global @openai/codex

Instala el plugin Codex Security en la CLI:

codex plugin add codex-security@openai-curated

El comando de instalación utiliza el marketplace público de plugins de la CLI de Codex, que puede ofrecer una versión diferente a la del catálogo alojado de la aplicación de escritorio. Consulta el registro de cambios del plugin antes de depender de una versión o función específica del plugin en CI.

Luego, expón una API key de OpenAI desde el almacén de secretos de CI como CODEX_SECURITY_API_KEY únicamente para 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 análisis escribe su salida en $TMPDIR/codex-security-scans/<repository>/<scan-id>/:

Archivo Contenido
report.md Punto de entrada principal y legible al directorio completo del análisis.
findings/<slug>/ Un informe detallado de vulnerabilidad por cada hallazgo notificable, con archivos de prueba de concepto complementarios cuando estén disponibles.
hardening/ Portafolio de refuerzo estructural y propuestas o diagramas complementarios cuando el análisis tenga hallazgos notificables.
findings.json Hallazgos con identificadores estables, gravedad, confianza, ubicaciones de origen y medidas correctivas. Proporciona estos datos a flujos de trabajo internos de seguridad aprobados o a herramientas posteriores.
scan-manifest.json Recibo sellado del análisis con el objetivo revisado, las revisiones y los hashes de los artefactos.
coverage.json Superficies revisadas y aplazadas, exclusiones y exhaustividad de la cobertura.

El esquema de findings.json define la estructura completa. El esquema incluye estos campos:

Campo Tipo Descripción
documentType Cadena Identifica el documento como codex-security.findings.
schemaVersion Cadena Identifica la versión del esquema de hallazgos.
scanId Cadena Identifica el análisis que produjo los hallazgos.
findings Matriz Contiene cero o más objetos de hallazgo.
findings[].findingId Cadena Identificador estable del hallazgo derivado de su huella digital.
findings[].occurrenceId Cadena Identifica esta aparición del hallazgo en un análisis específico.
findings[].ruleId Cadena Identifica la familia de vulnerabilidades.
findings[].identity Objeto Contiene el ancla semántica y un identificador opcional de instancia relacionada.
findings[].fingerprints Objeto Contiene el algoritmo de huella digital y la huella digital principal.
findings[].title Cadena Proporciona el título breve del hallazgo.
findings[].summary Cadena Resume la vulnerabilidad y su impacto.
findings[].severity Objeto Contiene el nivel de gravedad y los detalles opcionales de puntuación.
findings[].confidence Objeto Contiene el nivel de confianza y su justificación.
findings[].taxonomy Objeto Contiene la categoría de la vulnerabilidad y los identificadores CWE.
findings[].locations Matriz Enumera los archivos afectados, los números de línea y las funciones de las ubicaciones.
findings[].remediation Cadena Describe la corrección recomendada.
findings[].provenance Objeto Identifica el origen del hallazgo.

Por ejemplo, este comando imprime una fila separada por tabulaciones por cada hallazgo:

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

Estos ejemplos presuponen un ejecutor Linux de confianza con Node.js y npm, Git, Python 3, jq y las herramientas de línea de comandos del proveedor. El prefijo global de paquetes npm debe permitir escritura.

Elige el ejemplo de tu proveedor de CI. Los resultados del análisis pueden incluir detalles confidenciales de vulnerabilidades. Mantén los artefactos privados y publica los hallazgos solo después de revisar el público, el contenido y las aprobaciones necesarias.

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 las solicitudes de incorporación de cambios procedentes de bifurcaciones. Ejecuta trabajos con credenciales únicamente desde una definición de canalización protegida y solo para colaboradores de confianza a los que se pueda permitir usar la credencial del análisis. Archiva codex-security-scans para conservar juntos los hallazgos estructurados, el manifiesto, los artefactos de cobertura, report.md y sus salidas vinculadas findings/ y hardening/. Comienza con resultados informativos y revisa la cobertura y el tiempo de ejecución antes de convertir el trabajo en una comprobación obligatoria.

Para obtener información sobre la gestión de API key y los controles del entorno aislado, consulta el Modo no interactivo. Si tu organización permite la Codex GitHub Action, esta puede instalar la CLI durante la ejecución, pero aun así debes instalar primero el plugin y dirigir la entrada codex-home de la acción al mismo CODEX_HOME.