Création de bases de données CodeQL

À propos de la création de bases de données CodeQL

Avant d’analyser votre code avec CodeQL, 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. Vous pouvez créer vous-même des bases de données CodeQL avec CodeQL CLI, ou les télécharger depuis GitHub.com.

L’analyse CodeQL repose sur l’extraction de données relationnelles de votre code et sur leur utilisation pour créer une base de données CodeQL. Les bases de données CodeQL contiennent toutes les informations importantes relatives à un codebase, qui peuvent être analysées en exécutant des requêtes CodeQL dessus. GitHub crée et stocke des bases de données CodeQL pour un grand nombre de projets open source. Pour plus d’informations, consultez « Téléchargement des bases de données CodeQL à partir de GitHub.com ».

Vous pouvez également créer vous-même des bases de données CodeQL avec CodeQL CLI. Avant de générer une base de données CodeQL, vous devez :

• Installer et configurer CodeQL CLI Pour plus d’informations, consultez « Bien démarrer avec CodeQL CLI ».
• Vérifiez la version de votre codebase que vous souhaitez analyser. Le répertoire doit être prêt à être généré, avec toutes les dépendances déjà installées.

Pour plus d’informations sur l’utilisation de CodeQL CLI dans un système CI tiers pour créer des résultats à afficher dans GitHub en tant qu’alertes d’analyse du code, consultez Configuration de CodeQL CLI dans votre système CI. Pour plus d’informations sur l’activation de l’analyse du code CodeQL avec GitHub Actions, consultez Configuration de l’analyse du code pour un dépôt.

En cours d’exécution codeql database create

Les bases de données CodeQL sont créées en exécutant la commande suivante à partir de la racine d’extraction de votre projet :

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

Vous devez spécifier :

• <database> : chemin de la nouvelle base de données à créer. Ce répertoire est créé lorsque vous exécutez la commande. Vous ne pouvez pas spécifier de répertoire existant.
• --language : identificateur du langage pour lequel créer une base de données. Utilisée avec --db-cluster, l’option accepte une liste séparée par des virgules ou peut être spécifiée plusieurs fois. CodeQL prend en charge la création de bases de données pour les langages suivants :

Langage	Identificateur
C/C++	cpp
C#	csharp
Go	go
Java/Kotlin	java
JavaScript/TypeScript	javascript
Python	python
Ruby	ruby

Vous pouvez spécifier des options supplémentaires en fonction de l’emplacement de votre fichier source, si le code doit être compilé et si vous souhaitez créer des bases de données CodeQL pour plusieurs langages :

• --source-root : dossier racine pour les fichiers sources primaires utilisés lors de la création de la base de données Par défaut, la commande suppose que le répertoire actuel est la racine source. Utilisez cette option pour spécifier un autre emplacement.
• --db-cluster : utilisé pour les codebases multi-langages lorsque vous souhaitez créer des bases de données pour plusieurs langages.
• --command : utilisé lorsque vous créez une base de données pour un ou plusieurs langages compilés, à omettre si les seuls langages demandés sont Python et JavaScript. Cela spécifie les commandes de build nécessaires pour appeler le compilateur. Les commandes sont exécutées à partir du dossier actif, ou --source-root si spécifié. Si vous n’incluez pas de --command, CodeQL tente de détecter automatiquement le système de build à l’aide d’un générateur automatique (« autobuilder ») intégré.
• --no-run-unnecessary-builds : utilisé avec --db-cluster pour supprimer la commande de build pour les langages où CodeQL CLI n’a pas besoin de superviser la génération (par exemple, Python et JavaScript/TypeScript).

Vous pouvez spécifier des options d’extracteur pour personnaliser le comportement des extracteurs qui créent les bases de données CodeQL. Pour plus d’informations, consultez « Options d’extracteur ».

Pour des détails complets sur toutes les options que vous pouvez utiliser lors de la création de bases de données, consultez la documentation de référence sur database create.

Progression et résultats

Des erreurs sont signalées en cas de problèmes avec les options que vous avez spécifiées. Pour les langages interprétés, la progression de l’extraction s’affiche dans la console : pour chaque fichier source, elle indique si l’extraction a réussi ou si elle a échoué. Pour les langages compilés, la console affiche la sortie du système de build.

