CodeQL considère le code comme des données.

Vous créez une base de données en utilisant des données interrogeables extraites de votre base de code. Ensuite, vous pouvez exécuter des requêtes CodeQL sur cette base de données pour identifier des vulnérabilités de sécurité, des bugs et d’autres erreurs. Vous pouvez écrire vos propres requêtes ou exécuter des requêtes standard CodeQL rédigées par des chercheurs de GitHub et des contributeurs de 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 pour exécuter des requêtes sur votre code.

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

Vous pouvez utiliser le produit autonome CodeQL CLI pour analyser du code et générer une représentation en base de données d’une base de code. Une fois la base de données 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 CodeQL CLI. Ensuite, vous devez récupérer la version de votre base de code que vous souhaitez analyser.

• Pour les langages compilés, le répertoire doit être prêt à être compilé, avec toutes les dépendances déjà installées. CodeQL commence par extraire une représentation relationnelle de chaque fichier source dans la base de code pour créer une base de données. Vous utilisez cette base pour analyser votre code.
• Pour les langages interprétés, l’extracteur s’exécute directement sur le code source. Cette capacité vous donne une représentation précise de la base de code et résout toutes les dépendances.

L’extraction des fichiers source fonctionne en surveillant le processus de compilation normal pour les langages compilés. CodeQL fait une copie du fichier source chaque fois que vous invoquez un compilateur pour traiter un fichier source. Il collecte toutes les informations pertinentes sur le code source avec chaque fichier.

Configuration du CLI

Suivez les étapes ci-dessous pour configurer le CodeQL CLI :

1. Télécharger l’archive .zip du bundle CodeQL CLI

Il est recommandé d’installer le CodeQL CLI et les requêtes en téléchargeant le package groupé. Cette méthode garantit une meilleure compatibilité et performance, contrairement au téléchargement séparé du CLI et des requêtes.

Le package de téléchargement est une archive .zip contenant des outils, des scripts et divers fichiers spécifiques à CodeQL. Le bundle inclut : le CodeQL CLI, 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.

• Rendez-vous sur la page Releases du dépôt public CodeQL.
• Téléchargez le bundle spécifique à votre plateforme sous Assets.
• Sur cette page, vous pouvez aussi consulter les journaux de modifications et télécharger des versions antérieures. Si nécessaire, vous pouvez télécharger codeql-bundle.tar.gz, qui contient le CLI pour toutes les plateformes prises en charge.

2. Extraire l’archive .zip

Si vous utilisez Linux, Windows ou macOS, vous pouvez extraire l’archive dans le répertoire de votre choix.

Les utilisateurs de macOS Catalina (ou version ultérieure) doivent suivre des étapes supplémentaires. Pour plus d’informations, consultez la documentation CodeQL sur la prise en main du CLI.

3. Exécuter les processus CodeQL

Après extraction, effectuez l’une des actions suivantes pour utiliser le fichier exécutable codeql :

• Exécutez <extraction-root>/codeql/codeql, où <extraction-root> est le dossier dans lequel vous avez extrait le package.
• Ajoutez <extraction-root>/codeql à votre variable PATH, afin de pouvoir exécuter le fichier simplement avec codeql.

Vous pouvez maintenant exécuter des commandes CodeQL.

Vérification de la configuration du CLI

Vous pouvez exécuter des sous-commandes CodeQL CLI pour vérifier que le CLI est correctement configuré et peut analyser des bases de données :

• Exécutez codeql resolve packs (si vous avez ajouté codeql au PATH) pour afficher les packs CodeQL que le CLI peut trouver. Sinon, utilisez /extraction-root/codeql/codeql resolve packs. Cette commande affiche les noms des packs inclus dans le bundle CLI.
• Si le CLI ne trouve pas les packs pour les langages attendus, vérifiez que vous avez bien téléchargé le bundle complet et non une copie autonome du CLI.
• Exécutez codeql resolve languages pour afficher les langages pris en charge par défaut par le package CLI.

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 que vous avez récupéré :

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

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

In the command:

• Replace <database> with the path to the new database to be created.
• Replace <language-identifier> with the identifier for the language that you’re using to create the database. You can use this identifier with --db-cluster to accept comma-separated lists, or you can specify it more than once.

