CodeQL 和靜態工具標誌測試

發行項
06/13/2024

CodeQL 和驅動程式安全性

Microsoft致力於減輕 Windows 作業系統的攻擊面，並確保第三方驅動程式符合強式安全性列，對於達成該目標至關重要。設定此安全性列的其中一個步驟是 Windows 硬體相容性計劃（WHCP）的需求，指出所有驅動程式提交都必須在驅動程式原始程式碼上使用 CodeQL 引擎，並修正任何被視為 「必須修正」的違規。

由 GitHub 撰寫的 CodeQL 是功能強大的語意程式代碼分析引擎，以及廣泛的高價值安全性查詢套件組合，以及強固的平臺，使其成為保護驅動程式程式代碼的寶貴工具。

在硬體實驗室套件（HLK）終端使用者許可協定下，WHCP 測試目的可接受 CodeQL 的使用方式。對於 WHCP 參與者，HLK 的 EULA 會藉由指出 CodeQL 可在自動化分析、CI 或 CD 期間使用，作為一般工程程式的一部分，以分析要提交並認證為 WHCP 一部分的驅動程式，以覆寫 GitHub 的 CodeQL 條款及條件。

靜態工具標誌測試會強制執行分析驅動程式原始程式碼並修正任何「必須修正」違規的需求。

本主題說明如何：

使用 CodeQL 分析驅動程式原始程式碼，以取得已知的高影響安全性問題。
確定靜態工具標誌測試可以使用執行 CodeQL 的結果。
判斷哪些「必須修正」查詢必須針對 WHCP 認證執行。

重要

Windows 硬體相容性計劃需要 CodeQL，在我們的用戶端和伺服器作業系統上進行靜態工具標誌（STL）測試。我們將繼續在舊版產品上維護 SDV 和 CA 的支援。強烈建議合作夥伴檢閱靜態工具標誌測試的程式代碼QL需求。

HLK EULA 和 CodeQL

在硬體實驗室套件（HLK）終端使用者許可協定下，可接受用於認證 Windows 硬體相容性計畫測試的程式碼QL。對於 WHCP 參與者，HLK 的 EULA 會覆寫 GitHub 的 CodeQL 條款及條件。 HLK EULA 指出 CodeQL 可在自動化分析、CI 或 CD 期間使用，作為一般工程程式的一部分，以便分析要提交並認證驅動程式作為 Windows 硬體相容性計畫的一部分。如需後續的一般用途，請閱讀 GitHub CodeQL 條款及條件和/或連絡 CodeQL。

CodeQL 概念

CodeQL 是開發人員用來對即時環境外部程式代碼執行安全性分析的靜態分析引擎。程式代碼QL 會在編譯程式代碼時內嵌程序代碼，並從中建置資料庫。資料庫會變成包含可查詢數據的目錄、來源參考和記錄檔。建置資料庫之後，就可以利用 CodeQL 查詢（也稱為檢查或規則）對它執行分析，以判斷原始程式碼是否包含違規或安全性弱點。 CodeQL 提供標準查詢的連結庫，可檢查語言正確性、語意，併為想要確保程式代碼不受 Bug 和弱點的開發人員提供絕佳的價值。

CodeQL 也提供建置自定義查詢的選項。如需撰寫自定義查詢的詳細資訊，請參閱在 CodeQL 檔中撰寫查詢。

CodeQL 也提供 CodeQL 命令行工具（CLI），輕鬆執行 CodeQL 動作和/或執行大規模分析。

您可以在 CodeQL 用戶入門中找到補充 CodeQL CLI 檔。

1. CodeQL 安裝程式

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

Windows 硬體相容性程式發行版本矩陣

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

Windows 版本	CodeQL CLI 版本	microsoft/windows-drivers QL 套件版本	codeql/cpp-queries QL Pack 版本	要使用的分支
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 未指定 QL 套件的版本，因為只有較新版本的 CodeQL 支援 QL 套件。

針對一般用途

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

CodeQL CLI 版本	microsoft/windows-drivers qlpack 版本	codeql/cpp-queries 版本	要使用的分支
2.15.4	最新	最新	main

