Exécuter l’analyse CodeQL sur le code du pilote Windows

CodeQL est un puissant moteur d’analyse statique qui aide les développeurs à identifier les vulnérabilités de sécurité et les violations de code dans le code source du pilote Windows. Cet article explique comment utiliser l’analyse CodeQL pour créer une certification WHCP (Driver Verification File for Windows Hardware Compatibility Program).

Dans cet article, vous découvrirez comment :

• Installez la version CodeQL appropriée.
• Installez les packages CodeQL et les suites de requêtes nécessaires.
• Exécutez CodeQL pour générer une base de données et analyser votre code.
• Générez un fichier de vérification de pilote.

Sélectionnez la version CodeQL appropriée pour votre pilote

Sélectionnez l’onglet de votre scénario :

Télécharger et installer CodeQL

1. Créez un répertoire pour contenir CodeQL. Cet exemple utilise C:\codeql-home\

   C:\> mkdir C:\codeql-home
   

2. Reportez-vous aux tables précédentes pour sélectionner la version de l’interface CLI CodeQL à utiliser conformément à la branche souhaitée des requêtes de pilotes de Microsoft. Si vous effectuez une analyse dans le cadre du programme WHCP, reportez-vous au tableau Pour l’utilisation du programme de compatibilité matérielle Windows, sinon utilisez la branche principale et la version 2.15.4. L’utilisation d’une autre version peut entraîner l’incompatibilité d’une base de données avec les bibliothèques.

3. Accédez à la version binaire de l’interface CLI CodeQL associée aux tables précédentes, puis téléchargez le fichier zip conformément à l’architecture de votre projet. Par exemple, pour Windows 64 bits codeql-win64.zip.

4. Extrayez le répertoire CLI Codeql dans celui que vous venez de créer, par exemple : C :\codeql-home\codeql\codeql\.

5. Vérifiez que CodeQL est installé correctement en vérifiant la version :

    C:\codeql-home\codeql>codeql --version
    CodeQL command-line toolchain release 2.15.4.
    Copyright (C) 2019-2023 GitHub, Inc.
    Unpacked in: C:\codeql-home\codeql
        Analysis results depend critically on separately distributed query and
        extractor modules. To list modules that are visible to the toolchain,
        use 'codeql resolve qlpacks' and 'codeql resolve languages'.
   

Utilisation de l’aide de CodeQL

C:\codeql-home\codeql\>codeql --help
Usage: codeql <command> <argument>...
Create and query CodeQL databases, or work with the QL language.

GitHub makes this program freely available for the analysis of open-source software and certain other uses, but it is
not itself free software. Type codeql --license to see the license terms.

      --license              Show the license terms for the CodeQL toolchain.
Common options:
  -h, --help                 Show this help text.
  -v, --verbose              Incrementally increase the number of progress messages printed.
  -q, --quiet                Incrementally decrease the number of progress messages printed.
Some advanced options have been hidden; try --help -v for a fuller view.
Commands:
  query     Compile and execute QL code.
  bqrs      Get information from .bqrs files.
  database  Create, analyze and process CodeQL databases.
  dataset   [Plumbing] Work with raw QL datasets.
  test      Execute QL unit tests.
  resolve   [Deep plumbing] Helper commands to resolve disk locations etc.
  execute   [Deep plumbing] Low-level commands that need special JVM options.
  version   Show the version of the CodeQL toolchain.
  generate  Generate formatted QL documentation.

Pour obtenir de l’aide sur une commande spécifique, exécutez la commande< codeql >--help. Par exemple:

codeql create --help

Pour obtenir de l'aide pour les sous-commandes, listez-les de manière hiérarchique, par exemple

codeql create language --help

Installer les packages CodeQL

Sélectionnez l’onglet de votre environnement de build :

C:\codeql-home\> codeql pack download microsoft/windows-drivers@<version>

C:\codeql-home\> codeql pack download microsoft/windows-drivers@1.1.0

C:\codeql-home\> codeql pack download microsoft/cpp-queries@0.9.0

C:\codeql-home\codeql> codeql database create D:\DriverDatabase --language=cpp --source-root=D:\Drivers\SingleDriver --command="msbuild /t:rebuild D:\Drivers\SingleDriver\SingleDriver.sln"

C:\codeql-home\codeql> codeql database create D:\SampleDriversDatabase --language=cpp --source-root=D:\AllMyDrivers\SampleDrivers --command=D:\AllMyDrivers\SampleDrivers\BuildAllSampleDrivers.cmd

Afficher et interpréter les résultats

Nous allons nous concentrer sur le format SARIF pour cette section, car c’est ce qui est nécessaire pour les étapes suivantes, bien que vous soyez invité à utiliser le format CSV s’il convient mieux à vos besoins.

