Ejecutar el ejecutor de CodeQL en tu sistema de IC

Nota: CodeQL runner está en desuso. En GitHub Enterprise Server� 3.0 y posterior, puede instalar la versión� 2.6.3 de CodeQL CLI para reemplazar CodeQL runner.

Para más información, vea Ejecutor de CodeQL en desuso. Para obtener información sobre la migración a CodeQL CLI, vea "Migración del ejecutor de CodeQL a la CLI de CodeQL".

Note: Your site administrator must enable code scanning for your GitHub Enterprise Server instance before you can use this feature. For more information, see "Configuring code scanning for your appliance."

Acerca de CodeQL runner

El CodeQL runner es una herramienta que puedes utilizar para ejecutar el code scanning en el código que estás procesando en un sistema de integración contínua (IC) de terceros. Code scanning es una característica que utilizas para analizar el código en un repositorio de GitHub para encontrar vulnerabilidades de seguridad y errores de código. Cualquier problema que se identifique con el análisis se muestra en GitHub Enterprise Server. Para obtener información, consulta "Acerca de code scanning con CodeQL".

En muchos casos es más fácil configurar el code scanning de CodeQL utilizando el CodeQL CLI directamente en tu sistema de IC.

Como alternativa, puedes utilizar las GitHub Actions en tu sistema de IC, o al code scanning dentro de GitHub Enterprise Server. Para obtener información, consulta "Configuración de code scanning para un repositorio".

El CodeQL runner es una herramienta de línea de comandos que ejecuta un análisis de CodeQL en un control de un repositorio de GitHub. Puedes agregar el ejecutor a tu sistema de terceros y, luego, llamarlo para que analice el código y cargue los resultados en GitHub Enterprise Server. Estos resultados se muestran como alertas del code scanning en el repositorio.

Nota:

El CodeQL runner se encuentra disponible para los clientes con una licencia de Advanced Security.

Descargar el CodeQL runner

Puedes descargar CodeQL runner desde https://HOSTNAME/github/codeql-action/releases. En algunos sistemas operativos, puede que necesites cambiar permisos para el archivo de descarga antes de que lo puedas ejecutar.

En Linux:

chmod +x codeql-runner-linux

En macOS:

chmod +x codeql-runner-macos
sudo xattr -d com.apple.quarantine codeql-runner-macos

En Windows, el archivo codeql-runner-win.exe normalmente no requiere ningún cambio en los permisos.

Agregar el CodeQL runner a tu sistema de IC

Una vez que descargas el CodeQL runner y verificas que puede ejecutarse, debes poner el ejecutor disponible para cada servidor de IC que pretendas utilizar para el code scanning. Por ejemplo, podrías configurar cada servidor para que copie el ejecutor desde una ubicación interna y central. Como alternativa, puedes utilizar la API de REST para obtener el ejecutor directamente de GitHub, por ejemplo:

wget https://HOSTNAME/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux

Además, cada servidor de IC necesitará también:

Un token de GitHub App o de acceso personal para que lo use el CodeQL runner. Debes usar un token de acceso con el ámbito repo o una GitHub App con el permiso de escritura security_events y los permisos de lectura metadata y contents. Para obtener información, consulta "Compilación de GitHub Apps" y "Creación de un token de acceso personal".
Acceso al paquete de CodeQL asociado con este lanzamiento del CodeQL runner. Este paquete contiene consultas y bibliotecas necesarias para el análisis de CodeQL, adicionado con el CLI de CodeQL, el cual utiliza internamente el ejecutor. Para obtener información, consulta "CLI de CodeQL".

Las opciones para proporcionar acceso al paquete de CodeQL son:

Permitir que los servidores de CI accedan a https://HOSTNAME/github/codeql-action para que el CodeQL runner pueda descargar el paquete automáticamente.
Descargar o extraer el paquete manualmente, almacenarlo con otros recursos centrales y usar la marca --codeql-path para especificar la ubicación del paquete en las llamadas para inicializar el CodeQL runner.