下載並安裝 CodeQL

注意

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

建立包含 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'.

說明命令會顯示命令行使用資訊。

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 套件

針對WHCP_21H2和WHCP_22H2分支

如果使用 Visual Studio 2022 17.8 或更新版本搭配 WHCP_21H2 或 WHCP_22H2 和 CodeQL CLI 2.15.4 版：

請遵循「所有其他分支」的步驟。
如果您仍然複製舊版的存放庫，請務必移除CodeQL子模組。 CodeQL 預設可能會嘗試使用子模組中的查詢，這會導致錯誤，因為版本不相符。

如果使用 Visual Studio 17.7 版或更新版本 AND WHCP_21H2或WHCP_22H2 AND CodeQL CLI 2.4.6 版或 2.6.3 版：

請遵循 下列 VS17.7 或更早版本 WHCP_21H2和WHCP_22H2的特殊指示。

所有其他分支

下載 CodeQL 查詢套件

不再需要複製 Windows-Driver-Developer-Supplemental-Tools 存放庫，以使用查詢進行認證。現在會使用 CodeQL 套件（“QL packs” 或 “query packs”。

從 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

（您可以略過上述步驟，因為 --download 選項稍後會在分析程式中下載所需的查詢。

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

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

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

下載 Windows 驅動程式查詢套件

找出並複製到本機計算機這兩個主要查詢套件檔案。

windows-driver-recommended.qls
windows-driver-mustfix.qls

其內容會顯示在查詢和套件中;這兩個檔案位於https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/tree/main/suites

2.建置 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 資料庫或使用下列命令：

C:\codeql-home\codeql> codeql database create --help

3. 執行分析

注意

如果使用 Visual Studio 17.7 版或更新版本 AND WHCP_21H2或WHCP_22H2 AND CodeQL VLI 2.4.6 版或 2.6.3 版，請遵循 以下 VS17.7 或更早版本 WHCP_21H2和WHCP_22H2的特殊指示。

此時，設定已完成，下一個步驟是對驅動程式原始程式碼執行實際分析。

使用 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 analyze CodeQL CLI分析資料庫和使用 CodeQL套件來分析CodeQL資料庫。

針對命令列說明，請使用下列命令：
```
C:\codeql-home\codeql> codeql database analyze --help
```

使用 VS17.7 或更早版本WHCP_21H2和WHCP_22H2的特殊指示

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

如上述步驟所示，安裝 CodeQL 版本。
複製並安裝 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 資料庫。

更新此範例命令以符合您的環境。將參數、路徑設定為新的資料庫、格式、輸出 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

請務必檢查您想要執行的套件或查詢路徑，並非所有分支都有相同的檔案結構。
如需後續步驟，請參閱本檔中的其他指引，例如檢閱和提交測試結果。

4.檢視和解譯結果

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

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

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

Microsoft Sarif Viewer （Web）的功能可讓您將 SARIF 檔案拖放到查看器中，然後顯示依規則分類的結果。這是一個非常快速且容易的方式，可查看違規計數，或查詢有違規，但較不容易找到原始程式碼資訊，除了行號之外。請注意，如果沒有違規，頁面將不會更新。
適用於 Visual Studio 的 Microsoft SARIF 查看器非常適合在 Visual Studio 中顯示結果，以便順暢地從結果轉換至原始程式碼。
Visual Studio Code 的 SARIF 延伸模組

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

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

5. 隱藏 CodeQL 結果（選擇性）

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

針對已從程式代碼分析移植的檢查，將會接受現有的程式代碼分析歸併。如需詳細資訊，請參閱 C++警告 pragma。

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 檔案將會包含隱藏結果的數據，而且大部分的結果查看器預設不會顯示結果。

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

靜態工具標誌測試會剖析驅動程式驗證記錄檔（DVL），這是在驅動程式原始程式碼上執行的數個靜態分析引擎所編譯的結果。有三種方式可將 SARIF 檔案轉換成 DVL 格式，請選取最符合您設定的方法。

