diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 28727ac..a97c3a7 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -92,5 +92,4 @@ jobs: run: cargo +${{ matrix.rust_toolchain }} install --git https://github.com/microsoft/windows-drivers-rs.git cargo-wdk --branch main --rev 5b9aa0a14e385daf5217c0f5232bcd4d3f4780a6 --locked --force - name: Build and Package Sample Drivers with cargo-wdk - run: cargo +${{ matrix.rust_toolchain }} wdk build --profile ${{ matrix.cargo_profile }} --target-arch ${{ matrix.target_triple.arch }} - continue-on-error: true # cargo-wdk build fails for a known reason + run: cargo +${{ matrix.rust_toolchain }} wdk build --sample --profile ${{ matrix.cargo_profile }} --target-arch ${{ matrix.target_triple.arch }} diff --git a/tools/dv/kmdf/fail_driver_pool_leak/README.md b/tools/dv/kmdf/fail_driver_pool_leak/README.md index 52c89d9..1dd2f47 100644 --- a/tools/dv/kmdf/fail_driver_pool_leak/README.md +++ b/tools/dv/kmdf/fail_driver_pool_leak/README.md @@ -1,23 +1,22 @@ -# Fail_Driver_Pool_Leak Sample +# Fail_Driver_Pool_Leak Sample Driver -This sample KMDF Fail Driver demonstrates the capabilities and features of **Driver Verifier** and the **Device Fundamentals Tests**. +The `fail_driver_pool_leak` sample demonstrates running the [Device Fundamentals Tests](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/device-fundamentals-tests) and enabling the [Driver Verifier](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/driver-verifier) for a Rust driver. We have intentionally injected a pool leak fault in the driver by allocating a global buffer using WDM's `ExAllocatePool2` function and not freeing this buffer (using `ExFreePool`) anywhere in the driver. This fault, which is not caught at compile time, can be detected by running the Device Fundamentals Tests and also by enabling the Driver Verifier on the driver. -It allocates a pool of memory to a global buffer when a supported device is added by the PnP Manager and intentionally does not free it before the driver is unloaded. This memory leak fault is a system vulnerability that could lead to security and performance issues and bad user experience. - -By enabling Driver Verifier on this driver, this pool leak violation can be caught before the driver is unloaded and with an active KDNET session, the bug can be analyzed further. - -NOTE: The driver uses WDM's ExAllocatePool2 API directly to allocate memory for its buffer. Ideally, such allocations should be freed by using ExFreePool API. A cleaner way to manage memory in a WDF Driver is to use [wdfmemory](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdfmemory/) - - -## Steps to reproduce the issue +## Steps 1. Clone the repository and navigate to the project root. -2. Build the driver project using the following command in a WDK environment (or EWDK prompt) - +2. Install [Clang](https://clang.llvm.org/get_started.html) + * Easy install option: + ``` + winget install LLVM.LLVM + ``` + +3. Build the driver project using the following command in an [EWDK environment](https://learn.microsoft.com/en-us/legal/windows/hardware/enterprise-wdk-license-2022) - ``` cargo make ``` -3. Prepare a target system (a Hyper-V VM can be used) for testing +4. Prepare a target system (a Hyper-V VM can be used) for testing Follow the below steps to setup the test system - 1. Disable Secure boot and start the system @@ -37,11 +36,11 @@ NOTE: The driver uses WDM's ExAllocatePool2 API directly to allocate memory for shutdown -r -t 0 ``` -4. Copy the driver package, available under ".\target\debug\fail_driver_pool_leak_package" to the target system. +5. Copy the driver package, available under ".\target\debug\fail_driver_pool_leak_package" to the target system. -5. Copy "devgen.exe" from host to the target system. Alternatively you may install WDK on the target system and add the directory that contains "devgen.exe" to PATH variable. +6. Copy "devgen.exe" from host to the target system. Alternatively you may install WDK on the target system and add the directory that contains "devgen.exe" to PATH variable. -6. Install the driver package and create the device in the target system using the below commands - +7. Install the driver package and create the device in the target system using the below commands - ``` cd "fail_driver_pool_leak_package" devgen.exe /add /bus ROOT /hardwareid "fail_driver_pool_leak" @@ -50,7 +49,7 @@ NOTE: The driver uses WDM's ExAllocatePool2 API directly to allocate memory for pnputil.exe /add-driver .\fail_driver_pool_leak.inf /install ``` -7. Enable Driver Verifier for 'fail_driver_pool_leak.sys' driver package +8. Enable Driver Verifier for 'fail_driver_pool_leak.sys' driver package 1. Open run command prompt (Start + R) or cmd as administator and run "verifier" 2. In the verifier manager, - Create Standard Settings @@ -59,23 +58,23 @@ NOTE: The driver uses WDM's ExAllocatePool2 API directly to allocate memory for - Finish - Restart the system -8. Follow the steps in https://learn.microsoft.com/en-us/windows-hardware/drivers/develop/how-to-test-a-driver-at-runtime-from-a-command-prompt to run tests against the device managed by this driver +9. Follow the steps in https://learn.microsoft.com/en-us/windows-hardware/drivers/develop/how-to-test-a-driver-at-runtime-from-a-command-prompt to run tests against the device managed by this driver -9. Install TAEF and WDTF on the test computer and run the following test - +10. Install TAEF and WDTF on the test computer and run the following test - ``` cd "C:\Program Files (x86)\Windows Kits\10\Testing\Tests\Additional Tests\x64\DevFund" TE.exe .\Devfund_PnPDTest_WLK_Certification.dll /P:"DQ=DeviceID='ROOT\DEVGEN\{PASTE-DEVICE-ID-HERE}'" --rebootResumeOption:Manual ``` -10. The test will lead to a Bugcheck and a BlueScreen on the target system with the following error - +11. The test will lead to a Bugcheck and a BlueScreen on the target system with the following error - ``` DRIVER_VERIFIER_DETECTED_VIOLATION (c4) - ``` - The logs will be available in WinDbg - run ```!analyze -v``` for detailed bugcheck report - run ```!verifier 3 fail_driver_pool_leak.sys``` for info on the allocations that were leaked that caused the bugcheck. + ``` + Run ```!analyze -v``` for detailed bugcheck report + + Run ```!verifier 3 fail_driver_pool_leak.sys``` for info on the allocations that were leaked that caused the bugcheck. -11. (Alternatively), the bugcheck can be observed when all the devices managed by this driver are removed, i.e, when the driver is unloaded from the system. +12. (Alternatively), the bugcheck can be observed when all the devices managed by this driver are removed, i.e, when the driver is unloaded from the system. You may use pnputil/devcon to enumerate and remove the devices - ``` # To enumerate the devices @@ -86,9 +85,8 @@ NOTE: The driver uses WDM's ExAllocatePool2 API directly to allocate memory for ### References -- [Driver Verifier](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/driver-verifier) -- [Device Fundamentals Tests](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/device-fundamentals-tests) - [TAEF](https://learn.microsoft.com/en-us/windows-hardware/drivers/taef/getting-started) - [WDTF](https://learn.microsoft.com/en-us/windows-hardware/drivers/wdtf/wdtf-runtime-library) - [Testing a driver at runtime](https://learn.microsoft.com/en-us/windows-hardware/drivers/develop/how-to-test-a-driver-at-runtime-from-a-command-prompt) - [Using WDF to Develop a Driver](https://learn.microsoft.com/en-us/windows-hardware/drivers/wdf/using-the-framework-to-develop-a-driver) +- [wdfmemory](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdfmemory/) \ No newline at end of file diff --git a/tools/dv/kmdf/fail_driver_pool_leak/fail_driver_pool_leak.inx b/tools/dv/kmdf/fail_driver_pool_leak/fail_driver_pool_leak.inx index ba33969..afe081a 100644 --- a/tools/dv/kmdf/fail_driver_pool_leak/fail_driver_pool_leak.inx +++ b/tools/dv/kmdf/fail_driver_pool_leak/fail_driver_pool_leak.inx @@ -7,8 +7,8 @@ [Version] Signature = "$WINDOWS NT$" -Class = SoftwareComponent -ClassGuid = {5c4c3332-344d-483c-8739-259e934c9cc8} +Class = Sample +ClassGuid = {78A1C341-4539-11d3-B88D-00C04FAD5171} Provider = %ProviderString% PnpLockDown = 1