在 Windows 驅動程式程式代碼上執行 CodeQL 分析

2025-05-14

CodeQL 是功能強大的靜態分析引擎，可協助開發人員識別 Windows 驅動程式原始程式碼中的安全性弱點和程式碼違規。本文說明如何使用 CodeQL 分析來建立 Windows 硬體相容性計劃（WHCP）認證的驅動程式驗證檔案。

本文中您將會：

安裝適當的 CodeQL 版本。
安裝必要的 CodeQL 套件和查詢套件。
執行 CodeQL 來建置資料庫並分析您的程式代碼。
建置驅動程式驗證檔案。

為您的驅動程式選取適當的 CodeQL 版本

備註

Visual Studio （VS） 17.8 會中斷與WHCP_21H2和WHCP_22H2分支中舊版 CodeQL 的相容性。使用 Visual Studio 17.8 或更新版本時，CodeQL CLI 2.15.4 版會經過驗證，以搭配 WHCP 21H2 和 WHCP 22H2 使用。使用 Visual Studio 17.7 或更早版本時，請使用 2.4.6 版或 2.6.3 版。針對 WHCP 程式，請使用您要認證的 CodeQL CLI 版本和 Windows 版本 - 2.4.6、2.6.3 版或 2.15.4 版。若要搭配主要分支使用，請使用 CodeQL CLI 2.15.4 版。

選取案例的索引標籤：

針對 Windows 硬體相容性程式使用
針對一般用途

使用此矩陣來判斷要下載的版本。

Windows 版本	CodeQL CLI 版本	微軟/Windows 驅動程式 CodeQL 套件版本	codeql/cpp-queries CodeQL 套件版本	要使用的分支
Windows Server 2022	2.4.6 或 2.15.4	1.0.13 （如果使用 codeql 2.15.4）	0.9.0 （如果使用 codeql 2.15.4）	WHCP_21H2
Windows 11	2.4.6 或 2.15.4	1.0.13 （如果使用 codeql 2.15.4）	0.9.0 （如果使用 codeql 2.15.4）	WHCP_21H2
Windows 11 版本 22H2	2.6.3 或 2.15.4	1.0.13 （如果使用 codeql 2.15.4）	0.9.0 （如果使用 codeql 2.15.4）	WHCP_22H2
Windows 11 版本 23H2	2.6.3 或 2.15.4	1.0.13 （如果使用 codeql 2.15.4）	0.9.0 （如果使用 codeql 2.15.4）	WHCP_22H2
Windows 11 版本 24H2	2.15.4	1.1.0	0.9.0	WHCP_24H2

備註

CodeQL CLI 2.4.6 和 2.6.3 未指定 CodeQL 套件的版本，因為比 v2.7.0 更新版本的 CodeQL 支援 CodeQL 套件。

為了一般使用 CodeQL 搭配 WHCP 程式以外的其他 Windows 版本，或用於開發和測試查詢，我們目前建議使用下列版本和分支：

CodeQL CLI 版本	微軟/Windows 驅動程式 CodeQL 套件版本	codeql/cpp-queries 版本	要使用的分支
2.15.4	最新	最新	主要

下載並安裝 CodeQL

建立包含 CodeQL 的目錄。此範例使用 C:\codeql-home\
```
C:\> mkdir C:\codeql-home
```
請參閱先前的表格，以選取依據所需 Microsoft 驅動程式查詢的分支使用的 CodeQL CLI 版本。如果您要在WHCP 程式中執行分析，請參閱 Windows 硬體相容性計劃使用數據表，否則請使用 Main 分支和 2.15.4。使用不同的版本可能會導致資料庫與連結庫不相容。
流覽至與先前數據表相關聯的 CodeQL CLI 二進位檔版本，並根據專案的架構下載 zip 檔案。例如，針對 64 位 Windows codeql-win64.zip。
將 Codeql CLI 目錄解壓縮到您剛才建立的目錄，例如：*C：\codeql-home\codeql*。

請確認 CodeQL 是否已正確安裝，方法是查看版本：

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

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.

如需特定命令的說明，請執行 codeql <命令> --help。例如：

codeql create --help

若要取得子命令的說明，請以階層方式列出它們，例如

codeql create language --help

安裝 CodeQL 套件

選取建置環境的標籤：

VS 17.8 或更高版本和 CodeQL 2.15.4 版本
VS 17.7 或更早版本和 CodeQL 2.4.6 或 2.6.3

