Minidump File Parser

0.0.24 · active · verified Fri Apr 17

minidump is a Python library designed for parsing Windows minidump (.dmp) files. It allows developers and security researchers to programmatically extract information such as modules, threads, handles, and exception data from crash dumps. Currently at version 0.0.24, the library receives updates primarily for bug fixes and feature enhancements related to parsing accuracy and additional stream support.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'your_minidump.dmp'
```
cause The specified minidump file does not exist at the provided path.

fix Ensure the file path is correct and the file exists. Use an absolute path or verify the relative path from your script's execution directory. Example: `MinidumpFile.parse(open('/path/to/your_minidump.dmp', 'rb'))`
```
minidump.exceptions.MinidumpParseError: Invalid minidump header
```
cause The file provided is either not a valid minidump file, is corrupted, or is not supported by the parser (e.g., an extremely old or malformed dump).

fix Verify the integrity of your `.dmp` file. Try opening it with a dedicated minidump viewer (like WinDbg or a similar forensic tool) to confirm its validity. Ensure it's not truncated or corrupted.
```
AttributeError: 'MinidumpFile' object has no attribute 'threads'
```
cause You are attempting to access a stream (e.g., 'threads', 'modules', 'exceptions') that is not present in the specific minidump file you are parsing.

fix Not all minidump files contain all possible streams. Always check if a stream exists before attempting to iterate or access its contents. Example: `if md.threads: for thread in md.threads: ...`

Warnings

gotcha Parsing accuracy for MINIDUMP_EXCEPTION records and certain memory range (`inrange`) calculations was improved in versions 0.0.23 and 0.0.24. Older versions (prior to 0.0.23) may yield incorrect or incomplete data for these specific fields.
Fix: Upgrade to `minidump>=0.0.24` to benefit from the latest parsing fixes and improvements.
gotcha Minidump files can be very large. The library handles file I/O, but ensure your system has sufficient memory and I/O capacity, especially when processing many or very large dumps. Buffered reading was introduced in version 0.0.17 for improved efficiency.
Fix: Ensure you are using `minidump>=0.0.17` or newer for better performance, especially with large files. Always open files in binary read mode (`'rb'`).
gotcha The library expects a valid minidump file. Providing a corrupted, incomplete, or non-minidump file will likely result in a `minidump.exceptions.MinidumpParseError` or other unexpected errors.
Fix: Verify the integrity and format of your `.dmp` files before parsing. Consider adding robust error handling (`try-except`) around `MinidumpFile.parse()` calls.

Install

pip install minidump Install stable version

Imports

MinidumpFile

from minidump.minidumpfile import MinidumpFile

Quickstart

This example demonstrates how to parse a minidump file and access its basic streams like modules, threads, and exception records. It assumes a file named 'example.dmp' exists in the same directory. Note that for actual parsing, 'example.dmp' must be a valid Windows minidump file.

from minidump.minidumpfile import MinidumpFile
import os

# For this example, ensure 'example.dmp' exists in the current directory
# and is a valid Windows minidump file.
# You can create a dummy file for testing, but real parsing requires a valid minidump.
minidump_path = os.path.join(os.path.dirname(__file__), 'example.dmp')

# Create a dummy file if it doesn't exist, though it won't be a valid minidump
# This is just to make the example runnable without crashing on FileNotFoundError
if not os.path.exists(minidump_path):
    with open(minidump_path, 'w') as f:
        f.write('DUMMY MINIDUMP CONTENT - REPLACE WITH REAL .dmp FILE')
    print(f"Warning: '{minidump_path}' created as a dummy. Replace with a real minidump for actual parsing.")

try:
    with open(minidump_path, 'rb') as f:
        md = MinidumpFile.parse(f)
        print(f"Successfully parsed minidump: {minidump_path}")
        
        # Accessing common streams
        if md.modules:
            print(f"\nModules found: {len(md.modules)}")
            for module in md.modules[:5]: # Print first 5 modules
                print(f"  - {module.name} (Base: {hex(module.baseofdll)})")
        
        if md.threads:
            print(f"\nThreads found: {len(md.threads)}")
            for thread in md.threads[:5]: # Print first 5 threads
                print(f"  - TID: {thread.threadid}, EIP: {hex(thread.stack.stackptr)}")

        if md.exceptions:
            print(f"\nException Record found: {md.exceptions.exceptionrecord.exceptioncode}")
            
except FileNotFoundError:
    print(f"Error: Minidump file not found at '{minidump_path}'. Please ensure it exists.")
except Exception as e:
    print(f"An error occurred during parsing: {e}")

# Clean up dummy file if it was created and is still dummy content
if os.path.exists(minidump_path) and os.path.getsize(minidump_path) > 0:
    with open(minidump_path, 'r') as f:
        content = f.read(100) # Read first 100 chars
        if 'DUMMY MINIDUMP CONTENT' in content:
            os.remove(minidump_path)
            print(f"Cleaned up dummy file: '{minidump_path}'.")

view raw JSON →