使用 Visual Studio （WDK Preview Build 20190 and up）

將您的 SARIF 結果檔案放在與.vcxproj檔案相同的目錄中。
從 [驅動程序擴充功能] 功能表中，選取 [ 建立驅動程序驗證記錄]。
確認 DVL UI 偵測到您的 SARIF 檔案。
- 注意：如果您使用 Visual Studio UI 將 SARIF 檔案移至.vcxproj目錄，則 Visual Studio 可能會建立 SARIF 檔案的參考 ，而不是實際移動它。請嘗試在 Visual Studio 外部開啟目錄，以確保目錄確實存在。
選取建立。

使用 MSBuild

將您的 SARIF 結果檔案放在與.vcxproj檔案相同的目錄中。
開啟 Visual Studio 命令提示字元、Visual Studio Native Tools 命令提示字元或企業 Windows 驅動程式套件（EWDK）。
使用 msbuild 命令搭配下列參數：
- vcx 專案檔的路徑
- /target:dvl
- /p:Configuration="Release"
- /P:Platform=<platform> （僅使用下列其中一個字符串：x86、x64、arm、arm64）
msbuild.exe <vcxprojectfile> /target:dvl /p:Configuration="Release" /P:Platform=<platform>

使用 CMD

從 WDK 或掛接的 eWDK 找出dvl.exe。
搭配下列參數使用 exe：
- /manualCreate
- driver name （不包含.sys檔案格式）
- driver architecture （僅使用下列其中一個字符串：x86、x64、arm、arm64）
"C:\Program Files (x86)\Windows Kits\10\Tools\dvl\dvl.exe" /manualCreate <driver name> <driver architecture>

如需靜態工具標誌 HLK 測試的進一步指示，以及可在執行測試中找到放置 DVL 檔案的位置的指引。

7. 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" "C:\codeql-home\Windows-Driver-Developer-Supplemental-Tools\codeql\codeql-queries\cpp\ql\src\Likely Bugs\Underspecified Functions" --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 <<<"

疑難排解

如果您要向 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'.

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

查詢和套件

作為Microsoft CodeQL GitHub 存放庫的一部分，我們提供兩個查詢套件來簡化端對端驅動程式開發人員工作流程。 windows_driver_recommended.qls 查詢套件是驅動程式開發人員認為對驅動程序開發人員有價值的所有查詢Microsoft超集。 windows_driver_mustfix.qls 查詢套件包含視為「必須修正」的 WHCP 認證查詢，該認證必須執行並通過，才能通過靜態工具標誌測試。必須修正和建議的查詢套件都會定期更新。

必須修正查詢

下列查詢子集是WHCP 認證的 Must-Fix，也包含在建議的修正套件中。

這組規則包含在 windows_driver_mustfix.qls 中。

識別碼	Location	常見弱點列舉
cpp/bad-addition-overflow-check	codeql/cpp-queries/`<Version>`/Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql	CWE-190、 CWE-192
cpp/pointer-overflow-check	codeql/cpp-queries/`<Version>`/Likely Bugs/Memory Management/PointerOverflow.ql	N/A
cpp/too-few-arguments	codeql/cpp-queries/`<Version>`/Likely Bugs/Underspecified Functions/TooFewArguments.ql	N/A
cpp/comparison-with-wider-type	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-190/ComparisonWithWiderType.ql	CWE-190、 CWE-197、 CWE-835
cpp/hresult-boolean-conversion	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-253/HResultBooleanConversion.ql	CWE-253

windows_driver_mustfix.qls 檔案包含這些檔案必須修正程式代碼查詢。

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

- description: Security queries required to fix when certifying Windows Drivers
- queries: . 
  from: codeql/cpp-queries
  version: 0.9.0
- include:
    query path: 
      - Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql
      - Likely Bugs/Memory Management/PointerOverflow.ql
      - Likely Bugs/Underspecified Functions/TooFewArguments.ql
      - Security/CWE/CWE-190/ComparisonWithWiderType.ql
      - Security/CWE/CWE-253/HResultBooleanConversion.ql
