microsoft / windbg-samples

Sample extensions, scripts, and API uses for WinDbg.

This is a collection of extensions and sample scripts for extending WinDbg. We'll be adding more samples and extensions over time.

Getting Started

To load JavaScript extensions:

1. Download the script file locally.
2. Ensure you have a recent version of WinDbg - WinDbg Preview from the Microsoft Store will always be up to date. Otherwise you can use one of the other methods listed here to install it.
3. Start your debugging session.
4. The JavaScript extension (JSProvider) should load automatically. You can validate it's loaded by running the .scriptproviders command and checking if JavaScript is on the list.
   • If JavaScript isn't on the list, run .load jsprovider
5. Run .scriptload <path to script> or .scriptrun <path to script>. The README for each script has more detailed usage information.

We have more information on our JavaScript support at https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/javascript-debugger-scripting. If you want to learn more about a script you can open in it WinDbg Preview by hitting the "Scripting" ribbon and clicking "Open Script...". It has intellisense support for JavaScript and NatVis and you can load scripts by hitting "Execute" in the scripting ribbon.

Contribute

All the samples and extensions we are publishing are open to contributions of fixes and improvements. At this point we aren't open to accepting new scripts and extensions from the community, but you can make your own repo and share them that way.

windbg-samples's Issues

exdigdb server support for non-HW debuggers

I'm not sure whether my subject is clear.

From the documentation, https://github.com/microsoft/WinDbg-Samples/blob/master/Exdi/exdigdbsrv/doc/ExdiGdbSrv_readme.md#exdi-gdbserver--getting-started - I see that exdigdb is supported only for hardware debuggers (e.g. JTAG-based, or GdbServer-JTAG based).

The question is does it work for regular remote gdb debugging for software applications - https://gcc.gnu.org/onlinedocs/gcc-4.7.4/gnat_ugn_unw/Remote-Debugging-using-gdbserver.html ?

If yes, can you please update the documentation. If not, can you please add support?

Why the mess of abstractions?

How did Microsoft take the process basics like [CPU registers, memory, threads, breakpoints, stack, tracing, exceptions] into this mess of confusing infinite abstractions for debugger plugins/extensions?

And of all language choices why JavaScript?
Who actually wants to use JavaScript unless they really have to (like web developers)?
Although in a twisted sense, so obsessed with abstractions, it's also fitting to force people to use a class-based language.

How to interface JS through TCP

I want to make a TCP connection between my JS script and another process, is that possible? I know that I can read/write files, but that is not really convenient as a means of talking to another process compared to a TCP connection [over localhost], if no networking is possible, what is the ideal solution for this?

SymbolBuilder fails in a kernel debugger

Trying to create a symbol builder in a live kernel debugger session fails with unspecified error:

dx Debugger.Utility.SymbolBuilder.CreateSymbols("ntkrnlmp.exe")
Error: Unspecified error (0x80004005)

This happens regardless of the module used. The same DLL works fine in a user mode debugging session

Wana an EXE or MSI installer for WinDbg-Preview

I want to install WinDbg-Preview on Windows Server 2019, which has no Store Environment. Provide EXE or MSI installer would be a good idea.

Question: Data Model Client Library Accessible To Rust

The client library DbgModelClientEx.h is an excellent abstraction to (relatively) quickly create powerful data model abstractions but is limited to c++ only. Are there future plans to support Rust bindings so when one wants to write Windbg Rust extensions, they have excellent support for creating/consuming data models without the COM madness?

Tasks

Beta Give feedback

No tasks being tracked yet.

Symbol builder fails to import global data

If you set "AutoImportSymbols = true" for an underlying PRIVATE PDB with global data, any of the global data is not imported correctly because the importer does not handle the "DataIsGlobal" data kind.

Symbol Builder fails to import transitively self-referential function types

When using "AutoImportSymbols = true", the symbol builder dynamically imports types and data symbols from an underlying PDB. Unfortunately, this auto import is broken for any function type symbol which has a transitive self-reference within it. If some UDT has a pointer-to-function... and the signature for that function has a return type or a parameter which refers back to that same signature (e.g.: a similar pointer-to-function), the import fails...