Llamar al CodeQL runner

Debes llamar al CodeQL runner desde la ubicación de verificación del repositorio que quieres analizar. Los dos comandos principales son:

init que se requiere para inicializar el ejecutor y para crear una base de datos de CodeQL para que se analice cada lenguaje. Estas bases de datos se llenan y analizan mediante comandos subsecuentes.
analyze que se requiere para rellenar las bases de datos de CodeQL, analizarlas y cargar los resultados en GitHub Enterprise Server.

Para ambos comandos, debes especificar la URL de GitHub Enterprise Server, el PROPIETARIO/NOMBRE del repositorio y el token de GitHub Apps o de acceso personal que se usará para la autenticación. También necesitas especificar la ubicación del paquete de CodeQL, a menos de que el servidor de CI tenga acceso para descargarlo directamente del repositorio de github/codeql-action.

Puedes configurar en qué lugar el CodeQL runner almacena la agrupación de CodeQL para el análisis futuro en un servidor mediante la marca --tools-dir y dónde almacena los archivos temporales durante el análisis mediante --temp-dir.

Para ver la referencia de línea de comandos para el ejecutor, usa la marca -h. Por ejemplo, para enumerar todos los comandos ejecuta codeql-runner-OS -h, o bien para enumerar todas las marcas disponibles para el comando init ejecuta codeql-runner-OS init -h (donde OS varía según el ejecutable que se use). Para obtener más información, consulta "Configuración de code scanning en el sistema de CI".

Notas:

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.

Ejemplo básico

En este ejemplo se ejecuta el análisis de CodeQL en un servidor de CI de Linux para el repositorio octo-org/example-repo hospedado en https://github.example.com. El proceso es muy simple, ya que el repositorio contiene únicamente los lenguajes que puede analizar CodeQL directamente, sin que se tenga que compilar (es decir, Go, JavaScript, Python, y TypeScript).

En este ejemplo, el servidor tiene acceso para descargar la agrupación CodeQL directamente desde el repositorio github/codeql-action, así que no hay necesidad de usar la marca --codeql-path.

Verifica el repositorio a analizar.
Posiciónate en el directorio donde se seleccionó el repositorio.

Inicializa el CodeQL runner y crea bases de datos de CodeQL para los lenguajes detectados.

$ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
    --github-url https://github.example.com --github-auth-stdin
> Cleaning temp directory /srv/checkout/example-repo/codeql-runner
> ...
> Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.

Rellene las bases de datos de CodeQL, analícelas y cargue los resultados a GitHub Enterprise Server. Los resultados aparecerán en la pestaña Security del repositorio.

$ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
    --github-url https://github.example.com --github-auth-stdin
    --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
> Finalizing database creation
> ...
> POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
> Successfully uploaded results

Para cargar los resultados de code scanning como comprobaciones de solicitudes de incorporación de cambios, especifique la solicitud de incorporación de cambios mediante la marca --ref. Se recomienda configurar CodeQL runner para que se ejecute en el evento de webhook pull_request.

$ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
    --github-url https://github.example.com --github-auth-stdin
    --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
> Finalizing database creation
> ...
> POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
> Successfully uploaded results

Para más información sobre cómo ver las alertas de code scanning, vea "Evaluación de prioridades de alertas de examen de código en solicitudes de incorporación de cambios" y "Administración de alertas de análisis de código para el repositorio".

Ejemplo de lenguaje compilado

Este ejemplo es similar al anterior, sin embargo, esta vez el repositorio tiene código en C/C++, C#, o Java. Para crear una base de datos de CodeQL para estos lenguajes, el CLI necesita monitorear la compilación. Al final del proceso de inicialización, el ejecutor reportará el comando que necesitas configurar en el ambiente antes de compilar el código. Necesitas ejecutar este comando antes de llamar al proceso normal de compilación de CI y ejecutar el comando analyze.

Verifica el repositorio a analizar.
Posiciónate en el directorio donde se seleccionó el repositorio.