Ausführen der CodeQL-Analyse unter Windows-Treibercode

CodeQL ist ein leistungsfähiges statisches Analysemodul, das Entwicklern hilft, Sicherheitsrisiken und Codeverletzungen in Windows-Treiberquellcode zu erkennen. In diesem Artikel wird erläutert, wie Sie mithilfe der CodeQL-Analyse eine Treiberüberprüfungsdatei für die WHCP-Zertifizierung (Driver Verification File for Windows Hardware Compatibility Program) erstellen.

In diesem Artikel führen Sie folgende Schritte aus:

• Installieren Sie die entsprechende CodeQL-Version.
• Installieren Sie die erforderlichen CodeQL-Pakete und Abfragesammlungen.
• Führen Sie CodeQL aus, um eine Datenbank zu erstellen und Den Code zu analysieren.
• Erstellen Sie eine Treiberüberprüfungsdatei.

Wählen Sie die entsprechende CodeQL-Version für Ihren Treiber aus.

Wählen Sie die Registerkarte für Ihr Szenario aus:

CodeQL herunterladen und installieren

1. Erstellen Sie ein Verzeichnis, das CodeQL enthält. In diesem Beispiel wird C:\codeql-home\

   C:\> mkdir C:\codeql-home
   

2. In den vorherigen Tabellen können Sie auswählen, welche Version von CodeQL CLI entsprechend dem gewünschten Branch der Treiberabfragen von Microsoft verwendet werden soll. Wenn Sie eine Analyse als Teil des WHCP-Programms durchführen, lesen Sie die Tabelle für die Verwendung des Windows-Hardwarekompatibilitätsprogramms, andernfalls verwenden Sie "Main Branch" und die Version der CLI, die in der GitHub README oder der vorherigen Tabelle "für die allgemeine Verwendung" aufgeführt ist. Die Verwendung einer anderen Version kann dazu führen, dass eine Datenbank nicht mit den Bibliotheken kompatibel ist.

3. Navigieren Sie zu der CodeQL CLI-Binärdateien-Version, die den vorherigen Tabellen zugeordnet ist, und laden Sie die ZIP-Datei entsprechend der Architektur Ihres Projekts herunter. Zum Beispiel für 64-Bit-Windows codeql-win64.zip.

4. Extrahieren Sie das Codeql CLI-Verzeichnis in das von Ihnen erstellte Verzeichnis, z. B. *C:\codeql-home\codeql*.

5. Überprüfen Sie, ob CodeQL ordnungsgemäß installiert ist, indem Sie die Version überprüfen:

    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'.
   

Verwenden der CodeQL-Hilfe

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.

Um Hilfe zu einem bestimmten Befehl zu ermöglichen, führen Sie codeql-Befehl <> --help aus. Beispiel:

codeql create --help

Um Hilfe zu Unterbefehlen zu erhalten, listen Sie sie hierarchisch auf, z. B.

codeql create language --help

Installieren der CodeQL-Pakete

Wählen Sie die Registerkarte für Ihre Build-Umgebung aus.

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

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

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

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

Anzeigen und Interpretieren von Ergebnissen

Dieser Abschnitt konzentriert sich auf das Generieren und Interpretieren von Ergebnissen im SARIF-Format. Andere Ergebnisformate wie CSV sind verfügbar, werden jedoch vom Logotest für statische Tools nicht unterstützt.

Static Analysis Results Interchange Format (SARIF) ist ein JSON-Typformat, das für die Freigabe statischer Analyseergebnisse verwendet wird. Erfahren Sie mehr über den Standard bei OASIS Static Analysis Results Interchange Format (SARIF), wie CodeQL SARIF Output und das Schema json verwendet.

Es gibt mehrere Methoden zum Interpretieren der Analyseergebnisse, einschließlich der manuellen Sortierung durch die Objekte. Hier sind einige, die wir verwenden:

• Der Microsoft Sarif Viewer (Web) verfügt über Funktionen, mit denen Sie Ihre SARIF-Datei in den Viewer ziehen und ablegen können. Anschließend werden ergebnisse nach Regel kategorisiert angezeigt. Dieser Viewer bietet eine schnelle und einfache Möglichkeit, die Anzahl der Verstöße zu sehen oder herauszufinden, welche Abfragen Verstöße enthalten. Er liefert jedoch nur begrenzte Informationen darüber, wo im Quellcode der Verstoß aufgetreten ist. Die Seite wird nicht aktualisiert, wenn keine Verstöße vorliegen.