- import: windows-driver-suites/windows_mustfix_partial.qls
  from: microsoft/windows-drivers

這組規則包含在 windows-driver-suites/windows_mustfix_partial.qls 中。

識別碼	Location	常見弱點列舉
cpp/windows/wdk/deprecated-api	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/WdkDeprecatedApis/wdk-deprecated-api.ql	N/A
microsoft/Security/CWE/CWE-704/WcharCharConversionLimited	/microsoft/windows-drivers/`<Version>`/microsoft/Security/CWE/CWE-704/WcharCharConversionLimited.ql	CWE-704

windows_mustfix_partial.qls 檔案包含這些檔案必須修正程式代碼查詢。

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

- description: Security queries required to fix when certifying Windows Drivers
- queries: .
  from: microsoft/windows-drivers
- include:
    query path: 
      - drivers/general/queries/WdkDeprecatedApis/wdk-deprecated-api.ql
      - microsoft/Security/CWE/CWE-704/WcharCharConversionLimited.ql

建議的修正查詢

這些查詢是 Microsoft GitHub CodeQL 存放庫中windows_driver_recommended.qls 查詢套件的一部分。 [一般弱點列舉] （CWE）數據行會指定指定查詢所搜尋的安全性問題種類。如需 CWE 的詳細資訊，請參閱 CWE 上的 Mitre 頁面。

最佳做法

識別碼	Location	常見弱點列舉
cpp/offset-use-before-range-check	codeql/cpp-queries/`<Version>`/Best Practices/Likely Errors/OffsetUseBeforeRangeCheck.ql	N/A

可能的錯誤

識別碼	Location	常見弱點列舉
cpp/bad-addition-overflow-check	codeql/cpp-queries/`<Version>`/Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql	CWE-190、 CWE-192
cpp/integer-multiplication-cast-to-long	codeql/cpp-queries/`<Version>`/Likely Bugs/Arithmetic/IntMultToLong.ql	CWE-190、 CWE-192、 CWE-197、 CWE-681
cpp/signed-overflow-check	codeql/cpp-queries/`<Version>`/Likely Bugs/Arithmetic/SignedOverflowCheck.ql	N/A
cpp/upcast-array-pointer-arithmetic	codeql/cpp-queries/`<Version>`/Likely Bugs/Conversion/CastArrayPointerArithmetic.ql	CWE-119，CWE-843
cpp/pointer-overflow-check	codeql/cpp-queries/`<Version>`/Likely Bugs/Memory Management/PointerOverflow.ql	N/A
cpp/too-few-arguments	codeql/cpp-queries/`<Version>`/Likely Bugs/Underspecified Functions/TooFewArguments.ql	N/A
cpp/incorrect-not-operator-usage	codeql/cpp-queries/`<Version>`/Likely Bugs/Likely Typos/IncorrectNotOperatorUsage.ql	CWE-480
cpp/suspicious-add-sizeof	codeql/cpp-queries/`<Version>`/Likely Bugs/Memory Management/SuspiciousSizeof.ql	CWE-468
cpp/uninitialized-local	codeql/cpp-queries/`<Version>`/Likely Bugs/Memory Management/UninitializedLocal.ql	CWE-457、 CWE-665

安全性

識別碼	Location	常見弱點列舉
cpp/conditionally-uninitialized-variable	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-457/ConditionallyUninitializedVariable.ql。	CWE-457
cpp/unterminated-variadic-call	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-121/UnterminatedVarargsCall.ql	CWE-121
cpp/suspicious-pointer-scaling	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-468/IncorrectPointerScaling.ql	CWE-468
cpp/suspicious-pointer-scaling-void	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-468/IncorrectPointerScalingVoid.ql	CWE-468
cpp/potentially-dangerous-function	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-676/PotentiallyDangerousFunction.ql	CWE-676
cpp/incorrect-string-type-conversion	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-704/WcharCharConversion.ql	CWE-704
cpp/comparison-with-wider-type	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-190/ComparisonWithWiderType.ql	CWE-190、 CWE-197、 CWE-835
cpp/hresult-boolean-conversion	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-253/HResultBooleanConversion.ql	CWE-253
cpp/suspicious-add-sizeof	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-468/CWE-468/SuspiciousAddWithSizeof.ql	CWE-468

