CodeQL 和静态工具徽标测试

项目
05/20/2024

CodeQL 和驱动程序安全性

Microsoft 致力于减少 Windows 操作系统的攻击面，而确保第三方驱动程序符合严格的安全标准是实现这一目标的关键。设置此安全标准的一个步骤是 Windows 硬件兼容性计划 (WHCP) 的要求，该计划指出所有驱动程序提交都必须在驱动程序源代码上使用 CodeQL 引擎，并修复被视为“必须修复”的任何冲突。

GitHub 的 CodeQL 是一个强大的语义代码分析引擎，它结合了广泛的高价值安全查询套件和强大的平台，是保护驱动程序代码安全的宝贵工具。

根据硬件实验室工具包 (HLK) 最终用户许可协议，可以使用 CodeQL 进行 WHCP 测试。对于 WHCP 参与者，HLK 的 EULA 覆盖了 GitHub 的 CodeQL 条款和条件，规定 CodeQL 可以在自动化分析、CI 或 CD期间作为正常工程过程的一部分使用 CodeQL，用于分析作为 WHCP 一部分提交和认证的驱动程序。

静态工具徽标测试将强制要求分析驱动程序源代码并修复任何“必须修复”冲突。

本主题介绍如何执行以下操作：

使用 CodeQL 分析驱动程序源代码，查找已知的高影响安全问题。
确保静态工具徽标测试可以使用运行 CodeQL 的结果。
确定必须为 WHCP 认证运行哪些“必须修复”查询。

重要

Windows 硬件兼容性计划要求在我们的客户端和服务器操作系统上使用 CodeQL 进行静态工具徽标 (STL) 测试。我们将继续在旧版产品上支持 SDV 和 CA。我们强烈建议合作伙伴查看 CodeQL 对静态工具徽标测试的要求。

HLK EULA 和 CodeQL

根据硬件实验室工具包 (HLK) 最终用户许可协议，可以接受将 CodeQL 用于 Windows 硬件兼容性计划测试。对于 WHCP 参与者，HLK 的 EULA 覆盖 GitHub 的 CodeQL 条款和条件。 HLK EULA 规定，CodeQL 可以在自动化分析、CI 或 CD 期间作为正常工程过程的一部分，用于分析作为 Windows 硬件兼容性计划的一部分提交和认证的驱动程序。有关以供常规使用的后续操作，请阅读 GitHub CodeQL 条款和条件和/或联系 CodeQL。

CodeQL 概念

CodeQL 是一个静态分析引擎，供开发人员在实时环境之外对代码进行安全分析。 CodeQL 在编译时引入代码，并从中生成数据库。数据库将变成一个包含可查询数据、源引用和日志文件的目录。生成数据库后，可以使用 CodeQL 查询（也称为检查或规则）对其运行分析，从而确定源代码是否包含违规或安全漏洞。 CodeQL 提供了一个标准查询库，它可以检查语言的正确性和语义，并为希望确保代码没有错误和漏洞的开发人员提供了极大的价值。

CodeQL 还提供生成自定义查询的选项。有关编写自定义查询的更多信息，请参阅 CodeQL 文档中的编写查询。

CodeQL 还提供 CodeQL 命令行工具 (CLI)，以便轻松执行 CodeQL 操作和/或执行大规模分析。

可以在 CodeQL 入门指南中找到补充 CodeQL CLI 文档。

1. CodeQL 设置

用于 Windows 硬件兼容性计划使用

Windows 硬件兼容性计划版本矩阵

使用此矩阵确定要下载的版本。

Windows 版本	CodeQL CLI 版本	microsoft/windows-drivers QL 包版本	codeql/cpp-queries QL 包版本	要使用的分支
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 包。

一般用途

对于在 WHCP 程序之外的其他 Windows 版本中使用 CodeQL，或用于开发和测试查询，我们目前推荐使用以下版本和分支：

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

下载并安装 CodeQL

注意

Visual Studio 17.8 破坏了与 WHCP_21H2 和 WHCP_22H2 分支中使用的旧版 CodeQL 的兼容性。 CodeQL CLI 2.15.4 版已通过验证，可在使用 Visual Studio 17.8 或更高版本时与 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 硬件兼容性计划使用表，否则请使用主分支和 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'.

help 命令显示命令行使用信息。

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 包”或“查询包”）。

