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 acción de CodeQL, no hay que hacer nada más. La acción de CodeQL carga el archivo de SARIF automáticamente cuando completa el análisis.
• GitHub Actions para ejecutar una herramienta de análisis compatible con SARIF, podría actualizar el flujo de trabajo para incluir un último paso que cargue los resultados. Consulte Carga de un análisis de code scanning con GitHub Actions.
• CodeQL CLI para ejecutar code scanning en el sistema de CI, puede usar la CLI para cargar los resultados en GitHub. Consulta Utilizar el análisis de código de CodeQL con tu sistema de IC existente.
• Una herramienta que genera resultados como un artefacto fuera del repositorio, puede usar la API de code scanning para cargar el archivo. Consulta Puntos de conexión de la API de REST para el análisis de código.

Predeterminadamente, el code scanning espera un archivo de resultado SARIF por cada análisis de 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.

Cargar un análisis de code scanning con GitHub Actions

Para utilizar las GitHub Actions para cargar un archivo SARIF de terceros en un repositorio, necesita un flujo de trabajo. Para más información, consulta 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 te permite analizar la misma confirmación de varias formas y revisar los resultados utilizando la vista del 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 obtener más información, consulte la acción upload-sarif.

La acción upload-sarif se puede configurar para ejecutarse cuando se producen los eventos push y scheduled. Para obtener más información sobre eventos de GitHub Actions, consulte 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 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.

Puedes comprobar que las propiedades SARIF tienen el tamaño compatible 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 más información, consulta 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 más información, consulta 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 tienes un flujo de trabajo de IC, puedes crearlo utilizando una plantilla de GitHub Actions. Para obtener más información, consulte Guía de inicio rápido para GitHub Actions.

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 más información, consulta Eventos que desencadenan flujos de trabajo.

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. Después, el flujo de trabajo carga el archivo results.sarif en GitHub mediante la acción upload-sarif. Para obtener más información sobre cómo crear un archivo de flujo de trabajo, consulte Entender las 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

Predeterminadamente, el code scanning espera un archivo de resultado SARIF por cada análisis de 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:

• Si usa directamente CodeQL CLI, puede enviar el argumento --sarif-category al comando codeql database analyze cuando genere los archivos SARIF. Para más información, consulta Acerca de la CLI de CodeQL.
• Utilice GitHub Actions con codeql-action/analyze para que la categoría se establezca automáticamente a partir del nombre del flujo de trabajo y las variables de matriz (normalmente, es 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.
• Si GitHub Actions para cargar los resultados de otras herramientas de análisis estático, debe especificar una entrada en category si carga más de un archivo de resultados para la misma herramienta en un flujo de trabajo. Para más información, consulta 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 intentas cargar varios archivos SARIF para la misma herramienta y categoría en una ejecución de flujo de trabajo de GitHub Actions sencilla, esta configuración errónea se detectará y la ejecución fallará.

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)