├── .github ├── FUNDING.yml └── workflows │ └── symbolizer-rs.yml ├── .gitignore ├── Cargo.toml ├── LICENSE ├── README.md ├── pics ├── batch.webp ├── single.webp ├── symbolizer-rs-download.webp ├── symbolizer-rs-symbolizer.webp └── symbolizer-rs.webp ├── rustfmt.toml └── src ├── hex_addrs_iter.rs ├── human.rs └── main.rs /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | github: 0vercl0k 2 | -------------------------------------------------------------------------------- /.github/workflows/symbolizer-rs.yml: -------------------------------------------------------------------------------- 1 | name: Builds 2 | 3 | on: [push, pull_request] 4 | 5 | jobs: 6 | fmt: 7 | runs-on: ubuntu-latest 8 | name: fmt 9 | steps: 10 | - name: Checkout 11 | uses: actions/checkout@v4 12 | 13 | - name: Set up rust 14 | run: rustup default nightly 15 | 16 | - name: Install rustfmt 17 | run: rustup component add rustfmt 18 | 19 | - name: cargo fmt 20 | run: cargo +nightly fmt --check 21 | 22 | clippy: 23 | name: clippy 24 | runs-on: ubuntu-latest 25 | steps: 26 | - name: Checkout 27 | uses: actions/checkout@v4 28 | 29 | - name: Set up rust 30 | run: rustup default stable 31 | 32 | - name: cargo clippy 33 | env: 34 | RUSTFLAGS: "-Dwarnings" 35 | run: cargo clippy --workspace --tests --examples 36 | 37 | doc: 38 | name: doc 39 | runs-on: ubuntu-latest 40 | steps: 41 | - name: Checkout 42 | uses: actions/checkout@v4 43 | 44 | - name: Set up rust 45 | run: rustup default stable 46 | 47 | - name: cargo doc 48 | env: 49 | RUSTDOCFLAGS: "-Dwarnings" 50 | run: cargo doc 51 | 52 | build: 53 | strategy: 54 | fail-fast: false 55 | matrix: 56 | os: [ubuntu-latest, windows-latest, macos-latest] 57 | 58 | runs-on: ${{ matrix.os }} 59 | name: build & test / ${{ matrix.os }} 60 | steps: 61 | - name: Checkout 62 | uses: actions/checkout@v4 63 | 64 | - name: Set up rust 65 | run: rustup default stable 66 | 67 | - name: cargo test 68 | run: cargo test --all-targets 69 | 70 | - name: cargo test release 71 | run: cargo test --release --all-targets 72 | 73 | - name: cargo check 74 | run: cargo check --all-targets 75 | 76 | - name: cargo build 77 | run: cargo build --release --all-targets 78 | 79 | - name: Upload artifacts 80 | uses: actions/upload-artifact@v4 81 | with: 82 | name: symbolizer-rs.${{ matrix.os }} 83 | path: | 84 | target/release/symbolizer-rs.exe 85 | target/release/symbolizer_rs.pdb 86 | target/release/symbolizer-rs 87 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Generated by Cargo 2 | # will have compiled files and executables 3 | debug/ 4 | target/ 5 | 6 | # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries 7 | # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html 8 | Cargo.lock 9 | 10 | # These are backup files generated by rustfmt 11 | **/*.rs.bk 12 | 13 | # MSVC Windows builds of rustc generate these, which store debugging information 14 | *.pdb 15 | -------------------------------------------------------------------------------- /Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "symbolizer-rs" 3 | categories = ["command-line-utilities", "development-tools::debugging"] 4 | description = "A fast execution trace symbolizer for Windows that runs on all major platforms and doesn't depend on any Microsoft libraries." 5 | include = ["/Cargo.toml", "/LICENSE", "/src/**", "README.md"] 6 | version = "0.2.0" 7 | authors = ["Axel '0vercl0k' Souchet"] 8 | license = "MIT" 9 | rust-version = "1.70" 10 | repository = "https://github.com/0vercl0k/symbolizer-rs" 11 | keywords = ["windows", "kernel", "crash-dump", "symbols", "pdb"] 12 | edition = "2021" 13 | 14 | [dependencies] 15 | anyhow = "1.0" 16 | clap = { version = "4.5", features = ["derive"] } 17 | addr-symbolizer = { version = "0.1" } 18 | env_logger = "0.11" 19 | itoa = "1.0" 20 | kdmp-parser = "0.5" 21 | 22 | [profile.release] 23 | debug = true 24 | panic = "abort" 25 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 Axel Souchet 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 |

symbolizer-rs

3 |

4 | A fast execution trace symbolizer for Windows that runs on all major platforms and doesn't depend on any Microsoft libraries. 5 |

6 |

7 | 8 | 9 |

10 |

11 | 12 |

