winappdbg.crash

Crash dump support.

Crash reporting: - Crash - CrashDictionary

Warnings: - CrashWarning

class winappdbg.crash.Crash(event)

Represents a crash, bug, or another interesting event in the debugee.

Basic information

timeStamp
signature
eventCode
eventName
pid
tid
arch
os
bits
registers
labelPC
pc
sp
fp

Optional information

debugString
modFileName
lpBaseOfDll
exceptionCode
exceptionName
exceptionDescription
exceptionAddress
exceptionLabel
firstChance
faultType
faultAddress
faultLabel
isOurBreakpoint
isSystemBreakpoint
stackTrace
stackTracePC
stackTraceLabels
stackTracePretty

Extra information

commandLine
environment
environmentData
registersPeek
stackRange
stackFrame
stackPeek
faultCode
faultMem
faultPeek
faultDisasm
memoryMap

Report

briefReport()
fullReport()
notesReport()
environmentReport()
isExploitable()

Notes

addNote()
getNotes()
iterNotes()
hasNotes()
clearNotes()
notes

Miscellaneous

fetch_extra_data()

Variables:

timeStamp (float) – Timestamp as returned by time.time().
signature (str) –
SHA256 hash-based signature for the Crash object.

This signature can be used as an heuristic to determine if two crashes were caused by the same software error. It is a stable hash based on key crash attributes that can be used for deduplication.
notes (list[str]) – List of strings, each string is a note.
eventCode (int) – Event code as defined by the Win32 API.
eventName (str) – Event code user-friendly name.
pid (int) – Process global ID.
tid (int) – Thread global ID.
arch (str) – Processor architecture.
os (str) –
Operating system version.

May indicate a 64 bit version even if arch and bits indicate 32 bits. This means the crash occurred inside a WOW64 process.
bits (int) – 32 or 64 bits.
commandLine (str or None) – Command line for the target process. None if unapplicable or unable to retrieve.
environmentData (list[str] or None) – Environment data for the target process. None if unapplicable or unable to retrieve.
environment (dict[str, str] or None) – Environment variables for the target process. None if unapplicable or unable to retrieve.
registers (dict[str, int]) – Dictionary mapping register names to their values.
registersPeek (dict[str, str] or None) – Dictionary mapping register names to the data they point to. None if unapplicable or unable to retrieve.
labelPC (str or None) – Label pointing to the program counter. None or invalid if unapplicable or unable to retrieve.
debugString (str or None) – Debug string sent by the debugee. None if unapplicable or unable to retrieve.
exceptionCode (int or None) – Exception code as defined by the Win32 API. None if unapplicable or unable to retrieve.
exceptionName (str or None) – Exception code user-friendly name. None if unapplicable or unable to retrieve.
exceptionDescription (str or None) – Exception description. None if unapplicable or unable to retrieve.
exceptionAddress (int or None) – Memory address where the exception occured. None if unapplicable or unable to retrieve.
exceptionLabel (str or None) – Label pointing to the exception address. None or invalid if unapplicable or unable to retrieve.
faultType (int or None) –
Access violation type. Only applicable to memory faults. Should be one of the following constants:
- win32.ACCESS_VIOLATION_TYPE_READ
- win32.ACCESS_VIOLATION_TYPE_WRITE
- win32.ACCESS_VIOLATION_TYPE_DEP
None if unapplicable or unable to retrieve.
faultAddress (int or None) – Access violation memory address. Only applicable to memory faults. None if unapplicable or unable to retrieve.
faultLabel (str or None) – Label pointing to the access violation memory address. Only applicable to memory faults. None if unapplicable or unable to retrieve.
firstChance (bool or None) – True for first chance exceptions, False for second chance. None if unapplicable or unable to retrieve.
isOurBreakpoint (bool) – True for breakpoints defined by the Debug class, False otherwise. None if unapplicable.
isSystemBreakpoint (bool) – True for known system-defined breakpoints, False otherwise. None if unapplicable.
modFileName (str or None) – File name of module where the program counter points to. None or invalid if unapplicable or unable to retrieve.
lpBaseOfDll (int or None) – Base of module where the program counter points to. None if unapplicable or unable to retrieve.
stackTrace (tuple[tuple[int, int, str]] or None) – Stack trace of the current thread as a tuple of (frame pointer, return address, module filename). None or empty if unapplicable or unable to retrieve.
stackTracePretty (tuple[tuple[int, str]] or None) – Stack trace of the current thread as a tuple of (frame pointer, return location). None or empty if unapplicable or unable to retrieve.
stackTracePC (tuple[int, ...] or None) – Tuple of return addresses in the stack trace. None or empty if unapplicable or unable to retrieve.
stackTraceLabels (tuple[str, ...] or None) – Tuple of labels pointing to the return addresses in the stack trace. None or empty if unapplicable or unable to retrieve.
stackRange (tuple[int, int]) – Stack beginning and end pointers, in memory addresses order. None if unapplicable or unable to retrieve.
stackFrame (str or None) – Data pointed to by the stack pointer. None or empty if unapplicable or unable to retrieve.
stackPeek (dict[int, str] or None) – Dictionary mapping stack offsets to the data they point to. None or empty if unapplicable or unable to retrieve.
faultCode (str or None) – Data pointed to by the program counter. None or empty if unapplicable or unable to retrieve.
faultMem (str or None) – Data pointed to by the exception address. None or empty if unapplicable or unable to retrieve.
faultPeek (dict[int, str] or None) – Dictionary mapping guessed pointers at faultMem to the data they point to. None or empty if unapplicable or unable to retrieve.
faultDisasm (tuple[tuple[int, int, str, str]] or None) – Dissassembly around the program counter. None or empty if unapplicable or unable to retrieve.
memoryMap (list[MemoryBasicInformation] or None) – Memory snapshot of the program. May contain the actual data from the entire process memory if requested. See fetch_extra_data() for more details. None or empty if unapplicable or unable to retrieve.
_rowid (int) – Row ID in the database. Internally used by the DAO layer. Only present in crash dumps retrieved from the database. Do not rely on this property to be present in future versions of WinAppDbg.

