Utilisation de l’éditeur de modèle CodeQL

À propos de l’éditeur de modèle CodeQL

Avec les packs de modèles CodeQL, vous pouvez étendre votre analyse CodeQL code scanning pour reconnaître les bibliothèques et infrastructures personnalisées utilisées par votre codebase qui ne sont pas prises en charge par défaut. Avec l’éditeur de modèle CodeQL, vous pouvez créer vos propres packs de modèles. L’éditeur de modèle vous guide tout au long de la modélisation des appels aux dépendances externes dans votre application, ou en modélisant entièrement tous les points d’entrée et de sortie publics dans une dépendance externe.

Pour plus d’informations sur la personnalisation des données code scanning avec des packs de modèles, notamment le téléchargement des packs d’autres personnes pour les exécuter dans votre propre analyse, consultez « Personnalisation de l’analyse avec des packs CodeQL ».

Lorsque vous ouvrez l’éditeur de modèle, il analyse la base de données CodeQL actuellement sélectionnée et identifie où l’application utilise des API externes et toutes les méthodes publiques. Une API externe (ou tierce) est une API qui ne fait pas partie de la base de données CodeQL que vous avez sélectionnée.

L’éditeur de modèle a deux modes différents :

• Mode d’application (affichage par défaut) : l’éditeur répertorie chaque framework externe utilisé par la base de données CodeQL sélectionnée. Lorsque vous développez un cadre, une liste de tous les appels vers et depuis l’API externe s’affiche avec les options disponibles pour modéliser le flux de données via chaque appel. Ce mode est le plus utile pour améliorer les résultats CodeQL pour un codebase spécifique.

• Mode de dépendance : l’éditeur identifie toutes les API accessibles publiquement dans la base de données CodeQL sélectionnée. Cette vue vous guide tout au long de la modélisation de chaque API publique que le codebase met à disposition. Une fois que vous avez terminé la modélisation de l’API entière, vous pouvez enregistrer le modèle et l’utiliser pour améliorer l’analyse CodeQL pour toutes les codebases qui utilisent la dépendance.

Affichage de l’éditeur de modèle CodeQL

1. Ouvrez votre espace de travail CodeQL dans VS Code. Par exemple, l’vscode-codeql-starterespace de travail. Si vous utilisez l’espace de travail de démarrage, mettez à jour la sous-modification ql depuis main pour vous assurer que vous disposez des requêtes utilisées pour collecter des données pour l’éditeur de modèle.

2. Dans Visual Studio Code, cliquez sur QL dans la barre latérale gauche pour afficher l’extension GitHub Copilot.

3. Dans la vue « Bases de données », sélectionnez la base de données CodeQL à partir de laquelle vous souhaitez modéliser.

4. Dans la vue CodeQL « Modélisation des méthodes », cliquez sur Démarrer la modélisation pour afficher l’éditeur de modèle. Vous pouvez également utiliser le VS Code Command Palette pour exécuter la commande CodeQL : Ouvrir l’éditeur de modèle (Bêta).

5. L’éditeur de modèle CodeQL exécute une série de requêtes de télémétrie pour identifier les API dans le code, et l’éditeur s’affiche dans un nouvel onglet.

6. Une fois les requêtes de télémétrie terminées, les API identifiées sont affichées dans l’éditeur.

Modélisation des appels effectués par votre codebase aux API externes

Vous utilisez généralement cette approche lorsque vous examinez un codebase spécifique dans lequel vous souhaitez améliorer la précision des résultats CodeQL. Cela est utile lorsque le codebase utilise des frameworks ou des bibliothèques qui ne sont pas pris en charge par CodeQL, et si le code source du cadre ou de la bibliothèque n’est pas inclus dans l’analyse.

Cette section utilise un projet Java open source appelé « sofa-jraft » comme exemple. L’expérience de modélisation des appels aux API externes écrites dans d’autres langages compilés est similaire.

1. Dans Visual Studio Code, sélectionnez la base de données CodeQL pour laquelle vous voulez améliorer la couverture de CodeQL.

2. Affichez l’éditeur de modèle CodeQL. Par défaut, l’éditeur s’exécute en mode application, de sorte que la liste des API externes utilisées par le codebase sélectionné s’affiche.

   

3. Cliquez pour développer une API externe et afficher la liste des appels du codebase vers la dépendance externe.

   

4. Cliquez sur Vue associé à un appel ou une méthode d’API pour afficher l’emplacement où il est utilisé dans votre codebase.

5. Le fichier contenant le premier appel de votre base de code vers l’API est ouvert, et une vue CodeQL « Utilisation des méthodes » s’affiche dans VS Code (où les vues « Problèmes » et « Terminal » sont généralement affichées). Les données CodeQL « Utilisation des méthodes » répertorient tous les appels de votre code à l’API, regroupés par méthode. Vous pouvez cliquer sur chaque utilisation pour décider comment modéliser votre utilisation de la méthode.

6. Lorsque vous avez déterminé comment modéliser votre utilisation de la méthode, vous pouvez sélectionner un type de modèle différent. Cliquez sur la liste déroulante sous « Type de modèle » dans la vue CodeQL « Modélisation des méthodes » de l’extension CodeQL. Cette modification est automatiquement reflétée dans l’éditeur de modèle principal.

7. Les champs restants de cette ligne sont mis à jour avec les options disponibles pour le type de modèle choisi :

   • « Source » : choisissez l’élément « Sortie » à modéliser.
   • « Récepteur » : choisissez l’élément « Entrée » à modéliser.
   • « Résumé du flux » : choisissez les éléments « Entrée » et « Sortie » pour modéliser.