从 Windows 硬件兼容性程序版本矩阵下载正确的 microsoft/windows-drivers 程序包版本。在以下命令中指定 @<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

使用此命令下载 0.9.0 版本的 CodeQL cpp-queries 查询包。

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 驱动程序查询套件

找到并将两个主要查询套件文件复制到本地 PC。

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 或更低版本和 WHCP_21H2 或 WHCP_22H2 和 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 格式更符合需求，欢迎使用 CSV 格式。

静态分析结果交换格式 (SARIF) 是一种 JSON 类型的格式，用于分享静态分析结果。详细了解 OASIS 静态分析结果交换格式（SARIF）的标准、CodeQL 如何使用 SARIF 输出和架构 json。

有多种方法可以解释分析结果，包括对对象手动排序。以下是我们使用的一些：

Microsoft Sarif 查看器 (Web) 的功能允许将 SARIF 文件拖放到查看器中，然后显示按规则分类的结果。这是查看违规次数或哪些查询存在违规行为的一种非常简单快捷的方法，但除了行号外，要查找源代码信息并非易事。请注意，如果没有违规，页面就不会更新。
适用于 Visual Studio 的 Microsoft SARIF 查看器非常适合在 Visual Studio 中显示结果，以便实现从结果到源代码的无缝转换。
适用于 Visual Studio Code 的 SARIF 扩展

SARIF 文件中最重要的部分是“Run”对象中的“Results”属性。每个查询都有一个 Results 属性，其中包含有关任何检测到的违规及其发生位置的详细信息。如果未找到违规，则属性值将为空。

查询使用“错误”“警告”和“问题”等状态进行分类，但此分类与 Windows 硬件兼容性计划，特别是静态工具徽标测试，对结果进行评分的方式有所不同。无论原始查询文件中的查询分类（例如“警告”）如何，“必须修复”套件中任何查询存在缺陷的任何驱动程序都不会通过静态工具徽标测试，并且都无法进行认证。

5. 禁止显示 CodeQL 结果（可选）

驱动程序的 CodeQL 支持取消结果。目前提供抑制是为了方便开发人员分流问题和减少噪音，而不是为了绕过必须修复的检查。它们目前对生成驱动程序验证日志或通过静态工具徽标测试没有影响。要使用抑制，必须在运行其他查询或套件的同时运行 DriverAlertSuppression.ql 查询。默认情况下，从 githubs main/development 分支运行套件时将启用此查询。

对于从代码分析移植的检查，将遵循现有的代码分析抑制。有关详细信息，请参阅 C++ warning 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 预览版 20190 及更新版本）

将 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 / Edit 选项在现有 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 进行认证，首先要确保使用的 HLK 版本与目标 Windows 版本、Windows 驱动程序开发人员补充工具库中的相关分支以及随后的 CodeQL CLI 版本相关联。有关 HLK/Windows 发布兼容性矩阵，请参阅 Windows 硬件实验室工具包，有关 Windows Release/Windows 驱动程序开发人员补充工具存储库分支/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'.

数据库升级命令将更新数据库。请注意，这是一种单向升级，不可逆。有关详细信息，请参阅 database upgrade。

查询和套件

作为 Microsoft CodeQL GitHub 存储库的一部分，我们提供了两个查询套件来简化端到端驱动程序开发人员工作流。 windows_driver_recommended.qls 查询套件是 Microsoft 认为对驱动程序开发人员有价值的所有查询的超集。该 windows_driver_mustfix.qls 查询套件包含视为 WHCP 认证“必须修复”的查询，必须运行并通过这些查询才能通过静态工具徽标测试。必须修复和建议的修复查询套件都会定期更新。

必须修复的查询

下面的查询子集是 WHCP 认证的必须修复，也包含在建议的修复套件中。

此规则集包含在 windows_driver_mustfix.qls 中。

ID	位置	常见漏洞枚举
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	空值
cpp/too-few-arguments	codeql/cpp-queries/`<Version>`/Likely Bugs/Underspecified Functions/TooFewArguments.ql	空值
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 中。

ID	位置	常见漏洞枚举
cpp/windows/wdk/deprecated-api	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/WdkDeprecatedApis/wdk-deprecated-api.ql	空值
microsoft/Security/CWE/CWE-704/WcharCharConversionLimited	/microsoft/windows-drivers/`<Version>`/microsoft/Security/CWE/CWE-704/WcharCharConversionLimited.ql	CWE-704