• Der Microsoft SARIF Viewer für Visual Studio eignet sich hervorragend zum Anzeigen der Ergebnisse in Visual Studio für den nahtlosen Übergang von Ergebnissen zu Quellcode.

• Die SARIF-Erweiterung für Visual Studio Code öffnet einen Vorschaubereich und zeigt alle Fehler, Warnungen oder Probleme an, die von CodeQL gemeldet wurden. Um die Sarif-Datei in einem lesbaren Format anzuzeigen, öffnen Sie die Datei in Visual Studio Code, und wählen Sie UMSCHALT-ALT-F aus.

Der wichtigste Abschnitt der SARIF-Datei ist die Results Eigenschaft innerhalb des Run Objekts. Jede Abfrage verfügt über eine Results-Eigenschaft mit Details zu erkannten Verstößen und deren Auftreten. Wenn keine Verstöße gefunden werden, ist der Eigenschaftswert leer.

Abfragen werden mithilfe von Status wie Fehler, Warnung und Problem klassifiziert. Diese Klassifizierung unterscheidet sich jedoch davon, wie das Windows-Hardwarekompatibilitätsprogramm und der Logotest für statische Tools die Ergebnisse benoten. Alle Treiber mit Fehlern aus einer Abfrage innerhalb der Must-Fix-Suitebestehen nicht den Logotest für statische Tools und werden nicht zertifiziert, unabhängig von der Abfrageklassifizierung in der unformatierten Abfragedatei (z. B. Warnung).

Konvertieren von SARIF in das Treiberüberprüfungsprotokollformat (DVL)

Der Logotest für statische Tools analysiert ein Treiberüberprüfungsprotokoll (Driver Verification Log, DVL), das das kompilierte Ergebnis der statischen CodeQL-Analyse darstellt, die Sie im Treiberquellcode ausführen. Es gibt drei Möglichkeiten zum Konvertieren Ihrer SARIF-Datei in das DVL-Format: Visual Studio, MSBuild oder über die Befehlszeile mit dem tooldvl.exe . Vollständige Schritte finden Sie unter Erstellen eines Treiberüberprüfungsprotokolls.

Weitere Anweisungen für den Static Tools Logo Hardware Lab Kit (HLK) Test und die Platzierung der DVL-Datei finden Sie unter Ausführen des Logotests für statische Tools.

Troubleshooting

Wenn Sie mit WHCP zertifizieren, stellen Sie zunächst sicher, dass Sie die HLK-Version verwenden, die mit der Windows-Version verknüpft ist, die Sie verwenden, die zugeordnete Verzweigung im Repository für Zusätzliche Tools für Windows-Treiberentwickler und die nachfolgende CodeQL CLI-Version. Informationen zur HLK/Windows-Release-Kompatibilitätsmatrix finden Sie unter Windows Hardware Lab Kit und zur Windows-Release/Windows-Driver-Developer-Supplemental-Tools-Repo-Zweig/CodeQL-CLI-Version in der WHCP-Tabelle im Abschnitt "CodeQL-Version auswählen".

Fehler und Problemumgehungen

Bei Problemen mit datenbankversionskonflikten können die folgenden Tools hilfreich sein.

Verwenden Sie den Codeql-Versionsbefehl, um die Version der codeql exe anzuzeigen.

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'.

Der Datenbankupgradebefehl aktualisiert eine Datenbank. Dieses Upgrade ist eine Möglichkeit und kann nicht rückgängig gemacht werden. Weitere Informationen finden Sie unter Datenbankupgrade.

Optionale Prozeduren

Optional können Sie CodeQL-Ergebnisse unterdrücken oder die Build- und Analyseprozeduren als Postbuildereignis in Visual Studio ausführen.

Unterdrücken von CodeQL-Ergebnissen