Une fois la base de données créée, vous trouverez un nouveau répertoire dans le chemin spécifié dans la commande. Si vous avez utilisé l’option --db-cluster pour créer plusieurs bases de données, un sous-répertoire est créé pour chaque langage. Chaque répertoire de base de données CodeQL contient un certain nombre de sous-répertoires, notamment les données relationnelles (requises pour l’analyse) et une archive source (une copie des fichiers sources créée au moment de la création de la base de données) qui est utilisée pour afficher les résultats de l’analyse.

Création de bases de données pour les langages non compilés

CodeQL CLI comprend des extracteurs pour créer des bases de données pour les langages non compilés, en particulier JavaScript (et TypeScript), Python et Ruby. Ces extracteurs sont appelés automatiquement lorsque vous spécifiez JavaScript, Python ou Ruby comme option --language lors de l’exécution de database create. Lorsque vous créez des bases de données pour ces langages, vous devez vous assurer que toutes les dépendances supplémentaires sont disponibles.

JavaScript et TypeScript

La création de bases de données pour JavaScript ne demande aucune dépendance supplémentaire, mais si le projet inclut des fichiers TypeScript, vous devez installer Node.js 6.x ou ultérieur. Dans la ligne de commande, vous pouvez spécifier --language=javascript pour extraire les fichiers JavaScript et TypeScript :

codeql database create --language=javascript --source-root <folder-to-extract> <output-folder>/javascript-database

Ici, nous avons spécifié un chemin --source-root, qui est l’emplacement où la création de la base de données est exécutée, mais qui n’est pas nécessairement la racine d’extraction du codebase.

Par défaut, les fichiers dans les répertoires node_modules et bower_components ne sont pas extraits.

Python

Lorsque vous créez des bases de données pour Python, vous devez vous assurer que :

• Python 3 est installé et disponible pour l’extracteur CodeQL.
• La version de Python utilisée par votre code est installée.
• Vous avez accès au système de gestion de paquets pip et vous pouvez installer tous les packages dont dépend le codebase.
• Vous avez installé le module pip virtualenv.

Dans la ligne de commande, vous devez spécifier --language=python. Par exemple :

codeql database create --language=python <output-folder>/python-database

Cette opération exécute la sous-commande database create à partir de la racine d’extraction du code, générant une nouvelle base de données Python dans <output-folder>/python-database.

Ruby

La création de bases de données pour Ruby ne demande aucune dépendance supplémentaire. Dans la ligne de commande, vous devez spécifier --language=ruby. Par exemple :

codeql database create --language=ruby --source-root <folder-to-extract> <output-folder>/ruby-database

Ici, nous avons spécifié un chemin --source-root, qui est l’emplacement où la création de la base de données est exécutée, mais qui n’est pas nécessairement la racine d’extraction du codebase.

Création de bases de données pour les langages compilés

Pour les langages compilés, CodeQL doit appeler le système de build requis pour générer une base de données. Par conséquent, la méthode de build doit être disponible pour l’interface CLI.

Détection du système de build

CodeQL CLI comprend des générateurs automatiques pour le code C/C++, C#, Go et Java. Les générateurs automatiques CodeQL vous permettent de générer des projets pour les langages compilés sans spécifier de commandes de build. Quand un générateur automatique est appelé, CodeQL examine la source pour confirmer la présence d’un système de build et tente d’exécuter le jeu optimal de commandes requises pour extraire une base de données.

Un générateur automatique est appelé automatiquement lorsque vous exécutez codeql database create pour un --language compilé si vous n’incluez pas d’option --command. Par exemple, pour un codebase Java, vous exécuteriez simplement :

codeql database create --language=java <output-folder>/java-database

Si un codebase utilise un système de build standard, s’appuyer sur un générateur automatique est souvent le moyen le plus simple de créer une base de données. Pour les sources qui demandent des étapes de génération non standard, vous devrez peut-être définir explicitement chaque étape dans la ligne de commande.

Spécification des commandes de build

Les exemples suivants sont conçus pour vous donner une idée de quelques commandes de build que vous pouvez spécifier pour les langages compilés.

• Projet C/C++ généré avec make :

  CodeQL database create cpp-database --language=cpp --command=make
  

• Projet C# généré avec dotnet build :

  Il est judicieux d’ajouter /t:rebuild pour vous assurer que tout le code sera généré ou d’effectuer un dotnet clean avant (le code qui n’est pas généré ne sera pas inclus dans la base de données CodeQL) :

  CodeQL database create csharp-database --language=csharp --command='dotnet build /t:rebuild'
  