You can also specify the following options. These options depend on the location of the source file, whether your code needs to be compiled, or whether you want to create CodeQL databases for more than one language.

• Use --source-root to identify the root folder for the primary source files for database creation.
• Use --db-cluster for multiple-language codebases when you want to create databases for more than one language.
• Use --command when you create a database for one or more compiled languages. You don’t need this option if you’re using only Python and JavaScript.
• Use --no-run-unnecessary-builds along with --db-cluster to suppress the build command for languages where the CodeQL CLI doesn’t need to monitor the build.

After you successfully create the database, a new directory appears at the path specified in the command. If you used the --db-cluster option to create more than one database, a subdirectory is created for each language.

Each CodeQL database directory contains multiple subdirectories, including the relational data that’s used for analysis and a source archive. The source archive is a copy of the source files made at the time that you created the database. CodeQL uses it for displaying analysis results.

Extractors

An extractor is a tool that produces the relational data and source reference for each input file, from which a CodeQL database can be built. Each language that CodeQL supports has one extractor. This structure ensures that the extraction process is as accurate as possible.

Each extractor defines its own set of configuration options. Entering codeql resolve extractor --format=betterjson results in data formatted like the following example:

{
    "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,

entrez la commande suivante :

codeql resolve languages --format=betterjson

codeql resolve languages --format=betterjson

ou

codeql resolve extractor --format=betterjson

codeql resolve extractor --format=betterjson

Le format de sortie betterjson fournit également la racine de l’extracteur et 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,
• des copies 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 capture instantanée des données interrogeables d’un langage particulier extraites d’une base de code. Ces données représentent une structure hiérarchique complète du code, incluant :

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

Les bases de données sont générées langage par langage pour les projets multi-langages. Chaque langage possède son propre schéma de base de données. Ce schéma sert d’interface entre l’analyse lexicale initiale (lors de l’extraction) et l’analyse complexe effectuée par CodeQL.

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

• La table expressions contient une ligne pour chaque expression dans le code source analysé pendant le processus de compilation.
• La table statements contient une ligne pour chaque instruction dans le code source analysé.

La bibliothèque CodeQL définit des classes pour fournir une couche d’abstraction au-dessus de ces tables, incluant les tables auxiliaires associées : Expr et Stmt.

Limites potentielles de CodeQL

La création de base de données dans le cadre du workflow d’analyse de code peut présenter certaines limites, notamment lors de l’utilisation de l’action GitHub CodeQL.

• Il est nécessaire d’utiliser une matrice de langages pour que autobuild puisse compiler chaque langage listé. Cette matrice permet de créer des jobs pour plusieurs versions d’un langage, système d’exploitation ou outil.
• Si vous n’utilisez pas de matrice, autobuild essaiera de compiler le langage avec le plus grand nombre de fichiers source dans le dépôt. L’analyse des langages compilés (sauf Go) échoue souvent si vous ne fournissez pas de commandes explicites pour compiler le code avant l’analyse.
• Le comportement de autobuild varie selon le système d’exploitation sur lequel l’extracteur s’exécute. Il tente de détecter automatiquement une méthode de compilation adaptée au langage, ce qui peut entraîner des résultats peu fiables, voire des échecs.

👉 Il est recommandé de configurer une étape de compilation dans le fichier de workflow avant l’analyse, plutôt que de laisser autobuild compiler les langages. Cela permet d’adapter le workflow aux exigences spécifiques de votre système et projet, pour des analyses plus fiables.

Vous pouvez consulter la documentation CodeQL sur autobuild pour en savoir plus sur les étapes spécifiques à chaque langage.

Extension VS Code

Vous pouvez utiliser Visual Studio Code (VS Code) et l’extension CodeQL pour compiler et exécuter des requêtes, à condition d’utiliser VS Code version 1.39 ou ultérieure.

• L’extension est disponible sur le Visual Studio Code Marketplace ou en téléchargeant le fichier CodeQL VSIX.
• L’extension utilise le CLI installé sur votre système (détecté via PATH) si disponible. Sinon, elle gère automatiquement l’accès au fichier exécutable du CLI. Cette gestion automatique garantit la compatibilité entre le CLI et l’extension CodeQL.