8. Définissez le « Type » de flux de données pour le modèle.

9. Une fois la modélisation terminée, affichez l’éditeur de modèle principal, puis cliquez sur Enregistrer tout ou Enregistrer (affiché en bas à droite de chaque liste développée de méthodes). Le pourcentage de méthodes modélisées dans l’éditeur est mis à jour.

Les modèles sont stockés dans votre espace de travail sur .github/codeql/extensions/CODEQL-MODEl-PACK, où CODEQL-MODEL-PACK est le nom de la base de données CodeQL que vous avez sélectionnée. Autrement dit, le nom du référentiel, trait d’union, la langue analysée par CodeQL. Pour plus d’informations, consultez « Création et utilisation de packs CodeQL ».

Les modèles sont stockés dans une série de fichiers d’extension de données YAML, un pour chaque API externe. Par exemple :

.github/codeql/extensions/sofa-jraft-java # the model pack directory
    models
        jmh-core.model.yml                  # models calls to jmh-core@1.20
        rocksdbjni.model.yml                # models calls to rocksdbjni@7.7.3

Modélisation de l’API publique d’un codebase

Vous utilisez généralement cette méthode lorsque vous souhaitez modéliser un cadre ou une bibliothèque que votre organisation utilise dans plusieurs codebases. Une fois que vous avez terminé la création et le test du modèle, vous pouvez publier le pack de modèles CodeQL sur le GitHub Container registry pour que toute votre organisation utilise.

Cette section utilise un projet Java open source appelé « sofa-jraft » comme exemple. L’expérience de modélisation des appels aux API externes écrites dans d’autres langages compilés est similaire.

1. Sélectionnez la base de données CodeQL que vous voulez modéliser.

2. Affichez l’éditeur de modèle CodeQL. Par défaut, l’éditeur s’exécute en mode application. Cliquez sur Modèle comme dépendance pour afficher le mode de dépendance. L’écran change pour afficher l’API publique du cadre ou de la bibliothèque.

   

3. Cliquez pour développer un package et afficher la liste des méthodes disponibles.

4. Cliquez sur Affichage associé à une méthode pour afficher sa définition.

   

5. Lorsque vous avez déterminé comment modéliser la méthode, définissez le « Type de modèle ».

6. Les champs restants de cette ligne sont mis à jour avec les options disponibles pour le type de modèle choisi :

   • « Source » : choisissez l’élément « Sortie » à modéliser.
   • « Récepteur » : choisissez l’élément « Entrée » à modéliser.
   • « Résumé du flux » : choisissez les éléments « Entrée » et « Sortie » pour modéliser.

7. Définissez le « Type » de flux de données pour le modèle.

8. Une fois la modélisation terminée, cliquez surEnregistrer tout ou Enregistrer (affiché en bas à droite de chaque liste développée de méthodes). Le pourcentage d’appels modélisés dans l’éditeur est mis à jour.

Les modèles sont stockés dans votre espace de travail sur .github/codeql/extensions/CODEQL-MODEL-PACK, où CODEQL-MODEL-PACK est le nom de la base de données CodeQL que vous avez sélectionnée. Autrement dit, le nom du référentiel, trait d’union, la langue analysée par CodeQL. Pour plus d’informations, consultez « Création et utilisation de packs CodeQL ».

Les modèles sont stockés dans une série de fichiers d’extension de données YAML, un pour chaque méthode publique. Par exemple :

.github/codeql/extensions/sofa-jraft-java          # the model pack directory
    models
        com.alipay.sofa.jraft.option.model.yml # models public methods in package
        com.alipay.sofa.jraft.rhea.options.model.yml

L’éditeur crée un fichier de modèle distinct pour chaque package que vous modélisez.

Méthodes de modélisation avec plusieurs flux potentiels

Certaines méthodes prennent en charge plusieurs flux de données. Il est important de modéliser tous les flux de données pour une méthode ; sinon, vous ne pouvez pas détecter tous les problèmes potentiels associés à l’utilisation de la méthode. Tout d’abord, vous modélisez un flux de données pour la méthode, puis utilisez le bouton + dans la ligne de méthode pour spécifier un deuxième modèle de flux de données.

Tests des packs de modèles CodeQL dans VS Code

Vous pouvez tester les packs de modèles CodeQL que vous créez dans VS Code avec le paramètre « Requêtes en cours d’exécution : Utiliser les packs d’extension ». Pour plus d’informations, consultez « Personnaliser les paramètres ». Cette méthode fonctionne à la fois pour les bases de données et pour les référentiels d’analyse de variantes.

• Pour exécuter des requêtes sur une base de données CodeQL avec tous les packs de modèles stockés dans le répertoire .github/codeql/extensions de l’espace de travail, mettez à jour votre fichier settings.json avec : "codeQL.runningQueries.useExtensionPacks": "all",

• Pour exécuter des requêtes sur une base de données CodeQL sans utiliser de packs de modèles, mettez à jour votre fichier settings.json avec : "codeQL.runningQueries.useExtensionPacks": "none",

Si votre modèle fonctionne correctement, vous devez voir une différence dans les résultats des deux exécutions différentes. Si vous ne voyez aucune différence dans les résultats, vous devrez peut-être introduire un bogue connu pour vérifier que le modèle se comporte comme prévu.

Pour aller plus loin

• Modification de la configuration d’installation par défaut

• Personnalisation de votre configuration avancée pour l’analyse du code