WinDbg

https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/
Admin
WinDbg is a powerful debugger for Windows that analyzes crash dumps, debugs live user-mode and...
Tokens:874,887
Snippets:6,466
Trust Score:10
Update:1 day ago
Show doc for...
Tokens:
Raw
### .querypackages example output

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/debugging-a-uwp-app-using-windbg

Example output of .querypackages showing multiple installed packages with their details and states.

```text
0:000> .querypackages
...
Package Full Name: Microsoft.MicrosoftSolitaireCollection_3.9.5250.0_x64__8wekyb3d8bbwe
Package Display Name: Microsoft Solitaire Collection
Version: 3.9.5250.0
Processor Architecture: x64
Publisher: CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US
Publisher Display Name: Microsoft Studios
Install Folder: C:\Program Files\WindowsApps\Microsoft.MicrosoftSolitaireCollection_3.9.5250.0_x64__8wekyb3d8bbwe
Package State: Unknown
AppId: App

Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
Package Display Name: HelloWorld
Version: 1.0.0.0
Processor Architecture: x86
Publisher: CN=user1
Publisher Display Name: user1
Install Folder: c:\users\user1\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX
Package State: Running
AppId: App
Executable: HelloWorld.exe

Package Full Name: Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x86__8wekyb3d8bbwe
Package Display Name: BackgroundTask C++ sample
Version: 1.0.0.0
Processor Architecture: x86
Publisher: CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US
Publisher Display Name: Microsoft Corporation
Install Folder: C:\Users\user1\Documents\Visual Studio 2015\Projects\Background_task_sample\C++\Debug\BackgroundTask.Windows\AppX
Package State: Unknown
AppId: BackgroundTask.App

...
```

--------------------------------

### Start Remote.exe Server with CDB

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/starting-a-remote-exe-session

Example of starting a Remote.exe Server with CDB, using the general syntax.

```text
remote /s "CDB [options]" MyBrokenApp 
```

--------------------------------

### Start Remote.exe Server with KD

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/starting-a-remote-exe-session

Example of starting a Remote.exe Server with KD, using the general syntax.

```text
remote /s "KD [options]" MyBrokenBox 
```

--------------------------------

### Query installed packages and create package app

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/debugging-a-uwp-app-using-windbg

Shows how to verify a package is installed using .querypackages and then launch and attach to the app using .createpackageapp. The .querypackages output is shown as an example.

```windbg
.querypackages 
...

Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
Package Display Name: HelloWorld
Version: 1.0.0.0
Processor Architecture: x86
Publisher: CN=user1
Publisher Display Name: user1
Install Folder: c:\users\user1\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX
Package State: Unknown
AppId: App

...
```

```windbg
.createpackageapp e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 App
```

--------------------------------

### .createpackageapp example

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/debugging-a-uwp-app-using-windbg

Example that enables debugging and launches the HelloWorld app using its package name and AppId.

```text
.createpackageapp e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 App
```

--------------------------------

### Convert Start VPN to Address Using ? Command

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/mapping-symbols-when-the-peb-is-paged-out

Use the ? (Evaluate Expression) command to multiply the starting virtual page number (0x37d9bd3e) by the page size (0x2000) to get the actual starting address. The output shows the result in decimal and hexadecimal.

```kd
kd> ? 37d9bd3e*2000 
Evaluate expression: 7676040298496 = 000006fb`37a7c000
```

--------------------------------

### .enablepackagedebug example

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/debugging-a-uwp-app-using-windbg

Example that enables debugging for the HelloWorld package.

```text
.enablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
```

--------------------------------

### .querypackage example output

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/debugging-a-uwp-app-using-windbg

Example output of .querypackage showing package details and state (Running).

```text
0:000> .querypackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
Package Display Name: HelloWorld
Version: 1.0.0.0
Processor Architecture: x86
Publisher: CN=user1
Publisher Display Name: user1
Install Folder: c:\users\user1\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX
Package State: Running
AppId: App
Executable: HelloWorld.exe
```

--------------------------------

### Install.cmd Parameter Usage Example

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/symproxy-automated-installation

Example command line for running the Install.cmd script with the required parameters: virtual directory path, username, and password for the application pool.

```plaintext
Install.cmd D:\SymStore\Symbols CONTOSO\SymProxyService Pa$$word
```

--------------------------------

### Command-line syntax for recommended connection methods

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/activating-a-smart-client

Syntax for starting a smart client with the -premote option using recommended, more secure protocols: spipe, ssl, and com. The protocol must match the process server's protocol.

```plaintext
Debugger -premote spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password] [Options]

Debugger -premote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password] [Options]

Debugger -premote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password] [Options]