如果您正在使用 Visual Studio 2022 17.8 或更新版本，搭配 WHCP_21H2 或 WHCP_22H2 和 CodeQL CLI 2.15.4 版，請使用本程序。

備註

如果您使用舊版 CodeQL 執行 CodeQL 測試，如果您仍然有舊版的複製存放庫，請務必移除舊的 CodeQL 子模組。 CodeQL 可能會預設嘗試使用子模組中的查詢，這可能會因為版本不相符而造成錯誤。

下載 CodeQL 查詢套件

CodeQL 在 2.7.0 版中引進 CodeQL 套件（CodeQL 套件 或 查詢套件），不需要複製 Windows-Driver-Developer-Supplemental-Tools 存放庫，以使用查詢進行認證。

備註

您可以略過步驟 1，因為 --download 選項稍後在執行分析程式時會下載任何必要的查詢。

從 Windows 硬體相容性計劃使用表格下載正確的 microsoft/windows 驅動程式套件版本。在下列指令中指定@<version>。

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

例如，如果使用 WHCP_24H2，請執行下列命令來下載 1.1.0 windows-drivers 查詢套件：

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

使用此命令下載 CodeQL cpp 查詢套件 0.9.0 版。

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

CodeQL 會將查詢套件安裝到預設目錄：

C:\Users\<current user>\.codeql\packages\microsoft\windows-drivers\<downloaded version>\

這很重要

請勿變更安裝目錄或移動已安裝的查詢套件。

下載 Windows 驅動程式查詢套件

Microsoft提供兩個查詢套件，以簡化端對端驅動程式開發人員工作流程。 windows_driver_recommended.qls 套件是驅動程式開發人員認為有價值之所有 Microsoft查詢的超集，windows_driver_mustfix.qls 套件包含視為「必須修正」的 WHCP 認證查詢。 windows_driver_mustfix.qls 必須執行並通過，才能通過靜態工具標誌測試。

將兩個查詢套件檔案從 https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/tree/main/suites 複製到本地電腦。

windows_driver_recommended.qls
windows_driver_mustfix.qls

如需查詢套件內容的詳細資訊，請參閱 CodeQL 查詢和套件。

建置 CodeQL 資料庫

這些範例假設使用 Windows 開發環境，而且安裝位置是 C：\codeql-home，但您可以使用適合您的設定。如需支援哪些編譯程序的清單，請參閱 CodeQL支援的語言和架構。

建立 CodeQL 的目錄，以放置它建立的資料庫。例如：C：\codeql-home\databases
```
mkdir C:\codeql-home\databases
```
使用 CodeQL 命令來建立具有下列參數的資料庫：
- 第一個參數是資料庫目錄的連結。例如，C：\codeql-home\databases\MyDriverDatabase。（如果目錄已經存在，此命令就會失敗。
- --language 或 -l 指定您的原始程式碼所使用的語言或語言。這可以是逗號分隔清單，例如 [cpp、javascript]。
- --source 或 -s 指定原始碼的路徑。
- --command 或 -c 指定組建命令或組建檔案的路徑。
```
codeql database create <database directory> --language=<language> --source=<path to source code> --command=<build command or path to build file>
```

範例

單一驅動程式範例。

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

如需使用 database create 命令的詳細資訊或說明，請參閱建立CodeQL資料庫或使用 CodeQL說明。

執行分析

此時，資料庫建立已完成，下一個步驟是在驅動程式原始程式碼上執行實際分析。

使用 CodeQL 命令，使用下列參數來分析資料庫：
- 第一個參數是資料庫目錄的連結。例如， C：\codeql-home\databases\MyDriverDatabase。（注意：如果目錄不存在，此命令就會失敗。
- --download 旗標會指示 CodeQL 在執行查詢之前先下載相依性。
- --format 是輸出檔案的文件類型。選項包括：SARIF 和 CSV。（對於 WHCP 使用者 使用 SARIF 格式。）
- --output 是您想要輸出檔案的路徑，請務必在檔名中包含格式。（如果目錄不存在，此命令就會失敗。
- 查詢規範參數是一個空格分隔的自變數清單，可包括：
  - 查詢檔案的路徑
  - 包含查詢檔案之目錄的路徑
  - 查詢套件檔案的路徑
  - CodeQL 查詢套件的名稱
```
codeql database analyze --download <path to database> <path to query suite .qls file> --format=sarifv2.1.0 --output=<outputname>.sarif
```
範例：
```
codeql database analyze --download D:\DriverDatabase suites/windows\_driver_recommended.qls --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif 
```
如需使用命令的詳細資訊或說明，請參閱使用 database analyzeCodeQL CLI分析資料庫、使用CodeQL套件來分析CodeQL資料庫，或使用 CodeQL說明。

這些指示僅適用於同時使用 Visual Studio 17.7 或更早版本，以及 CodeQL 2.6.3 或 2.4.6 時。

複製並安裝 Windows 驅動程式開發人員補充工具存放庫，其中包含驅動程式專屬的 CodeQL 查詢：

git clone https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools.git --recurse-submodules
請參閱 Windows 硬體相容性計劃使用數據表，以識別您想要認證之 Windows 版本的正確分支。
git checkout使用命令來簽出已識別的分支。

確認子模組存在於codeql-home目錄中。

 D:/codeql-home
     |--- codeql
     |--- Windows-Driver-Developer-Supplemental-Tools

建置 CodeQL 資料庫
1. 建立 CodeQL 的目錄，以放置它建立的資料庫。例如：C：\codeql-home\databases
```
mkdir C:\codeql-home\databases
```
2. 使用 CodeQL 命令，使用下列參數建立資料庫：
  - 第一個參數是資料庫目錄的連結，例如：C：\codeql-home\databases\MyDriverDatabase。（注意：如果目錄已經存在，此命令將會失敗。
  - --language 或 -l 是您原始程式碼所使用的語言或語言（參數可以是逗號分隔清單，例如 [cpp，javascript]）。
  - -- source 或 -s 是您原始程式碼的路徑。
  - --command 或 -c 是您組建命令或組建檔案的路徑。
```
codeql database create <database directory> --language=<language> --source=<path to source code> --command=<build command or path to build file>
```
  範例
  
  單一驅動程式範例。
```
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
```
  如需使用 database create 命令的詳細資訊或說明，請參閱建立CodeQL資料庫或使用 CodeQL說明。
分析您的 CodeQL 資料庫。

更新此範例命令以符合您的環境。將參數、路徑設定為新的資料庫、格式、輸出 sarif 檔案、CodeQL 查詢或查詢套件的路徑，以用於分析。

codeql database analyze <path to database> --format=sarifv2.1.0 --output=<"path to output file".sarif> <path to query/suite to run>

範例：

codeql database analyze D:\DriverDatabase --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif D:\codeql-home\Windows-driver-developer-supplemental-tools\src\suites\windows_driver_mustfix.qls

請務必檢查您想要執行的套件或查詢路徑，並非所有分支都有相同的檔案結構。

檢視和解譯結果

我們將著重於本節的 SARIF 格式，因為它是下列步驟所需的格式，不過，如果符合您的需求，歡迎使用 CSV 格式。

靜態分析結果交換格式（SARIF）是用於共用靜態分析結果的 JSON 類型格式。深入瞭解 OASIS 靜態分析結果交換格式（SARIF）的標準、CodeQL 如何使用 SARIF 輸出，以及架構 json。

有數種方法可用來解譯分析結果，包括手動排序物件。以下是我們使用的一些專案：

Microsoft Sarif Viewer （Web）的功能可讓您將 SARIF 檔案拖放到查看器中，然後顯示依規則分類的結果。這是一種非常快速且簡便的方式，可以查看違規計數或查詢哪些查詢有違規情況，但要找到除了行號之外的原始程式碼資訊則不容易。請注意，如果沒有違規，頁面將不會更新。
Microsoft適用於 Visual Studio 的 SARIF 查看器非常適合在 Visual Studio 中顯示結果，以便順暢地從結果轉換至原始程式碼。
Visual Studio Code 的 SARIF 延伸模組會開啟預覽窗格，並顯示 CodeQL 所報告的任何錯誤、警告或問題。若要以可讀取的格式顯示 Sarif 檔案，請在 Visual Studio Code 中開啟檔案，然後選取 Shift-Alt-F。

SARIF 檔案最重要的區段是 Results 物件內的 Run 屬性。每個查詢都會有 Results 屬性，其中包含任何偵測到的違規和發生位置的詳細數據。如果未發現違規，則屬性值將會是空的。

查詢會使用錯誤、警告和問題等狀態進行分類。不過，此分類與 Windows 硬體相容性計劃與靜態工具標誌測試評分結果的方式不同。 任何在 Must-Fix 套件內有缺陷的驅動程式都不會通過靜態工具標誌測試，而且無論原始查詢檔案中的查詢分類為何，都不會通過認證（例如警告）。

將 SARIF 轉換為驅動程式驗證記錄格式（DVL）

