`Pkg.WinDMP` — API for parsing Windows crash dump files¶

Overview¶

The Pkg.WinDMP module contains the API for parsing Windows crash dump files. It transparently supports every common dump variant: kernel summary, kernel triage, kernel bitmap, full kernel dumps (x86/x64), user full dumps, user minidumps and Windows CE dumps. Identification of the dump layout is automatic, so the same code works across all variants.

Inspecting a Dump File¶

The following code example shows how to identify the dump layout, read the exception record and, for kernel dumps, the bug check information:

from Pro.Core import *
from Pkg.WinDMP import *

def inspectDump(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = WinDMPObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    print("type:", obj.GetDumpTypeInfo())
    print("64-bit:", obj.Is64Bit())
    print("has physical memory:", obj.HasPhysicalMemory())
    exc = obj.GetExceptionStruct()
    if not exc.IsNull():
        print(obj.GetExceptionDescr(exc))
    if obj.IsKernelDump():
        bci = obj.GetBugCheckInfo()
        print(bci.output(is64=obj.Is64Bit()))

Enumerating Modules and Threads¶

The following code example iterates over the module and thread lists of a minidump and reads the PDB association and stack view for the first thread:

from Pro.Core import *
from Pkg.WinDMP import *

def enumerate(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = WinDMPObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    # modules
    sdesc = obj.FindDumpStream("ModuleListStream")
    modlist = obj.ParseCommonDumpStreamList(sdesc) if sdesc else None
    if modlist:
        for i in range(modlist.count()):
            m = modlist.at(i)
            ai = obj.GetModulePDBAssociationInfo(m)
            print("module:", m.Uns("BaseOfImage"), ai.name, ai.uid)
    # threads
    sdesc = obj.FindDumpStream("ThreadListStream")
    tl = obj.ParseCommonDumpStreamList(sdesc) if sdesc else None
    if tl and tl.count() > 0:
        t = tl.at(0)
        ci = obj.GetThreadContextInfo(obj.GetThreadContext(t))
        if ci:
            print("ip:0x%X sp:0x%X" % (ci.ip, ci.sp))
            sv = obj.GetStackViewFromThread(t)
            if sv:
                for i in range(min(sv.count(), 16)):
                    print(sv.stringAddress(i), sv.stringValue(i))

Module API¶

Pkg.WinDMP module API.

Classes:

BugCheckInfo()

Describes the bug check (stop code) information extracted from a kernel dump.

DumpStreamList()

Simple iterator over a homogeneous list of entries inside a minidump stream.

StackView()

Read-only view over a thread stack region.

SystemInfo()

Describes basic information about the system that produced the dump.

ThreadContextInfo()

Describes the essential registers extracted from a thread context structure.

WinDMPObject()

This class represents a Windows crash dump file.

class BugCheckInfo¶

Describes the bug check (stop code) information extracted from a kernel dump.

Instances are returned by WinDMPObject.GetBugCheckInfo().

Attributes:

args

The four bug check parameters.

cause

Human-readable explanation of the likely cause.

code

The bug check code.

descr

Human-readable description of the bug check.

name

The symbolic name of the bug check (e.g.

params

Human-readable description for each of the four parameters.

Methods:

output([with_cause, is64])

Formats the bug check information as a printable multi-line string.

args: Tuple[int, int, int, int]¶

The four bug check parameters.

cause: str¶

Human-readable explanation of the likely cause.

code: int¶

The bug check code.

descr: str¶

Human-readable description of the bug check.

name: str¶

The symbolic name of the bug check (e.g. "IRQL_NOT_LESS_OR_EQUAL").

output(with_cause: bool = True, is64: bool = True) → str¶

Formats the bug check information as a printable multi-line string.

Parameters

with_cause (bool) – When True, the cause description is appended.

is64 (bool) – When True, parameters are formatted as 64-bit values; otherwise as 32-bit values.

Returns

Returns the formatted description.

Return type

str

params: List[str]¶

Human-readable description for each of the four parameters.

class DumpStreamList¶

Simple iterator over a homogeneous list of entries inside a minidump stream.

Instances are returned by WinDMPObject.ParseCommonDumpStreamList(). The iterator exposes both random access (at()) and sequential access (next()).

Methods:

at(i)

Returns the entry at the given index, positioning the shared struct on it.

count()

Returns the number of entries in the list.

hasNext()

Indicates whether more entries are available for sequential iteration.

next()

Advances the sequential cursor and returns the current entry.

reset()

Resets the sequential iteration cursor back to the first entry.

at(i: int) → Optional[Pro.Core.CFFStruct]¶

Returns the entry at the given index, positioning the shared struct on it.

Parameters

i (int) – The zero-based entry index.

Returns

Returns the entry struct on success; otherwise returns None when the index is out of range.

Return type

Optional[CFFStruct]

count() → int¶

Returns the number of entries in the list.

Returns

Returns the entry count.

Return type

int

hasNext() → bool¶

Indicates whether more entries are available for sequential iteration.

Returns

Returns True if next() will return an entry.

Return type

bool

next() → Optional[Pro.Core.CFFStruct]¶

Advances the sequential cursor and returns the current entry.

Returns

Returns the next entry struct; otherwise returns None when the end of the list is reached.

Return type

Optional[CFFStruct]

reset() → None¶

Resets the sequential iteration cursor back to the first entry.

class StackView¶

Read-only view over a thread stack region.

Instances are returned by WinDMPObject.GetStackViewFromContextInfo() and WinDMPObject.GetStackViewFromThread().

Methods:

address(i)

Returns the virtual address of the slot at the given index.

count()

Returns the number of pointer-sized slots in the stack region.

isStackPointer(i)

Indicates whether the slot at the given index is the current stack pointer.

stackAddress()

Returns the base virtual address of the stack region.

stackPointer()

Returns the stack pointer (Esp/Rsp) recorded in the thread context.

stackSize()

Returns the size of the stack region in bytes.

stringAddress(i)

Returns the formatted address for the slot at the given index.

stringFormat()

Returns the printf-style format string that matches the pointer size.

stringValue(i)

Returns the formatted value for the slot at the given index.

value(i)

Returns the value stored at the slot.

address(i: int) → int¶

Returns the virtual address of the slot at the given index.

Parameters

i (int) – The zero-based slot index.

Returns

Returns the virtual address.

Return type

int

count() → int¶

Returns the number of pointer-sized slots in the stack region.

Returns

Returns the slot count.

Return type

int

isStackPointer(i: int) → bool¶

Indicates whether the slot at the given index is the current stack pointer.

Parameters

i (int) – The zero-based slot index.

Returns

Returns True when the slot address equals the stack pointer.

Return type

bool

stackAddress() → int¶

Returns the base virtual address of the stack region.

Returns

Returns the base address.

Return type

int

stackPointer() → int¶

Returns the stack pointer (Esp/Rsp) recorded in the thread context.

Returns

Returns the stack pointer.

Return type

int

stackSize() → int¶

Returns the size of the stack region in bytes.

Returns

Returns the size in bytes.

Return type

int

stringAddress(i: int) → str¶

Returns the formatted address for the slot at the given index.

Parameters

i (int) – The zero-based slot index.

Returns

Returns the formatted address.

Return type

str

stringFormat() → str¶

Returns the printf-style format string that matches the pointer size.

Returns

Returns "%016X" on 64-bit or "%08X" on 32-bit.

Return type

str

stringValue(i: int) → Optional[str]¶

Returns the formatted value for the slot at the given index.

Parameters

i (int) – The zero-based slot index.

Returns

Returns the formatted value, or None if the slot could not be read.

Return type

Optional[str]

value(i: int) → Optional[int]¶

Returns the value stored at the slot.

Parameters

i (int) – The zero-based slot index.

Returns

Returns the pointer-sized value read from the slot, or None if the value could not be read.

Return type

Optional[int]

class SystemInfo¶

Describes basic information about the system that produced the dump.

Instances are returned by WinDMPObject.GetSystemInfo().

Attributes:

asm

Carbon assembly type identifier (e.g.

is64

Indicates whether the dumped system was 64-bit.

asm: int¶

Carbon assembly type identifier (e.g. CarbonType_I_x86 or CarbonType_I_x64).

is64: bool¶

Indicates whether the dumped system was 64-bit.

class ThreadContextInfo¶

Describes the essential registers extracted from a thread context structure.

Instances are returned by WinDMPObject.GetThreadContextInfo().

Attributes:

asm

Carbon assembly type identifier matching the context architecture.

ip

Instruction pointer (Eip on x86, Rip on x64).

is64

Indicates whether the context is 64-bit.

sp

Stack pointer (Esp on x86, Rsp on x64).

asm: int¶

Carbon assembly type identifier matching the context architecture.

ip: int¶

Instruction pointer (Eip on x86, Rip on x64).

is64: bool¶

Indicates whether the context is 64-bit.

sp: int¶

Stack pointer (Esp on x86, Rsp on x64).

class WinDMPObject¶

Bases: Pro.Core.CFFObject

This class represents a Windows crash dump file.

The class transparently supports all common dump variants: kernel summary, kernel triage, kernel bitmap, full kernel dumps (x86/x64), user full dumps, user minidumps and Windows CE dumps. Identification of the dump layout and parsing of the streams is deferred until Initialize() or LoadDumpFileInfo() is called.

Methods:

FindDumpStream(name)

Finds a minidump-style stream by its symbolic name (e.g.

GetBugCheckInfo()

Returns the bug check (stop code) information for the dump.

GetDumpInfo()

Returns a multi-line human-readable summary of the dump (system information, memory layout, flags, etc.).

GetDumpTypeInfo()

Returns a short human-readable description of the dump layout (category and summary).

GetExceptionDescr(s)

Formats a human-readable description of an exception record.

GetExceptionStreamStruct(sdesc)

Returns the exception record from an explicit ExceptionStream descriptor.

GetExceptionStruct()

Returns the exception record associated with the dump.

GetHeader()

Returns the main dump header structure.

GetMemoryInfo()

Returns information about the memory regions described by the dump (minidumps only).

GetModulePDBAssociationInfo(module)

Reads the PDB debug information (CodeView NB10 or RSDS record) associated with a module entry.

GetRawMemory()

Returns the raw memory stream (physical memory for kernel dumps, or the memory dump container for user dumps).

GetStackViewFromContextInfo(ci)

Builds a stack view covering the entire memory region above the stack pointer in ci.

GetStackViewFromThread(thread[, from_sp])

Builds a stack view for a thread list entry.

GetSystemInfo()

Returns basic system information (bitness and assembly type).

GetSystemMemory()

Returns the stream backing the system memory object.

GetSystemObject()

Returns the system memory object, which exposes physical (or virtual, when a directory table base is available) memory as a CFFObject.

GetThreadContext(entry)

Returns the CPU context structure (_CONTEXT_X86 or _CONTEXT_X64) referenced by a thread list entry.

GetThreadContextFromHeader(hdr)

Returns the CPU context structure embedded in a user dump header.

GetThreadContextInfo(s)

Extracts the essential registers (instruction pointer, stack pointer, bitness) from a context structure.

HasPhysicalMemory()

Indicates whether the dump exposes physical memory (kernel dumps with a valid DirectoryTableBase).

Is64Bit()

Indicates whether the dumped system is 64-bit.

IsKernelDump()

Indicates whether the dump is a kernel-mode dump.

LoadDumpFileInfo()

Identifies the dump format and initializes the internal memory objects.

ParseCommonDumpStreamList(sdesc)

Parses a simple list-oriented minidump stream into a DumpStreamList iterator.

FindDumpStream(name: str) → Optional[Dict[str, Any]]¶

Finds a minidump-style stream by its symbolic name (e.g. "ThreadListStream", "ModuleListStream", "ExceptionStream").

Parameters

name (str) – The stream name.

Returns

Returns a descriptor dictionary for the stream, or None when the stream is not present.

Return type

Optional[Dict[str, Any]]

GetBugCheckInfo() → Pkg.WinDMP.BugCheckInfo ¶

Returns the bug check (stop code) information for the dump.

Returns

Returns a BugCheckInfo describing the stop code. For non-kernel dumps returns an empty descriptor.

Return type

BugCheckInfo

GetDumpInfo() → str¶

Returns a multi-line human-readable summary of the dump (system information, memory layout, flags, etc.).

Returns

Returns the dump summary string.

Return type

str

GetDumpTypeInfo() → str¶

Returns a short human-readable description of the dump layout (category and summary).

Returns

Returns the dump type description.

Return type

str

GetExceptionDescr(s: Pro.Core.CFFStruct) → str¶

Formats a human-readable description of an exception record.

Handles both the exception record embedded in user dump headers and the one from the ExceptionStream. Decodes well-known exception codes and annotates access-violation parameters.

Parameters

s (CFFStruct) – The exception struct.

Returns

Returns the formatted description. Returns an empty string when the record is invalid.

Return type

str

GetExceptionStreamStruct(sdesc: Dict[str, Any]) → Pro.Core.CFFStruct ¶

Returns the exception record from an explicit ExceptionStream descriptor.

Parameters

sdesc (Dict[str, Any]) – The stream descriptor returned by FindDumpStream().

Returns

Returns the exception struct. On failure returns an invalid CFFStruct.

Return type

CFFStruct

GetExceptionStruct() → Pro.Core.CFFStruct ¶

Returns the exception record associated with the dump.

For kernel dumps this is the record embedded in the main header; for user dumps it is read from the ExceptionStream.

Returns

Returns the exception struct. On failure returns an invalid CFFStruct.

Return type

CFFStruct

See also GetExceptionDescr().

GetHeader() → Pro.Core.CFFStruct ¶

Returns the main dump header structure.

The exact layout depends on the dump type (e.g. _MINIDUMP_HEADER for minidumps, DUMP_HEADER32/DUMP_HEADER64 for kernel dumps).

Returns

Returns the header struct. On failure returns an invalid CFFStruct.

Return type

CFFStruct

GetMemoryInfo() → Optional[Dict[str, Any]]¶

Returns information about the memory regions described by the dump (minidumps only).

Returns

Returns a dictionary describing the memory layout, or None when the dump has no memory information stream.

Return type

Optional[Dict[str, Any]]

GetModulePDBAssociationInfo(module: Pro.Core.CFFStruct) → Pro.Core.PDBAssociationInfo ¶

Reads the PDB debug information (CodeView NB10 or RSDS record) associated with a module entry.

Parameters

module (CFFStruct) – A module entry (from ParseCommonDumpStreamList() on ModuleListStream).

Returns

Returns the PDBAssociationInfo. When no debug information is present, PDBAssociationInfo.uid is empty.

Return type

PDBAssociationInfo

GetRawMemory() → Pro.Core.NTContainer ¶

Returns the raw memory stream (physical memory for kernel dumps, or the memory dump container for user dumps).

Returns

Returns the raw memory stream, or None when no memory data is available.

Return type

NTContainer

GetStackViewFromContextInfo(ci: Pkg.WinDMP.ThreadContextInfo) → Pkg.WinDMP.StackView ¶

Builds a stack view covering the entire memory region above the stack pointer in ci.

Parameters

ci (ThreadContextInfo) – The thread context info.

Returns

Returns the StackView.

Return type

StackView

GetStackViewFromThread(thread: Pro.Core.CFFStruct, from_sp: bool = True) → Optional[Pkg.WinDMP.StackView]¶

Builds a stack view for a thread list entry.

Parameters

thread (CFFStruct) – The thread list entry (from ParseCommonDumpStreamList() on ThreadListStream).

from_sp (bool) – When True, the view starts at the thread’s stack pointer; when False, it covers the thread’s saved Stack range.

Returns

Returns the StackView, or None when the thread context is not recognized.

Return type

Optional[StackView]

GetSystemInfo() → Pkg.WinDMP.SystemInfo ¶

Returns basic system information (bitness and assembly type).

Returns

Returns the SystemInfo describing the dumped system.

Return type

SystemInfo

GetSystemMemory() → Optional[Pro.Core.NTContainer]¶

Returns the stream backing the system memory object.

Returns

Returns the memory stream, or None when no memory data is available.

Return type

Optional[NTContainer]

See also GetSystemObject().

GetSystemObject() → Optional[Pro.Core.CFFObject]¶

Returns the system memory object, which exposes physical (or virtual, when a directory table base is available) memory as a CFFObject.

Returns

Returns the system memory object, or None when no memory data is available.

Return type

Optional[CFFObject]

GetThreadContext(entry: Pro.Core.CFFStruct) → Pro.Core.CFFStruct ¶

Returns the CPU context structure (_CONTEXT_X86 or _CONTEXT_X64) referenced by a thread list entry.

Parameters

entry (CFFStruct) – The thread list entry.

Returns

Returns the context struct. On failure returns an invalid CFFStruct.

Return type

CFFStruct

See also GetThreadContextInfo(), GetThreadContextFromHeader().

GetThreadContextFromHeader(hdr: Pro.Core.CFFStruct) → Pro.Core.CFFStruct ¶

Returns the CPU context structure embedded in a user dump header.

Parameters

hdr (CFFStruct) – The dump header struct.

Returns

Returns the context struct. On failure returns an invalid CFFStruct.

Return type

CFFStruct

GetThreadContextInfo(s: Pro.Core.CFFStruct) → Optional[Pkg.WinDMP.ThreadContextInfo]¶

Extracts the essential registers (instruction pointer, stack pointer, bitness) from a context structure.

Parameters

s (CFFStruct) – The context struct returned by GetThreadContext() or GetThreadContextFromHeader().

Returns

Returns the ThreadContextInfo, or None when the structure is not a recognized context type.

Return type

Optional[ThreadContextInfo]

HasPhysicalMemory() → bool¶

Indicates whether the dump exposes physical memory (kernel dumps with a valid DirectoryTableBase).

Returns

Returns True when physical memory is available.

Return type

bool

See also GetRawMemory(), GetSystemMemory().

Is64Bit() → bool¶

Indicates whether the dumped system is 64-bit.

Returns

Returns True for 64-bit systems; otherwise returns False.

Return type

bool

See also GetSystemInfo().

IsKernelDump() → bool¶

Indicates whether the dump is a kernel-mode dump.

Returns

Returns True for kernel summary/triage/bitmap/full dumps; otherwise returns False (user dumps, minidumps, CE dumps).

Return type

bool

LoadDumpFileInfo() → Any¶

Identifies the dump format and initializes the internal memory objects.

This method is invoked automatically by Initialize() and is exposed so that scan providers can call it on a loaded stream before invoking the other accessors. Subsequent calls are cached.

Returns

Returns the internal dump descriptor on success; otherwise returns None or an unloaded descriptor on failure. Use the return value of Initialize() to test for success instead.

Return type

Any

ParseCommonDumpStreamList(sdesc: Dict[str, Any]) → Optional[Pkg.WinDMP.DumpStreamList]¶

Parses a simple list-oriented minidump stream into a DumpStreamList iterator.

Supported streams are ModuleListStream, UnloadedModuleListStream, MemoryInfoListStream and ThreadListStream.

Parameters

sdesc (Dict[str, Any]) – The stream descriptor returned by FindDumpStream().

Returns

Returns the iterator on success; otherwise returns None.

Return type

Optional[DumpStreamList]

Pkg.WinDMP — API for parsing Windows crash dump files¶

Overview¶

Inspecting a Dump File¶

Enumerating Modules and Threads¶

Module API¶

`Pkg.WinDMP` — API for parsing Windows crash dump files¶