Debugger -premote com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] [Options]
```

--------------------------------

### Get help on debugger commands with .hh

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/getting-started-with-windows-debugging

Use the .hh command followed by a command name to get help on any debugger command while debugging. The examples show getting help on breakpoint commands (.hh bp) and call stack commands (.hh k).

```debugger
.hh bp # Get help on breakpoint commands
.hh k # Get help on call stack commands
```

--------------------------------

### uninitializeScript function example

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/javascript-debugger-scripting

Called when a script is unlinked and getting ready to unload. Its job is to undo imperative object model changes and destroy cached objects. This example logs a message when the function is called.

```javascript
function uninitializeScript()
{
    // Add code here that you want to run every time the script is unloaded. 
    // We will just send a message to indicate that function was called.
    host.diagnostics.debugLog("***> uninitialize was called\n");
}
```

--------------------------------

### Start KD kernel debugging over USB 3.0

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/setting-up-a-usb-3-0-debug-cable-connection

Command to start a kernel debugging session with KD using a USB 3.0 debug cable. Replace TargetName with the target name created during setup.

```text
kd /k usb:targetname=<TargetName>
```

--------------------------------

### Sample QEMU x64 Windows VM Launch Script

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/setting-up-qemu-kernel-mode-debugging-using-exdi

Example batch script for launching a Windows x64 VM on QEMU. It sets up machine parameters, CPU, BIOS, graphics, USB, drive, and network options. Replace the disk and CDROM paths with your own. The script ends with the QEMU executable invocation.

```batch
    REM
    REM  This script is used to run a Windows x64 VM on QEMU that is hosted by a Windows x64 host system
    REM  The Host system is a PC with Intel(R) Xeon(R) CPU.
    REM
    set EXECUTABLE=qemu-system-x86_64
    set MACHINE=-m 6G -smp 4

    REM No acceleration
    REM generic cpu emulation.
    REM to find out which CPU types are supported by the QEMU version on your system, then run:
    REM	 qemu-system-x86_64.exe -cpu help
    REM the see if your host system CPU is listed
    REM

    set CPU=-machine q35 

    REM Enables x64 UEFI-BIOS that will be used by QEMU :
    set BIOS=-bios "C:\Program Files\qemu\Firmware\OVMF.fd"

    REM  Use regular GFX simulation
    set GFX=-device ramfb -device VGA 
    set USB_CTRL=-device usb-ehci,id=usbctrl
    set KEYB_MOUSE=-device usb-kbd -device usb-tablet

    REM # The following line enable the full-speed HD controller (requires separate driver)
    REM # Following line uses the AHCI controller for the Virtual Hard Disk:
    set DRIVE0=-device ahci,id=ahci -device ide-hd,drive=disk,bus=ahci.0

    REM
    REM This will set the Windows VM x64 disk image that will be launched by QEMU
    REM The disk image is in the qcow2 format accepted by QEMU.
    REM You get the .qcow2 image, once you get the VHDX Windows VM x64 image 
    REM and apply the script to inject the virtio x64 drivers and then run the 
    REM the QEMU tool to convert the .VHDX image to .qcow2 format
    REM 	i.e. 
    REM	qemu-img convert -c -p -O qcow2 Windows_VM_VHDX_with_injected_drivers_file.vhdx file.qcow2
    REM file : points to the specified qcow2 image path.
    REM
    set DISK0=-drive id=disk,file="C:\Program Files\qemu\MyQEMUFile.qcow2",if=none

    REM
    REM for kdnet on, then best option:
    REM   NETWORK0="-netdev user,id=net0,hostfwd=tcp::53389-:3389,hostfwd=tcp::50001-:50001 -device virtio-net,netdev=net0,disable-legacy=on"
    REM
    REM Create a mapping for the RDP service from port 3389 to 3589.
    REM
    set NETHOST=-netdev user,id=net0,hostfwd=tcp::3589-:3389
    set NETGUEST=-device e1000,netdev=net0

    REM # The following line should enable the Daemon (instead of interactive)
    set DAEMON=-daemonize"
    %EXECUTABLE% %MACHINE% %CPU% %BIOS% %GFX% %USB_CTRL% %DRIVE0% %DISK0% %NETHOST% %NETGUEST%
```

--------------------------------

### Start WinDbg kernel debugging over USB 3.0

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/setting-up-a-usb-3-0-debug-cable-connection

Command to start a kernel debugging session with WinDbg using a USB 3.0 debug cable. Replace TargetName with the target name created during setup.

```text
windbg /k usb:targetname=<TargetName>
```

--------------------------------

### Driver replacement map file example

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/mapping-driver-files

Example of a driver replacement map file. Each replacement is a three-line block: 'map', old driver path, new driver path. Comments start with '#' and blank lines are allowed, but cannot break up a map block.

```text
# Use the # for comments like this one
map
\Systemroot\system32\drivers\videoprt.sys
e:\MyNewDriver\binaries\videoprt.sys
map
\Systemroot\system32\mydriver.sys
\\myserver\myshare\new_drivers\mydriver0031.sys