• Projet Go généré avec la variable d’environnement CODEQL_EXTRACTOR_GO_BUILD_TRACING=on :

  CODEQL_EXTRACTOR_GO_BUILD_TRACING=on CodeQL database create go-database --language=go
  

• Projet Go généré avec un script de build personnalisé :

  CodeQL database create go-database --language=go --command='./scripts/build.sh'
  

• Projet Java généré avec Gradle :

  # Use `--no-daemon` because a build delegated to an existing daemon cannot be detected by CodeQL: CodeQL database create java-database --language=java --command='gradle --no-daemon clean test'
  

• Projet Java généré avec Maven :

  CodeQL database create java-database --language=java --command='mvn clean install'
  

• Projet Java généré avec Ant :

  CodeQL database create java-database --language=java --command='ant -f build.xml'
  

• Projet généré avec Bazel :

  # Navigate to the Bazel workspace.
  
  # Before building, remove cached objects
  # and stop all running Bazel server processes.
  bazel clean --expunge
  
  # Build using the following Bazel flags, to help CodeQL detect the build:
  # `--spawn_strategy=local`: build locally, instead of using a distributed build
  # `--nouse_action_cache`: turn off build caching, which might prevent recompilation of source code
  # `--noremote_accept_cached`, `--noremote_upload_local_results`: avoid using a remote cache
  CodeQL database create new-database --language=<language> \
  --command='bazel build --spawn_strategy=local --nouse_action_cache --noremote_accept_cached --noremote_upload_local_results //path/to/package:target'
  
  # After building, stop all running Bazel server processes.
  # This ensures future build commands start in a clean Bazel server process
  # without CodeQL attached.
  bazel shutdown
  

• Projet généré avec un script de build personnalisé :

  CodeQL database create new-database --language=<language> --command='./scripts/build.sh'
  

Cette commande exécute un script personnalisé qui contient toutes les commandes requises pour générer le projet.

Utilisation du traçage de build indirect

Si les générateurs automatiques CodeQL CLI pour les langages compilés ne fonctionnent pas avec votre workflow CI et que vous ne pouvez pas wrapper les appels de commandes de build avec codeql database trace-command, vous pouvez utiliser le traçage de build indirect pour créer une base de données CodeQL. Pour utiliser le traçage de build indirect, votre système CI doit être en mesure de définir des variables d’environnement personnalisées pour chaque action de génération.

Pour créer une base de données CodeQL avec le traçage de build indirect, exécutez la commande suivante à partir de la racine d’extraction de votre projet :

codeql database init ... --begin-tracing <database>

Vous devez spécifier :

• <database> : chemin de la nouvelle base de données à créer. Ce répertoire est créé lorsque vous exécutez la commande. Vous ne pouvez pas spécifier de répertoire existant.
• --begin-tracing : crée des scripts qui peuvent être utilisés pour configurer un environnement dans lequel les commandes de build seront tracées.

Vous pouvez spécifier d’autres options pour la commande codeql database init comme d’habitude.

La commande codeql database init génère un message :

Created skeleton <database>. This in-progress database is ready to be populated by an extractor. In order to initialise tracing, some environment variables need to be set in the shell your build will run in. A number of scripts to do this have been created in <database>/temp/tracingEnvironment. Please run one of these scripts before invoking your build command.

Based on your operating system, we recommend you run: ...

La commande codeql database init crée <database>/temp/tracingEnvironment avec des fichiers qui contiennent des variables d’environnement et des valeurs qui permettent à CodeQL de tracer une séquence d’étapes de génération. Ces fichiers sont appelés start-tracing.{json,sh,bat,ps1}. Utilisez l’un de ces fichiers avec le mécanisme de votre système CI afin de définir les variables d’environnement pour les étapes futures. Vous pouvez :

• Lisez le fichier JSON, traitez-le et affichez les variables d’environnement au format attendu par votre système CI. Par exemple, Azure DevOps attend echo "##vso[task.setvariable variable=NAME]VALUE".
• Ou, si votre système CI conserve l’environnement, sourcez le script start-tracing approprié pour définir les variables CodeQL dans l’environnement shell du système CI.

