Instalar el CLI de CodeQL en tu sistema de IC

Acerca de utilizar el CodeQL CLI para el code scanning

Puedes usar la CodeQL CLI para ejecutar code scanning en el código que estás procesando en un sistema de integración continua (CI) de terceros. Code scanning es una característica que se usa para analizar el código en un repositorio de GitHub para buscar vulnerabilidades de seguridad y errores de código. Cualquier problema que se identifique con el análisis se muestra en GitHub. Para información, consulta "Acerca del examen de código con CodeQL". Para conocer las especificaciones recomendadas (RAM, núcleos de CPU y disco) para ejecutar análisis de CodeQL, consulta "Recursos de hardware recomendados para ejecutar CodeQL".

El CodeQL CLI es un producto independiente que puedes utilizar para analizar código. Su propósito principal es generar una representación de base de datos de una base de código, una base de datos de CodeQL. Una vez que esté lista la base de datos, puedes consultarla interactivamente o ejecutar un varias consultas para generar un conjunto de resultados en formato SARIF y cargarlos a GitHub.com.

Como alternativa, puedes utilizar las GitHub Actions en tu sistema de IC, o al code scanning dentro de GitHub. Para información sobre code scanning mediante acciones, consulta "Configuración del análisis de código para un repositorio". Para información general sobre las opciones de los sistemas de CI, consulta "Acerca del escaneo de código de CodeQL en tu sistema de IC".

Notas:

La CodeQL CLI puede usarse libremente en repositorios públicos. CodeQL CLI también está disponible en los repositorios privados que pertenecen a las organizaciones que usan GitHub Enterprise Cloud y que tienen una licencia de GitHub Advanced Security. Para obtener información, vea "Términos y condiciones de GitHub CodeQL" y "CLI de CodeQL".
La CodeQL CLI no es compatible actualmente con distribuciones de Linux que no sean glibc, como Alpine Linux (basado en musl).

Descarga de CodeQL CLI

Debes descargar el conjunto de CodeQL desde https://github.com/github/codeql-action/releases. La agrupación contiene lo siguiente:

El producto de CodeQL CLI
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 debes utilizar Siempre debes utilizar el paquete de CodeQL, ya que este garantiza la compatibilidad y también te da un rendimiento mucho mejor que una descarga independiente del CodeQL CLI y una verificación de las consultas de CodeQL. Si solo vas a ejecutar la CLI en una plataforma específica, descarga el archivo codeql-bundle-PLATFORM.tar.gz adecuado. Como alternativa, puedes descargar codeql-bundle.tar.gz, que contiene la CLI para todas las plataformas compatibles.

Nota: La funcionalidad de administración de paquetes de CodeQL, incluidos los de CodeQL, se encuentra actualmente en versión beta y está sujeta a cambios.

Configurar el CodeQL CLI en tu sistema de IC

Necesitas habilitar el contenido integral del paquete de CodeQL CLI para cada servidor de IC en el que quieras ejecutar el análiss del code scanning de CodeQL. Por ejemplo, puedes configurar cada servidor para copiar el paquete desde una ubicación intera y centrar y extraerlo. Como alternativa, puedes utilizar la API de REST para obtener el paquete directamente desde GitHub para garantizar que te beneificarás de las últimas mejoras a las consultas. Las actualizaciones del CodeQL CLI se lanzan cada 2 o 3 semanas. Por ejemplo:

$ wget https://github.com/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
$ tar -xvzf ./codeql-bundle-linux64.tar.gz

Después de extraer el paquete de CodeQL CLI, puedes ejecutar el archivo ejecutable codeql en el servidor:

Ejecutando /<extraction-root>/codeql/codeql, donde <extraction-root> es la carpeta donde has extraído el paquete CodeQL CLI.
Agregando /<extraction-root>/codeql a PATH, para poder ejecutar el archivo ejecutable simplemente como codeql.

Si usas CodeQL CLI para analizar el código escrito en Python, debes asegurarte de que el sistema de CI tenga instalado Python 3.

Prueba de la configuración de la CodeQL CLI

Después de extraer el paquete de CodeQL CLI, puedes ejecutar el siguiente comando para comprobar que la CLI esté configurada correctamente para crear y analizar bases de datos.

codeql resolve qlpacks si /<extraction-root>/codeql está en PATH.
En caso contrario, es /<extraction-root>/codeql/codeql resolve qlpacks.

Extraer desde una salida satisfactoria:

codeql/cpp-all (/<extraction-root>/qlpacks/codeql/cpp-all/<version>)
codeql/cpp-examples (/<extraction-root>/qlpacks/codeql/cpp-examples/<version>)
codeql/cpp-queries (/<extraction-root>/qlpacks/codeql/cpp-queries/<version>)
codeql/csharp-all (/<extraction-root>/qlpacks/codeql/charp-all/<version>)
codeql/csharp-examples (/<extraction-root>/qlpacks/codeql/charp-examples/<version>)
codeql/csharp-queries (/<extraction-root>/qlpacks/codeql/charp-queries/<version>)
codeql/java-all (/<extraction-root>/qlpacks/codeql/java-all/<version>)
codeql/java-examples (/<extraction-root>/qlpacks/codeql/java-examples/<version>)
codeql/java-queries (/<extraction-root>/qlpacks/codeql/java-queries/<version>)
codeql/javascript-all (/<extraction-root>/qlpacks/codeql/javascript-all/<version>)
codeql/javascript-examples (/<extraction-root>/qlpacks/codeql/javascript-examples/<version>)
codeql/javascript-queries (/<extraction-root>/qlpacks/codeql/javascript-queries/<version>)
codeql/python-all (/<extraction-root>/qlpacks/codeql/python-all/<version>)
codeql/python-examples (/<extraction-root>/qlpacks/codeql/python-examples/<version>)
codeql/python-queries (/<extraction-root>/qlpacks/codeql/python-queries/<version>)
codeql/ruby-all (/<extraction-root>/qlpacks/codeql/ruby-all/<version>)
codeql/ruby-examples (/<extraction-root>/qlpacks/codeql/ruby-examples/<version>)
codeql/ruby-queries (/<extraction-root>/qlpacks/codeql/ruby-queries/<version>)
...

Debes verificar que la salida contenga los lenguajes esperados y también que la ubicación del directorio para el archivo de qlpack sea correcta. La ubicación debe ser dentro del paquete de CodeQL CLI extraído, que se muestra anteriormente como <extraction root>, a menos que estés utilizando una restauración de github/codeql. Si el CodeQL CLI no es capaz de localizar los qlpacks para los lenguajes esperados, verifica que hayas descargado el paquete de CodeQL y no una copia independiente del CodeQL CLI.

Generar un token para autenticarse con GitHub

Cada servidor de CI necesita GitHub App o personal access token para CodeQL CLI para cargar los resultados en GitHub. Debes usar un token de acceso o GitHub App con el permiso de escritura security_events. Si los servidores de IC utilizan un token con este alcance para verificar los repositorios de GitHub, podrías permitir potencialmente que CodeQL CLI utilice el mismo token. De lo contrario, crea un token nuevo con el permiso de escritura security_events y agrégalo al almacén de secretos del sistema de CI. Para información, consulta "Creación de aplicaciones de GitHub" y "Managing your personal access tokens".

Pasos siguientes

Ahora estás listo para configurar el sistema de IC para que ejecute el análisis de CodeQL, genere resultados y los cargue en GitHub donde dichos resultados se empatarán con una rama o solicitud de cambios y se mostrarán como alertas del code scanning. Para más información, consulta "Configurar el CLI de CodeQL en tu sistema de IC".