Skip to content

Commit 72208d3

Browse files
jacob-ronstadtjacob-ronstadt
committed
Updating documentation for new version
1 parent 4246e2a commit 72208d3

1 file changed

Lines changed: 54 additions & 56 deletions

File tree

‎README.md‎

Lines changed: 54 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -4,42 +4,47 @@ This repository contains open-source components for supplemental use in developi
44

55
### For General 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 qlpack version | microsoft/cpp-queries version | codeql/cpp-queries version |Associated Repo Branch|
8+
|--------------------------|------------------------------------------|-------------------------------|-----------------------------|------------------------|
9+
| 2.20.1 | 1.5.0 | 0.0.2 | N/A | Main |
1010

1111
### For Windows Hardware Compatibility Program Use
1212

1313
### 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 |
14+
| Release | CodeQL CLI version | microsoft/windows-drivers qlpack version| microsoft/cpp-queries 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)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_21H2 |
17+
| 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 |
18+
| 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 |
19+
| 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 |
20+
| 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 |
21+
| Windows Server 2025 | [2.20.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.20.1) | 1.5.0 | 0.0.2 | N/A | WHCP_TODO |
22+
| Windows 11, version <todo> | [2.20.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.20.1) | 1.5.0 | 0.0.2 | N/A | WHCP_TODO |
2123

2224

25+
### For Testing the Latest in Development
2326

2427

28+
| CodeQL CLI version | microsoft/windows-drivers qlpack version | microsoft/cpp-queries version | codeql/cpp-queries version |Associated Repo Branch|
29+
|--------------------------|------------------------------------------|-------------------------------|-----------------------------|------------------------|
30+
| [Latest](https://github.com/github/codeql-cli-binaries/releases/latest) | [Latest](https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/pkgs/container/windows-drivers) | [Latest](https://github.com/orgs/microsoft/packages/container/package/cpp-queries) | N/A | Development |
31+
2532
## Quickstart
2633

2734
1. Create a directory where you can place the CodeQL CLI and the queries you want to use:
2835
```
2936
D:\> mkdir codeql-home
3037
```
3138
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-
39+
1. Download the CodeQL CLI
40+
3441
**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-
42+
43+
For the WHCP Program, use the CodeQL CLI version in accordance with the table above and Windows release you are certifying for
44+
1. Navigate to the [CodeQL CLI Release Page](https://github.com/github/codeql-cli-binaries/releases)
45+
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.),
46+
1. Extract the downloaded zip to the directory you created in the previous step.
47+
1. (Optional) Add the CodeQL install location to your PATH
4348
4449
1. Verify CodeQL is installed correctly by checking the version:
4550
```
@@ -54,20 +59,7 @@ This repository contains open-source components for supplemental use in developi
5459
5560
1. Install CodeQL Packages
5661
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-
6762
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.
7163
7264
Download the correct version of the CodeQL packs from the Windows Hardware Compatibility Program Release Version Matrix:
7365
```
@@ -86,7 +78,7 @@ This repository contains open-source components for supplemental use in developi
8678
codeql pack download microsoft/windows-drivers@1.1.0
8779
```
8880
89-
81+
For special cases, see appendix below.
9082
9183
1. Build your CodeQL database:
9284
@@ -101,44 +93,36 @@ This repository contains open-source components for supplemental use in developi
10193
10294
1. Analyze your CodeQL database:
10395
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.)
96+
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.
10597
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
98+
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.
11299
113-
2. To analyze a CodeQL database run the following command:
100+
1. To analyze a CodeQL database run the following command:
114101
```
115-
codeql database analyze --download <path to database> <path to query suite .qls file> --format=sarifv2.1.0 --output=<outputname>.sarif
102+
codeql database analyze <path to database> <path to query suite .qls file> --format=sarifv2.1.0 --output=<outputname>.sarif
116103
```
117-
**NOTE** The "--download" flag tells CodeQL to download dependencies before running the queries.
104+
Example:
105+
```codeql database analyze D:\DriverDatabase microsoft/windows-drivers:windows-driver-suites/recommended.qls --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif ```
118106
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).
107+
**NOTE** The "--download" flag can be used to tell CodeQL to download dependencies before running the queries.
108+
109+
**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).
120110
121111
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-
126112
127113
1. ***For WHCP Users Only***: Prepare to Create a Driver Verification Log (DVL):
128114
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`
115+
Tocreate 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
116+
117+
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).
134118
135119
## Navigation
136120
137121
Windows drivers queries are in the `src/drivers` directory.
138122
139123
Non-driver Microsoft-specific queries provided by Microsoft are in the `src/microsoft` directory.
140124
141-
Query suites are located in the `suites` directory and contain the Must-Fix and Recommended-Fix suites used by the WHCP Program.
125+
Query suites are located in the `windows-driver-suites` directory and contain the Must-Fix and Recommended-Fix suites used by the WHCP Program.
142126
143127
144128
@@ -177,7 +161,21 @@ Use of Microsoft trademarks or logos in modified versions of this project must n
177161
Any use of third-party trademarks or logos are subject to those third-party's policies.
178162
179163
180-
## Special instructions for WHCP_21H2 and WHCP_22H2 using VS17.7 or below
164+
## Appendix
165+
166+
### Special instructions for for WHCP_21H2 and WHCP_22H2 branches:
167+
168+
1. If using Visual Studio 2022 17.8 or greater with WHCP_21H2 or WHCP_22H2 and CodeQL CLI version 2.15.4:
169+
170+
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.
171+
172+
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:
173+
174+
Follow special instructions for WHCP_21H2 and WHCP_22H2 using VS17.7 at the end of this readme
175+
176+
### Special instructions for WHCP_21H2 and WHCP_22H2 using VS17.7 or below
177+
178+
181179
These instructions only apply when using both Visual Studio 17.7 or below along with CodeQL 2.6.3 or 2.4.6
182180
183181

0 commit comments

Comments
 (0)