Merge branch 'development' into user/nated-msft/pack-requirement-updates

Author: NateD-MSFT

README.md

@@ -1,34 +1,28 @@
 # Windows Driver Developer Supplemental Tools
-
 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).
 
-### For General Use or Windows Hardware Compatibility Program Use
-
+### For General Use
 |  CodeQL CLI Version      | microsoft/windows-drivers CodeQL Pack Version | microsoft/cpp-queries CodeQL Pack Version | Associated Repo Branch|
 |--------------------------|------------------------------------------|-------------------------------|-----------------------------|
-|  2.15.4 or greater* | [Latest Stable Version](https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/pkgs/container/windows-drivers) | 0.0.4 | Main |
+|  2.24.1 or greater* | [Latest Stable Version](https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/pkgs/container/windows-drivers) | 0.0.4 | Main |
 
-#### Validated CodeQL Versions For Use with WHCP
-|  CodeQL CLI Version      |
-|--------------------------|
-|  2.23.3 |
-|  2.21.4 |
-|  2.21.2 |
-|  2.20.1 |
-|  2.15.4 |
 
 When using the precompiled pack, please use the most recent CodeQL CLI version listed above.
 
-*See appendix for more information
+### For WHCP Use (26H1)
+|  CodeQL CLI Version      | microsoft/windows-drivers CodeQL Pack Version | microsoft/cpp-queries CodeQL Pack Version | Associated Repo Branch|
+|--------------------------|------------------------------------------|-------------------------------|-----------------------------|
+|  2.24.1 | [1.8.2](https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/pkgs/container/windows-drivers/655126590?tag=1.8.2) | 0.0.4 | Main |
+
+See appendix for information on CLI+query version combinations for previous Windows releases and WHCP programs.
 
-### For Testing the Latest in Development
 