The 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 页面。

最佳方案

ID	位置	常见漏洞枚举
cpp/offset-use-before-range-check	codeql/cpp-queries/`<Version>`/Best Practices/Likely Errors/OffsetUseBeforeRangeCheck.ql	空值

可能的错误

ID	位置	常见漏洞枚举
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	空值
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	空值
cpp/too-few-arguments	codeql/cpp-queries/`<Version>`/Likely Bugs/Underspecified Functions/TooFewArguments.ql	空值
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

安全性

ID	位置	常见漏洞枚举
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

The 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

ID	位置	常见漏洞枚举
cpp/paddingbyteinformationdisclosure	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Boundary Violations/PaddingByteInformationDisclosure.ql	空值
cpp/badoverflowguard	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Conversion/BadOverflowGuard.ql	空值
cpp/infiniteloop	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Conversion/InfiniteLoop.ql	空值
cpp/uninitializedptrfield	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/UninitializedPtrField.ql	空值
cpp/use-after-free	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Memory Management/UseAfterFree/UseAfterFree.ql	空值

Security - windows_recommended_partial.qls

ID	位置	代码分析警告
cpp/weak-crypto/cng/hardcoded-iv	/microsoft/windows-drivers/`<Version>`/microsoft/Security/Crytpography/HardcodedIVCNG.ql	空值

驱动程序 - 常规

ID	位置	代码分析警告
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 Warning
cpp/drivers/irql-set-too-high	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/IrqlTooHigh/IrqlTooHigh.ql	C28150 Warning
cpp/drivers/irql-too-low	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/IrqlTooLow/IrqlTooLow.ql	C28120 Warning
cpp/drivers/irql-set-too-high	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/IrqlSetTooHigh/IrqlTooHigh.ql	C28121 Warning
cpp/drivers/irql-set-too-low	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/IrqlSetTooLow/IrqlSetTooLow.ql	C28124 Warning
cpp/drivers/pool-tag-integral	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/PoolTagIntegral/PoolTagIntegral.ql	C28134 Warning
cpp/drivers/str-safe	/microsoft/windows-drivers/`<Version>`/drivers/general/queries/StrSafe/StrSafe.ql	C28146 Warning

Drivers - WDM

ID	位置	代码分析警告
cpp/drivers/illegal-field-access	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/IllegalFieldAccess/IllegalFieldAccess.ql	C28128 Warning
cpp/drivers/illegal-field-access2	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/IllegalFieldAccess2/IllegalFieldAccess2.ql	C28175 Warning
cpp/drivers/illegal-field-write	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/IllegalFieldWrite/IllegalFieldWrite.ql	C28176 Warning
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 Warning
cpp/drivers/pending-status-error	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/PendingStatusError/PendingStatusError.ql	C28143 Warning
cpp/drivers/wrong-dispatch-table-assignment	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/WrongDispatchTableAssignment/WrongDispatchTableAssignment.ql	C28169 Warning

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 认证的组件安全性的一个步骤。
codeQL 查询由Microsoft的安全工程师积极开发，因为Microsoft致力于确保其硬件生态系统受益于Microsoft中使用的高质量工具。

CodeQL 和静态工具徽标测试适用于哪些类型的驱动程序？

目前，静态工具徽标测试要求运行 CodeQL，并为除图形驱动程序外的所有内核模式驱动程序传递“必须修复”查询集。注意：强烈建议在图形驱动程序上运行 CodeQL，即使当前不需要这样做。一些查询还可能在用户模式组件中发现有用的缺陷。

我们预计未来将扩展测试及其查询，以要求图形驱动程序、用户模式驱动程序和驱动程序组件以及其他驱动程序包组件的结果。如果在图形驱动程序或用户模式驱动程序上运行 CodeQL 时遇到意外行为或误报，请在 Windows-Driver-Developer-Supplemental-Tools repo 上提交问题。

哪个许可证控制驱动程序开发人员 CodeQL 的使用？

根据硬件实验室工具包 (HLK) 最终用户许可协议，可以使用 CodeQL 进行 WHCP 测试。对于 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 存储库中提交问题，我们将尽快解决。

对于静态工具徽标测试，查询的“警告”或“错误”分类是否很重要？

在 CodeQ 中，查询使用状态（如“错误”“警告”和“问题”）进行分类，但此分类与 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。

通过