The first attempt to import the function type starts.... it recurses... hits the transitive reference... which attempts to import again... which succeeds (generating a new symbol with an id of 'A') ... as the recursion unwinds, the importer creates a NEW FunctionTypeSymbol at the outer level with an id of 'B'). When the importer sees that one PDB ID (for the function type symbol) maps to two DIFFERENT symbol builder IDs (both 'A' and 'B'), it fails with a catastrophic failure leaving the import half complete.

UDTs solve this issue by creating a shell of the UDT upfront and filling it in as the import progresses. Function types need to do a similar thing to deal with this.

Advanced Kernel Debug

It's their anyway to Attach WinDbg at BOOTMGR stage(Before ntoskern.exe start?)

Or May I Debug the Kernel Code during its dieing (To Research How BSOD Actually do, such as paint VGA blue screen)

Redistribution of "ext.dll"

I've recently been looking into using Microsoft.Debugging.Platform.DbgX to perform remote analysis of minidump files. It's working great but I need to include "ext.dll" in order to use the "!analyze -v" command (which conveniently gives us all the information we need).

Are there any plans to include this in the 'Microsoft.Debugging.Platform.DbgX' package? If not, is "ext.dll" licensed for redistribution? This concern is currently blocking the adoption of DgbX.

Unable to build SimpleIntroClientLibrary (Cpp)

I'm trying to build the SimpleIntroClientLibrary sample, and I'm running into some issues.

First off, I retargeted the solution to the 10.0.18362.0 SDK and the v142 platforms tools since that's all I had installed. After that I had to make a few changes to get things building farther:

• Edited SimpleIntro.h
  • Added #include <new> to deal with an error around the use of bad_alloc
  • Changed #include "DbgModelClientEx.h" to #include <DbgModelClientEx.h> and remove/install the nuget package. (not sure why I had to do this) I changed this back and it works now, so maybe I just had to fiddle with the nuget package.

This cleared most of the errors, but there's one left that I'm not sure how to resolve.

I'm getting a C2039 error from the use of ExtractString in DbgModelClientEx.h. I'm told that 'ExtractString': is not a member of 'Debugger::DataModel::ClientEx::Details'... but it clearly is when looking at the header.

Any ideas as to what might be the problem?

Symbol Builder: PDB auto import of "<unnamed-*>" symbols can result in mismatches and import failure

Repro:

• Open a Win11 KD
• dx @$s = Debugger.Utility.SymbolBuilder.CreateSymbols("nt", new {AutoImportSymbols=true})
• .reload
• !vad

When doing PDB auto-import, we do lookup "by name" for types to see if someone manually created a type before we try to import one of the same "name". Unfortunately, various things assign "<unnamed-tag"> or "<unnamed-*>" to "unnamed" symbols (e.g.: non-named unions/structures/etc...).

These names aren't unique... and when we attempt to look up that "name" and find something, it's the WRONG TYPE.

This repo is missing important files

There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

Merge this pull request

Windbg and Usermode Code, Build-in commands

Hello,

I am working with Windebugger and a User Mode Driver sample code(attached for reference). Created an executable file of the Sample Driver Code by altering the Settings in Visual Studio and connected with Windebugger. Symbol file path is set to the folder where the Pdb file is located.
After reload, new executable command tab opens.

`#include "driver.h"

VOID Unload(IN PDRIVER_OBJECT DriverObject){
DbgPrint("Driver unload \r\n");
}
NTSTATUS DriverEntry(IN PDRIVER_OBJECT DriverObject, IN PUNICODE_STRING RegistryPath){
DbgPrint("Hello world\r\n");
return STATUS_SUCCESS;
}`

Ran few build-in commands in Windbg such as lm,kp,dv
During execution of dv, received the following error

dv
Unable to enumerate locals, Win32 error 0n318
Private symbols (symbols.pri) are required for locals.
Type ".hh dbgerr005" for details.
windbg> .hh dbgerr005

Questions:

1. Which private symbol to be added and how to add them?
2. Can I able to print the driver code output in Windbg?
3. Kindly share with some usermode driver code samples for Windbg to get familiarise

