Exécution de requêtes CodeQL

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

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

Prérequis

Pour analyser un codebase, vous exécutez des requêtes sur une base de données CodeQL extraite du code, donc vous devrez sélectionner une base de données pour travailler avec l’extension. Vous pouvez sélectionner une base de données localement (à partir d’une archive ZIP ou d’un dossier nonarchivé), à partir d’une URL publique ou de 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, passez sur 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 active et signale la progression 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 » CodeQL.

S’il existe des problèmes 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 détails sur la façon de résoudre le problème.

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

Vous pouvez exécuter chaque requête dans un annuaire.

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

2. Pointez sur l’annuaire souhaité des requêtes, puis cliquez sur l’icône Exécuter les requêtes locales.

Exécution d’une sélection de requêtes

Vous pouvez exécuter plusieurs requêtes avec une seule commande.

1. Accédez à File Explorer.

2. Sélectionnez plusieurs fichiers ou dossiers qui contiennent 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écution d’une requête sans configuration

Lorsque vous travaillez sur une nouvelle requête, vous pouvez ouvrir un onglet « Requête rapide » pour exécuter facilement votre code et afficher les résultats, sans avoir à enregistrer un fichier .ql dans votre espace de travail. Sélectionnez CodeQL : Requête rapide à partir de 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 voir toutes les requêtes rapides que vous avez exécutées dans la session active dans la vue « Historique des requêtes ». Cliquez sur une entrée pour afficher le texte exact de la requête rapide qui a produit les résultats. Pour plus d’informations, consultez « Afficher votre historique de requêtes ».

Une fois que vous êtes 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 si vous déboguez une requête ou une bibliothèque et que vous souhaitez localiser la partie qui est incorrecte.

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

**CodeQL : l’évaluation rapide ** évalue un extrait de code que vous avez sélectionné, au lieu de la requête entière, et affiche les résultats de cette sélection dans la vue « Résultats ».

Les cibles possibles pour l’évaluation rapide sont les suivantes :

• Sélection du nom d’une entité CodeQL (par ex. une [classe ou un prédicat](https://codeql.github.com/docs/ql-language-reference/predicates/#predicates)) pour évaluer cette entité.

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

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

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

Exécution d’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 trouver 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écutez la requête sur plusieurs bases de données.

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

Affichage de l’historique des requêtes

Pour afficher les requêtes que vous avez exécutées dans la session active, ouvrez la vue « Historique des requêtes ».

La vue « Historique des requêtes » contient des informations, notamment la date et l’heure de l’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 le temps nécessaire pour exécuter la requête :

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

• Si vous le souhaitez, filtrez l’affichage par langue à l’aide du sélecteur de langue. Pour plus d’informations, consultez « Filtrage des bases de données et des requêtes par langage ».

• Cliquez sur une entrée pour afficher les résultats correspondants, puis 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 qui a produit les résultats d’une entrée particulière, cliquez dessus avec le bouton droit et sélectionnez Afficher le texte de la requête. Cela peut différer de la requête d’affichage, car le fichier de requête a peut-être été modifié depuis la dernière exécution.

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

Comprendre vos résultats de requête

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

   Note

   Selon la requête, vous pouvez également choisir différentes vues telles 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 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 dans la vue « Résultats » pour choisir les résultats à afficher et dans quel formulaire les afficher, tels qu’un message d’alerte mis en forme ou un tableau de résultats bruts.

3. Pour trier les résultats par les entrées d’une colonne particulière, cliquez sur l’en-tête de colonne.

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

Pour utiliser des fonctionnalités de navigation de code standard dans le code source, vous pouvez cliquer avec le bouton droit sur un élément et utiliser les commandes Atteindre la définition ou Accéder aux références. Cette opération exécute une requête CodeQL sur le fichier actif, ce qui peut prendre quelques secondes. Cette requête doit s’exécuter une fois pour chaque fichier. Par conséquent, toutes les références supplémentaires du même fichier seront rapides.

Comparer des résultats de 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 pour voir exactement ce qui a changé. Pour comparer les 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 », puis sélectionnez Comparer les résultats.

2. Un menu Sélection rapide affiche toutes les requêtes valides à comparer. Sélectionnez une requête.

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

Dépannage

Pour afficher les journaux d’activité de l’exécution d’une requête particulière, cliquez avec le bouton droit sur la requête dans la vue « Historique des requêtes », puis sélectionnez Afficher le journal des requêtes. Si le fichier journal est trop volumineux pour que l’extension s’ouvre dans VS Code, le fichier s’affiche dans votre explorateur de fichiers afin de pouvoir l’ouvrir avec un programme externe.

Pour plus d’informations sur la compilation et l’exécution de requêtes, ainsi que sur les mises à niveau de base de données, vérifiez 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 d’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 « Personnaliser les paramètres ».

Vous pouvez utiliser la commande CodeQL : Redémarrer le serveur de requêtes pour redémarrer le serveur de requêtes. Cela redémarre le serveur sans affecter votre historique de session CodeQL. Vous devrez probablement redémarrer le serveur de requêtes si vous apportez des modifications externes aux fichiers que l’extension utilise. Par exemple, régénérer une base de données CodeQL ouverte dans VS Code. En plus des problèmes dans le journal, vous pouvez également voir : erreurs dans la mise en surbrillance du code, totaux de résultats incorrects ou notifications en double qu’une requête exécute.

Étapes suivantes

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

Pour plus d’informations sur l’exécution de l’analyse à grande échelle sur de nombreuses bases de données CodeQL, consultez « Exécution de requêtes CodeQL à grande échelle avec l’analyse de variantes multi-référentiels ».