addNote(msg)

Add a note to the crash event.

Parameters:: msg (str) – Note text.

briefReport()

Return type:: str
Returns:: Short description of the event.

clearNotes(): Clear the notes of this crash event.

environmentReport()

Return type:: str
Returns:: The process environment variables, merged and formatted for a report.

fetch_extra_data(event, takeMemorySnapshot=0)

Fetch extra data from the Event object.

Note

Since this method may take a little longer to run, it’s best to call it only after you’ve determined the crash is interesting and you want to save it.

Parameters:

event (Event) – Event object for crash.
takeMemorySnapshot (int) –
Memory snapshot behavior:
- 0 to take no memory information (default).
- 1 to take only the memory map. See get_memory_map().
- 2 to take a full memory snapshot. See take_memory_snapshot().
- 3 to take a live memory snapshot. See generate_memory_snapshot().

property fp

Value of the frame pointer register.

Return type:: int

fullReport(bShowNotes=True)

Parameters:: bShowNotes (bool) – True to show the user notes, False otherwise.
Return type:: str
Returns:: Long description of the event.

getNotes()

Get the list of notes of this crash event.

Return type:: list[str]
Returns:: List of notes.

hasNotes()

Return type:: bool
Returns:: True if there are notes for this crash event.

isExploitable()

Guess how likely is it that the bug causing the crash can be leveraged into an exploitable vulnerability.

Note

Don’t take this as an equivalent of a real exploitability analysis, that can only be done by a human being! This is only a guideline, useful for example to sort crashes - placing the most interesting ones at the top.

The heuristics are similar to those of the !exploitable extension for WinDBG: https://web.archive.org/web/20210413145507/https://archive.codeplex.com/?p=msecdbg

Return type:

tuple[str, str, str]

Returns:

The first element of the tuple is the result of the analysis, being one of the following:

Not an exception
Not exploitable
Not likely exploitable
Unknown
Probably exploitable
Exploitable

The second element of the tuple is a code to identify the matched heuristic rule.

The third element of the tuple is a description string of the reason behind the result.

iterNotes()

Iterate the notes of this crash event.

Return type:: iterator
Returns:: Iterator of the list of notes.

key(): Alias of signature. Deprecated since WinAppDbg 1.5.

notesReport()

Return type:: str
Returns:: All notes, merged and formatted for a report.

property pc

Value of the program counter register.

Return type:: int

property signature

Create a stable hash-based signature for crash deduplication.

Returns a SHA256 hash based on key crash attributes that determine if two crashes are likely caused by the same bug.

Return type:: str
Returns:: SHA256 hash as hexadecimal string

property sp

Value of the stack pointer register.

Return type:: int

class winappdbg.crash.CrashDictionary(url, creator=None, allowRepeatedKeys=True)

Dictionary-like persistence interface for Crash objects.

Currently the only implementation is through db.CrashDAO.

add(crash)

Adds a new crash to the container.

Note

When the allowRepeatedKeys parameter of the constructor is set to False, duplicated crashes are ignored.