Configuration de CodeQL CLI

Pour commencer à utiliser CodeQL CLI, vous devez télécharger et configurer l’interface CLI afin qu’elle puisse accéder aux outils et aux bibliothèques nécessaires à la création et à l’analyse des bases de données.

Qui peut utiliser cette fonctionnalité ?

CodeQL est disponible pour les types de référentiels suivants :

Dans cet article

Configuration de CodeQL CLI

Pour exécuter des commandes CodeQL, vous devez configurer le CodeQL CLI afin qu'il puisse accéder aux outils, requêtes et bibliothèques nécessaires pour créer et analyser des bases de données.

CodeQL CLI prend en charge un large éventail de cas d’utilisation et de structures de répertoires. Cet article décrit une configuration simple qui fonctionne pour la plupart des utilisateurs et des environnements.

Si vous envisagez d’utiliser le CodeQL CLI pour la recherche de sécurité ou pour tester ou contribuer des requêtes, vous aurez peut-être besoin d’une configuration plus avancée. Pour plus d’informations, consultez « Configuration avancée de l’interface CLI CodeQL ».

Avant de commencer

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.

Remarque

CodeQL CLI n’est actuellement pas compatible avec les distributions Linux non-glibc comme Alpine Linux (basée sur muslc).

1. Télécharger l’archive tar de 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 http://github.com/github/codeql-action/releases. Le bundle contient :

  • L’CodeQL CLI
  • Une version compatible des requêtes et des bibliothèques de http://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 de CodeQL CLI

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

Facultatif : rendre les données CodeQL CLI disponibles dans votre système CI

Si vous prévoyez d’exécuter une analyse code scanning CodeQL dans un système d’intégration continue (CI), assurez-vous que l’intégralité du contenu du bundle CodeQL CLI est disponible sur chaque serveur CI qui exécutera l’analyse.

Par exemple, vous pouvez :

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.

Remarque

Si vous ajoutez codeql à votre PATH, il est accessible par CodeQL pour que Visual Studio Code compile et exécute les requêtes. Pour plus d’informations sur la configuration de VS Code pour accéder à CodeQL CLI, consultez Configuration de l’accès à la 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 cela fonctionne, le résultat devrait ressembler à 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 le bundle CodeQL CLI extrait, 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 CodeQL CLI ne parvient pas à localiser les packs de requêtes qui devraient être disponibles pour l’analyse.

Remarque

La commande codeql resolve packs est disponible dans CodeQL CLI versions 2.19.0 et ultérieures. Pour les versions antérieures de la CLI, vous devez exécuter la commande codeql resolve qlpacks, qui produit un résultat similaire, mais moins détaillé.

Étapes suivantes

Pour savoir comment préparer votre code à analyser par CodeQL CLI, consultez Préparation de votre code pour l’analyse CodeQL.