kdumpling 0.1.0

A Python library for creating Linux kdump crash dump files

kdumpling

A Python library for creating Linux kdump crash dump files.

Note: This library is currently a work in progress. The API may change in future releases.

Overview

kdumpling allows you to synthesize valid ELF64 vmcore files from raw memory data and vmcoreinfo values. This is useful for:

• Testing crash dump analysis tools (like drgn, crash)
• Creating synthetic crash dumps for debugging
• Educational purposes for understanding Linux kernel crash dump formats

Installation

pip install kdumpling

Quick Start

from kdumpling import KdumpBuilder

# Create a builder for x86_64 architecture
builder = KdumpBuilder(arch='x86_64')

# Set the vmcoreinfo metadata
builder.set_vmcoreinfo("""OSRELEASE=5.14.0
PAGESIZE=4096
SYMBOL(swapper_pg_dir)=ffffffff82a00000
""")

# Add memory segments
builder.add_memory_segment(phys_addr=0x100000, data=b'\x00' * 4096)

# Add CPU register state (optional)
builder.add_cpu_context(
    cpu_id=0,
    registers={'RIP': 0xffffffff81000000, 'RSP': 0xffff888000000000},
    pid=1
)

# Check stats before writing
print(builder.stats)
# Dump Statistics:
#   Architecture: x86_64
#   Memory Segments: 1
#   CPU Contexts: 1
#   Total Memory: 4.0 KB (4096 bytes)
#   ...

# Write the vmcore file
builder.write("output.vmcore")

Features

• Multi-architecture support: x86_64, aarch64/arm64, s390x, ppc64/ppc64le, riscv64
• Fluent API: Chain method calls for concise code
• CPU context support: Include register state for debugging tools
• Memory from multiple sources: bytes, file paths, or file-like objects
• Statistics API: Inspect dump properties before writing
• Validated: Tested with pyelftools, drgn, and libkdumpfile

Supported Architectures

Architecture	Endianness	Description
x86_64	Little	64-bit x86 (AMD64/Intel 64)
aarch64 / arm64	Little	64-bit ARM
s390x	Big	IBM Z series
ppc64le	Little	64-bit PowerPC (little endian)
ppc64	Big	64-bit PowerPC (big endian)
riscv64	Little	64-bit RISC-V

Validating with drgn

import drgn

prog = drgn.Program()
prog.set_core_dump("output.vmcore")
print(f"Platform: {prog.platform}")  # Platform(<Architecture.X86_64: 1>, ...)
print(f"Flags: {prog.flags}")        # ProgramFlags.IS_LINUX_KERNEL

API Reference

KdumpBuilder

builder = KdumpBuilder(arch='x86_64')

# Set vmcoreinfo metadata
builder.set_vmcoreinfo("OSRELEASE=5.14.0\n...")

# Add memory segments
builder.add_memory_segment(phys_addr=0x100000, data=b'...')
builder.add_memory_segment(phys_addr=0x200000, data="/path/to/file")

# Add CPU context
builder.add_cpu_context(cpu_id=0, registers={'RIP': 0x...}, pid=1)

# Get statistics
stats = builder.stats
print(stats.num_memory_segments)
print(stats.total_memory_size_human)

# Write to file
builder.write("output.vmcore")

DumpStats

stats = builder.stats

stats.architecture          # 'x86_64'
stats.num_memory_segments   # Number of PT_LOAD segments
stats.num_cpu_contexts      # Number of NT_PRSTATUS notes
stats.total_memory_size     # Total memory in bytes
stats.vmcoreinfo_size       # VMCOREINFO size in bytes
stats.estimated_file_size   # Estimated output file size
stats.memory_segments       # List of (phys_addr, size) tuples

# Human-readable sizes
stats.total_memory_size_human     # "4.0 MB"
stats.estimated_file_size_human   # "4.0 MB"

Development

# Clone the repository
git clone https://github.com/sdimitro/kdumpling.git
cd kdumpling

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Run type checker
mypy kdumpling

License

MIT License - see LICENSE for details.