Carga de los resultados del análisis de CodeQL en GitHub

Puedes usar la CodeQL CLI para cargar los resultados del análisis de CodeQL en GitHub.

¿Quién puede utilizar esta característica?

Las licencias de GitHub CodeQL se otorgan por usuario tras la instalación. Puedes usar CodeQL solo para determinadas tareas según las restricciones de las licencias. Para obtener más información, vea «Acerca de la CLI de CodeQL».

Si tienes una licencia de GitHub Advanced Security, puedes usar CodeQL para el análisis automatizado, la integración continua y la entrega continua. Para obtener más información, vea «Acerca de GitHub Advanced Security».

En este artículo

Acerca de la salida SARIF

GitHub crea alertas de code scanning en un repositorio utilizando información de los archivos de Formato de Intercambio para Resultados de Análisis Estático (SARIF). SARIF es un formato diseñado para representar la salida de una amplia variedad de herramientas de análisis estático, y hay muchas características en la especificación SARIF que se consideran "opcionales". Los resultados deben usar la versión 2.1.0 de SARIF. Para obtener más información, vea «Soporte de SARIF para escaneo de código».

Después de analizar una base de datos de CodeQL mediante la CodeQL CLI, tendrá un archivo SARIF que contiene los resultados. Para obtener más información, vea «Análisis del código con consultas de CodeQL». A continuación, puedes usar la CodeQL CLI para cargar los resultados en GitHub.

Si has usado un método distinto de la CodeQL CLI para generar los resultados, puedes utilizar otros métodos de carga. Para obtener más información, vea «Subir un archivo SARIF a GitHub».

Nota: Cargar datos de SARIF para mostrarlos como resultados de code scanning en GitHub es compatible para los repositorios que pertenezcan a organizaciones con la GitHub Advanced Security habilitada y para los repositorios públicos en GitHub.com. Para obtener más información, vea «Administración de la configuración de seguridad y análisis para el repositorio».

Generar un token para autenticarse con GitHub

Antes de que puedas cargar los resultados en GitHub primero deberás generar un personal access token con el permiso de escritura security_events. Para obtener más información, vea «Administración de tokens de acceso personal».

Si has instalado la CodeQL CLI en un sistema de CI de terceros a fin de crear resultados que se muestren en GitHub como alertas de examen de código, puedes usar una GitHub App o un personal access token para cargar los resultados en GitHub. Para obtener más información, vea «Utilizar el análisis de código de CodeQL con tu sistema de IC existente».

Cargar resultados en GitHub

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".

Para poder cargar resultados en GitHub, debes determinar la mejor forma de pasar la GitHub App o el personal access token que creaste en la sección previa para la CodeQL CLI (consulta «AUTOTITLE»). Se recomienda revisar las instrucciones del sistema de CI sobre el uso seguro de un almacén de secretos. El CodeQL CLI es compatible con:

  • Interacción con un almacén de secretos mediante la opción --github-auth-stdin (recomendado).
  • Guardar el secreto en la variable de entorno GITHUB_TOKEN y ejecutar la CLI sin incluir la opción --github-auth-stdin.
  • Con fines de prueba, puedes pasar la opción de línea de comandos --github-auth-stdin y proporcionar un token temporal a través de la entrada estándar.

Cuando hayas decidido el método más seguro y confiable para la configuración, ejecuta codeql github upload-results en cada archivo de resultados SARIF e incluye --github-auth-stdin a menos que el token esté disponible en la variable de entorno GITHUB_TOKEN.

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file>
OpciónObligatorioUso
--repositoryEspecifique el PROPIETARIO/NOMBRE del repositorio en el que se cargarán los datos. El propietario debe ser una organización dentro de una empresa que tenga una licencia de GitHub Advanced Security, y la GitHub Advanced Security debe estar habilitada para el repositorio, a menos que sea público. Para obtener más información, vea «Administración de la configuración de seguridad y análisis para el repositorio».
--refEspecifique el nombre de la ref que ha extraído del repositorio y ha analizado para que los resultados puedan coincidir con el código correcto. Para usarla en una rama: refs/heads/BRANCH-NAME, para la confirmación del encabezado de una solicitud de incorporación de cambios use refs/pull/NUMBER/head, y para la confirmación de la combinación generada por GitHub de una solicitud de incorporación de cambios use refs/pull/NUMBER/merge.
--commitEspecifique el SHA completo de la confirmación que ha analizado.
--sarifEspecifique el archivo SARIF que se va a cargar.
--github-auth-stdinPasa a la CLI la instancia de GitHub App o el personal access token que creaste para autenticarte con la API REST de GitHub desde el almacén de secretos a través de una entrada estándar. Esto no es necesario si el comando tiene acceso a una variable de entorno GITHUB_TOKEN establecida con este token.

Para obtener más información, vea «github upload-results».

Nota: Si has analizado más de una base de datos de CodeQL para una sola confirmación, debes haber especificado una categoría SARIF para cada conjunto de resultados generados por este comando. Cuando cargas los resultados en GitHub, el code scanning utiliza esta categoría para almacenar los resultados para cada lenguaje por separado. Si olvida hacerlo, cada carga sobrescribe los resultados anteriores. Para obtener más información, vea «Análisis del código con consultas de CodeQL».

Ejemplo básico de carga de resultados en GitHub

En este ejemplo se cargan los resultados del archivo SARIF temp/example-repo-js.sarif en el repositorio my-org/example-repo. Se indica a la API de code scanning que los resultados son para la confirmación de deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 en la rama de main. En el ejemplo se da por hecho que la instancia de GitHub App o el personal access token creado para la autenticación con la API REST de GitHub usa la variable de entorno GITHUB_TOKEN.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif

No hay salida para este comando a menos de que la carga no sea exitosa. El símbolo de sistema regresa cuando la carga se completa e inicia el procesamiento de datos. En bases de código más pequeñas, debes poder explorar las alertas del code scanning en GitHub poco tiempo después. Puedes ver alertas directamente en la solicitud de incorporación de cambios o en la pestaña Seguridad de las ramas, según el código extraído del repositorio. Para más información, consulta "Clasificar las alertas del escaneo de código en las solicitudes de cambios" y "Administración de alertas de examen de código para el repositorio".

Carga de información de diagnóstico en GitHub si se produce un error en el análisis

Cuando CodeQL CLI termina de analizar correctamente una base de datos, recopila información de diagnóstico, como la cobertura de archivos, las advertencias y los errores, y lo incluye en el archivo SARIF con los resultados. Al cargar el archivo SARIF en GitHub, la información de diagnóstico se muestra en la code scanning página de estado de la herramienta del repositorio para facilitar la visualización del rendimiento de CodeQL y depurar los problemas. Para obtener más información, vea «Acerca de la página de estado de la herramienta para el examen de código».

Sin embargo, si codeql database analyze produce un error por cualquier motivo, no hay ningún archivo SARIF que se cargue en GitHub y no se muestra ninguna información de diagnóstico en la code scanning página de estado de la herramienta del repositorio. Esto dificulta a los usuarios solucionar problemas de análisis a menos que tengan acceso a los archivos de registro en el sistema de CI.

Se recomienda configurar el flujo de trabajo de CI para exportar y cargar información de diagnóstico en GitHub cuando se produce un error en un análisis. Puedes hacerlo con los siguientes comandos sencillos para exportar la información de diagnóstico y cargarla en GitHub.

Exportación de información de diagnóstico si se produce un error en el análisis

Puedes crear un archivo SARIF para el análisis con errores mediante "exportación de diagnóstico de base de datos", por ejemplo:

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript-typescript --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

Este archivo SARIF contendrá información de diagnóstico para el análisis con errores, incluida cualquier información de cobertura de archivos, advertencias y errores generados durante el análisis.

Carga de información de diagnóstico si se produce un error en el análisis

Para que esta información de diagnóstico esté disponible en la página de estado de la herramienta, carga el archivo SARIF en GitHub con "github upload-results", por ejemplo:

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif

Esto es el mismo que el proceso para cargar archivos SARIF a partir de análisis correctos.