Utiliser l'éditeur de modèles CodeQL

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

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

Pour plus d’informations sur la personnalisation de l’analyse code scanning avec des packs de modèles, consultez Modification de la configuration d’installation par défaut et Options de configuration de flux de travail pour l’analyse du code.

Lorsque vous ouvrez l’éditeur de modèle, il analyse la base de données actuellement sélectionnée CodeQL 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 CodeQL base de données que vous avez sélectionnée.

L'éditeur de modèles dispose de 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 sélectionnée CodeQL . Lorsque vous développez un framework, 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 à travers chaque appel. Ce mode est plus utile pour améliorer les CodeQL résultats d’une base de code spécifique.
  

•         **Mode dépendance :** L’éditeur identifie toutes les API accessibles publiquement dans la base de données sélectionnée CodeQL . Cet affichage vous guide dans la modélisation de chaque API publique mise à disposition par la base de code. Lorsque 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 de toutes les bases de code qui utilisent la dépendance.
  

Le reste de cet article aborde les aspects pratiques de la modélisation des dépendances à l’aide de l’éditeur de CodeQL modèle. Pour plus d’informations techniques, consultez La personnalisation des modèles de bibliothèque pour Java et Kotlin, la personnalisation des modèles de bibliothèque pour Python, la personnalisation des modèles de bibliothèque pour Ruby et la personnalisation des modèles de bibliothèque pour C# dans la CodeQL documentation du langage.

Affichage de l'éditeur de modèle CodeQL

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

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

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

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

5. L’éditeur CodeQL de modèle 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. Lorsque les requêtes de télémétrie sont terminées, les API qui ont été identifiées sont affichées dans l'éditeur.

Modéliser les appels que votre base de code effectue vers des API externes

Vous utilisez généralement cette approche lorsque vous examinez une base de code spécifique dans laquelle vous souhaitez améliorer la précision des CodeQL résultats. 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 de l’infrastructure ou de la bibliothèque n’est pas inclus dans l’analyse.

Cette section utilise un projet open source Java appelé « sofa-jraft » comme exemple. L'expérience de modélisation des appels à des 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 souhaitez améliorer la couverture 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 la base de code sélectionnée s'affiche.

   

3. Cliquez pour développer une API externe et afficher la liste des appels effectués depuis la base de code vers la dépendance externe.

   

4. Cliquez sur View associé à un appel d'API ou à une méthode pour afficher l'endroit où il est utilisé dans votre base de code.

5. Le fichier contenant le premier appel de votre base de code vers l’API est ouvert, et une CodeQL vue « Utilisation des méthodes » s’affiche dans VS Code (où les vues « Problèmes » et « Terminal » sont généralement affichées). La CodeQL vue « Utilisation des méthodes » répertorie tous les appels de votre code à l’API, regroupés par méthode. Vous pouvez parcourir 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 CodeQL vue « Modélisation des méthodes » de l’extension CodeQL . Cette modification est automatiquement répercutée dans l'éditeur de modèles 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 « Output » à modéliser.
   • « Sink » : choisissez l'élément « Input » à modéliser.
   • « Flow summary » : choisissez les éléments « Input » et « Output » à modéliser.

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

9. Lorsque vous avez terminé la modélisation, affichez l'éditeur de modèles principal et cliquez sur Save all ou Save (affichés en bas à droite de chaque liste de méthodes développée). 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, .github/codeql/extensions/CODEQL-MODEl-PACKoù CODEQL-MODEL-PACK est le nom de la CodeQL base de données 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éliser l'API publique d'une base de code

Vous utilisez généralement cette méthode lorsque vous souhaitez modéliser un framework ou une bibliothèque que votre organisation utilise dans plusieurs bases de code. Une fois que vous avez terminé la création et le test du modèle, vous pouvez publier le pack de CodeQL modèles pour que l’ensemble GitHubContainer registry de votre organisation puisse l’utiliser.

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

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

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

   

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

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

   

5. Lorsque vous avez déterminé comment modéliser la méthode, définissez le « Model type ».

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 « Output » à modéliser.
   • « Sink » : choisissez l'élément « Input » à modéliser.
   • « Flow summary » : choisissez les éléments « Input » et « Output » à modéliser.

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

8. Lorsque vous avez terminé la modélisation, cliquez sur Save all ou Save (affichés en bas à droite de chaque liste d'appels développée). Le pourcentage d'appels modélisés dans l'éditeur est mis à jour.

Les modèles sont stockés dans votre espace de travail, .github/codeql/extensions/CODEQL-MODEL-PACKoù CODEQL-MODEL-PACK est le nom de la CodeQL base de données 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éera un fichier de modèle distinct pour chaque package que vous modélisez.

Modéliser des méthodes avec plusieurs flux potentiels

Certaines méthodes prennent en charge plus d'un flux de données. Il est important de modéliser tous les flux de données d'une méthode, sinon vous ne pouvez pas détecter tous les problèmes potentiels associés à l'utilisation de la méthode. Commencez par modéliser un flux de données pour la méthode, puis utilisez le bouton + dans la ligne de la méthode pour spécifier un second modèle de flux de données.

Test des packs de modèles CodeQL dans VS Code

Vous pouvez tester les ensembles 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 « Personnalisation des 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 CodeQL base de données avec tous les packs de modèles stockés dans le .github/codeql/extensions répertoire de l’espace de travail, mettez à jour votre settings.json fichier avec : "codeQL.runningQueries.useExtensionPacks": "all",

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

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

Lectures complémentaires

•         [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup)
  

•         [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#codeql-model-packs)[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies).