CodeQL 是功能強大的靜態分析引擎，可協助開發人員識別 Windows 驅動程式原始程式碼中的安全性弱點和程式碼違規。 本文說明如何使用 CodeQL 分析來建立 Windows 硬體相容性計劃 （WHCP） 認證的驅動程式驗證檔案。
本文中您將會：
- 安裝適當的 CodeQL 版本。
- 安裝必要的 CodeQL 套件和查詢套件。
- 執行 CodeQL 來建置資料庫並分析您的程式代碼。
- 建置驅動程式驗證檔案。
為您的驅動程式選取適當的 CodeQL 版本
Note
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 版本。
選取案例的索引標籤：
使用此矩陣來判斷要下載的版本。
| Windows 版本 | CodeQL CLI 版本 | 微軟/Windows 驅動程式 CodeQL 套件版本 | microsoft/cpp-queries CodeQL pack 的版本 | codeql/cpp-queries 版本 | 相關分支 |
|---|---|---|---|---|---|
| Windows 伺服器 2022 | 2.4.6 或 2.15.4 | 1.0.13 （如果使用 codeql 2.15.4） | N/A | 0.9.0 （如果使用 codeql 2.15.4） | WHCP_21H2 |
| Windows 11 | 2.4.6 或 2.15.4 | 1.0.13 （如果使用 codeql 2.15.4） | N/A | 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） | N/A | 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） | N/A | 0.9.0 （如果使用 codeql 2.15.4） | WHCP_22H2 |
| Windows 11 版本 24H2 | 2.15.4 | 1.1.0 | N/A | 0.9.0 | WHCP_24H2 |
| Windows 伺服器 2025 | 2.20.1 | 1.8.0 | 0.0.4 | N/A | WHCP_25H2 |
| Windows 11 25H2 版 | 2.20.1 | 1.8.0 | 0.0.4 | N/A | WHCP_25H2 |
| Windows 11，版本 26H1 | 2.24.1 | 1.8.2 | 0.0.4 | N/A | WHCP_26H1 |
Note
CodeQL 套件的版本未針對 CodeQL CLI 2.4.6 與 2.6.3 指定，因為只有 v2.7.0 之後的版本才支援 CodeQL 套件。
驗證可與 WHCP 搭配使用的 CodeQL 版本
如需最新的版本資訊，包括測試開發的最新版本資訊，請參閱 Windows 驅動程式開發人員補充工具。
| CodeQL CLI 版本 |
|---|
| 2.24.1 |
| 2.23.3 |
| 2.21.4 |
| 2.21.2 |
| 2.20.1 |
| 2.15.4 |
下載並安裝 CodeQL
建立包含 CodeQL 的目錄。 此範例使用
C:\codeql-home\C:\> mkdir C:\codeql-home請參閱先前的表格，以選取依據所需 Microsoft 驅動程式查詢的分支使用的 CodeQL CLI 版本。 如果你是作為 WHCP 程式的一部分進行分析，請參考「 Windows 硬體相容性程式使用」表格，否則請使用主分支及 GitHub README 或前述「一般使用」表格中列出的 CLI 版本。 使用不同的版本可能會導致資料庫與連結庫不相容。
流覽至與先前數據表相關聯的 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 套件
選取建置環境的標籤：
如果你使用 Visual Studio 2022 17.8 或更高版本的 WHCP 認證（21H2 或更新版本）以及 CodeQL CLI 2.15.4 版本或更新，請使用此程序。
Note
如果您使用舊版 CodeQL 執行 CodeQL 測試，如果您仍然有舊版的複製存放庫，請務必移除舊的 CodeQL 子模組。 CodeQL 可能會預設嘗試使用子模組中的查詢，這可能會因為版本不相符而造成錯誤。
下載 CodeQL 查詢套件
CodeQL 在 2.7.0 版中引進 CodeQL 套件（CodeQL 套件 或 查詢套件），不需要複製 Windows-Driver-Developer-Supplemental-Tools 存放庫，以使用查詢進行認證。
- 從 Windows 硬體相容性計劃使用 表格下載正確的 microsoft/windows 驅動程式套件版本。 在下列指令中指定
@<version>。
C:\codeql-home\> codeql pack download microsoft/windows-drivers@<version>
例如，如果你正在認證 WHCP 26H1，請執行以下指令下載 1.8.2 Windows 驅動程式查詢包：
C:\codeql-home\> codeql pack download microsoft/windows-drivers@1.8.2
使用此指令下載 Microsoft cpp-queries 查詢包 0.0.4 版本。
C:\codeql-home\> codeql pack download microsoft/cpp-queries@0.0.4
CodeQL 會將查詢套件安裝到預設目錄：
C:\Users\<current user>\.codeql\packages\microsoft\windows-drivers\<downloaded version>\
Important
不要更改安裝目錄或移動已安裝的查詢包。
Microsoft 提供三種查詢套件，以簡化端對端驅動程式開發者的工作流程。 這些套件包含在 microsoft/windows-drivers CodeQL 套件中。
- recommended.qls 包含一套針對常見驅動程式及 C/C++ 錯誤的廣泛檢查。 我們建議預設使用此套件並檢視結果。
- mustrun.qls 包含 必須執行 的檢查，才能通過 Windows 硬體相容性程式（WHCP）認證。 由於這些查詢在某些情況下可能會產生誤報，未通過這些檢查不會讓靜態工具標誌測試失敗，但開發者應檢視結果並修正真正的錯誤。 若產生的 DVL 在這些檢查中沒有結果，則無法通過靜態工具標誌測試。 對於 26H1，mustrun.qls 和 recommended.qls 是相同的。
- mustfix.qls 作為必執行查詢的子集，包含報告 必須修正 的問題以通過 WHCP 認證的檢查。 若產生的 DVL 在這些規則中出現失效，則無法通過靜態工具標誌測試。
如需查詢套件內容的詳細資訊，請參閱 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-root或-s指定原始碼的路徑。 -
--command或-c指定組建命令或組建檔案的路徑。
codeql database create <path to new database> --language=<cpp> --source-root=<driver parent directory> --command=<build command or path to build file>
Examples
單一驅動程式範例。
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。 （注意：如果目錄不存在，此命令就會失敗。
-
--format是輸出檔案的文件類型。 選項包括：SARIF 和 CSV。 （對於 WHCP 使用者 使用 SARIF 格式。） -
--output是您想要輸出檔案的路徑，請務必在檔名中包含格式。 （如果目錄不存在，此命令就會失敗。 - 查詢指定符參數是一個空間分隔的參數列表，可包含：
- 查詢檔案的路徑
- 包含查詢檔案之目錄的路徑
- 查詢套件檔案的路徑
- CodeQL 查詢套件的名稱
codeql database analyze <path to database> <path to query suite .qls file> --format=sarifv2.1.0 --output=<outputname>.sarifExample:
codeql database analyze D:\DriverDatabase microsoft/windows-drivers:windows-driver-suites/recommended.qls --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif如需使用 命令的詳細資訊或說明，請參閱使用
database analyzeCodeQL CLI分析資料庫、 使用CodeQL套件來分析CodeQL資料庫，或使用 CodeQL說明。
檢視和解譯結果
本節著重於以SARIF格式產生與解讀結果。 其他結果格式如 CSV 可用，但 Static Tools Logo 測試不支援。
靜態分析結果交換格式 （SARIF） 是用於共用靜態分析結果的 JSON 類型格式。 深入瞭解 OASIS 靜態分析結果交換格式 （SARIF） 的標準、CodeQL 如何使用 SARIF 輸出，以及 架構 json。
有數種方法可用來解譯分析結果，包括手動排序物件。 以下是我們使用的一些專案：
Microsoft Sarif Viewer（網頁版）具備功能，允許你將 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 檔案放置位置的指引，請參閱 「執行靜態工具標誌測試」。
Troubleshooting
如果您要向 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 查詢，同時執行您想要執行的其他查詢或套件。
對於從代碼分析移植過來的檢查項目，現有的代碼分析抑制將會被保留。 如需詳細資訊，請參閱 C++ 警告指示。
-
Known limitation:你現在不能在同一行中同時使用#pragma禁用和#pragma抑制。
對於 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 結果，請安裝 Microsoft SARIF 檢視器（Visual Studio ），並參考相關說明以獲得更多資訊。
在驅動程式專案中，流覽至項目屬性。 在 [ 組態 ] 下拉式清單中，選取您想要使用 CodeQL 檢查的組建組態 - 我們建議 發行。 建立 CodeQL 資料庫並執行查詢需要幾分鐘的時間，因此不建議您在專案的偵錯組態上執行 CodeQL。
在驅動程式項目屬性中選取 [建置事件 ] 和 [ 建置後事件 ]。
提供批處理文件的路徑，以及建置後事件的描述。
批處理文件結果會顯示在組建輸出的結尾。
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 <<<"