# This is replacing a beep driver
map
\??\c:\windows\system32\beep.sys
\\myserver\myshare\new_drivers\new_beep.sys
```

--------------------------------

### .activatepackagebgtask command syntax and example

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/debugging-a-uwp-app-using-windbg

Enables debugging and launches a UWP background task. The syntax is shown first, followed by an example using a specific package name and background task ID.

```windbg
 .activatepackagebgtask <PLMPackageName> <bgTaskId>
```

```windbg
.activatepackagebgtask Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x64__8wekyb3d8bbwe {C05806B1-9647-4765-9A0F-97182CEA5AAD}
```

--------------------------------

### PowerShell script to configure and launch EXDI debugger

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/exdi-xml-configuration-files

This script automates the setup and launch of the Windows Debugger with EXDI. It stops dllhost.exe processes that may lock files, installs the EXDI server if not present, edits the EXDI configuration XML, sets required environment variables, and starts the debugger with EXDI connection arguments. It uses helper functions like Find-PathToWindbgX, Test-ParameterValidation, Test-ExdiServerInstalled, Install-ExdiServer, Get-ExdiInstallPath, and Edit-ExdiConfigFile which are expected to be defined elsewhere.

```powershell
Function Stop-ExdiContainingDllHosts
{
    $DllHostPids = Get-Process dllhost | ForEach-Object { $_.Id }
    foreach ($DllHostPid in $DllHostPids)
    {
        $DllHostExdiDlls = Get-Process -Id $DllHostPid -Module | Where-Object { $_.FileName -like "*ExdiGdbSrv.dll" }
        if ($DllHostExdiDlls.Count -ne 0)
        {
            Write-Verbose "Killing dllhost.exe with pid $DllHostPid (Contained instance of ExdiGdbSrv.dll)"
            Stop-Process -Id $DllHostPid -Force
        }
    }
}

#endregion

#region Script

# Apply defaults for $DebuggerPath before Parameter validation
if (-not $DebuggerPath)
{
    $DebuggerPath = Find-PathToWindbgX
}

Test-ParameterValidation

# look clean up dllhost.exe early since it can hold a lock on files which
# need to be overwritten
if (-not $DontTryDllHostCleanup)
{
    Stop-ExdiContainingDllHosts
}

if (-not $(Test-ExdiServerInstalled))
{
    if (-not $ExdiDropPath)
    {
        throw "ExdiServer is not installed and -ExdiDropPath is not valid"
    }

    $ExdiInstallDir = Join-Path -Path "$([System.IO.Path]::GetDirectoryName($DebuggerPath))" -ChildPath "exdi"
    Install-ExdiServer -InstallFrom "$ExdiDropPath" -InstallTo "$ExdiInstallDir"
}

$SystemRegistersFilepath = Join-Path -Path "$([System.IO.Path]::GetDirectoryName($(Get-ExdiInstallPath)))" -ChildPath "systemregisters.xml"
$ExdiConfigFilepath      = Join-Path -Path "$([System.IO.Path]::GetDirectoryName($(Get-ExdiInstallPath)))" -ChildPath "exdiConfigData.xml"

# Calculate implied parameters
$HeuristicScanSize = if ($PreNTAppDebugging) { "0xffe" } else { "0xfffe" }
$ArchitectureFamily = switch($Architecture)
{
    x64   { "ProcessorFamilyx64" }
    x86   { "ProcessorFamilyx86" }
    arm64 { "ProcessorFamilyARM64" }
}

# Path is evaluated relative to the relevant ExdiTarget's ExdiGdbServerConfigData node in the xml schema
$SettingsToChange = @(
    [pscustomobject]@{ Path = 'GdbServerConnectionParameters.Value.HostNameAndPort' ; Value = "${HostName}:$GdbPort" },
    [pscustomobject]@{ Path = 'ExdiGdbServerTargetData.targetArchitecture'          ; Value = "$Architecture" },
    [pscustomobject]@{ Path = 'ExdiGdbServerTargetData.targetFamily'                ; Value = "$ArchitectureFamily" },
    [pscustomobject]@{ Path = 'ExdiGdbServerTargetData.heuristicScanSize'           ; Value = "$HeuristicScanSize" },
    [pscustomobject]@{ Path = 'displayCommPackets'                                  ; value = "no" }
)
Edit-ExdiConfigFile -ExdiFilePath "$ExdiConfigFilepath" -ExdiTargetType "$ExdiTarget" -XmlSettingPathValueList $SettingsToChange