靜態工具標誌測試會剖析驅動程式驗證記錄檔（DVL），這是您在驅動程式原始程式碼上執行之 CodeQL 靜態分析的編譯結果。有三種方式可將 SARIF 檔案轉換成 DVL 格式：Visual Studio、MSBuild，或使用 dvl.exe 工具從命令行轉換。如需完整步驟，請參閱建立驅動程序驗證記錄。

如需靜態工具標誌 HLK 測試的進一步指示，以及如何放置 DVL 檔案的指引，請參閱執行靜態工具標誌測試。

故障排除

如果您要向 WHCP 認證，請先確定您使用與您目標 Windows 版本相關聯的 HLK 版本、Windows 驅動程式開發人員補充工具存放庫中的相關聯分支，以及後續的 CodeQL CLI 版本。如需 HLK/Windows 版本相容性矩陣，請參閱 Windows Hardware Lab Kit 和 Windows Release/Windows Driver Developer Supplemental Tools 存放庫分支/ CodeQL CLI 版本，請參閱選取 CodeQL 版本一節中的 WHCP 數據表。

錯誤和因應措施

針對資料庫版本不符的問題，下列工具可能會很有幫助。

使用 codeql version 命令來顯示 codeql exe 的版本。

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

資料庫升級命令會更新資料庫。請注意，這是一種單向升級，而且無法復原。如需詳細資訊，請參閱資料庫升級。

選擇性程序

您可以選擇性地隱藏 CodeQL 結果，或在 Visual Studio 中以建置後事件的形式執行組建及分析程式。

隱藏 CodeQL 結果

驅動程式的程式代碼QL 支援隱藏結果。隱藏功能目前提供方便，可協助開發人員分級問題並減少雜訊，而不是略過 「必須修正 」檢查的方法。目前，它們不會影響產生驅動程式驗證記錄，或者通過靜態工具標誌測試。若要使用隱藏，您必須執行 DriverAlertSuppression.ql 查詢，同時執行您想要執行的其他查詢或套件。根據預設，從 githubs main/development 分支執行套件時，會啟用此查詢。

針對已從程式代碼分析移植的檢查，將會遵循現有的程式代碼分析抑制設定。如需詳細資訊，請參閱 C++ 警告指示。

Known limitation: 目前您無法在同一行中結合 #pragma（disable）和 #pragma（suppress）。

對於 CodeQL 中的新檢查項目，可以透過以下兩種方式之一來抑制它們：

#pragma(suppress:the-rule-id-here)在違規上方的行上撰寫批注（不含引號），如同您針對程式代碼分析所做的一樣。將「the-rule-id-here」取代為 @id 查詢元數據中的值，可在檔案頂端檢視。
在上面這一行寫下批注，其中包含文字 “lgtm[the-rule-id-here]” （去掉引號）。您必須執行標準 C/C++警示歸並查詢，而不是驅動程式警示歸並查詢。

一旦隱藏存在並辨識，產生的 SARIF 檔案將會包含隱藏結果的數據，而且大部分的結果查看器預設不會顯示結果。

Visual Studio 建置後事件

如果您要使用 Visual Studio 建置驅動程式，您可以設定 CodeQL 查詢以建置後事件的形式執行。

在此範例中，會在目標位置建立小型批處理檔，並稱為建置後事件。如需 Visual Studio C++建置事件的詳細資訊，請參閱指定建置事件。

建立小型批處理檔，以重新建立 CodeQL 資料庫，然後對它執行所需的查詢。在這裡範例中，批次處理檔案會命名為 RunCodeQLRebuildQuery.bat。修改範例批處理文件中顯示的路徑，以符合您的目錄位置。

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

批處理檔中會使用 devenv.exe/編輯選項，在現有的Visual Studio實例中開啟SARIF結果檔案。若要檢視 SARIF 結果，請安裝適用於 Visual Studio 的 MICROSOFT SARIF 查看器，並參閱該處的指示以取得詳細資訊。
在驅動程式專案中，流覽至項目屬性。在 [ 組態 ] 下拉式清單中，選取您想要使用 CodeQL 檢查的組建組態 - 我們建議發行。建立 CodeQL 資料庫並執行查詢需要幾分鐘的時間，因此不建議您在專案的偵錯組態上執行 CodeQL。
在驅動程式項目屬性中選取 [建置事件 ] 和 [ 建置後事件 ]。
提供批處理文件的路徑，以及建置後事件的描述。

Visual Studio 建置後事件組態顯示已設定為命令行選項的批處理檔。

批處理文件結果會顯示在組建輸出的結尾。

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

共用方式為