Thanks in advance
Ranjani N

unrelated question about windbg itself

uh...
if this is a new ui for windbg i've gotta wonder what it looked like before. it looks like a nice windows 8 era win32 app:

can y'all update whatever ui framework you're using?

SymBuilder Fails to Compile With Undefined Type Error From DbgModelClientEx.h

When trying to build SymBuilder the following error occurs on compilation:

1>...\WinDbg-Samples\TargetComposition\SymBuilder\packages\Microsoft.Debugging.DataModel.CppLib.1.0.2\build\native\include\DbgModelClientEx.h(3576,5): error C2027: use of undefined type 'Debugger::DataModel::ClientEx::Object'
1>...\WinDbg-Samples\TargetComposition\SymBuilder\packages\Microsoft.Debugging.DataModel.CppLib.1.0.2\build\native\include\DbgModelClientEx.h(423,7): message : see declaration of 'Debugger::DataModel::ClientEx::Object'

Assuming it's something templately within SymBuilder that it's not liking as the latest DbgModelClientEx.h (same as the one used for SymBuilder) builds fine with a separate WinDbg extension. Specifically, PackValues is where the error points to.

Update: I only get this error with the latest build tools. 2019 build tools (v142) does not experience this issue. So the issue does indeed stem directly from DbgModelClientEx.h as with the new toolset, I cannot build other extensions with it.

ImageInfo.js doesn't display module's image info

I followed the Usage guide, but it doesn't seem to show the PE image info when I run dx @$curprocess.Modules[0].

0:000> .scriptload C:\Users\[myusername]\Documents\GitHub\WinDbg-Samples\ImageInfo\ImageInfo.js
JavaScript script successfully loaded from 'C:\Users\[myusername]\Documents\GitHub\WinDbg-Samples\ImageInfo\ImageInfo.js'
0:000> dx @$curprocess.Modules[0]
@$curprocess.Modules[0] : cmd.exe
    BaseAddress      : 0x7ff684150000
    Name             : cmd.exe
    Size             : 0x65000
    Contents        

Debugger client version: 1.0.1810.02001
Debugger engine version: 10.0.18239.1000
OS: Windows 10 x64 17763.134

Did I misunderstand how this script work? How do I use it to display PE image info, like import table?

Thank you!

multiple JavaScript scripts that reference each other?

console.js

class console{
    static log(...args) {
        host.diagnostics.debugLog(`${args}\n`);
    }
}
module.exports = console;

test.js

import {console} from "./console";
console.log("hello???");

How can multiple JavaScript scripts be used in combination, or is there a similar compiler (merge)?

Something like frida-compile?

No Samples in the repository

there is no samples in the repository :)

Are there any ways to troubleshoot gallery loading?

I am including a BinaryComponent in my manifest, based on the manifest.1.xml that ships with the SDK. I am able to .load and use the extension fine on my own but the ExtensionPackage that contains it is not being loaded. I can see from procmon that it is not attempting to open the file. I've looked at the Logs window but I don't see anything relevant. Is there any other logging I can enable/find that might help me discover the problem?

SimpleIntroRawCOM Build Errors in DbgModel.h

I hit some build errors when trying to build the DbgModel.h sample.

1>------ Build started: Project: SimpleIntroRawCOM, Configuration: Debug x64 ------
1>HelloExtension.cpp
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7133): error C3861: 'ClassicCom': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7185): error C3861: 'Make': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7208): error C3861: 'ClassicCom': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7248): error C3861: 'Make': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7286): error C3861: 'ClassicCom': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7321): error C3861: 'Make': identifier not found
1>SimpleIntroExtension.cpp
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7133): error C3861: 'ClassicCom': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7185): error C3861: 'Make': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7208): error C3861: 'ClassicCom': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7248): error C3861: 'Make': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7286): error C3861: 'ClassicCom': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7321): error C3861: 'Make': identifier not found
1>Utility.cpp
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7133): error C3861: 'ClassicCom': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7185): error C3861: 'Make': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7208): error C3861: 'ClassicCom': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7248): error C3861: 'Make': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7286): error C3861: 'ClassicCom': identifier not found
1>c:\program files (x86)\windows kits\10\include\10.0.17763.0\um\dbgmodel.h(7321): error C3861: 'Make': identifier not found
1>Generating Code...
1>Done building project "SimpleIntroRawCOM.vcxproj" -- FAILED.
========== Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

