Configuration de CodeQL CLI

Configuration de CodeQL CLI

Pour exécuter les commandes CodeQL, vous devez configurer l’interface CLI afin qu’elle puisse accéder aux outils, aux requêtes et aux bibliothèques nécessaires à la création et à l’analyse des bases de données.

CodeQL CLI peut être configuré pour prendre en charge de nombreux cas d’usage et structures de répertoires différents. Pour commencer rapidement, nous vous recommandons d’adopter une configuration relativement simple, comme indiqué dans les étapes ci-dessous.

Si vous prévoyez d'utiliser CodeQL CLI pour des recherches sur la sécurité ou pour tester ou contribuer à des requêtes, vous voudrez peut-être une configuration plus avancée de CodeQL CLI. Pour plus d’informations, consultez « Installation avancée de l'interface CLI CodeQL ».

Si vous créez CodeQL CLI dans votre système de CI, vous devez rendre le contenu complet de l'offre groupée CodeQL CLI disponible pour chaque serveur CI sur lequel vous souhaitez exécuter l'analyse CodeQL code scanning. 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. Pour plus d’informations, consultez Points de terminaison d’API REST pour les versions et les ressources de mise en production dans la documentation de l’API REST.

Si vous utilisez macOS sur Apple Silicon (par exemple, Apple M1), assurez-vous que les outils de développement en ligne de commande Xcode et Rosetta 2 sont installés.

1. Télécharger l’archive tar CodeQL CLI

Le package de téléchargement CodeQL CLI est une archive tar contenant des outils, des scripts et divers fichiers spécifiques à CodeQL. Si vous n’avez pas de licence GitHub Enterprise, en téléchargeant cette archive, vous acceptez les conditions générales de GitHub CodeQL.

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. Cela garantit la compatibilité et offre de meilleures performances qu’un téléchargement de CodeQL CLI et une extraction des requêtes CodeQL. Si vous envisagez d’exécuter l’interface CLI sur une seule plateforme, téléchargez le fichier codeql-bundle-PLATFORM.tar.zst approprié. Vous pouvez également télécharger codeql-bundle.tar.zst qui contient l’interface CLI pour toutes les plateformes prises en charge.

Il existe également des variantes tar.gz du bundle, qui sont identiques aux variantes tar.zst, sauf qu’elles sont compressées à l’aide de l’algorithme gzip moins efficace. La seule raison de télécharger les variantes tar.gz est si vous utilisez des outils de décompression plus anciens qui ne prennent pas en charge l’algorithme de compression Zstandard.

2. Extraire l’archive tar CodeQL CLI

Extrayez l’archive tar CodeQL CLI dans un répertoire de votre choix.

3. Lancer codeql

Une fois extrait, vous pouvez exécuter des processus CodeQL en exécutant le fichier exécutable codeql de deux façons :

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

À ce stade, vous pouvez exécuter des commandes CodeQL. Pour obtenir la liste complète des commandes CodeQL CLI, consultez « Manuel des commandes de l’interface CLI CodeQL ».

Test de la configuration de l’CodeQL CLI

Après avoir extrait le bundle de 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 packs si /<extraction root>/codeql est dans le PATH.
• Sinon, /<extraction root>/codeql/codeql resolve packs.

Si vous avez réussi, vous devriez obtenir un résultat similaire à l’extrait ci-dessous :

Searching directories specified by `--additional-packs`. All directories have equal priority.
  Searching in:
    No packs were found at this location.
Searching directories specified by `--search-path`. Directories are searched in order.
Searching the root of the CodeQL distribution.
  Searching in:
      <extraction root>
    The following packs were found:
      codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml
      codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml
      codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml
      codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml
      codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml
      codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml
...

Les résultats ont été tronqués par souci de concision. Les résultats réels seront plus longs et détaillés.

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 l'offre groupée CodeQL CLI extraite, qui est montré dans l'exemple précédent en tant que <extraction root>. 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.

Vous pouvez aussi exécuter codeql resolve languages pour montrer les langages disponibles pour la création de base de données. Cette opération liste les langages pris en charge par défaut dans votre package CodeQL CLI.

Si vous le souhaitez, vous pouvez télécharger des packs CodeQL contenant des requêtes précompilées que vous voulez exécuter. Pour plus d’informations, consultez « Personnalisation de l’analyse avec des packs CodeQL ».

La commande codeql resolve packs est utile pour diagnostiquer les problèmes lorsque le CodeQL CLI ne parvient pas à localiser les packs de requêtes qui devraient être disponibles pour l’analyse.

Étapes suivantes

Pour savoir comment préparer votre code à analyser par les données CodeQL CLI, reportez-vous à Préparation de votre code pour l’analyse CodeQL.