CodeQL für Treiber unterstützt das Unterdrücken von Ergebnissen. Unterdrückungen werden derzeit als Benutzerfreundlichkeit bereitgestellt, um Entwicklern das Triagen von Problemen zu erleichtern und Rauschen zu reduzieren, nicht als Möglichkeit, die Must-Fix-Prüfungen zu umgehen. Sie haben im Moment keine Auswirkungen auf die Erstellung eines Treiberprüfungsprotokolls oder auf das Bestehen des statischen Tool-Logotests. Um Unterdrückungen zu verwenden, müssen Sie die DriverAlertSuppression.ql-Abfrage gleichzeitig mit den anderen Abfragen oder Suites ausführen, die Sie ausführen möchten.

Bei Überprüfungen, die aus der Codeanalyse portiert werden, werden vorhandene Codeanalyseunterdrückungen berücksichtigt. Weitere Informationen finden Sie unter C++-Warnungs pragma.

• Known limitation: Sie können derzeit keine #pragma(deaktivieren) und #pragma(unterdrücken) in derselben Zeile kombinieren.

Für CodeQL-Überprüfungen, die neu sind, unterdrücken Sie sie, indem Sie eine der beiden folgenden Optionen ausführen:

• Schreiben Sie eine #pragma(suppress:the-rule-id-here) Anmerkung (ohne Anführungszeichen) in der Zeile oberhalb der Verletzung, wie Sie für die Codeanalyse tun. Ersetzen Sie "the-rule-id-here" durch den Wert in den @id Metadaten der Abfrage, der oben in der Datei angezeigt werden kann.

• Schreiben Sie einen Kommentar in der obigen Zeile, die aus dem Text "lgtm[the-rule-id-here]" (minus Anführungszeichen) besteht. Sie müssen die standardmäßige C/C++-Warnungsunterdrückungsabfrage anstelle der Treiberbenachrichtigungsunterdrückungsabfrage ausführen.

Sobald eine Unterdrückung vorhanden und erkannt wurde, enthält die resultierende SARIF-Datei Daten, die anzeigen, dass ein Ergebnis unterdrückt wird. Die meisten Ergebnisanzeigen zeigen standardmäßig keine unterdrückten Ergebnisse an.

Visual Studio Nach-Build-Ereignis

Wenn Sie den Treiber mit Visual Studio erstellen, können Sie CodeQL-Abfragen so konfigurieren, dass sie als Postbuildereignis ausgeführt werden.

In diesem Beispiel wird eine kleine Batchdatei am Zielspeicherort erstellt und als Ereignis nach dem Build aufgerufen. Weitere Informationen zu Visual Studio C++-Buildereignissen finden Sie unter Angeben von Buildereignissen.

1. Erstellen Sie eine kleine Batchdatei, mit der die CodeQL-Datenbank neu erstellt wird, und führen Sie dann die gewünschten Abfragen darauf aus. In diesem Beispiel wird die Batchdatei benannt RunCodeQLRebuildQuery.bat. Ändern Sie die in der Beispielbatchdatei angezeigten Pfade so, dass sie ihren Verzeichnisspeicherorten entsprechen.

   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. Die Optiondevenv.exe/Bearbeiten wird in der Batchdatei verwendet, um die SARIF-Ergebnisdatei in der vorhandenen Instanz von Visual Studio zu öffnen. Um die SARIF-Ergebnisse anzuzeigen, installieren Sie den Microsoft SARIF Viewer für Visual Studio , und lesen Sie die Anweisungen dort, um weitere Informationen zu erhalten.

3. Navigieren Sie im Treiberprojekt zu Projekteigenschaften. Wählen Sie im Pulldown "Konfiguration " die Buildkonfiguration aus, die Sie mit CodeQL überprüfen möchten. Wir empfehlen Release. Das Erstellen der CodeQL-Datenbank und das Ausführen der Abfragen dauert einige Minuten, daher wird nicht empfohlen, CodeQL für die Debugkonfiguration Ihres Projekts auszuführen.

4. Wählen Sie Build-Ereignisse und Post-Build-Ereignis in den Eigenschaften des Treiberprojekts aus.

5. Geben Sie einen Pfad zur Batchdatei und eine Beschreibung des Postbuildereignisses an.

1. Die Ergebnisse der Batchdatei werden am Ende der Buildausgabe angezeigt.

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

Verwandte Inhalte

• Häufig gestellte Fragen zu CodeQL
• CodeQL-Übersicht
• CodeQL-Abfragen und -Suites