+### For Testing the Latest in Development
 |  CodeQL CLI Version      | microsoft/windows-drivers CodeQL Pack Version | microsoft/cpp-queries CodeQL Pack Version | Associated Repo Branch|
 |--------------------------|------------------------------------------|-------------------------------|-----------------------------|
 | [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 |
 
 ## Quickstart
-
 1. Create a directory where you can place the CodeQL CLI and the queries you want to use:
     ```
     mkdir codeql-home
@@ -98,9 +92,7 @@ Windows drivers queries are in the `src/drivers` directory.
 
 Non-driver Microsoft-specific queries provided by Microsoft are in the `src/microsoft` directory.
 
-Query suites are located in the `windows-driver-suites` directory and contain the Must-Fix and Recommended suites used by the WHCP Program.
-
-
+Query suites are located in the `windows-driver-suites` directory and contain the Must-Fix, Must-Run, and Recommended suites used by the WHCP Program.
 
 ## Contributing
 This project welcomes contributions, feedback, and suggestions!
@@ -114,6 +106,7 @@ We are in the process of setting up pull request checks, but to ensure our requi
 1. Add a .qhelp file for any new queries or update the existing one if there is new functionality for the end user.
 
 #### Note
+
 All "Must-Fix" suite queries must have been run on the Windows Drivers Samples, and any bugs found as a result must be filed prior to being merged into the suite.
 
 Most contributions require you to agree to a
@@ -150,7 +143,16 @@ The versions below are the minumum required versions for WHCP certification. New
 | 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 |
 | Windows Server 2025      |  [2.20.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.20.1)		                                                                        |  1.8.0                          | 0.0.4 | N/A                          | WHCP_25H2 |
 | Windows 11, version 25H2 |  [2.20.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.20.1)		                                                                        |  1.8.0                          | 0.0.4 | N/A                          | WHCP_25H2 |
+| Windows 11, version 26H1 |  [2.24.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.24.1)		                                                                        |  1.8.2                          | 0.0.4 | N/A                          | WHCP_26H1 |
 
+#### Previously validated CodeQL Versions For Use with WHCP
+|  CodeQL CLI Version      |
+|--------------------------|
+|  2.23.3 |
+|  2.21.4 |
+|  2.21.2 |
+|  2.20.1 |
+|  2.15.4 |
 
 ### Special instructions for for WHCP_21H2 and WHCP_22H2 branches:
 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. 
@@ -165,11 +167,8 @@ Visual Studio 17.8 broke compatibility with the older versions of CodeQL used in
     Follow special instructions for WHCP_21H2 and WHCP_22H2 using VS17.7 at the end of this readme
  
 ### Special instructions for WHCP_21H2 and WHCP_22H2 using VS17.7 or below
-   
-    
 These instructions only apply when using both Visual Studio 17.7 or below along with CodeQL 2.6.3 or 2.4.6
 
-
 1. Install CodeQL version as indicated in above steps.
 
 1. 

src/drivers/apps/queries/experimental/UnsafeCallInGlobalInit/UnsafeCallInGlobalInit.md

@@ -0,0 +1,51 @@
+# UnsafeCallInGlobalInit
+When using a DLL, it is frequently the case that any static construtors are called from DllMain. There are a number of constraints that apply to calling other functions from DllMain. In particular, it is possible to create memory leaks if the DLL is loaded and unloaded dynamically. SysAllocString is an example of a function that, in this case, could cause a memory leak.
+
+
+## Recommendation
+The ideal DllMain would be just an empty stub. However, given the complexity of many applications, this is generally too restrictive. A good rule of thumb for DllMain is to postpone as much initialization as possible. Lazy initialization increases robustness of the application because this initialization is not performed while the loader lock is held. Also, lazy initialization enables you to safely use much more of the Windows API.
+
+
+## Example
+DLLMain function
+
+```c
+ 
+		BOOL WINAPI DllMain(
+		HINSTANCE hinstDLL,  // handle to DLL module
+		DWORD fdwReason,     // reason for calling function
+		LPVOID lpvReserved )  // reserved
+		{
+			// Perform actions based on the reason for calling.
+			switch( fdwReason ) 
+			{ 
+				case DLL_PROCESS_ATTACH:
+				// Initialize once for each new process.
+				// Return FALSE to fail DLL load.
+					break;
+
+				case DLL_THREAD_ATTACH:
+				// Do thread-specific initialization.
+					break;
+
+				case DLL_THREAD_DETACH:
+				// Do thread-specific cleanup.
+					break;
+
+				case DLL_PROCESS_DETACH:
+				
+					if (lpvReserved != nullptr)
+					{
+						break; // do not do cleanup if process termination scenario
+					}
+					
+				// Perform any necessary cleanup.
+					break;
+			}
+			return TRUE;  // Successful DLL_PROCESS_ATTACH.
+		}
+		
+```
+
+## References
+* [ C28637 ](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/28637-calling-function-in-a-global-initializer-is-unsafe)

src/drivers/apps/queries/experimental/UnsafeCallInGlobalInit/UnsafeCallInGlobalInit.qhelp

@@ -47,15 +47,9 @@
 					break;
 			}
 			return TRUE;  // Successful DLL_PROCESS_ATTACH.
-		}
 		}]]>
-		
+		</sample>
 	</example>
-	<semmleNotes>
-		<p>
-
-		</p>
-	</semmleNotes>
 	<references>
 		<li>
 			<a href="https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/28637-calling-function-in-a-global-initializer-is-unsafe">

src/drivers/general/DriverAlertSuppression.md

@@ -0,0 +1 @@
+# Driver alert suppression

src/drivers/general/queries/AnnotationSyntax/AnnotationSyntax.md

@@ -0,0 +1,44 @@
+# Annotation syntax error
+A syntax error in the annotations was found for the property in the function.
+
+
+## Recommendation
+This warning indicates an error in the annotations, not in the code that is being analyzed.
+
+
+## Example
+_IRQL_saves_global_ not applied to entire function
+
+```c
+ 
+		// FAIL 
+		VOID test1(
+			_IRQL_saves_global_(OldIrql, *Irql) PKIRQL Irql)
+		{
+			// ...
+			;
+		}
+		
+```
+_Kernel_clear_do_init_ not used with either "yes" or "no"
+
+```c
+ 
+		// FAIL
+		_Function_class_(DRIVER_ADD_DEVICE)
+			_IRQL_requires_(PASSIVE_LEVEL)
+				_IRQL_requires_same_
+			_Kernel_clear_do_init_(IRP_MJ_CREATE)
+		NTSTATUS
+		test4(
+			_In_ PDRIVER_OBJECT DriverObject,
+			_In_ PDEVICE_OBJECT PhysicalDeviceObject)
+
+		{
+			; // do nothing
+		}
+		
+```
+
+## References
+* [ C28266 ](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/28266-function-property-syntax-error)

src/drivers/general/queries/AnnotationSyntax/AnnotationSyntax.qhelp

@@ -21,7 +21,6 @@
 		{
 			// ...
 			;
-		}
 		}]]>
 		</sample>
 		<p>
@@ -40,14 +39,9 @@
 
 		{
 			; // do nothing
-		}
 		}]]>
 		</sample>
 	</example>
-	<semmleNotes>
-		<p>
-		</p>
-	</semmleNotes>
 	<references>
 		<li>
 			<a href="https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/28266-function-property-syntax-error">

src/drivers/general/queries/CurrentFunctionTypeNotCorrect/CurrentFunctionTypeNotCorrect.md

@@ -0,0 +1,10 @@
+# Current function type not correct (C28101)
+This function appears to be an unannotated DriverEntry function
+
+
+## Recommendation
+DriverEntry functions should be declared using the DRIVER_INITIALIZE function typedef.
+
+
+## References
+* [ C28101 ](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/28101-wrong-function-type)

src/drivers/general/queries/DefaultPoolTag/DefaultPoolTag.md

@@ -0,0 +1,30 @@
+# Use of default pool tag in memory allocation (C28147)
+Memory should not be allocated with the default tags of ' mdW' or ' kdD'.
+
+
+## Recommendation
+The driver is specifying a default pool tag. Because the system tracks pool use by pool tag, only those drivers that use a unique pool tag can identify and distinguish their pool use.
+
+
+## Example
+In this example, the driver allocates memory with the default tag:
+
+```c
+ 
+		PVOID InternalNonPagedAllocator(SIZE_T size) {
+			return ExAllocatePool3(POOL_FLAG_NON_PAGED, size, ' mdW');
+		}
+		
+```
+The driver should use a custom tag instead:
+
+```c
+ 
+		PVOID InternalNonPagedAllocator(SIZE_T size) {
+			return ExAllocatePool3(POOL_FLAG_NON_PAGED, size, 'vdxE');
+		}
+		
+```
+
+## References
+* [ C28147 warning - Windows Drivers ](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/28147-improper-use-of-default-pool-tag)

src/drivers/general/queries/DriverEntrySaveBuffer/DriverEntrySaveBuffer.md

@@ -0,0 +1,85 @@
+# Driver Entry Save Buffer
+The DriverEntry routine should save a copy of the argument, not the pointer, because the I/O Manager frees the buffer
+
+
+## Recommendation
+The driver's DriverEntry routine is saving a copy of the pointer to the buffer instead of saving a copy of the buffer. Because the buffer is freed when the DriverEntry routine returns, the pointer to the buffer will soon be invalid.
+
+
+## Example
+
+```c
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+// driver_snippet.c
+//
+#include "ntstrsafe.h"
+
+#define SET_DISPATCH 1
+// Template. Not called in this test.
+void top_level_call() {}
+
+PUNICODE_STRING g_RP1;
+
+NTSTATUS
+DriverEntryBad(
+    PDRIVER_OBJECT DriverObject,
+    PUNICODE_STRING RegistryPath
+    )
+{
+    g_RP1 = RegistryPath;
+    return 0;
+}
+
+
+UNICODE_STRING g_RP2;
+
+NTSTATUS
+DriverEntryGood(
+    PDRIVER_OBJECT DriverObject,
+    PUNICODE_STRING RegistryPath
+    )
+{
+    return RtlUnicodeStringCopy(&g_RP2,RegistryPath); 
+}
+
+
+UNICODE_STRING g_RP3;
+
+NTSTATUS
+DriverEntryGood2(
+    PDRIVER_OBJECT DriverObject,
+    PUNICODE_STRING RegistryPath
+    )
+{
+    g_RP3 = *RegistryPath;
+    return 0;
+}
+
+typedef struct _test_struct {
+    int a;
+    PUNICODE_STRING g_RP4;
+    char b;
+} test_struct;
+
+test_struct g_test_struct;
+
+NTSTATUS
+DriverEntryBad2(
+    PDRIVER_OBJECT DriverObject,
+    PUNICODE_STRING RegistryPath
+    )
+{
+    test_struct* localPtr = &g_test_struct;
+    localPtr->g_RP4 = RegistryPath;
+    return 0;
+}
+```
+
+## References
+* [ C28131 ](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/28131-driverentry-saving-pointer-to-buffer)
+
+## Semmle-specific notes
+This rule reports a false positive when the registry path pointer is saved for use in functions such as HidRegisterMinidriver
+