CodeQL traite le code comme des données. Vous créez une base de données en extrayant des données interrogeables à partir de votre base de code. Ensuite, vous pouvez exécuter des requêtes CodeQL sur cette base pour identifier des vulnérabilités de sécurité, des bogues et d’autres erreurs. Vous pouvez écrire vos propres requêtes ou utiliser celles fournies par les chercheurs de GitHub et la communauté.

Dans cette unité, vous apprendrez à créer une base de données. Cette étape est nécessaire avant de pouvoir analyser votre code. Vous devez créer une base de données CodeQL contenant toutes les données nécessaires à l’exécution de requêtes sur votre code.

L’analyse CodeQL repose sur l’extraction de données relationnelles à partir de votre code pour construire une base de données CodeQL. Ces bases contiennent toutes les informations importantes sur une base de code.

Vous pouvez utiliser l’outil en ligne de commande CodeQL (CLI) pour analyser le code et générer une représentation en base de données. Une fois la base prête, vous pouvez l’interroger ou exécuter une suite de requêtes pour générer un ensemble de résultats au format SARIF (Static Analysis Results Interchange Format).

Préparation de la base de données pour CodeQL

Avant de générer une base de données CodeQL, vous devez installer et configurer le CLI CodeQL. Ensuite, vous devez récupérer la version du code que vous souhaitez analyser.

• Pour les langages compilés, le répertoire doit être prêt à être compilé, avec toutes les dépendances installées. CodeQL commence par extraire une représentation relationnelle de chaque fichier source pour créer la base de données.
• Pour les langages interprétés, l’extracteur s’exécute directement sur le code source, ce qui permet une représentation précise de la base de code et la résolution des dépendances.

L’extraction des fichiers source fonctionne en surveillant le processus de compilation normal. CodeQL copie chaque fichier source à chaque fois que le compilateur est invoqué, collectant toutes les informations pertinentes.

Configuration du CLI

Voici les étapes pour configurer le CLI CodeQL :

1. Télécharger l’archive .zip du bundle CodeQL CLI
   Il est recommandé de télécharger le bundle complet (CLI + requêtes) pour garantir la compatibilité et de meilleures performances.
   Le bundle contient : le CLI CodeQL, des versions compatibles des requêtes et bibliothèques du dépôt GitHub CodeQL, et des versions précompilées des requêtes incluses.
   • Allez sur la page des versions (Releases) du dépôt public CodeQL.
   • Téléchargez le bundle spécifique à votre plateforme sous la section Assets.
   • Vous pouvez aussi télécharger codeql-bundle.tar.gz pour toutes les plateformes.
2. Extraire l’archive .zip
   Sous Linux, Windows ou macOS, extrayez l’archive dans le répertoire de votre choix.
   Les utilisateurs de macOS Catalina (ou version ultérieure) doivent suivre des étapes supplémentaires (voir la documentation CodeQL).
3. Exécuter les processus CodeQL
   Après extraction, vous pouvez :
   • Exécuter <chemin-extraction>/codeql/codeql
   • Ou ajouter <chemin-extraction>/codeql à votre variable d’environnement PATH pour exécuter simplement codeql.

Vérification de la configuration du CLI

• Exécutez codeql resolve packs (ou le chemin complet si non ajouté au PATH) pour afficher les packs CodeQL disponibles.
• Exécutez codeql resolve languages pour voir les langages pris en charge par défaut.

Création de la base de données

Créez une base de données CodeQL en exécutant cette commande depuis la racine du projet cloné :

codeql database create <database> --language=<language-identifier>

codeql database create <database> --language=<language-identifier>

Dans la commande :

• Remplacez <database> par le chemin vers la nouvelle base de données à créer.
• Remplacez <language-identifier> par l’identifiant du langage que vous utilisez pour créer la base. Vous pouvez utiliser cet identifiant avec --db-cluster pour accepter une liste séparée par des virgules, ou le spécifier plusieurs fois.

Vous pouvez également spécifier les options suivantes, selon l’emplacement des fichiers sources, si votre code doit être compilé, ou si vous souhaitez créer des bases CodeQL pour plusieurs langages :

