Carga de resultados de análisis de CodeQL en GitHub

Después de analizar una CodeQL base de datos mediante CodeQL CLI, tendrá un archivo SARIF que contenga los resultados. A continuación, puede usar CodeQL CLI para cargar los resultados en GitHub.

Si usó un método distinto del CodeQL CLI para generar resultados, puede usar otros métodos de carga. Para más información, consulta Subir un archivo SARIF a GitHub.

Generación de un token para la autenticación con GitHub

Para poder cargar los resultados en GitHub, primero deberá generar un personal access token. Consulta Administración de tokens de acceso personal.

        **
        Personal access token (classic)
        ** requiere "Code scanning alertas" **Acceso de lectura y escritura** para los repositorios necesarios.

        **
        Fine-grained personal access token
        ** requiere acceso al repositorio "security_events".

Si ha instalado el CodeQL CLI en un sistema CI de terceros, también puede usar un GitHub App para cargar los resultados en GitHub. Consulta Utilizar el análisis de código de CodeQL con tu sistema de IC existente.

Carga de resultados en GitHub

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.
Determine la mejor manera de pasar el GitHub App o el personal access token que creó en la sección anterior al CodeQL CLI. Se recomienda revisar las instrucciones del sistema de CI sobre el uso seguro de un almacén de secretos. El CodeQL CLI admite:
- Interfaz con un almacén secreto 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ón	Obligatorio	Usage
`--repository`		Especifique el PROPIETARIO/NOMBRE del repositorio en el que se cargarán los datos. El propietario debe ser una organización dentro de una empresa, o tener un GitHub Team plan habilitado para el repositorioGitHub Code Security, a menos que el repositorio sea público. Para más información, consulta Administración de la configuración de seguridad y análisis para el repositorio.
`--ref`		Especifique 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 un uso de rama: `refs/heads/BRANCH-NAME`, para la confirmación principal de una solicitud de incorporación de cambios, use `refs/pull/NUMBER/head`, o para la GitHub confirmación de combinación generada por una solicitud de incorporación de cambios, use `refs/pull/NUMBER/merge`.
`--commit`		Especifique el SHA completo de la confirmación que ha analizado.
`--sarif`		Especifique el archivo SARIF que se cargará.
`--github-auth-stdin`		Pase al CLI el GitHub App o personal access token creados para la autenticación con la API REST de GitHub desde su almacén de secretos a través de la entrada estándar. Esto no es necesario si el comando tiene acceso a una variable de entorno `GITHUB_TOKEN` establecida con este token.

Para más información, consulta github upload-results.

Nota:

Si ha analizado más de una CodeQL base de datos para una sola confirmación, debe haber especificado una categoría SARIF para cada conjunto de resultados generados por este comando. Al cargar los resultados en GitHub, code scanning usa esta categoría para almacenar los resultados de cada idioma por separado. Si olvida hacerlo, cada carga sobrescribe los resultados anteriores. Para más información, consulta 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. Indica a la code scanning API que los resultados son para el commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 en la rama main. En el ejemplo se supone que el GitHub App o 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. La línea de comandos regresa cuando la carga se completa y el procesamiento de datos ha comenzado. En bases de código más pequeñas, debería poder explorar las alertas en code scanning poco después en GitHub. Puede ver las alertas directamente en el pull request o en la pestaña Security and quality para ramas, dependiendo del código que clonó.

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

Cuando CodeQL CLI termine de analizar correctamente una base de datos, recopila información de diagnóstico como la cobertura de archivos, las advertencias y los errores, e incluyela en el archivo SARIF con los resultados. Al cargar el archivo SARIF en GitHub, la información de diagnóstico se muestra en code scanningpágina de estado de la herramienta del repositorio para que sea fácil ver cómo CodeQL está funcionando y depurar cualquier problema. Para más información, consulta Usar la página de estado de la herramienta para el examen de código.

Sin embargo, si codeql database analyze falla por cualquier motivo, no hay ningún archivo SARIF para cargar en GitHub y no hay información de diagnóstico para mostrar en code scanningpá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 a GitHub cuando se produce un error en un análisis. Puede hacerlo mediante 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 fallido 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

Puede hacer que esta información de diagnóstico esté disponible en página de estado de la herramienta si carga el archivo SARIF en GitHub mediante 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 lo mismo que el proceso para cargar archivos SARIF de análisis exitosos.