windows_driver_recommended.qls 檔案包含這些建議的程式代碼查詢。

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

- description: Recommended and required queries for Windows Drivers.
- import: windows-driver-suites/windows_mustfix_partial.qls
  from: microsoft/windows-drivers
- import: windows-driver-suites/windows_recommended_partial.qls
  from: microsoft/windows-drivers
- queries: . 
  from: codeql/cpp-queries
  version: 0.9.0
- include:
    query path: 
      - Best Practices/Likely Errors/OffsetUseBeforeRangeCheck.ql
      - Likely Bugs/Arithmetic/IntMultToLong.ql
      - Likely Bugs/Arithmetic/SignedOverflowCheck.ql
      - Likely Bugs/Conversion/CastArrayPointerArithmetic.ql
      - Likely Bugs/Likely Typos/IncorrectNotOperatorUsage.ql
      - Likely Bugs/Memory Management/SuspiciousSizeof.ql
      - Likely Bugs/Memory Management/UninitializedLocal.ql
      - Security/CWE/CWE-121/UnterminatedVarargsCall.ql
      - Security/CWE/CWE-457/ConditionallyUninitializedVariable.ql
      - Security/CWE/CWE-468/IncorrectPointerScaling.ql
      - Security/CWE/CWE-468/IncorrectPointerScalingVoid.ql
      - Security/CWE/CWE-468/SuspiciousAddWithSizeof.ql
      - Security/CWE/CWE-676/PotentiallyDangerousFunction.ql
      - Security/CWE/CWE-704/WcharCharConversion.ql
      - Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql
      - Likely Bugs/Memory Management/PointerOverflow.ql
      - Likely Bugs/Underspecified Functions/TooFewArguments.ql
      - Security/CWE/CWE-190/ComparisonWithWiderType.ql
      - Security/CWE/CWE-253/HResultBooleanConversion.ql

這些查詢是 windows_recommended_partial.qls 的一部分。

可能的 Bug - windows_recommended_partial.qls

識別碼	Location	常見弱點列舉
cpp/paddingbyteinformationdisclosure	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Boundary Violations/PaddingByteInformationDisclosure.ql	N/A
cpp/badoverflowguard	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Conversion/BadOverflowGuard.ql	N/A
cpp/infiniteloop	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Conversion/InfiniteLoop.ql	N/A
cpp/uninitializedptrfield	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/UninitializedPtrField.ql	N/A
cpp/use-after-free	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Memory Management/UseAfterFree/UseAfterFree.ql	N/A

安全性 - windows_recommended_partial.qls

識別碼	Location	程序代碼分析警告
cpp/weak-crypto/cng/hardcoded-iv	/microsoft/windows-drivers/`<Version>`/microsoft/Security/Crytpography/HardcodedIVCNG.ql	N/A

驅動程式 - 一般

識別碼	Location	程序代碼分析警告
cpp/drivers/ke-set-event-pageable	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/KeSetEventPageable/KeSetEventPageable.ql	沒有相關聯的 CA 檢查
cpp/drivers/role-type-correctly-used	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/RoleTypeCorrectlyUsed/RoleTypeCorrectlyUsed.ql	沒有相關聯的 CA 檢查
cpp/drivers/extended-deprecated-apis	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/ExtendedDeprecatedApis.ql	C28719 警告、C28726 警告、C28735 警告、C28750 警告
cpp/drivers/irql-not-saved	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/IrqlNotSaved/IrqlNotSaved.ql	C28158 警告
cpp/drivers/irql-not-used	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/IrqlNotUsed/IrqlNotUsed.ql	C28157 警告
cpp/drivers/irql-set-too-high	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/IrqlTooHigh/IrqlTooHigh.ql	C28150 警告
cpp/drivers/irql-too-low	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/IrqlTooLow/IrqlTooLow.ql	C28120 警告
cpp/drivers/irql-set-too-high	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/IrqlSetTooHigh/IrqlTooHigh.ql	C28121 警告
cpp/drivers/irql-set-too-low	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/IrqlSetTooLow/IrqlSetTooLow.ql	C28124 警告
cpp/drivers/pool-tag-integral	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/PoolTagIntegral/PoolTagIntegral.ql	C28134 警告
cpp/drivers/str-safe	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/StrSafe/StrSafe.ql	C28146 警告