Looking at DblModel.h, it does seem like the references to Make and ClassicCom are insufficiently qualified. Oddly, Intellisense seemed to find the definitions through those usages just fine.

I was able to successfully build by adding these lines to SimpleIntro.h just before the dbgmodel.h include:

static constexpr Microsoft::WRL::RuntimeClassType ClassicCom =
	Microsoft::WRL::RuntimeClassType::ClassicCom;
using Microsoft::WRL::Make;

But I'm guessing that's not supposed to be required.

Using Visual Studio 2017, SDK 10.0.17763, and winver 17763.

Pass SynchronizationContext to Dbgx.DebugEngine

Hi,

I'm loving the 'Microsoft.Debugging.Platform.DbgX' package and seeing some early successes from it's use.

One frustration however is the use of the SynchronizationContext.Current static value. Would it be possible to pass the SynchronizationContext to use into the DebugEngine constructor? This would simplify it's use and facilite synchronization with other frameworks such as RX.

BTW, I'd happily submit a PR for this but Microsoft.Debugging.Platform.DbgX doesn't seem to be open-source (links from the Nuget page direct to Microsoft.Windows.SDK.Contracts).

Thanks,
Ian

Error loading CodeFlow extension

I'm trying to load the CodeFlow.js extension using .scriptload, and I get this error: Error (0x80004005): Cannot modify debugger object model for 'functionAlias (dflow)'.

I am able to successfully load the ImageInfo.js extension in the same manner though.

JsProvider.d.ts issue

I can see that "host.namespace.Debugger.Utility.*" functionality does work in WinDbg, but it is not included in the 'JsProvider.d.ts' that came with my Windows Kit (it has most of the stuff, but does not have the [Utility] part, why? And why can't we just get the "JsProvider.d.ts" here in this repo?
[I tried the Scripting ribbon, it also does not suggest "Utility" after "host.namespace.Debugger." this is probably a bug?]

Symbol builder fails to import bit fields correctly

If you "AutoImportSymbols = true", any UDTs with bit fields end up omitting the bit field data on the import which makes the structures less than usable.

Writing tests for debugger scripts

I'm new in the Javascript world. Is there any common knowledge here on how you go about writing unit tests for debug scripts?

Do you have any internal frameworks or setups that can be shared?

Ideally in a TypeScript setting!

Error: Unknown exception

Hi,
I have imported successfully the script CodeFlow.js via .scriptload but I'm not able to get the control flow from certain address using "dx Debugger.Utility.Code.TraceDataFlow(address)" or its alias !dflow address. All I get are errors like:

Error: Unknown exception [at CodeFlow (line 734 col 9)]

Not sure if the address format is correct (0x00414122, 00414122) or the error is caused by another problem. I have tried with addresses and symbols from different processes (x86 and 64) with no luck. Could you please set any example along with the output. I haven't found anything.

I'm using WinDBG Preview (1.0.1910.03003) from Windows 10.
Thank you

New sample repo refers to 'The debugger's target composition API' and DbgServices.h. How can these be acquired?

I have the latest Windows SDK installed with debugging tools but this header is not present. Not seeing anything searching the web. Where can we find the headers, etc... for this API?

How is help text added to function aliases?

With

dx -r1 Debugger.State.FunctionAliases

I get

    dflow            [!dflow [<address>]
Shows the instructions of the function containing [<address>] which influence the source operands of that instruction.]
    dis              [!dis [<address>]
Disassembles instructions starting at [<address>] using the data model disassembler.]
    printExceptionStack        <- my function

When registering my own function, it only shows the name of the function.
How can I add help texts?

Regards

Windbg Preview
Debugger client version: 1.2202.7001.0
Debugger engine version: 10.0.22549.1000

can jsProvider handle event?

I want to find a javascript api that can handle event(such as breakpoint triggered), and I have read jsProvider.d.ts.