• Utilisez --source-root pour indiquer le dossier racine des fichiers sources principaux pour la création de la base.
• Utilisez --db-cluster pour les bases de code multilingues lorsque vous souhaitez créer des bases pour plusieurs langages.
• Utilisez --command lorsque vous créez une base pour un ou plusieurs langages compilés. Cette option n’est pas nécessaire si vous utilisez uniquement Python ou JavaScript.
• Utilisez --no-run-unnecessary-builds avec --db-cluster pour éviter d’exécuter la commande de compilation pour les langages où le CLI CodeQL n’a pas besoin de surveiller la compilation.

Après avoir créé la base avec succès, un nouveau répertoire apparaît à l’emplacement spécifié dans la commande. Si vous avez utilisé l’option --db-cluster pour créer plusieurs bases, un sous-répertoire est créé pour chaque langage.

Chaque répertoire de base de données CodeQL contient plusieurs sous-dossiers, y compris les données relationnelles utilisées pour l’analyse et une archive source. Cette archive est une copie des fichiers source au moment de la création de la base, utilisée par CodeQL pour afficher les résultats d’analyse.

Extracteurs

Un extracteur est un outil qui produit les données relationnelles et les références aux sources pour chaque fichier d’entrée, à partir desquels une base CodeQL peut être construite. Chaque langage pris en charge par CodeQL possède son propre extracteur, ce qui garantit une extraction aussi précise que possible.

Chaque extracteur définit son propre ensemble d’options de configuration.
L’exécution de la commande suivante :

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

Pour connaître les options disponibles pour l’extracteur de votre langage

Exécutez l’une des commandes suivantes :

codeql resolve languages –format=betterjson ou codeql resolve extractor –format=betterjson

Le format de sortie betterjson fournit également le chemin racine de l’extracteur ainsi que d’autres options spécifiques au langage.

Données dans une base de données CodeQL

Une base de données CodeQL est un répertoire unique contenant toutes les données nécessaires à l’analyse. Ces données incluent :

• des données relationnelles,
• une copie des fichiers source,
• un schéma de base de données spécifique au langage, qui définit les relations entre les données.

CodeQL importe ces données après l’extraction.

Les bases de données CodeQL offrent une vue instantanée des données interrogeables d’un langage, extraites d’une base de code. Ces données représentent de manière hiérarchique l’ensemble du code, y compris :

• l’arbre de syntaxe abstraite (AST),
• le graphe de flux de données,
• le graphe de flux de contrôle.

Pour les bases de code multilingues, les bases sont générées langage par langage, chacune avec son propre schéma. Le schéma sert d’interface entre l’analyse lexicale initiale et l’analyse complexe effectuée par CodeQL.

Une base de données CodeQL contient deux tables principales :

• expressions : une ligne pour chaque expression analysée dans le code source.
• statements : une ligne pour chaque instruction analysée dans le code source.

La bibliothèque CodeQL définit des classes qui fournissent une couche d’abstraction au-dessus de ces tables, notamment les tables auxiliaires Expr et Stmt.

Limitations potentielles de CodeQL

La création de base de données dans le cadre de l’analyse de code (code scanning) peut présenter certaines limites, notamment avec l’action GitHub CodeQL.

• Vous devez utiliser une matrice de langages pour que l’autobuild compile chaque langage compilé listé. Cela permet de créer des jobs pour plusieurs versions d’un langage, système d’exploitation ou outil.
• Sans matrice, autobuild tente de compiler le langage compilé avec le plus de fichiers source. Cela échoue souvent (sauf pour Go) si vous ne fournissez pas de commande explicite de compilation avant l’analyse.
• Le comportement de l’étape autobuild varie selon le système d’exploitation. Elle tente de détecter automatiquement une méthode de compilation, ce qui peut entraîner des résultats peu fiables, voire des échecs.

Recommandation : configurez une étape de compilation dans votre fichier de workflow avant l’analyse, au lieu de laisser autobuild compiler automatiquement. Cela rend l’analyse plus fiable et adaptée à votre projet.

Vous pouvez consulter la documentation de CodeQL sur autobuild pour plus de détails selon les langages.

Extension VS Code

Vous pouvez utiliser Visual Studio Code (version 1.39 ou plus récente) avec l’extension CodeQL pour compiler et exécuter des requêtes.

L’extension utilise le CLI installé (s’il est dans le PATH). Sinon, elle gère automatiquement l’accès à l’exécutable, garantissant la compatibilité avec l’extension.
Téléchargez l’extension depuis le Visual Studio Code Marketplace ou via le fichier CodeQL VSIX.