驅動程式 - WDM

識別碼	Location	程序代碼分析警告
cpp/drivers/illegal-field-access	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/IllegalFieldAccess/IllegalFieldAccess.ql	C28128 警告
cpp/drivers/illegal-field-access2	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/IllegalFieldAccess2/IllegalFieldAccess2.ql	C28175 警告
cpp/drivers/illegal-field-write	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/IllegalFieldWrite/IllegalFieldWrite.ql	C28176 警告
cpp/drivers/opaque-mdl-use	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlUse.ql	（沒有相關聯的 CA 檢查）
cpp/drivers/opaque-mdl-write	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlWrite.ql	C28145 警告
cpp/drivers/pending-status-error	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/PendingStatusError/PendingStatusError.ql	C28143 警告
cpp/drivers/wrong-dispatch-table-assignment	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/WrongDispatchTableAssignment/WrongDispatchTableAssignment.ql	C28169 警告

windows-driver-suites/windows_recommended_partial.qls 檔案包含這些建議的程式碼查詢。

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

- description: Recommended and required queries for Windows Drivers.
- import: windows-driver-suites/windows_mustfix_partial.qls
- queries: .
  from: microsoft/windows-drivers
- include:
    query path: 
      - microsoft/Likely Bugs/Boundary Violations/PaddingByteInformationDisclosure.ql
      - microsoft/Likely Bugs/Conversion/BadOverflowGuard.ql
      - microsoft/Likely Bugs/Conversion/InfiniteLoop.ql
      - microsoft/Likely Bugs/Memory Management/UseAfterFree/UseAfterFree.ql
      - microsoft/Likely Bugs/UninitializedPtrField.ql
      - microsoft/Security/Crytpography/HardcodedIVCNG.ql
      - drivers/general/queries/KeSetEventPageable/KeSetEventPageable.ql
      - drivers/general/queries/RoleTypeCorrectlyUsed/RoleTypeCorrectlyUsed.ql
      - drivers/general/queries/DefaultPoolTag/DefaultPoolTag.ql
      - drivers/general/queries/ExaminedValue/ExaminedValue.ql
      - drivers/general/queries/ExtendedDeprecatedApis/ExtendedDeprecatedApis.ql
      - drivers/general/queries/IrqlNotSaved/IrqlNotSaved.ql
      - drivers/general/queries/IrqlNotUsed/IrqlNotUsed.ql
      - drivers/general/queries/IrqlTooHigh/IrqlTooHigh.ql
      - drivers/general/queries/IrqlTooLow/IrqlTooLow.ql
      - drivers/general/queries/IrqlSetTooHigh/IrqlTooHigh.ql
      - drivers/general/queries/IrqlSetTooLow/IrqlSetTooLow.ql
      - drivers/general/queries/PoolTagIntegral/PoolTagIntegral.ql
      - drivers/general/queries/StrSafe/StrSafe.ql
      - drivers/wdm/queries/IllegalFieldAccess/IllegalFieldAccess.ql
      - drivers/wdm/queries/IllegalFieldAccess2/IllegalFieldAccess2.ql
      - drivers/wdm/queries/IllegalFieldWrite/IllegalFieldWrite.ql
      - drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlUse.ql
      - drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlWrite.ql
      - drivers/wdm/queries/PendingStatusError/PendingStatusError.ql
      - drivers/wdm/queries/WrongDispatchTableAssignment/WrongDispatchTableAssignment.ql

常見問題集 (FAQ)

何時需要進行裝置認證？

如需需求詳細數據，請參閱 Windows 硬體相容性計劃認證程式。

