Exportación a SARIF e integración con GitHub code scanning

Exporta una auditoría de vetkit completada mediante su endpoint de informes con format=sarif y luego sube el archivo SARIF 2.1.0 desde tu workflow de GitHub Actions. Antes de subirlo, comprueba que la auditoría corresponde al repositorio y al commit que se analizan. Descargar el informe no publica por sí mismo alertas en GitHub; la subida es un paso aparte que configuras tú.

1. Comprueba los requisitos previos

• Ten a mano el ID de la organización, el ID de la auditoría y una API key de vetkit con reports:read. Un workflow automatizado que además inicie auditorías y consulte su estado necesita audits:write y audits:read.
• Confirma el repositorio y el SHA del commit de la auditoría. En CI, solicita o reutiliza una auditoría del commit exacto del workflow y espera a que termine antes de exportarla.
• Revisa el informe JSON para ver si hay resultados parciales y cuál fue el alcance real del escaneo. Un documento SARIF válido puede seguir representando un análisis incompleto.

GitHub admite code scanning en repositorios públicos y en repositorios de organizaciones que cumplan los requisitos y tengan GitHub Code Security activado. Comprueba si tu repositorio cumple los requisitos y si tienes acceso de escritura en la documentación de GitHub sobre la subida de SARIF.

2. Exporta la auditoría

Define las variables siguientes en tu shell local o en el entorno de CI. VETKIT_API_URL es el origen de tu API de vetkit sin /v1. Guarda la clave en un gestor de secretos o en un secreto de CI, no en el archivo del workflow, en el repositorio ni en un script de shell. Este comando requiere curl y jq:

$ set -euo pipefail$ : "${VETKIT_API_URL:?Set the API origin}"$ : "${VETKIT_ORG_ID:?Set the organization ID}"$ : "${VETKIT_AUDIT_ID:?Set the completed audit ID}"$ : "${VETKIT_API_KEY:?Set a reports:read key}" $ curl --fail-with-body --silent --show-error --max-time 30 \  "$VETKIT_API_URL/v1/orgs/$VETKIT_ORG_ID/audits/$VETKIT_AUDIT_ID/report?format=sarif" \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -o vetkit.sarif$ jq -e '.version == "2.1.0" and (.runs | type == "array")' vetkit.sarif >/dev/null

El endpoint devuelve application/sarif+json y un nombre de archivo adjunto basado en el commit auditado. El comando lo guarda a propósito como vetkit.sarif para el paso de subida. La comprobación con jq es una verificación básica del formato, no una validación completa del esquema ni una confirmación de que el escaneo esté completo. Trata el informe descargado como información del repositorio y controla quién tiene acceso a él.

3. Súbelo desde tu workflow

En un workflow del repositorio escaneado, haz checkout del código correspondiente, obtén la auditoría completada y ejecuta el comando de descarga anterior. Guarda VETKIT_API_KEY en un secreto de Actions. El siguiente fragmento muestra los permisos y el paso final de subida; no es un workflow de escaneo independiente. Añade la descarga entre el checkout y la subida:

permissions:  contents: read  actions: read  security-events: write # Inside the job's steps, after choosing the matching audit:steps:  - uses: actions/checkout@v6    with:      persist-credentials: false  # Insert the authenticated download step here.  - name: Upload vetkit results    uses: github/codeql-action/upload-sarif@v4    with:      sarif_file: vetkit.sarif      category: vetkit

La action de subida de GitHub usa sarif_file para la ruta del informe y category para distinguir análisis. Reutilizar una herramienta/categoría para el mismo commit puede sustituir resultados anteriores; usa categorías distintas para análisis independientes. Los permisos y las versiones de las actions de arriba siguen el ejemplo de GitHub.

El ejemplo de integración con repositorios de vetkit deja la subida de SARIF como opcional tras VETKIT_UPLOAD_SARIF=true. Su workflow de escaneo completo solicita una auditoría del commit exacto y rechaza los resultados fallidos, parciales o sin puntuación antes de la subida opcional. Esa comprobación de que la auditoría ha terminado no impone ningún umbral de severidad de hallazgos ni de puntuación: define tu política de lanzamiento por separado. Los checks de la GitHub App y la subida de SARIF son vías de integración distintas.

4. Interpreta los resultados importados

vetkit exporta un único run SARIF con vetkit como driver. Los resultados incluyen los IDs de las reglas, las ubicaciones en los archivos cuando están disponibles, el texto de remediación y las fingerprints de vetkit. Las versiones de los analizadores se registran como extensiones, y se incluye la procedencia del repositorio y del commit. La correspondencia de severidades usa los niveles de SARIF junto con las propiedades de severidad de vetkit; esas correspondencias numéricas no son puntuaciones CVSS calculadas de forma independiente.

Los hallazgos a nivel de repositorio usan una ubicación sintética (repository), así que puede que no apunten a una línea real del código fuente. Los hallazgos suprimidos siguen en la exportación con metadatos de supresión de SARIF. No des por hecho que el número de resultados exportados es igual al número de alertas activas que muestra GitHub. Conserva el informe original de vetkit para la cobertura, el contexto de la puntuación y los detalles de la revisión.

Solución de problemas

• Falla la descarga: comprueba el origen de la API, los IDs de la organización y de la auditoría, la validez de la clave y el scope reports:read. No imprimas la clave al depurar.
• Ubicaciones incorrectas en el código fuente: compara el commit de la auditoría con el commit y el checkout del workflow. No subas un informe antiguo como evidencia de una revisión más reciente.
• Se rechaza la subida: comprueba si cumples los requisitos de GitHub, los permisos del workflow y la salida de errores de la action de subida. GitHub aplica sus propias propiedades SARIF admitidas y sus propios límites de tamaño.
• No aparece ninguna alerta: revisa los resultados del archivo, los metadatos de supresión, el análisis seleccionado y la cobertura de la auditoría original. Que la transferencia funcione no demuestra que el escaneo esté limpio.

Fuentes y límites

Revisado el 1 de noviembre de 2026 con el controlador y el servicio de informes de vetkit, el serializador SARIF y el ejemplo de integración con GitHub Actions del repositorio. Consulta la referencia de la API y los requisitos de subida de GitHub para los dos lados de la integración. Los requisitos de GitHub y el comportamiento de la action pueden cambiar. La exportación a SARIF transfiere hallazgos existentes; no ejecuta CodeQL, no añade checks a la auditoría original ni garantiza que todos los detalles del informe de vetkit aparezcan en la interfaz de GitHub.