13 |
14 | 15 | ## Overview 16 | 17 | [symbolizer-rs](https://github.com/0vercl0k/symbolizer-rs) is the successor of [symbolizer](https://github.com/0vercl0k/symbolizer): it is faster, better and runs on all major platforms. 18 | 19 |

20 | 21 |

22 | 23 | It doesn't depend on [dbgeng](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-engine-api-overview) and download / parse PDB symbols on its own (thanks to the [pdb](https://github.com/getsentry/pdb) crate) unlike [symbolizer](https://github.com/0vercl0k/symbolizer) which was depending on Microsoft's [dbgeng](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-engine-api-overview) for that. 24 | 25 |

26 | 27 |

28 | 29 | [symbolizer-rs](https://github.com/0vercl0k/symbolizer-rs) allows you to transform raw execution traces (`0xfffff8053b9ca5c0`) into symbolized ones (`nt!KiPageFault+0x0`). In order to be able to do this, it needs a kernel crash-dump that contains the lists of user / kernel modules available as well as their PE headers to extract the PDB information necessary to download them off Microsoft or any other symbol server. This tool was made originally to be paired with the [what the fuzz](https://github.com/0vercl0k/wtf) snapshot fuzzer but can be used by any similar tools. 30 | 31 | Here is an example of a raw execution trace..: 32 | 33 | ```text 34 | 0xfffff8053b9ca5c0 35 | 0xfffff8053b9ca5c1 36 | 0xfffff8053b9ca5c8 37 | 0xfffff8053b9ca5d0 38 | 0xfffff8053b9ca5d4 39 | 0xfffff8053b9ca5d8 40 | 0xfffff8053b9ca5dc 41 | 0xfffff8053b9ca5e0 42 | ``` 43 | 44 | ..transformed into a full symbolized trace: 45 | 46 | ```text 47 | ntoskrnl.exe!KiPageFault+0x0 48 | ntoskrnl.exe!KiPageFault+0x1 49 | ntoskrnl.exe!KiPageFault+0x8 50 | ntoskrnl.exe!KiPageFault+0x10 51 | ntoskrnl.exe!KiPageFault+0x14 52 | ntoskrnl.exe!KiPageFault+0x18 53 | ntoskrnl.exe!KiPageFault+0x1c 54 | ntoskrnl.exe!KiPageFault+0x20 55 | ``` 56 | 57 | Or into a `mod+offset` (*modoff*) trace to load it into [Lighthouse](https://github.com/gaasedelen/lighthouse) for code-coverage exploration: 58 | 59 | ```text 60 | ntoskrnl.exe+0x1ca5c0 61 | ntoskrnl.exe+0x1ca5c1 62 | ntoskrnl.exe+0x1ca5c8 63 | ntoskrnl.exe+0x1ca5d0 64 | ntoskrnl.exe+0x1ca5d4 65 | ntoskrnl.exe+0x1ca5d8 66 | ntoskrnl.exe+0x1ca5dc 67 | ntoskrnl.exe+0x1ca5e0 68 | ntoskrnl.exe+0x1ca5e4 69 | ntoskrnl.exe+0x1ca5e8 70 | ``` 71 | 72 | ## Installation 73 | 74 | - `cargo install symbolizer-rs` 75 | - Build it yourself with by cloning the repository with `git clone https://github.com/0vercl0k/symbolizer-rs.git`, and build with `cargo build --release`. 76 | - Prebuilts binaries available in the [Releases](https://github.com/0vercl0k/symbolizer-rs/releases/) section 77 | 78 | ### Batch mode 79 | 80 | The batch mode is designed to symbolize an entire directory filled with execution traces. You can turn on batch mode by simply specifying a directory for the `--trace` command line option and an output directory for the `--output` option. 81 | 82 | ![Batch mode](https://github.com/0vercl0k/symbolizer-rs/raw/main/pics/batch.webp) 83 | 84 | ### Single file mode 85 | 86 | As opposed to batch mode, you can symbolize a single trace file by specifying a trace file path via the `--trace` command line option. 87 | 88 | ![Single mode](https://github.com/0vercl0k/symbolizer-rs/raw/main/pics/single.webp) 89 | 90 | ## Usage 91 | 92 | ```text 93 | A fast execution trace symbolizer for Windows. 94 | 95 | Usage: symbolizer-rs.exe [OPTIONS] --trace 96 | 97 | Options: 98 | -t, --trace 99 | Directory path full of traces or single input trace file 100 | 101 | -o, --output 102 | Output directory where to write symbolized traces, a path to an output file, or empty for the output to go on stdout 103 | 104 | -c, --crash-dump 105 | Path to the crash-dump to load. If not specified, an attempt is made to find a 'state/mem.dmp' file in the same directory than the trace file 106 | 107 | -s, --skip 108 | Skip a number of lines 109 | 110 | [default: 0] 111 | 112 | -m, --max 113 | The maximum amount of lines to process per file 114 | 115 | [default: 20000000] 116 | 117 | --style