Générez votre code, et annulez si vous voulez les variables d’environnement à l’aide d’un script end-tracing.{json,sh,bat,ps1} du répertoire où les scripts start-tracing sont stockés, puis exécutez la commande codeql database finalize <database>.

Une fois que vous avez créé une base de données CodeQL à l’aide du traçage de build indirect, vous pouvez l’utiliser comme n’importe quelle autre base de données CodeQL. Par exemple, analysez la base de données et chargez les résultats dans GitHub si vous utilisez l’analyse du code.

Exemple de création d’une base de données CodeQL à l’aide du traçage de build indirect

L’exemple suivant montre comment vous pourriez utiliser le traçage de build indirect dans un pipeline Azure DevOps pour créer une base de données CodeQL :

steps:
    # Download the CodeQL CLI and query packs...
    # Check out the repository ...

    # Run any pre-build tasks, for example, restore NuGet dependencies...

    # Initialize the CodeQL database.
    # In this example, the CodeQL CLI has been downloaded and placed on the PATH.
    - task: CmdLine@1
       displayName: Initialize CodeQL database
      inputs:
          # Assumes the source code is checked out to the current working directory.
          # Creates a database at `<current working directory>/db`.
          # Running on Windows, so specifies a trace process level.
          script: "codeql database init --language csharp --trace-process-name Agent.Worker.exe --source-root . --begin-tracing db"

    # Read the generated environment variables and values,
    # and set them so they are available for subsequent commands
    # in the build pipeline. This is done in PowerShell in this example.
    - task: PowerShell@1
       displayName: Set CodeQL environment variables
       inputs:
          targetType: inline
          script: >
             $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/start-tracing.json | ConvertFrom-Json
             $json.PSObject.Properties | ForEach-Object {
                 $template = "##vso[task.setvariable variable="
                 $template += $_.Name
                 $template += "]"
                 $template += $_.Value
                 echo "$template"
             }

    # Execute the pre-defined build step. Note the `msbuildArgs` variable.
    - task: VSBuild@1
        inputs:
          solution: '**/*.sln'
          msbuildArgs: /p:OutDir=$(Build.ArtifactStagingDirectory)
          platform: Any CPU
          configuration: Release
          # Execute a clean build, in order to remove any existing build artifacts prior to the build.
          clean: True
       displayName: Visual Studio Build

    # Read and set the generated environment variables to end build tracing. This is done in PowerShell in this example.
    - task: PowerShell@1
       displayName: Clear CodeQL environment variables
       inputs:
          targetType: inline
          script: >
             $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/end-tracing.json | ConvertFrom-Json
             $json.PSObject.Properties | ForEach-Object {
                 $template = "##vso[task.setvariable variable="
                 $template += $_.Name
                 $template += "]"
                 $template += $_.Value
                 echo "$template"
             }

    - task: CmdLine@2
       displayName: Finalize CodeQL database
       inputs:
          script: 'codeql database finalize db'

    # Other tasks go here, for example:
    # `codeql database analyze`
    # then `codeql github upload-results` ...

Téléchargement des bases de données à partir de GitHub.com

GitHub stocke les bases de données CodeQL pour plus de 200 000 dépôts sur GitHub.com, que vous pouvez télécharger à l’aide de l’API REST. La liste des dépôts s’allonge et évolue constamment pour s’assurer qu’elle inclut les codebases les plus intéressants pour la recherche sur la sécurité.

Vous pouvez vérifier si un dépôt a des bases de données CodeQL disponibles en téléchargement à l’aide du point de terminaison /repos/<owner>/<repo>/code-scanning/codeql/databases. Par exemple, pour rechercher des bases de données CodeQL avec GitHub CLI, vous devez exécuter :

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/

Cette commande retourne des informations sur toutes les bases de données CodeQL disponibles dans un dépôt, y compris le langage que représente la base de données et la date de la dernière mise à jour de la base de données. Si aucune base de données CodeQL n’est disponible, la réponse est vide.

Une fois que vous avez confirmé qu’une base de données CodeQL existe pour le langage qui vous intéresse, vous pouvez la télécharger en utilisant la commande suivante :

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

Pour plus d’informations, consultez la documentation pour Obtenir un point de terminaison de base de données CodeQL.

Avant d’exécuter une analyse avec CodeQL CLI, vous devez décompresser les bases de données.

Pour aller plus loin

• « Analyse de vos projets dans CodeQL pour VS Code »