Subir un archivo SARIF a GitHub

Si usa una herramienta de análisis de terceros o un sistema ci/CD para examinar el código de vulnerabilidades, puede generar el archivo SARIF y cargarlo en GitHub. El mejor método de carga depende de cómo genere el archivo SARIF.

Por ejemplo, si usa:

        GitHub Actions para ejecutar la CodeQL acción, no se requiere ninguna otra acción. La CodeQL acción carga automáticamente el archivo SARIF cuando completa el análisis.

        GitHub Actions para ejecutar una herramienta de análisis compatible con SARIF, puede actualizar el flujo de trabajo para incluir un paso final que cargue los resultados. Consulte [Carga de un análisis de code scanning con GitHub Actions](#uploading-a-code-scanning-analysis-with-github-actions).

El CodeQL CLI para ejecutar code scanning en su sistema de CI, puede usar la CLI para cargar los resultados en GitHub. Consulte Utilizar el análisis de código de CodeQL con tu sistema de IC existente.
Una herramienta que genera resultados como un artefacto fuera de su repositorio, puede usar la API de code scanning para cargar el archivo. Consulte Puntos de conexión de la API de REST para el análisis de código.

De forma predeterminada, code scanning espera un archivo de resultados SARIF por análisis para un repositorio. Si quieres cargar más de un conjunto de resultados para una confirmación en un repositorio, debes identificar cada conjunto de resultados como un conjunto único.

Nota:

En el caso de los repositorios privados e internos, code scanning está disponible cuando GitHub Code Security las características están habilitadas para el repositorio. Si ve el error GitHub Code Security or GitHub Advanced Security must be enabled for this repository to use code scanning, compruebe que GitHub Code Security está habilitado. Para obtener más información, vea Administración de la configuración de seguridad y análisis para el repositorio.

Carga de un análisis de code scanning con GitHub Actions

Para usar GitHub Actions para cargar un archivo SARIF de terceros en un repositorio, necesitará un flujo de trabajo. Para obtener más información, vea Escritura de flujos de trabajo.

El flujo de trabajo tendrá que usar la acción upload-sarif, que forma parte del repositorio github/codeql-action. Tiene parámetros de entrada que puedes utilizar para configurar la carga. Los parámetros de entrada principales que utilizarás serán:

        `sarif_file`, que configura el archivo o directorio de los archivos SARIF que se van a cargar. La ruta de acceso del directorio o archivo es relativa a la raíz del repositorio.

        `category` (opcional), que asigna una categoría para los resultados en el archivo SARIF. Esto le permite analizar la misma confirmación de varias maneras y revisar los resultados mediante las vistas de code scanning en GitHub. Por ejemplo, puedes analizar herramientas múltiples y, en los mono-repositorios, puedes analizar pedazos diferentes del repositorio con base en el subconjunto de archivos que cambiaron.

Para más información, vea la acción upload-sarif.

La acción upload-sarif se puede configurar para ejecutarse cuando se producen los eventos push y scheduled. Para más información sobre los eventos GitHub Actions, consulta Eventos que desencadenan flujos de trabajo.

Si el archivo SARIF no incluye partialFingerprints, la acción upload-sarif calculará el campo partialFingerprints automáticamente e intentará evitar alertas duplicadas. GitHub solo se puede crear partialFingerprints cuando el repositorio contiene el archivo SARIF y el código fuente usado en el análisis estático. Para obtener más información sobre cómo evitar alertas duplicadas, consulte Soporte de SARIF para escaneo de código.

Compruebe que las propiedades SARIF tienen el tamaño admitido para la carga y que el archivo es compatible con el examen de código. Para más información, consulta Soporte de SARIF para escaneo de código.

Ejemplo de flujo de trabajo para los archivos SARIF generados fuera de un repositorio

Puedes crear un nuevo flujo de trabajo que cargue archivos SARIF después de que los confirmes en tu repositorio. Esto resulta útil cuando el archivo SARIF se genera como un artefacto fuera del repositorio.

Este ejemplo de flujo de trabajo se ejecuta cada que las confirmaciones se cargan al repositorio. La acción usa la propiedad partialFingerprints para determinar si se han producido cambios. Además de ejecutarse cuando se insertan confirmaciones, el flujo de trabajo está programado para ejecutarse una vez a la semana. Para obtener más información, vea Eventos que desencadenan flujos de trabajo.

Este flujo de trabajo carga el archivo results.sarif ubicado en la raíz del repositorio. Para obtener más información sobre cómo crear un archivo de flujo de trabajo, consulte Escritura de flujos de trabajo.

Como alternativa, puedes modificar este flujo de trabajo para cargar un directorio de archivos SARIF. Por ejemplo, podría colocar todos los archivos SARIF en un directorio en la raíz del repositorio denominado sarif-output y establecer el parámetro de entrada de la acción sarif_file en sarif-output. Tenga en cuenta que si carga un directorio, cada archivo SARIF debe incluir un valor runAutomationDetails.id único para definir la categoría de los resultados. Para obtener más información, vea Soporte de SARIF para escaneo de código.

name: "Upload SARIF"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Thursday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 4'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      # This step checks out a copy of your repository.
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif
          # Optional category for the results
          # Used to differentiate multiple results for one commit
          category: my-analysis-tool

Ejemplo de flujo de trabajo que ejecuta la herramienta de análisis ESLint

Si genera el archivo SARIF de terceros como parte de un flujo de trabajo de integración continua (CI), puede agregar la acción upload-sarif como un paso después de ejecutar las pruebas de CI. Si aún no tiene un flujo de trabajo de CI, puede crear uno mediante una GitHub Actions plantilla. Para obtener más información, consulta el Inicio rápido para GitHub Actions.

El flujo de trabajo muestra un ejemplo de ejecución de la herramienta de análisis estático ESLint como un paso en un flujo de trabajo. El paso Run ESLint ejecuta la herramienta ESLint y genera el archivo results.sarif. A continuación, el flujo de trabajo carga el results.sarif archivo en GitHub mediante la upload-sarif acción . Para obtener más información sobre cómo crear un archivo de flujo de trabajo, consulte Descripción de GitHub Actions.

name: "ESLint analysis"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Wednesday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 3'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      - uses: actions/checkout@v5
      - name: Run npm install
        run: npm install
      # Runs the ESlint code analysis
      - name: Run ESLint
        # eslint exits 1 if it finds anything to report
        run: node_modules/.bin/eslint build docs lib script spec-main -f node_modules/@microsoft/eslint-formatter-sarif/sarif.js -o results.sarif || true
      # Uploads results.sarif to GitHub repository using the upload-sarif action
      - uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

Carga de más de un archivo SARIF para una confirmación

De forma predeterminada, code scanning espera un archivo de resultados SARIF por análisis para un repositorio. Como consecuencia, cuando cargues un segundo archivo de resultados SARIF para una confirmación, este se tratará como un reemplazo para el conjunto de datos original. Puede que desees cargar dos archivos SARIF diferentes para un análisis si, por ejemplo, la herramienta de análisis genera un archivo SARIF diferente para cada idioma que analizas o cada conjunto de reglas que usas. Si quieres cargar más de un conjunto de resultados para una confirmación en un repositorio, debes identificar cada conjunto de resultados como un conjunto único.

Cuando cargas varios archivos de SARIF en una confirmación, debes indicar una "Categoría" para cada análisis. La forma de especificar una categoría varía de acuerdo con el método de análisis:

Utilizando directamente CodeQL CLI, pase el argumento --sarif-category al comando codeql database analyze al generar archivos SARIF. Para obtener más información, vea Acerca de la CLI de CodeQL.
Con GitHub Actions , codeql-action/analyzela categoría se establece automáticamente desde el nombre del flujo de trabajo y cualquier variable de matriz (normalmente, language). Para ignorarlo, especifica una entrada category para la acción, lo que resulta útil cuando analiza diferentes secciones de un repositorio único en un flujo de trabajo individual.
Usando GitHub Actions para cargar los resultados de otras herramientas de análisis estático, debe especificar una entrada category si carga más de un archivo de resultados para la misma herramienta en un flujo de trabajo. Para obtener más información, vea Subir un archivo SARIF a GitHub.
Si no usa ninguno de estos enfoques, debe especificar un runAutomationDetails.id único en cada archivo SARIF que se va a cargar. Para obtener más información sobre esta propiedad, consulte el objeto runAutomationDetails.

Si cargas un archivo de SARIF para una confirmación con la misma categoría y desde la misma herramienta, los resultados anteriores se sobreescribirán. Sin embargo, si intenta cargar varios archivos SARIF para la misma herramienta y categoría en una sola GitHub Actions ejecución de flujo de trabajo, se detecta la configuración incorrecta y se producirá un error en la ejecución.

Lectura adicional

        [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-sarif-uploads)

        [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)

        [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history)

        [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)

        [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data)