Le format SARIF (Static Analysis Results Interchange Format) est un format de type JSON utilisé pour partager les résultats d’analyse statique. En savoir plus sur la norme au format OASIS (Static Analysis Results Interchange Format - SARIF), comment CodeQL utilise la sortie SARIF et le schéma JSON.

Il existe plusieurs méthodes pour interpréter les résultats d’analyse, notamment trier manuellement les objets. Voici quelques-uns que nous utilisons :

• Microsoft Sarif Viewer (Web) dispose de fonctionnalités qui vous permettent de faire glisser et déposer votre fichier SARIF dans la visionneuse, puis affiche les résultats classés par règle. Il s’agit d’un moyen très rapide et facile de voir le nombre de violations ou les requêtes qui ont des violations, mais moins facile à trouver des informations de code source en dehors du numéro de ligne. Notez que la page ne sera pas mise à jour s’il n’y a aucune violation.

• Microsoft SARIF Viewer pour Visual Studio est idéal pour afficher les résultats dans Visual Studio pour une transition transparente des résultats vers le code source.

• L’extension SARIF pour Visual Studio Code ouvre un volet d’aperçu et affiche les erreurs, avertissements ou problèmes signalés par CodeQL. Pour afficher le fichier Sarif dans un format lisible, ouvrez le fichier dans Visual Studio Code et sélectionnez Maj-Alt-F.

La section la plus importante du fichier SARIF est la Results propriété dans l’objet Run . Chaque requête aura une propriété Results avec des détails sur les violations détectées et l’emplacement où elle s’est produite. Si aucune violation n’est trouvée, la valeur de la propriété est vide.

Les requêtes sont classées à l’aide d’états tels que l’erreur, l’avertissement et leproblème. Toutefois, cette classification est distincte de la façon dont le programme de compatibilité matérielle Windows et le test du logo Static Tools classent les résultats. Tout pilote présentant des défauts de toute requête dans la suite Must-Fixne passe pas le test du logo Static Tools et ne sera pas certifié, quelle que soit la classification de requête dans le fichier de requête brut (par exemple, avertissement).

Convertir SARIF au format du journal de vérification du pilote (DVL)

Le test du logo Static Tools analyse un journal de vérification de pilote (DVL), qui est le résultat compilé de l’analyse statique CodeQL que vous exécutez sur le code source du pilote. Il existe trois façons de convertir votre fichier SARIF au format DVL : Visual Studio, MSBuild ou à partir de la ligne de commande à l’aide de l’outil dvl.exe . Pour connaître les étapes complètes, consultez Création d’un journal de vérification de pilote.

Vous trouverez d’autres instructions pour le test HLK du logo des outils statiques et des informations sur l'emplacement du fichier DVL dans Exécuter le test du logo des outils statiques.

Troubleshooting

Si vous effectuez une certification avec WHCP, vérifiez d’abord que vous utilisez la version HLK associée à la version Windows que vous ciblez, la branche associée dans le référentiel Outils supplémentaires pour les développeurs windows et la version CLI CodeQL suivante. Pour obtenir la matrice de compatibilité de la version HLK/Windows, consultez le Kit de laboratoire matériel Windows et, quant à Windows Release/Windows Driver Developer Supplemental Tools branch/version de la CLI CodeQL, consultez le tableau WHCP dans la section Sélectionner la version CodeQL.

Erreurs et solutions de contournement

Pour les problèmes d’incompatibilité de version de base de données , les outils suivants peuvent être utiles.

Utilisez la commande de version codeql pour afficher la version de l’exe codeql.

C:\codeql-home\codeql\>codeql version
CodeQL command-line toolchain release 2.4.0.
Copyright (C) 2019-2020 GitHub, Inc.
Unpacked in: C:\codeql-home\codeql\
   Analysis results depend critically on separately distributed query and
   extractor modules. To list modules that are visible to the toolchain,
   use 'codeql resolve qlpacks' and 'codeql resolve languages'.

La commande de mise à niveau de la base de données met à jour une base de données. Sachez qu’il s’agit d’une mise à niveau unidirectionnel et n’est pas réversible. Pour plus d’informations, consultez la mise à niveau de la base de données.

Procédures facultatives

Si vous le souhaitez, vous pouvez supprimer les résultats CodeQL ou exécuter les procédures de génération et d’analyse en tant qu’événement post build dans Visual Studio.

Suppression des résultats CodeQL

CodeQL pour les pilotes prend en charge la fonctionnalité de suppression des résultats. Les suppressions sont actuellement offertes comme une commodité pour aider les développeurs à trier les problèmes et à réduire le bruit, et non pas pour contourner les vérifications Must-Fix. Ils n'ont aucun impact sur la génération d'un journal de vérification de pilote ou la réussite du test Static Tools Logo pour l'instant. Pour utiliser des suppressions, vous devez exécuter la requête DriverAlertSuppression.ql en même temps que les autres requêtes ou suites que vous souhaitez exécuter. Par défaut, cette requête est activée lors de l’exécution de nos suites à partir de notre branche principale/développement githubs.

