Installation de l’interface CLI de CodeQL dans votre système CI

À propos de l’CodeQL CLI pour l’code scanning

Vous pouvez utiliser l’CodeQL CLI pour exécuter l’code scanning sur le code que vous traitez dans un système d’intégration continue (CI) tiers. Code scanning es une fonctionnalité que vous utilisez pour analyser le code dans un dépôt GitHub afin de détecter d’éventuelles vulnérabilités de sécurité et erreurs de codage. Tous les problèmes identifiés par l’analyse sont affichés dans GitHub Enterprise Cloud. Pour plus d’informations, consultez « À propos de l’analyse du code avec CodeQL ». Pour découvrir les spécifications recommandées (RAM, cœurs de processeur et disque) pour l’exécution de l’analyse CodeQL, consultez « Ressources matérielles recommandées pour l’exécution de CodeQL ».

CodeQL CLI est un produit autonome que vous pouvez utiliser pour analyser le code. Son objectif principal est de générer une représentation de base de données d’un codebase, une base de données CodeQL. Une fois que la base de données est prête, vous pouvez l’interroger de manière interactive, ou exécuter une suite de requêtes pour générer un ensemble de résultats au format SARIF et charger les résultats dans GitHub.com.

Vous pouvez également utiliser GitHub Actions pour exécuter l’code scanning dans GitHub Enterprise Cloud. Pour plus d’informations sur code scanning avec des actions, consultez « Configuration de l’analyse du code pour un référentiel ». Pour obtenir une vue d’ensemble des options pour les systèmes CI, consultez « À propos de l’analyse du code CodeQL dans votre système d’intégration continue ».

Remarques :

L’utilisation de CodeQL CLI est gratuite sur des dépôts publics gérés sur GitHub.com et disponible sur des dépôts privés appartenant à des clients disposant d’une licence Advanced Security. Pour plus d’informations, consultez « Conditions générales de GitHub Enterprise Cloud CodeQL » et « Interface CLI de CodeQL ».
CodeQL CLI n’est actuellement pas compatible avec les distributions Linux non-glibc comme Alpine Linux (basée sur musl).

Téléchargement de l’CodeQL CLI

Vous devez télécharger le bundle CodeQL à partir de https://github.com/github/codeql-action/releases. Le bundle contient :

L’CodeQL CLI
Une version compatible des requêtes et des bibliothèques de https://github.com/github/codeql
Versions précompilées de toutes les requêtes incluses dans le bundle

Vous devez toujours utiliser le bundle CodeQL, car cela garantit la compatibilité et offre de meilleures performances qu’un téléchargement de l’CodeQL CLI et une extraction des requêtes CodeQL à part. Si vous envisagez d’exécuter l’interface CLI sur une seule plateforme, téléchargez le fichier codeql-bundle-PLATFORM.tar.gz approprié. Vous pouvez également télécharger codeql-bundle.tar.gz qui contient l’interface CLI pour toutes les plateformes prises en charge.

Remarque : La fonctionnalité de gestion des packages CodeQL ainsi que les packs CodeQL sont en version bêta et peuvent être amenés à changer.

Configuration de l’CodeQL CLI dans votre système CI

Vous devez rendre le contenu complet du bundle de l’CodeQL CLI disponible pour chaque serveur CI sur lequel vous souhaitez exécuter l’code scanning CodeQL. Par exemple, vous pouvez configurer chaque serveur pour copier le bundle à partir d’un emplacement central interne et l’extraire. Vous pouvez également utiliser l’API REST pour obtenir le bundle directement à partir de GitHub, bénéficiant ainsi des dernières améliorations apportées aux requêtes. Les mises à jour de l’CodeQL CLI sont publiées toutes les 2 à 3 semaines. Par exemple :

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

Après avoir extrait le bundle de l’CodeQL CLI, vous pouvez exécuter l’exécutable codeql sur le serveur :

En exécutant /<extraction-root>/codeql/codeql, où <extraction-root> est le dossier dans lequel vous avez extrait le bundle de l’CodeQL CLI.
En ajoutant /<extraction-root>/codeql à votre PATH, afin de pouvoir exécuter le fichier exécutable uniquement comme codeql.

Si vous utilisez CodeQL CLI pour analyser du code écrit en Python, vous devez vous assurer que Python 3 est installé sur votre système CI.

Test de la configuration de l’CodeQL CLI

Après avoir extrait le bundle de l’CodeQL CLI, vous pouvez exécuter la commande suivante pour vérifier que l’interface CLI est correctement configurée pour créer et analyser des bases de données.

codeql resolve qlpacks si /<extraction-root>/codeql est dans le PATH.
Sinon, /<extraction-root>/codeql/codeql resolve qlpacks.

Extrait de la sortie réussie :

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

Vous devez vérifier que la sortie contient les langages attendus et que l’emplacement du répertoire des fichiers qlpack est correct. L’emplacement doit se trouver dans le bundle de l’CodeQL CLI extrait, indiqué ci-dessus sous la forme <extraction root>, sauf si vous utilisez une extraction de github/codeql. Si l’CodeQL CLI ne peut pas localiser les qlpacks pour les langages attendus, vérifiez que vous avez téléchargé le bundle CodeQL et non une copie autonome de l’CodeQL CLI.

Génération d’un jeton pour l’authentification auprès de GitHub Enterprise Cloud

Chaque serveur CI a besoin d’une GitHub App ou d’un personal access token qui permette à l’CodeQL CLI de charger les résultats sur GitHub Enterprise Cloud. Vous devez utiliser un jeton d’accès ou une GitHub App avec l’autorisation d’écriture security_events. Si les serveurs CI utilisent déjà un jeton avec cette étendue pour extraire les dépôts à partir de GitHub Enterprise Cloud, vous pouvez éventuellement autoriser l’CodeQL CLI à utiliser le même jeton. Sinon, vous devez créer un jeton avec l’autorisation d’accès en écriture security_events et l’ajouter au magasin de secrets du système CI. Pour plus d’informations, consultez « Création d’applications GitHub » et « Managing your personal access tokens ».

Étapes suivantes

Vous êtes maintenant prêt à configurer le système CI pour exécuter l’analyse CodeQL, générer des résultats et les charger sur GitHub Enterprise Cloud, où ils seront mis en correspondance avec une branche ou une demande de tirage (pull request) et affichés en tant qu’alertes d’code scanning. Pour plus d’informations, consultez Configuration de l’interface CLI de CodeQL dans votre système CI.