Skip to content

Commit 0bb0146

Browse files
jacob-ronstadtjacob-ronstadt
authored
Jacob ronstadt/mustrun (#174)
* Revert must-fix to current requirements. Make recommended contain what next mustfix will. Make mustrun suite. * update version * remove old suite files * Updating documentation for new version * update dependency versions. update dvl_tests.ps1 for changed mustfix suite name * fix version number in suites * update qlpack version * update readme * update qlpack dependency versions --------- Signed-off-by: Jacob Ronstadt <147542405+jacob-ronstadt@users.noreply.github.com>
1 parent b62be55 commit 0bb0146

2 files changed

Lines changed: 67 additions & 86 deletions

File tree

‎README.md‎

Lines changed: 65 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -2,96 +2,56 @@
22

33
This repository contains open-source components for supplemental use in developing device drivers for Windows, as well as driver specific [CodeQL](https://codeql.github.com/) query suites used for the [Windows Hardware Compatibility Program](https://learn.microsoft.com/en-us/windows-hardware/design/compatibility/). The quickstart below will get you set up to build your database and analyze your driver using CodeQL. For the full documentation, troubleshooting, and more details about the Static Tools Logo test within the WHCP Program, please visit [CodeQL and the Static Tools Logo Test](https://docs.microsoft.com/windows-hardware/drivers/devtest/static-tools-and-codeql).
44

5-
### For General Use
5+
### For General Use or Windows Hardware Compatibility Program Use
66

7-
| CodeQL CLI version | microsoft/windows-drivers qlpack version | codeql/cpp-queries version |Associated Repo Branch|
8-
|--------------------------|-------------------------------------------|------------------------|------------------------|
9-
| latest | latest | latest |main |
7+
| CodeQL CLI Version | microsoft/windows-drivers CodeQL Pack Version | microsoft/cpp-queries CodeQL Pack Version | Associated Repo Branch|
8+
|--------------------------|------------------------------------------|-------------------------------|-----------------------------|
9+
| 2.20.1 | 1.6.0 | 0.0.4 | Main |
10+
11+
See appendix for more information
1012

11-
### For Windows Hardware Compatibility Program Use
1213

13-
### Windows Hardware Compatibility Program Release Version Matrix
14-
| Release | CodeQL CLI version | microsoft/windows-drivers qlpack version| codeql/cpp-queries version | Associated Repo Branch|
15-
|--------------------------|--------------------|-----------------------------------------|----------------------|-----------------------------|
16-
| Windows Server 2022 | [2.4.6](https://github.com/github/codeql-cli-binaries/releases/tag/v2.4.6) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| 0.9.0 (If using codeql 2.15.4) | WHCP_21H2|
17-
| Windows 11 | [2.4.6](https://github.com/github/codeql-cli-binaries/releases/tag/v2.4.6) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| 0.9.0 (If using codeql 2.15.4)|WHCP_21H2|
18-
| Windows 11, version 22H2 | [2.6.3](https://github.com/github/codeql-cli-binaries/releases/tag/v2.6.3) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| 0.9.0 (If using codeql 2.15.4)|WHCP_22H2|
19-
| Windows 11, version 23H2 | [2.6.3](https://github.com/github/codeql-cli-binaries/releases/tag/v2.6.3) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| 0.9.0 (If using codeql 2.15.4)|WHCP_22H2|
20-
| Windows 11, version 24H2 | [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4) | 1.1.0 | 0.9.0 | WHCP_24H2 |
2114

15+
### For Testing the Latest in Development
2216

2317

18+
| CodeQL CLI Version | microsoft/windows-drivers CodeQL Pack Version | microsoft/cpp-queries CodeQL Pack Version | Associated Repo Branch|
19+
|--------------------------|------------------------------------------|-------------------------------|-----------------------------|
20+
| [Latest](https://github.com/github/codeql-cli-binaries/releases/latest) | [Latest Beta Version](https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/pkgs/container/windows-drivers) | [Latest](https://github.com/orgs/microsoft/packages/container/package/cpp-queries) | Development |
2421

2522
## Quickstart
2623

2724
1. Create a directory where you can place the CodeQL CLI and the queries you want to use:
2825
```
29-
D:\> mkdir codeql-home
26+
mkdir codeql-home
3027
```
3128
32-
1. Download the CodeQL CLI zip by selecting the asset associated with your OS and architecture (codeql-win64.zip, codeql-linux64.zip, etc.), then extract it to the directory you created in the previous step.
33-
34-
**NOTE** Visual Studio 17.8 broke compatibility with the older versions of CodeQL used in the WHCP_21H2 and WHCP_22H2 branches. [CodeQL CLI version 2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4) has been validated for use with WHCP 21H2 and WHCP 22H2 when using Visual Studio 17.8 or greater.
35-
36-
For the WHCP Program, use the CodeQL CLI version in accordance with the table above and Windows release you are certifying for: [version 2.4.6](https://github.com/github/codeql-cli-binaries/releases/tag/v2.4.6), [version 2.6.3](https://github.com/github/codeql-cli-binaries/releases/tag/v2.6.3), or [version 2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4).
37-
38-
39-
40-
For general use, use [CodeQL CLI version 2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4) and the latest version of the microsoft/windows-driver qlpack.
41-
42-
43-
44-
1. Verify CodeQL is installed correctly by checking the version:
45-
```
46-
D:\codeql-home\codeql>codeql --version
47-
CodeQL command-line toolchain release 2.15.4.
48-
Copyright (C) 2019-2023 GitHub, Inc.
49-
Unpacked in: D:\codeql-home\codeql
50-
Analysis results depend critically on separately distributed query and
51-
extractor modules. To list modules that are visible to the toolchain,
52-
use 'codeql resolve qlpacks' and 'codeql resolve languages'.
53-
```
29+
1. Download the CodeQL CLI
30+
31+
For the WHCP Program, use the CodeQL CLI version specified above. For special cases and more information see appendix.
32+
1. Navigate to the [CodeQL CLI Release Page](https://github.com/github/codeql-cli-binaries/releases)
33+
1. Find the release version based on the tables above and select the asset associated with your OS and architecture (codeql-win64.zip, codeql-linux64.zip, etc.),
34+
1. Extract the downloaded zip to the directory you created in the previous step.
35+
1. (Optional) Add the CodeQL install location to your PATH
36+
1. (Optional) Verify CodeQL is installed correctly by checking the version `codeql --version`
5437
5538
1. Install CodeQL Packages
5639
57-
For WHCP_21H2 and WHCP_22H2 branches:
58-
59-
1. If using Visual Studio 2022 17.8 or greater with WHCP_21H2 or WHCP_22H2 and CodeQL CLI version 2.15.4:
60-
61-
Follow the steps for "ALL OTHER BRANCHES." **Make sure to remove the CodeQL submodule if you still have an old version of the repo cloned.** CodeQL might try to use the queries in the submodule by default which will cause errors because of mismatched versions.
62-
63-
1. If using Visual Studio version 17.7 or below **AND** either WHCP_21H2 or WHCP_22H2 **AND** CodeQL VLI version 2.4.6 or 2.6.3:
64-
65-
Follow special instructions for WHCP_21H2 and WHCP_22H2 using VS17.7 at the end of this readme
66-
67-
68-
**For ALL OTHER BRANCHES:**
69-
70-
**Note:** It is no longer necessary to clone the Windows-Driver-Developer-Supplemental-Tools repo to use the queries for certification.
71-
72-
Download the correct version of the CodeQL packs from the Windows Hardware Compatibility Program Release Version Matrix:
40+
Download the correct version of the CodeQL packs. For special cases and more information see appendix.
7341
```
7442
codeql pack download microsoft/windows-drivers@<version>
7543
```
7644
7745
```
78-
codeql pack download codeql/cpp-queries@<version>
46+
codeql pack download microsoft/cpp-queries@<version>
7947
```
8048
8149
CodeQL will install the packs to the default directory `C:\Users\<current user>\.codeql\packages\microsoft\windows-drivers\<downloaded version>\`. Do not change this directory or move the installed pack.
8250
83-
For examples, if using WHCP_24H2, run the following command to download query the microsoft/windows-drivers pack:
84-
85-
```
86-
codeql pack download microsoft/windows-drivers@1.1.0
87-
```
88-
89-
90-
9151
1. Build your CodeQL database:
9252
9353
```
94-
D:\codeql-home\codeql>codeql database create <path to new database> --language=cpp --source-root=<driver parent directory> --command=<build command or path to build file>
54+
codeql database create <path to new database> --language=cpp --source-root=<driver parent directory> --command=<build command or path to build file>
9555
```
9656
Single driver example: `codeql database create D:\DriverDatabase --language=cpp --source-root=D:\Drivers\SingleDriver --command="msbuild /t:rebuild D:\Drivers\SingleDriver\SingleDriver.sln"`
9757
@@ -101,44 +61,36 @@ This repository contains open-source components for supplemental use in developi
10161
10262
1. Analyze your CodeQL database:
10363
104-
CodeQL's analysis output is provided in the form of a SARIF log file. For a human readable format, drop the SARIF file into [SARIF Viewer Website](https://microsoft.github.io/sarif-web-component/). (If there are violations, they will show up. If not, the page will not update.)
64+
CodeQL's analysis output is provided in the form of a SARIF log file. For a human readable format, drop the SARIF file into [SARIF Viewer Website](https://microsoft.github.io/sarif-web-component/) (If there are violations, they will show up. If not, the page will not update) or view using an extension in Visual Studio or Visual Studio Code.
10565
106-
CodeQL query suites are provided in the suites directory and contain the sets of all recommended and mustfix queries. The desired query suite file should be downloaded/copied locally.
107-
108-
1. Create a local copy of the desired query suite file:
109-
110-
* windows_driver_mustfix.qls
111-
* windows_driver_recommended.qls
66+
CodeQL query suites are provided in the windows-driver-suites directory and contain the sets of all recommended and mustfix queries. Both the recommended and mustfix queries must be run. Once the microsoft/windows-drivers pack is downloaded, these suites can be referenced relative to the pack name, as seen below.
11267
113-
2. To analyze a CodeQL database run the following command:
68+
1. To analyze a CodeQL database run the following command:
11469
```
115-
codeql database analyze --download <path to database> <path to query suite .qls file> --format=sarifv2.1.0 --output=<outputname>.sarif
70+
codeql database analyze <path to database> <path to query suite .qls file> --format=sarifv2.1.0 --output=<outputname>.sarif
11671
```
117-
**NOTE** The "--download" flag tells CodeQL to download dependencies before running the queries.
72+
Example:
73+
```codeql database analyze D:\DriverDatabase microsoft/windows-drivers:windows-driver-suites/recommended.qls --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif ```
74+
75+
**NOTE** The "--download" flag can be used to tell CodeQL to download dependencies before running the queries.
11876
119-
Specific versions, queries, or suites can be specified using the format `codeql database analyze <database> <scope>/<pack>@x.x.x:<path>`. For futher information, see the [CodeQL documentation](https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#using-a-codeql-pack-to-analyze-a-codeql-database).
77+
**NOTE** Specific versions, queries, or suites can be specified using the format `codeql database analyze <database> <scope>/<pack>@x.x.x:<path>`. For futher information, see the [CodeQL documentation](https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#using-a-codeql-pack-to-analyze-a-codeql-database).
12078
12179
122-
Example: `codeql database analyze --download D:\DriverDatabase suites/windows_driver_recommended.qls --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif `
123-
124-
_(Parameters: path to new database, query pack, format, output sarif file)_
125-
12680
12781
1. ***For WHCP Users Only***: Prepare to Create a Driver Verification Log (DVL):
12882
129-
Before you can create a DVL, you must copy your SARIF log file to the parent directory of your driver project. You can also modify your output location in the `codeql database analyze` step in order to skip this additional step. Once you have finished this step, please refer to the continued instructions at [CodeQL and the Static Tools Logo Test, Driver Verification Log DVL Consumption of SARIF Output](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/static-tools-and-codeql#driver-verification-log-dvl-consumption-of-sarif-output).
130-
```
131-
D:\codeql-home\codeql>copy <path to SARIF output file> <path to driver directory>
132-
```
133-
Example: `D:\codeql-home\codeql> copy D:\DriverAnalysis1.sarif D:\Drivers\SingleDriver`
83+
To create a DVL, your SARIF log file must be in the parent directory of your driver project. You can modify your output location in the `codeql database analyze` step or copy the file manyally
84+
85+
Please refer to the continued instructions at [CodeQL and the Static Tools Logo Test, Driver Verification Log DVL Consumption of SARIF Output](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/static-tools-and-codeql#driver-verification-log-dvl-consumption-of-sarif-output).
13486
13587
## Navigation
13688
13789
Windows drivers queries are in the `src/drivers` directory.
13890
13991
Non-driver Microsoft-specific queries provided by Microsoft are in the `src/microsoft` directory.
14092
141-
Query suites are located in the `suites` directory and contain the Must-Fix and Recommended-Fix suites used by the WHCP Program.
93+
Query suites are located in the `windows-driver-suites` directory and contain the Must-Fix and Recommended suites used by the WHCP Program.
14294
14395
14496
@@ -177,7 +129,36 @@ Use of Microsoft trademarks or logos in modified versions of this project must n
177129
Any use of third-party trademarks or logos are subject to those third-party's policies.
178130
179131
180-
## Special instructions for WHCP_21H2 and WHCP_22H2 using VS17.7 or below
132+
## Appendix
133+
134+
### Windows Hardware Compatibility Program Release Version Matrix
135+
For WHCP, these versions can be used in place of the latest versions specified above. These versions were the latest available at the time new WHCP requirements were released and can continue to be used for WHCP certifications. However, newer versions of CodeQL continue to be validated for use.
136+
| Release | CodeQL CLI version | microsoft/windows-drivers qlpack version| microsoft/cpp-queries version | codeql/cpp-queries version | Associated Repo Branch|
137+
|--------------------------|--------------------|-----------------------------------------|-------------------------------|-----------------------------|----------------------|
138+
| Windows Server 2022 | [2.4.6](https://github.com/github/codeql-cli-binaries/releases/tag/v2.4.6) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_21H2 |
139+
| Windows 11, version 22H2 | [2.6.3](https://github.com/github/codeql-cli-binaries/releases/tag/v2.6.3) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_22H2 |
140+
| Windows 11, version 23H2 | [2.6.3](https://github.com/github/codeql-cli-binaries/releases/tag/v2.6.3) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_22H2 |
141+
| Windows 11 | [2.4.6](https://github.com/github/codeql-cli-binaries/releases/tag/v2.4.6) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_21H2 |
142+
| Windows 11, version 24H2 | [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4) | 1.1.0 | N/A |0.9.0 | WHCP_24H2 |
143+
| Windows Server 2025 | [2.20.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.20.1) | 1.6.0 | 0.0.4 | N/A | <todo> |
144+
| Windows 11, version <todo> | [2.20.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.20.1) | 1.6.0 | 0.0.4 | N/A | <todo> |
145+
146+
147+
### Special instructions for for WHCP_21H2 and WHCP_22H2 branches:
148+
Visual Studio 17.8 broke compatibility with the older versions of CodeQL used in the WHCP_21H2 and WHCP_22H2 branches. [CodeQL CLI version 2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4) has been validated for use with WHCP 21H2 and WHCP 22H2 when using Visual Studio 17.8 or greater.
149+
150+
151+
1. If using Visual Studio 2022 17.8 or greater with WHCP_21H2 or WHCP_22H2 and CodeQL CLI version 2.15.4:
152+
153+
Follow regular steps, above. **Make sure to remove the CodeQL submodule if you still have an old version of the repo cloned.** CodeQL might try to use the queries in the submodule by default which will cause errors because of mismatched versions.
154+
155+
1. If using Visual Studio version 17.7 or below **AND** either WHCP_21H2 or WHCP_22H2 **AND** CodeQL VLI version 2.4.6 or 2.6.3:
156+
157+
Follow special instructions for WHCP_21H2 and WHCP_22H2 using VS17.7 at the end of this readme
158+
159+
### Special instructions for WHCP_21H2 and WHCP_22H2 using VS17.7 or below
160+
161+
181162
These instructions only apply when using both Visual Studio 17.7 or below along with CodeQL 2.6.3 or 2.4.6
182163
183164

‎src/qlpack.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
name: microsoft/windows-drivers
55
version: 1.6.0
66
dependencies:
7-
codeql/cpp-all: 4.2.0
8-
microsoft/cpp-queries: 0.0.4
7+
codeql/cpp-all: ^4.2.0
8+
microsoft/cpp-queries: ^0.0.4
99
suites: windows-driver-suites
1010
defaultSuiteFile: windows-driver-suites/recommended.qls
1111
extractor: cpp

0 commit comments

Comments
 (0)