# Set env vars for debugger
[System.Environment]::SetEnvironmentVariable('EXDI_GDBSRV_XML_CONFIG_FILE',"$ExdiConfigFilepath")
[System.Environment]::SetEnvironmentVariable('EXDI_SYSTEM_REGISTERS_MAP_XML_FILE',"$SystemRegistersFilepath")

$DebuggerArgs = @("-v", "-kx exdi:CLSID={29f9906e-9dbe-4d4b-b0fb-6acf7fb6d014},Kd=Guess,DataBreaks=Exdi")
Write-Verbose "DebuggerPath = $DebuggerPath"
Start-Process -FilePath "$DebuggerPath" -ArgumentList ($DebuggerArgs + $ExtraDebuggerArgs)

#endregion
```

--------------------------------

### .resumepackage command syntax and example

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/debugging-a-uwp-app-using-windbg

Resumes a suspended UWP application. The syntax is shown first, followed by an example using a specific package full name.

```windbg
.resumepackage <PLMPackageName> 
```

```windbg
.resumepackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8
```

--------------------------------

### Start debugger on BOXB with -premote and -server

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/symbols-in-the-middle

Starts the debugger on the middle machine BOXB, connecting to the process server on BOXA via -premote and exposing a debugging server via -server. The example uses PID 400 and symbol path G:\MySymbols.

```plaintext
cdb -server npipe:pipe=NearPipe -premote npipe:server=BOXA,pipe=FarPipe -v -y g:\mysymbols -p 400
```

--------------------------------

### Example of launching the SDKSamples.BackgroundTask code under the debugger

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/debugging-a-uwp-app-using-windbg

This example shows the windbg command with a specific package name and background task ID for the SDKSamples.BackgroundTask sample.

```plaintext
windbg.exe -plmPackage Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x64__8wekyb3d8bbwe -plmBgTaskId {ee4438ee-22db-4cdd-85e4-8ad8a1063523}
```

--------------------------------

### Example: Enable debug and set network host and port

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/setting-up-a-network-debugging-connection

Example commands using a specific host IP and port. This is the same as the generic version but with concrete values.

```plaintext
bcdedit /debug on
bcdedit /dbgsettings net hostip:192.168.1.100 port:50000
```

--------------------------------

### Remote Server Sample Usage

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/remote-server-syntax

Examples of using the remote command to start server sessions with different options, such as specifying a command, session name, colors, user permissions, and visibility flags.

```plaintext
remote /s "i386kd -v" TestSession
remote /s "cmd" "My Remote Session" /f white /b black /u Server01\Administrators
remote /s "ntsd -d -g -x" DebugIt /-v
remote /q Server01
```

--------------------------------

### Compute Number of Pages and Size in Bytes

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/mapping-symbols-when-the-peb-is-paged-out

These commands compute the number of pages in the range by subtracting the start VPN from the end VPN and adding 1, then multiply the page count by the page size to get the size in bytes. The outputs show the results.

```kd
kd> ? 37d9bd3e-37d9bd30+1 <--   computes the number of pages
Evaluate expression: 15 = 00000000`0000000f
```

```kd
kd> ? f*2000
Evaluate expression: 122880 = 00000000`0001e000
```

--------------------------------

### Batch file for remote debugging session setup

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/remote-exe-batch-files

Sets environment variables for the debug port (COM2), baud rate (19200), symbol path, and log file, then starts remote.exe with the kernel debugger. Requires remote.exe to be in the same directory or in the system path.

```batch
set _NT_DEBUG_PORT=com2
set _NT_DEBUG_BAUD_RATE=19200
set _NT_SYMBOL_PATH=c:\winnt\symbols
set _NT_LOG_FILE_OPEN=c:\temp\debug.log
remote /s "KD -v" debug
```

--------------------------------

### Example command using Svchost2.exe

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/preparing-to-debug-the-service-application

Example command that sets the binary path to use Svchost2.exe with the same parameters as the original.

```batch
sc config MyService binPath= "%SystemRoot%\System32\svchost2.exe -k LocalServiceNoNetwork"
```

--------------------------------

### WinDbg postmortem debugger registry values

Source: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/enabling-postmortem-debugging

Example registry values created by running 'windbg.exe -I'. The Debugger value uses -p %ld -e %ld -g to pass the process ID and event handle, and Auto is set to 1 to start the debugger automatically.

```registry
Debugger = "<Path>\WinDbg -p %ld -e %ld -g"
Auto = 1
```
Tokens:
Raw