Exécuter des requêtes CodeQL

À propos de l'exécution des requêtes CodeQL

Le référentiel github/codeql contient de nombreux exemples de requêtes. Vous pouvez accéder à toutes les requêtes existantes de votre espace de travail via la vue « Requêtes ».

Prerequisites

Pour analyser une base de code, vous exécutez des requêtes sur une base de données CodeQL extraite du code. Vous devez donc sélectionner une base de données avec laquelle travailler dans l’extension. Vous pouvez sélectionner une base de données en local (à partir d’une archive ZIP ou d’un dossier décompressé), depuis une URL publique ou depuis l’URL d’un projet sur GitHub.com. Pour plus d’informations, consultez « Gestion de bases de données CodeQL ».

Exécution d’une requête unique

1. Dans la barre latérale, ouvrez la vue « Requêtes ».

2. Pour exécuter une requête sur la base de données sélectionnée, survolez la requête souhaitée, puis cliquez sur l’icône Exécuter la requête locale.

L’extension CodeQL exécute la requête sur la base de données actuelle et affiche l’avancement dans le coin inférieur droit de l’application. Lorsque les résultats sont prêts, ils sont affichés dans la vue « Résultats de la requête » de CodeQL.

En cas de problème lors de l’exécution d’une requête, une notification s’affiche dans le coin inférieur droit de l’application. En plus du message d’erreur, la notification inclut des informations détaillant la manière de corriger le problème.

Exécution de toutes les requêtes dans un répertoire

Vous pouvez exécuter toutes les requêtes d’un répertoire.

1. Dans la barre latérale, ouvrez la vue « Requêtes ».

2. Survolez le répertoire de requêtes souhaité, puis cliquez sur l’icône Exécuter les requêtes locales.

Exécuter une sélection de requêtes

Vous pouvez exécuter plusieurs requêtes à l'aide d'une seule commande.

1. Accédez à Explorateur de fichiers.

2. Sélectionnez plusieurs fichiers ou dossiers contenant des requêtes.

3. Cliquez avec le bouton droit et sélectionnez CodeQL : exécuter des requêtes dans les fichiers sélectionnés.

Exécuter une requête sans configuration

Lorsque vous travaillez sur une nouvelle requête, vous pouvez ouvrir un onglet « Requête rapide » afin d’exécuter facilement votre code et d’afficher les résultats, sans avoir à enregistrer de fichier .ql dans votre espace de travail. Sélectionnez CodeQL : Requête rapide depuis VS Code Command Palette, puis pour exécuter la requête, utilisez CodeQL : Exécuter la requête sur la base de données sélectionnée.

Vous pouvez consulter toutes les requêtes rapides que vous avez exécutées durant la session en cours dans la vue « Historique des requêtes ». Cliquez sur une entrée pour afficher le texte exact de la requête rapide ayant produit les résultats. Pour en savoir plus, consultez Afficher votre historique des requêtes.

Une fois satisfait de votre requête rapide, vous devez l’enregistrer dans un pack CodeQL afin de pouvoir y accéder ultérieurement. Pour plus d’informations, consultez « Personnalisation de l’analyse avec des packs CodeQL ».

Exécution d’une partie spécifique d’une requête ou d’une bibliothèque

Cela peut être utile lorsque vous déboguez une requête ou une bibliothèque et que vous souhaitez localiser la partie incorrecte.

Au lieu d’utiliser CodeQL : Exécuter la requête sur la base de données sélectionnée pour exécuter l’intégralité de la requête (la clause select et tous les prédicats de requête), vous pouvez utiliser CodeQL : Évaluation rapide afin d’exécuter une partie spécifique d’un fichier .ql ou .qll.

          **CodeQL : Évaluation rapide ** évalue l’extrait de code que vous avez sélectionné, plutôt que l’intégralité de la requête, et affiche les résultats de cette sélection dans la vue « Résultats ».

Cibles possibles pour l’évaluation rapide :

• Sélection du nom d’une entité CodeQL (par ex. une classe ou un prédicat) afin d'évaluer cette entité.

• Sélection d’une formule ou d’une expression comportant des variables libres afin d’évaluer cette formule ou cette expression.

Par exemple, dans l’extrait suivant, vous pouvez sélectionner le nom du prédicat foo ou la formule s = "bar" pour une évaluation rapide :

predicate foo(string s) { s = "bar" }

Exécuter une requête sur plusieurs bases de données

Cela peut être utile si vous souhaitez tester votre requête sur plusieurs bases de code ou rechercher une vulnérabilité dans plusieurs projets.

1. Ouvrez un fichier de requête (.ql).

2. Cliquez avec le bouton droit et sélectionnez CodeQL : Exécuter la requête sur plusieurs bases de données.

3. Dans le menu déroulant, sélectionnez les bases de données sur lesquelles vous souhaitez exécuter la requête.

Afficher l’historique des requêtes

Pour consulter les requêtes que vous avez exécutées durant la session en cours, ouvrez la vue « Historique des requêtes »

