Habilitación del examen de código con herramientas de terceros
En lugar de ejecutar el examen de código en GitHub, puede realizar análisis en otro lugar y, después, cargar los resultados. Las alertas de examen de código que se ejecutan externamente se muestran de la misma manera que las que se ejecutan en GitHub. Puede cargar archivos de formato de intercambio de resultados de análisis estáticos (SARIF) generados fuera de GitHub o con Acciones de GitHub para ver alertas de examen de código de herramientas de terceros en el repositorio.
En esta unidad, aprenderá a habilitar el examen de código con herramientas de terceros y a usar y cargar archivos SARIF.
Acerca de las cargas de archivos SARIF para el examen de código
GitHub crea alertas de examen de código en un repositorio mediante información de archivos SARIF. Puede generar archivos SARIF con muchas herramientas de prueba de seguridad de análisis estáticos, incluido CodeQL. Los resultados deben usar la versión 2.1.0 de SARIF.
Puede cargar los resultados mediante la API de examen de código, la CLI de CodeQL o Acciones de GitHub. El mejor método de carga dependerá de cómo haya generado el archivo SARIF.
Code Scanning API
La API de análisis del código le permite recuperar información sobre las alertas del análisis del código, los análisis, las bases de datos y la configuración de configuración predeterminada de un repositorio. Además, puede actualizar las alertas de análisis del código y la configuración predeterminada. Puede usar los puntos de conexión para crear informes automatizados para las alertas de examen código en una organización o cargar los resultados del análisis generados mediante herramientas de examen de código sin conexión.
Puede acceder a la API de GitHub a través de HTTPS desde https://api.github.com. Todos los datos se envían y reciben como JSON. La API usa tipos de medios personalizados para permitir que los consumidores elijan el formato de los datos que desean recibir. Los tipos de medios son específicos de los recursos, lo que les permite cambiar de forma independiente y admitir formatos que otros recursos no admiten.
Hay un tipo de medio personalizado compatible para la API REST de examen de código, application/sarif+json.
Puede usar este tipo de medio con solicitudes GET enviadas al punto de conexión /analyses/{analysis_id}. Cuando se usa este tipo de medio con esta operación, la respuesta incluye un subconjunto de los datos reales que se cargaron para el análisis especificado, en lugar del resumen del análisis que se devuelve cuando se usa el tipo de medio predeterminado. La respuesta también incluye datos adicionales, como las propiedades github/alertNumber y github/alertUrl. El formato de los datos es SARIF, versión 2.1.0.
A continuación se muestra un comando de cURL de ejemplo mediante la API para enumerar las alertas de análisis de código de una organización:
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/code-scanning/alerts
Revise los documentos de la API rest de GitHub para obtener más información sobre el uso de la API de examen de código.
CLI de CodeQL
La CLI de CodeQL es un producto independiente que puede usar para analizar código. Su propósito principal es generar una representación de base de datos de un código base, una base de datos de CodeQL. Una vez lista la base de datos, puede consultarla de forma interactiva o ejecutar un conjunto de consultas para generar un conjunto de resultados en formato SARIF y cargar los resultados en GitHub.com. La CLI de CodeQL es gratuita para su uso en repositorios públicos mantenidos en GitHub.com y está disponible para su uso en repositorios privados propiedad del cliente con una licencia de Advanced Security. Descargue la agrupación de CodeQL de https://github.com/github/codeql-action/releases.
La agrupación contiene lo siguiente:
- Producto de la CLI de CodeQL
- Una versión compatible de las consultas y bibliotecas de https://github.com/github/codeql
- Versiones precompiladas de todas las consultas incluidas en la agrupación
Siempre debe usar la agrupación de CodeQL, porque esto garantiza la compatibilidad y también proporciona un rendimiento mucho mayor que una descarga independiente de la CLI de CodeQL y la restauración de las consultas de CodeQL.
Análisis de examen de código con Acciones de GitHub
Para usar Acciones de GitHub para cargar un archivo SARIF de terceros en un repositorio, necesitará un flujo de trabajo de Acciones de GitHub. Un flujo de trabajo de Acciones de GitHub es un proceso automatizado, integrado por uno o varios trabajos, configurado como un archivo .yml. Los flujos de trabajo se almacenan en el directorio .github/workflows del repositorio.
El flujo de trabajo usa la acción upload-sarif, que forma parte del repositorio github/codeql-action. Este flujo de trabajo incluye parámetros de entrada que puede usar para configurar la carga.
El parámetro de entrada principal es 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.
La acción upload-sarif se puede configurar para ejecutarse cuando se producen los eventos push y scheduled.
En este ejemplo se describen los elementos del archivo yml de la acción upload-sarif:
name: 'Code Scanning : Upload SARIF'
description: 'Upload the analysis results'
author: 'GitHub'
inputs:
sarif_file:
description: |
The SARIF file or directory of SARIF files to be uploaded to GitHub code scanning.
See https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/
uploading-a-sarif-file-to-github#uploading-a-code-scanning-analysis-with-github-actions
for information on the maximum number of results and maximum file size supported by code scanning.
required: false
default: '../results'
checkout_path:
description: "The path at which the analyzed repository was checked out.
Used to relativize any absolute paths in the uploaded SARIF file."
required: false
default: ${{ github.workspace }}
token:
default: ${{ github.token }}
matrix:
default: ${{ toJson(matrix) }}
category:
description: String used by Code Scanning for matching the analyses
required: false
wait-for-processing:
description: If true, the Action will wait for the uploaded SARIF to be processed before completing.
required: true
default: "false"
runs:
using: 'node12'
main: '../lib/upload-sarif-action.js'
Cada vez que se cargan los resultados de un nuevo examen de código, los resultados se procesan y se agregan alertas al repositorio. GitHub usa propiedades del archivo SARIF para mostrar alertas. Por ejemplo, para evitar alertas duplicadas para el mismo problema, el examen de código usa huellas digitales para buscar coincidencias con los resultados de varias ejecuciones, por lo que solo aparecen una vez en la última ejecución de la rama seleccionada. Los archivos SARIF creados por el flujo de trabajo de análisis de CodeQL incluyen estos datos de huella digital en el campo partialFingerprints. Si carga un archivo SARIF con la acción upload-sarif y faltan estos datos, GitHub intenta rellenar el campo partialFingerprints a partir de los archivo de código fuente.
Si el archivo SARIF no incluye partialFingerprints, la acción upload-sarif calculará el campo partialFingerprints automáticamente e intentará evitar alertas duplicadas. GitHub puede crear solo partialFingerprints cuando el repositorio contiene el archivo SARIF y el código fuente usado en el análisis estático.
La carga de SARIF admite un máximo de 5000 resultados por carga. Los resultados que superen este límite se omiten. Si una herramienta genera demasiados resultados, debe actualizar la configuración para centrarse en los resultados de las reglas o consultas más importantes.
Para cada carga, la carga de SARIF admite un tamaño máximo de 10 MB para el archivo SARIF comprimido con gzip. Se rechazarán las cargas que superen este límite. Si el archivo SARIF es demasiado grande porque contiene demasiados resultados, debe actualizar la configuración para centrarse en los resultados de las reglas o consultas más importantes.
Carga de los archivos SARIF generados fuera del repositorio
También puede crear un flujo de trabajo que cargue archivos SARIF después de confirmarlos en el repositorio. Esto resulta útil cuando el archivo SARIF se genera como un artefacto fuera del repositorio.
En el ejemplo siguiente, el flujo de trabajo se ejecuta cada vez que se insertan confirmaciones en el 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. Este flujo de trabajo carga el archivo results.sarif ubicado en la raíz del repositorio. También puede 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.
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:
security-events: write
steps:
# This step checks out a copy of your repository.
- name: Checkout repository
uses: actions/checkout@v2
- name: Upload SARIF file
uses: github/codeql-action/upload-sarif@v1
with:
# Path to SARIF file relative to the root of the repository
sarif_file: results.sarif
Carga de archivos SARIF generados como parte de un flujo de trabajo de CI
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 un flujo de trabajo de inicio en el repositorio https://github.com/actions/starter-workflows.
En este ejemplo, el flujo de trabajo se ejecuta cada vez que se insertan confirmaciones en el 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.
En este ejemplo se muestra la herramienta de análisis estático de ESLint como un paso del 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 archivo results.sarif en GitHub con la acción upload-sarif.
```
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:
security-events: write
steps:
- uses: actions/checkout@v2
- 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@v1
with:
// Path to SARIF file relative to the root of the repository
sarif_file: results.sarif
```