v0.1 (#1)

Author: 0vercl0k

.github/workflows/kdmp-parser-rs.yml

@@ -0,0 +1,117 @@
+name: Builds
+
+on: [push, pull_request]
+
+jobs:
+  testdatas:
+    env:
+      TESTDATA_URL: https://github.com/0vercl0k/kdmp-parser/releases/download/v0.1/testdatas.7z
+
+    name: fetch testdatas
+    runs-on: ubuntu-latest
+    steps:
+    - name: Cache Artifacts
+      id: cache-testdatas
+      uses: actions/cache@v4
+      with:
+        key: kdmp-parser-testdatas-cache
+        path: .
+    - if: steps.cache-testdatas.outputs.cache-hit != 'true'
+      run: |
+        sudo apt-get -y update; sudo apt-get install -y p7zip-full;
+        curl ${{ env.TESTDATA_URL }}  -O -L
+        7z x testdatas.7z; rm testdatas.7z
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        if-no-files-found: error
+        name: kdmp-parser-testdatas-cache
+        path: .
+
+  fmt:
+    runs-on: ubuntu-latest
+    name: fmt
+    steps:
+      - name: Checkout 
+        uses: actions/checkout@v4
+
+      - name: Set up rust
+        run: rustup default nightly
+
+      - name: Install rustfmt
+        run: rustup component add rustfmt
+
+      - name: cargo fmt
+        run: cargo +nightly fmt --check
+
+  clippy:
+    name: clippy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 
+        uses: actions/checkout@v4
+
+      - name: Set up rust
+        run: rustup default stable
+
+      - name: cargo clippy
+        env:
+          RUSTFLAGS: "-Dwarnings"
+        run: cargo clippy --example parser
+
+  doc:
+    name: doc
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 
+        uses: actions/checkout@v4
+
+      - name: Set up rust
+        run: rustup default stable
+
+      - name: cargo doc
+        env:
+          RUSTDOCFLAGS: "-Dwarnings"
+        run: cargo doc
+
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    needs: testdatas
+    runs-on: ${{ matrix.os }}
+    name: build & test / ${{ matrix.os }}
+    steps:
+      - name: Checkout 
+        uses: actions/checkout@v4
+
+      - name: Set up rust
+        run: rustup default stable
+
+      - name: Retrieve testdatas
+        uses: actions/download-artifact@v4
+        with:
+          name: kdmp-parser-testdatas-cache
+          path: .
+
+      - name: cargo test
+        env:
+          TESTDATAS: "."
+        run: cargo test
+
+      - name: cargo check
+        run: cargo check
+
+      - name: cargo build
+        run: cargo build --release --example parser
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: parser-${{ matrix.os }}
+          path: |
+            target/release/examples/parser.exe
+            target/release/examples/parser.pdb
+            target/release/examples/parser

.gitignore

@@ -0,0 +1,14 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb

Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "kdmp-parser"
+version = "0.1.0"
+edition = "2021"
+authors = ["Axel '0vercl0k' Souchet"]
+categories = ["parser-implementations"]
+description = "A Rust crate for parsing Windows kernel crashdumps"
+include = [
+    "/Cargo.toml",
+    "/LICENSE",
+    "/src/**",
+    "/examples/**",
+    "README.md",
+]
+keywords = ["windows", "kernel", "crashdump"]
+license = "MIT"
+repository = "https://github.com/0vercl0k/kdmp-parser-rs"
+rust-version = "1.70"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[dependencies]
+bitflags = "2.4.2"
+thiserror = "1.0.58"
+
+[dev-dependencies]
+anyhow = "1.0.80"
+clap = { version = "4.5.1", features = ["derive"] }
+
+[[example]]
+name = "parser"

README.md

@@ -1,2 +1,69 @@
-# kdmp-parser-rs
-A KISS Rust crate to parse Windows kernel crash-dumps created by Windows & its debugger.
+<div align='center'>
+  <h1><code>kdmp-parser-rs</code></h1>
+  <p>
+    <strong>A <a href="https://en.wikipedia.org/wiki/KISS_principle">KISS</a> Rust crate to parse Windows kernel crash-dumps created by Windows & its debugger.</strong>
+  </p>
+  <p>
+    <img src="https://github.com/0vercl0k/kdmp-parser-rs/raw/main/pics/kdmp-parser.gif" />
+    <a href="https://crates.io/crates/kdmp-parser-rs"><img src="https://img.shields.io/crates/v/kdmp-parser-rs.svg" /></a>
+    <a href="https://docs.rs/kdmp-parser-rs/"><img src="https://docs.rs/kdmp-parser-rs/badge.svg"></a>
+    <img src="https://github.com/0vercl0k/kdmp-parser-rs/workflows/Builds/badge.svg"/>
+  </p>
+</div>
+
+This is a cross-platform crate that parses Windows **kernel** crash-dumps that Windows / WinDbg generates. It exposes read-only access to the physical memory pages as well as the register / exception context. It can also read virtual memory addresses by walking the [page tables](https://en.wikipedia.org/wiki/Page_table).
+
+Compiled binaries are available in the [releases](https://github.com/0vercl0k/kdmp-parser-rs/releases) section.
+
+## Parser
+The [parser](src/examples/parser.rs) application is a small utility to show-case how to use the library and demonstrate its features. You can use it to dump memory, etc.
+
+![parser-usage](https://github.com/0vercl0k/kdmp-parser-rs/raw/main/pics/parser-usage.gif)
+
+Here are the options supported:
+```text
+A Rust crate for parsing Windows kernel crashdumps
+
+Usage: parser.exe [OPTIONS] <DUMP_PATH>
+
+Arguments:
+  <DUMP_PATH>
+          The dump path
+
+Options:
+  -c, --context-record
+          Show the context record
+
+  -e, --exception-record
+          Show the exception record
+
+  -m, --mem[=<MEM>]
+          Dump the first `len` bytes of every physical pages, unless an address is specified
+
+      --virt
+          The address specified is interpreted as a virtual address, not a physical address
+
+      --len <LEN>
+          [default: 16]
+
+  -r, --reader <READER>
+          [default: mmap]
+
+          Possible values:
+          - mmap: The crash-dump is memory-mapped
+          - file: The crash-dump is read as a file on disk
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+  -V, --version
+          Print version
+```
+
+# Authors
+
+* Axel '[@0vercl0k](https://twitter.com/0vercl0k)' Souchet
+
+# Contributors
+
+[ ![contributors-img](https://contrib.rocks/image?repo=0vercl0k/kdmp-parser-rs) ](https://github.com/0vercl0k/kdmp-parser-rs/graphs/contributors)

examples/parser.rs

@@ -0,0 +1,130 @@
+// Axel '0vercl0k' Souchet - February 25 2024
+use core::default::Default;
+use std::fs::File;
+use std::path::PathBuf;
+
+use anyhow::{anyhow, Context, Result};
+use clap::{Parser, ValueEnum};
+use kdmp_parser::{Gpa, Gva, Gxa, KernelDumpParser, MappedFileReader};
+
+#[derive(Debug, Default, Clone, Copy, ValueEnum)]
+enum ReaderMode {
+    #[default]
+    /// The crash-dump is memory-mapped.
+    Mmap,
+    /// The crash-dump is read as a file on disk.
+    File,
+}
+
+#[derive(Parser, Debug)]
+#[command(version, about)]
+struct Args {
+    /// The dump path.
+    dump_path: PathBuf,
+    /// Show the context record.
+    #[arg(short, long)]
+    context_record: bool,
+    /// Show the exception record.
+    #[arg(short, long)]
+    exception_record: bool,
+    /// Dump the first `len` bytes of every physical pages, unless an address is
+    /// specified.
+    #[arg(short, long, num_args = 0..=1, require_equals = true, default_missing_value = "0xffffffffffffffff")]
+    mem: Option<String>,
+    /// The address specified is interpreted as a virtual address, not a
+    /// physical address.
+    #[arg(long, default_value_t = false)]
+    virt: bool,
+    /// The number of bytes to dump out.
+    #[arg(long, default_value_t = 0x10)]
+    len: usize,
+    /// Reader mode.
+    #[arg(short, long, value_enum, default_value_t = ReaderMode::Mmap)]
+    reader: ReaderMode,
+}
+
+/// Print a hexdump of data that started at `address`.
+fn hexdump(address: u64, data: &[u8]) {
+    let len = data.len();
+    let mut it = data.iter();
+    for i in (0..len).step_by(16) {
+        print!("{:016x}: ", address + (i as u64 * 16));
+        let mut row = [None; 16];
+        for item in row.iter_mut() {
+            if let Some(c) = it.next() {
+                *item = Some(*c);
+                print!("{:02x}", c);
+            } else {
+                print!(" ");
+            }
+        }
+        print!(" |");
+        for item in &row {
+            if let Some(c) = item {
+                let c = char::from(*c);
+                print!("{}", if c.is_ascii_graphic() { c } else { '.' });
+            } else {
+                print!(" ");
+            }
+        }
+        println!("|");
+    }
+}
+
+/// Convert an hexadecimal string to a `u64`.
+fn to_hex(s: &str) -> Result<u64> {
+    u64::from_str_radix(s.trim_start_matches("0x"), 16).context("failed to convert string to u64")
+}
+
+fn main() -> Result<()> {
+    let args = Args::parse();
+    let parser = match args.reader {
+        ReaderMode::Mmap => {
+            let mapped_file = MappedFileReader::new(args.dump_path)?;
+            KernelDumpParser::with_reader(mapped_file)
+        }
+        ReaderMode::File => {
+            let file = File::open(args.dump_path)?;
+            KernelDumpParser::with_reader(file)
+        }
+    }
+    .context("failed to parse the kernel dump")?;
+
+    if args.context_record {
+        println!("{:#x?}", parser.context_record());
+    }
+
+    if args.exception_record {
+        println!("{:#x?}", parser.exception_record());
+    }
+
+    if let Some(addr) = args.mem {
+        let mut buffer = vec![0; args.len];
+        let addr = to_hex(&addr)?;
+        if addr == u64::MAX {
+            for (gpa, _) in parser.physmem() {
+                parser
+                    .phys_read_exact(gpa, &mut buffer)
+                    .ok_or_else(|| anyhow!("failed to read {gpa}"))?;
+                hexdump(gpa.u64(), &buffer)
+            }
+        } else {
+            let amount = if args.virt {
+                parser.virt_read(Gva::new(addr), &mut buffer)
+            } else {
+                parser.phys_read(Gpa::new(addr), &mut buffer)
+            };
+
+            if let Some(amount) = amount {
+                hexdump(addr, &buffer[..amount]);
+            } else {
+                println!(
+                    "There is no {} memory available for {addr:#x}",
+                    if args.virt { "virtual" } else { "physical" }
+                );
+            }
+        }
+    }
+
+    Ok(())
+}

pics/kdmp-parser.gif

@@ -0,0 +1,13 @@
+reorder_modules = true
+use_field_init_shorthand = true
+
+unstable_features = true
+indent_style = "Block"
+reorder_imports = true
+imports_granularity = "Module"
+normalize_comments = true
+normalize_doc_attributes = true
+overflow_delimited_expr = true
+reorder_impl_items = true
+group_imports = "StdExternalCrate"
+wrap_comments = true