La vue « Historique des requêtes » contient des informations telles que la date et l’heure d’exécution de la requête, le nom de la requête, la base de données sur laquelle elle a été exécutée et la durée d’exécution de la requête :

• Pour personnaliser les informations affichées, cliquez avec le bouton droit sur une entrée et sélectionnez Renommer.

• Facultativement, filtrez la vue par langage à l’aide du sélecteur de langage. Pour en savoir plus, consultez Filtrer des bases de données et des requêtes par langage.

• Cliquez sur une entrée pour afficher les résultats correspondants, et double-cliquez pour afficher la requête elle-même dans l’éditeur (ou cliquez avec le bouton droit et sélectionnez Afficher la requête).

• Pour afficher le texte exact ayant produit les résultats pour une entrée donnée, cliquez dessus avec le bouton droit et sélectionnez Afficher le texte de la requête. Cela peut différer de Afficher la requête, car le fichier de requête peut avoir été modifié depuis sa dernière exécution.

• Pour supprimer des requêtes de la vue, sélectionnez toutes les requêtes que vous souhaitez supprimer, puis cliquez avec le bouton droit et sélectionnez Supprimer.

Comprendre les résultats de vos requêtes

1. Cliquez sur une requête dans la vue « Historique des requêtes » pour afficher ses résultats dans la vue « Résultats ».

   Remarque

   Selon la requête, vous pouvez également choisir différents modes d’affichage, tels que CSV, Sortie SARIF dans l’interface CLI de CodeQL ou DIL. Par exemple, pour afficher le format DIL, cliquez avec le bouton droit sur un résultat et sélectionnez Afficher le DIL. Les vues de sortie disponibles sont déterminées par le format et les métadonnées de la requête. Pour plus d’informations, consultez Requêtes CodeQL.

2. Utilisez le menu déroulant de la vue « Résultats » pour choisir quels résultats afficher et sous quelle forme les afficher, par exemple sous la forme d’un message d’alerte formaté ou d’un tableau de résultats bruts.

3. Pour trier les résultats selon les entrées d’une colonne donnée, cliquez sur l’en-tête de la colonne.

Si un résultat est lié à un élément du code source, vous pouvez cliquer dessus pour l’afficher dans le code source.

Pour utiliser les fonctionnalités standard de navigation dans le code source, vous pouvez cliquer avec le bouton droit sur un élément et utiliser les commandes Aller à la définition ou Aller aux références. Cette action exécute une requête CodeQL sur le fichier actif, ce qui peut prendre quelques secondes. Cette requête doit être exécutée une fois pour chaque fichier ; les références supplémentaires provenant du même fichier seront donc rapides.

Comparer les résultats des requêtes

Lorsque vous écrivez ou déboguez une requête, il est utile de voir comment vos modifications affectent les résultats. Vous pouvez comparer deux ensembles de résultats afin de voir précisément ce qui a changé. Pour comparer des résultats, les deux requêtes doivent être exécutées sur la même base de données.

1. Cliquez avec le bouton droit sur une requête dans la vue « Historique des requêtes » et sélectionnez Comparer les résultats.

2. Un menu de sélection rapide affiche toutes les requêtes valides avec lesquelles effectuer la comparaison. Sélectionnez une requête.

3. La vue « Comparaison » affiche les différences entre les résultats des deux requêtes.

Résolution des problèmes

Pour afficher les journaux d’exécution d’une requête donnée, cliquez avec le bouton droit sur la requête dans la vue « Historique des requêtes » et sélectionnez Afficher le journal de la requête. Si le fichier journal est trop volumineux pour être ouvert par l’extension dans VS Code, il sera affiché dans votre explorateur de fichiers afin que vous puissiez l’ouvrir avec un programme externe.

Pour obtenir des détails sur la compilation et l’exécution des requêtes, ainsi que des informations sur les mises à niveau des bases de données, consultez le journal du serveur de requêtes CodeQL. Pour plus d’informations, consultez « Accès aux journaux d’activité ».

Par défaut, l’extension supprime les journaux après chaque session de l’espace de travail. Pour remplacer ce comportement, vous pouvez spécifier un répertoire personnalisé pour les journaux du serveur de requêtes. Pour plus d’informations, consultez « Personnalisation des paramètres ».

Vous pouvez utiliser la commande CodeQL : Redémarrer le serveur de requêtes pour redémarrer le serveur de requêtes. Cette action redémarre le serveur sans affecter l’historique de vos sessions CodeQL. Vous aurez très probablement besoin de redémarrer le serveur de requêtes si vous apportez des modifications externes aux fichiers utilisés par l’extension. Par exemple, lorsque vous régénérez une base de données CodeQL qui est ouverte dans VS Code. En plus des problèmes consignés dans le journal, vous pouvez également constater des erreurs dans la coloration du code, des totaux de résultats incorrects ou des notifications en double indiquant qu’une requête est en cours d’exécution.

Étapes suivantes

Vous pouvez également utiliser l’extension, de manière facultative, pour créer vos propres requêtes personnalisées. Pour plus d’informations, consultez « Création d’une requête personnalisée ».