Pour les vérifications qui ont été transférées à partir de l’analyse du code, les suppressions d’analyse du code existantes seront respectées. Pour plus d’informations, consultez pragma d’avertissement C++.

• Known limitation: Vous ne pouvez pas combiner une #pragma(désactiver) et #pragma(supprimer) dans la même ligne pour l’instant.

Pour les vérifications nouvelles de CodeQL, supprimez-les en effectuant l’une des deux opérations suivantes :

• Écrivez une #pragma(suppress:the-rule-id-here) annotation (sans guillemets) sur la ligne au-dessus de la violation, comme vous le faites pour l’analyse du code. Remplacez « the-rule-id-here » par la valeur de @id des métadonnées de la requête, visible en haut du fichier.

• Écrivez un commentaire sur la ligne ci-dessus comprenant le texte « lgtm[the-rule-id-here] » (guillemets moins). Vous devez exécuter la requête de suppression d’alerte C/C++ standard au lieu de la requête de suppression d’alerte de pilote.

Une fois qu’une suppression est présente et reconnue, le fichier SARIF résultant inclut les données qu’un résultat a été supprimé, et la plupart des visionneuses de résultats n’affichent pas le résultat par défaut.

Événement Post-construction de Visual Studio

Si vous générez le pilote à l’aide de Visual Studio, vous pouvez configurer des requêtes CodeQL pour qu’elles s’exécutent en tant qu’événement post build.

Dans cet exemple, un petit fichier de commandes est créé à l’emplacement cible et appelé en tant qu’événement post-build. Pour plus d’informations sur les événements de build Visual Studio C++, consultez Spécification d’événements de génération.

1. Créez un petit fichier de commandes qui recrée la base de données CodeQL, puis exécute les requêtes souhaitées dessus. Dans cet exemple, le fichier batch sera nommé RunCodeQLRebuildQuery.bat. Modifiez les chemins d’accès indiqués dans l’exemple de fichier batch pour qu’ils correspondent à vos emplacements de répertoire.

   ECHO ">>> Running CodeQL Security Rule V 1.0 <<<"
   ECHO ">>> Removing previously created rules database <<<"
   rmdir /s/q C:\codeql-home\databases\kmdf
   CALL C:\codeql-home\codeql\codeql\codeql.cmd database create -l=cpp -s="C:\codeql-home\drivers\kmdf" -c "msbuild /p:Configuration=Release /p:Platform=x64 C:\codeql-home\drivers\kmdf\kmdfecho.sln /t:rebuild /p:PostBuildEventUseInBuild=false " "C:\codeql-home\databases\kmdf" -j 0
   CALL C:\codeql-home\codeql\codeql\codeql database analyze "C:\codeql-home\databases\kmdf" "<path to query suite .qls file>" --format=sarifv2.1.0 --output=C:\codeql-home\databases\kmdf.sarif -j 0 --rerun
   ECHO ">>> Loading SARIF Results in Visual Studio <<<"
   CALL devenv /Edit C:\codeql-home\databases\kmdf.sarif
   SET ERRORLEVEL = 0
   

2. L’option devenv.exe /Edit est utilisée dans le fichier batch pour ouvrir le fichier de résultats SARIF dans l’instance existante de Visual Studio. Pour afficher les résultats de SARIF, installez Microsoft SARIF Viewer pour Visual Studio et reportez-vous aux instructions ci-dessous pour plus d’informations.

3. Dans le projet de pilote, accédez aux propriétés du projet. Dans la liste déroulante Configuration, sélectionnez la configuration de compilation que vous souhaitez vérifier avec CodeQL. Nous vous recommandons de choisir Release. La création de la base de données CodeQL et l’exécution des requêtes prend quelques minutes. Nous vous déconseillons donc d’exécuter CodeQL sur la configuration de débogage de votre projet.

4. Sélectionnez Événements de génération et événement post-génération dans les propriétés du projet de driver.

5. Fournissez un chemin d’accès au fichier batch et une description de l’événement post build.

1. Les résultats du fichier batch s’affichent à la fin de la sortie de build.

   1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\MistypedFunctionArguments.ql.
   1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\TooManyArguments.ql.
   1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\TooFewArguments.ql.
   1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\ImplicitFunctionDeclaration.ql.
   1>[1/4 eval 4.4s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\TooManyArguments.bqrs.
   1>[2/4 eval 4.4s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\TooFewArguments.bqrs.
   1>[3/4 eval 4.5s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\ImplicitFunctionDeclaration.bqrs.
   1>[4/4 eval 5.2s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\MistypedFunctionArguments.bqrs.
   1>Shutting down query evaluator.
   1>Interpreting results.
   1>">>> Loading SARIF Results in Visual Studio <<<"
   

Contenu connexe

• CodeQL FAQ
• Vue d’ensemble de CodeQL
• Requêtes et suites CodeQL