要求在驅動程式原始程式碼上執行 CodeQL 背後的動機為何？

要求在驅動程式原始碼上執行 CodeQL 的動機可以摘要說明兩個主要原因：

Windows 的安全性至關重要，而且要求在驅動程式原始程式碼上執行 CodeQL 是協助改善由 Microsoft 認證之元件安全性的一個步驟。
程序代碼QL 查詢是由Microsoft的安全性工程師所積極開發，因為Microsoft致力於確保其硬體生態系統受益於Microsoft所使用的相同高品質工具。

CodeQL 和靜態工具標誌測試適用於何種驅動程式類型？

目前，靜態工具標誌測試需要執行 CodeQL，且圖形驅動程式以外的所有核心模式驅動程式皆傳遞「Must-Fix」查詢集。請注意，儘管目前並非必要，但我們強烈建議對圖形驅動程序執行 CodeQL。某些查詢可能也會在使用者模式元件中找到實用的瑕疵。

我們期望擴充測試及其查詢，以便在未來能夠要求圖形驅動程式、使用者模式驅動程式、驅動程式元件和其他驅動程式套件元件的結果。如果您在圖形驅動程式或使用者模式驅動程式執行 CodeQL 時遇到非預期行為或誤判，請在 Windows-Driver-Developer-Supplemental-Tools 存放庫提出問題。

哪些授權會控管適用於驅動程序開發人員的CodeQL使用方式？

在硬體實驗室套件（HLK）終端使用者許可協定下，WHCP 測試目的可接受 CodeQL 的使用方式。對於 WHCP 參與者，HLK 的 EULA 會覆寫 GitHub 的 CodeQL 條款及條件。 HLK EULA 指出，CodeQL 可在自動化分析、CI 或 CD 期間使用 ，作為一般工程程式的一部分，以便分析要提交並認證驅動程式作為 WHCP 的一部分。

我需要使用 Visual Studio 或 msbuild 來執行 CodeQL 嗎？

CodeQL 不需要使用 MSBuild 或 Visual Studio。如需支援的編譯程式清單，請參閱支援的語言和架構。

HLK 如何確認我的驅動程式已由 CodeQL 掃描？

HLK 中的靜態工具標誌測試是強制執行這項需求的測試。靜態工具標誌測試的詳細數據可在其 MS Docs 頁面上找到。

CodeQL 是否報告所有瑕疵？

每個 CodeQL 查詢都有不同層級的精確度。我們的目標是將誤判降到最低，但偶爾會發生。我們的「必須修正」查詢套件已開發和手動挑選以搭配 WHCP 程式使用，因為我們的廣泛測試結果幾乎為零誤判。如果您在「必須修正」查詢的一組查詢中看到誤判，請立即傳送電子郵件stlogohelp@microsoft.com，或在 Windows-Driver-Developer-Supplemental-Tools 存放庫上提出問題，我們會儘快解決此問題。

查詢的「警告」或「錯誤」分類是否對靜態工具標誌測試的目的很重要？

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

我可以在 Visual Studio 解決方案上產生 DVL 嗎？

否，DVL 產生必須在專案層級執行，且無法在 Visual Studio 解決方案上執行。如需如何產生 DVL 的指示，請參閱：建立驅動程式驗證記錄檔。

我可以在 msbuild 或 Visual Studio 的內容之外產生驅動程式驗證記錄檔（DVL）嗎？

作為 Windows 驅動程式套件（WDK）和企業版 WDK （eWDK）的一部分，Microsoft隨附稱為 dvl.exe 的元件，可用來產生驅動程式驗證記錄（DVL）。從 WDK/eWDK 預覽版本 21342 和更新版本開始，可以傳遞驅動程式名稱和架構，從 msbuild 或 Visual Studio 內容以外的命令行產生 DVL。如需詳細資訊，請參閱建立驅動程式驗證記錄。

我有關於如何在驅動程式上使用 CodeQL 的批注或問題，我在哪裡傳送意見反應？

將意見反應與問題傳送至 stlogohelp@microsoft.com。

共用方式為