{"id":50728810,"url":"https://github.com/aximcode/rsod-decode","last_synced_at":"2026-06-10T06:48:02.582Z","repository":{"id":357423757,"uuid":"1209010904","full_name":"aximcode/rsod-decode","owner":"aximcode","description":"UEFI RSOD crash dump debugger — web UI with DWARF variable inspector, GDB backend, multi-format support","archived":false,"fork":false,"pushed_at":"2026-05-12T18:31:01.000Z","size":4535,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T06:47:58.400Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aximcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T02:21:30.000Z","updated_at":"2026-05-12T18:31:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aximcode/rsod-decode","commit_stats":null,"previous_names":["aximcode/rsod-decode"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/aximcode/rsod-decode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aximcode%2Frsod-decode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aximcode%2Frsod-decode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aximcode%2Frsod-decode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aximcode%2Frsod-decode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aximcode","download_url":"https://codeload.github.com/aximcode/rsod-decode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aximcode%2Frsod-decode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34140774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-10T06:47:57.395Z","updated_at":"2026-06-10T06:48:02.572Z","avatar_url":"https://github.com/aximcode.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rsod-decode\n\nInteractive UEFI **R**ed **S**creen **O**f **D**eath crash dump\ndebugger. Resolves raw addresses in serial-console crash captures\nto function names, source files, parameters, and locals via DWARF\nor PE+PDB. Ships as a single `rsod` binary with `decode` (text\nreport), `serve` (web UI), and `history` subcommands, plus a\nself-contained `rsod.pyzw` zipapp.\n\nSupports x86-64 and ARM64; auto-detects EDK2 ARM64, Dell UEFI\nARM64, Dell UEFI x86-64, and MSVC EPSA x86-64 (with or without\nPDB) formats.\n\n---\n\n## At a glance\n\nDrop an RSOD log + symbol files, get a clickable backtrace,\nper-frame parameters/locals, full-file source view, disassembly\nwith inline source annotations, and an in-browser LLDB/GDB\nterminal. Sessions persist across restarts, dedup by content\nhash, and export as `.rsod.zip` bundles for cross-team sharing.\n\n![Demo: upload screen → crash analysis → source tab → disassembly tab](docs/screenshots/demo.gif)\n\n---\n\n## Install\n\n\u003e **Most users:** grab the pre-built zipapp on Linux x86-64 (including\n\u003e WSL on Windows 11). It's the recommended path for everyone — full\n\u003e features, including LLDB integration. No pip, no venv, no Node, no\n\u003e build step.\n\n### Recommended: pre-built `rsod.pyzw` (Linux x86-64 / WSL)\n\n```bash\n# 1. Install Python + LLDB (one-time, host system)\nsudo apt install python3 python3-lldb lldb gdb            # Ubuntu / Debian / WSL\n# sudo dnf install python3 python3-lldb lldb gdb          # Fedora / RHEL\n\n# 2. Download the zipapp\n#    The -o flag prevents wget/curl from auto-renaming to\n#    rsod.pyzw.1 / .2 / etc. when an older copy is in cwd.\ncurl -L -o rsod.pyzw https://github.com/aximcode/rsod-decode/releases/latest/download/rsod.pyzw\nchmod +x rsod.pyzw\n\n# 3. Run it\n./rsod.pyzw serve                       # web UI at localhost:5000\n./rsod.pyzw decode rsod.txt symbols.so -v\n./rsod.pyzw history\n```\n\nRequires Python 3.11+. The zipapp bundles Flask, capstone, the React\nfrontend, and every Python dependency — only the LLDB and GDB\nbinaries come from your system packages.\n\n`python3-lldb` + `lldb` give you PE+PDB minidump analysis (the only\nway to get full parameter/local visibility for MSVC EPSA crashes)\nand callsite-arg reconstruction (recovers tail-call-elided frames).\n`gdb` enables the GDB cross-check backend. Both are optional — the\ntool degrades to the pyelftools backend if either is missing — but\nstrongly recommended for the full experience.\n\n### Other platforms (macOS, Windows native, Linux ARM64)\n\nThe released `rsod.pyzw` is Linux x86-64 only because `libcapstone.so`\nis baked into the bundle. To use rsod-decode on another platform, do\nthe source install below on the target host (works fine — capstone\nhas wheels for macOS, Windows, and Linux ARM64) and either run from\nsource or rebuild the zipapp via `python build_pyz.py`.\n\n### Source install (developers + non-Linux-x86 hosts)\n\n```bash\ngit clone https://github.com/aximcode/rsod-decode.git\ncd rsod-decode\n```\n\nPrerequisites by platform:\n\n| Platform | Run before `pip install` |\n|----------|--------------------------|\n| Ubuntu / Debian / WSL | `sudo apt install python3-pip python3-venv python3-lldb lldb gdb` |\n| Fedora / RHEL | `sudo dnf install python3-pip python3-lldb lldb gdb` |\n| macOS | `brew install python lldb gdb` |\n| Windows | install Python from [python.org](https://python.org) + LLVM from [llvm.org](https://llvm.org/) |\n\nA **venv is required** on modern Ubuntu / Debian (PEP 668 blocks\nsystem-wide `pip install`). Strongly recommended elsewhere too.\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate     # on Windows: .venv\\Scripts\\activate\n\npip install -e \".[gdb,dev]\"\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run build \u0026\u0026 cd ..\n\nrsod --help\n# Or rebuild the zipapp for distribution:\npython build_pyz.py            # → rsod.pyzw\n```\n\nOptional extras: `[gdb]` adds `pygdbmi`, `[dev]` adds `pytest`,\n`[browser]` adds `playwright` for the browser regression tests.\n\n---\n\n## Web UI (`rsod serve`)\n\nStarts a local Flask server, opens your default browser, and lets\nyou drop any combination of RSOD log + symbol files in one action.\n\n```bash\nrsod serve                                 # upload form at localhost:5000\nrsod serve rsod.txt app.efi.so             # pre-load a session on startup\nrsod serve rsod.txt app.efi -s app.pdb     # MSVC PE+PDB crash\nrsod serve --port 9090 --no-browser        # custom port, skip browser open\nrsod serve --source-path ~/src/myproject   # extra source tree for source view\n```\n\n### Features\n\n- **Clickable backtrace** with call-verification markers\n  (`[verified]` / `[stale?]`) and inline expansion\n- **Per-frame parameters and locals** with PC-accurate register/\n  stack location tracking; struct/pointer fields are expandable\n- **Memory hex-dump viewer** with region labels (stack, .text, etc.)\n- **Disassembly** around the faulting PC with source-line headers\n- **Full-file source view** that auto-scrolls to the crash line;\n  scroll freely, use **\"Go to line N\"** to reset\n- **Register panel** with symbol annotations and crash-vs-CFI-unwound\n  highlighting\n- **Three DWARF backends** — pyelftools (always), GDB/MI, system\n  LLDB (richer; PE+PDB minidumps + callsite-arg reconstruction)\n- **In-browser LLDB and GDB terminals** sharing the session's\n  debugger state\n- **Expression evaluation** via the LLDB/GDB backends\n- **Persistent session history** (see below)\n\n### Persistent session store\n\nUploaded sessions survive `rsod serve` restarts. Every upload writes\nto a SQLite store at `~/.rsod-debug/sessions.db` plus a per-session\nfiles directory under `~/.rsod-debug/files/\u003cid\u003e/`. The upload page\nshows a \"Recent sessions\" list below the upload zone — click any row\nto reopen the crash.\n\nSession IDs are 16-char sha256 prefixes over the input bytes, so\nre-uploading identical content deduplicates and Alice's id matches\nBob's id for the same crash. **Sessions are never auto-deleted**;\nthe only way to remove one is the explicit Delete button (in the\ncrash banner or per-row in history).\n\nOverride the data directory with `RSOD_DATA_DIR=...` for CI or\nproject-isolated history.\n\n### Cross-machine sharing — export / import bundles\n\nClick **Export** in the crash banner (or on a history row) to\ndownload an `.rsod.zip` bundle:\n\n```\ncrash-2026-04-15-ab12cd34.rsod.zip\n```\n\nThe bundle contains the original RSOD text, the symbol files, and\na small `metadata.json` manifest. Send it to a teammate; they click\n**Import bundle** on their upload page and drop straight into the\nimported session — no out-of-band symbol file transfer needed.\n\nBecause session IDs are content hashes, the imported session lands\non the same `ab12cd34` id Alice's machine has. A\n`#session/ab12cd34` permalink resolves to the same crash on any\ninstall that has imported the bundle.\n\n### Friendly session names\n\nClick the session name above the crash banner (or the **Name**\nbutton if unnamed) to set a friendly alias visible in history and\nthe banner. Useful for \"R470 fGndBounce\" vs `ae035623cff5c98a`.\n\n---\n\n## CLI (`rsod decode`)\n\nText report for a single crash. Default output is\n`\u003clog\u003e_decode.txt` (override with `-o`); `--session` writes to\nstdout.\n\n```bash\n# From files (also persists to history)\nrsod decode rsod.txt app.efi.so\nrsod decode rsod.txt app.efi.so -v                  # adds params/locals/disasm/source\nrsod decode rsod.txt app.efi.so --tag v1.0.3        # source from a git ref\nrsod decode rsod.txt app.efi.so --base 5948A000     # base address override\nrsod decode rsod.txt app.efi.so --name \"R470 crash\" # friendly name in history\n\n# From a previously persisted session\nrsod decode --session ae035623                      # 8-char prefix is enough\nrsod decode --session ae035623 -v                   # with params/disasm/source\n```\n\n### `rsod history`\n\nCompact table of all persisted sessions, newest first:\n\n```\nID          NAME                  IMAGE           EXCEPTION                 SYMBOL             FR   AGE\n-------------------------------------------------------------------------------------------------------\nae035623    PSA forcecrash XE77…  psa_x64         General Protection Faul…  trigger_gp_fault    8    1m\nb676f92c    PSA R470 fGndBounce   psa_x64         Invalid opcode (06)       not in image       14    1m\n5d5e566f    Dell x64 CrashTest    CrashTest       General Protection Faul…  not in image        6    1m\n```\n\n`--json` for machine-readable output. `-n N` to limit row count.\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `-o FILE` | Output file path (default: `\u003clog\u003e_decode.txt`, stdout for `--session`) |\n| `-v, --verbose` | Show disassembly, source context, and parameters |\n| `-s FILE` | Additional symbol file for multi-module traces (repeatable) |\n| `--base HEX` | Override image base address (hex, e.g. `5948A000`) |\n| `--source-path PATH` | Source tree to search (repeatable; auto-detected repo is fallback) |\n| `--tag TAG` | Git tag for source context (reads source at that revision) |\n| `--commit HASH` | Git commit hash for source context |\n| `--session ID` | Replay a persisted session by id (full or 4+ char prefix) |\n| `--name TEXT` | Friendly display name for the session (visible in history) |\n| `--backend NAME` | Force a DWARF backend (`auto`, `lldb`, `gdb`, `pyelftools`) |\n\n---\n\n## Capturing an RSOD\n\nConnect to the server's BMC/iDRAC via SSH, then use the serial\nconsole:\n\n```\nracadm\u003e\u003e console com2\n```\n\nWhen the RSOD appears, copy the full text from PuTTY (or save the\nPuTTY session log). The capture should include the register dump\nand stack dump.\n\n---\n\n## Symbol files\n\n| Source | Format | Functions | Source lines | Inlines | Param names | Locals |\n|--------|--------|-----------|-------------|---------|------------|--------|\n| MSVC `.map` | Text | yes | no | no | no | no |\n| MSVC `.efi` + `.pdb` | PE + PDB (LLDB) | yes | yes | yes | yes | yes |\n| GCC `.so` / unstripped `.efi` | ELF + DWARF | yes (demangled) | yes | yes | yes | yes |\n\nThe tool auto-detects format by magic bytes. The `.efi` produced by\n`objcopy` is typically **stripped** — use the `.so` (or unstripped\n`.efi`) for ELF builds.\n\nFor MSVC builds, drop the `.efi` + `.pdb` together for full\nparameter/local visibility; the PDB drives an LLDB minidump session\nbehind the scenes.\n\n---\n\n## Supported RSOD formats\n\n| Format | Detected by | Architecture |\n|--------|-------------|--------------|\n| UEFI BIOS x86 | `AX=`, `--\u003eRIP` | x86-64 |\n| UEFI BIOS ARM64 | `X0=`, `--\u003ePC`, `s00..sNN` | ARM64 |\n| EDK2 ARM64 | `Synchronous Exception`, `X0` | ARM64 |\n| EDK2 x64 | `!!!! X64 Exception`, `RIP  -` | x86-64 |\n\n---\n\n## Dependencies\n\nPython 3.11+. Pulled in automatically by `pip install -e .`:\n\n| Package | Purpose | Pulled by |\n|---------|---------|-----------|\n| `pyelftools` | ELF + DWARF baseline | base |\n| `capstone` | x86-64 / ARM64 disassembly | base |\n| `cxxfilt` | C++ name demangling | base |\n| `pefile` | PE binary parsing | base |\n| `flask` + `flask-sock` + `simple-websocket` | web UI + WS terminals | base |\n| `pygdbmi` | GDB/MI cross-check backend | `[gdb]` extra |\n| `pytest` | test suite | `[dev]` extra |\n| `playwright` | browser regression tests | `[browser]` extra |\n\nExternal commands: `gdb` if you use `--backend gdb`; `git` if you use\n`--tag`/`--commit` for source context; `node` + `npm` if you build the\nReact frontend yourself.\n\nFor the Playwright browser tests:\n\n```bash\npip install -e \".[browser]\"\npython -m playwright install chromium\n```\n\n## Running the tests\n\n```bash\npytest -q                # ~160 tests, ~30 seconds\npytest -m parser         # parser-only (fastest subset, no Flask)\npytest -m api            # Flask API\npytest -m lldb           # only the LLDB-gated tests (skipped if no LLDB)\n```\n\n---\n\n## Architecture\n\nSee [DESIGN.md](DESIGN.md) for the full backend architecture\n(SQLite session store, ingest pipeline, three DWARF backends,\nschema migrations, frontend persistence contract, etc.).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faximcode%2Frsod-decode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faximcode%2Frsod-decode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faximcode%2Frsod-decode/lists"}