[PR #3770] feat(native): inspect Windows minidump streams offline #5888

Open
opened 2026-10-31 01:10:12 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/3770
Author: @Kizuno18
Created: 10/15/2026
Status: 🔄 Open

Base: main ← Head: feat/windows-minidump-inspect


📝 Commits (5)

  • c1fa26d feat(native): inspect Windows minidump streams offline
  • 3674e7f Merge remote-tracking branch 'upstream/main' into feat/windows-minidump-inspect
  • da0754c fix(native): bound minidump decoding and close review gaps
  • 87db6a3 Merge remote-tracking branch 'upstream/main' into feat/windows-minidump-inspect
  • 798b00c fix(native): classify minidump budget refusals by boundary

📊 Changes

28 files changed (+1782 additions, -1 deletions)

View changed files

📝 docs/recorded-crashes.md (+26 -0)
➕ docs/specs/2355-windows-minidump-inspection/plan.md (+13 -0)
➕ docs/specs/2355-windows-minidump-inspection/spec.md (+66 -0)
➕ docs/specs/2355-windows-minidump-inspection/tasks.md (+9 -0)
➕ docs/specs/2355-windows-minidump-inspection/verification.md (+14 -0)
📝 scripts/lib/catalog-builders.mjs (+7 -0)
📝 src/application/CapabilityInventory.ts (+5 -1)
➕ src/application/binaryDiagnostics/WindowsMinidumpPort.ts (+20 -0)
➕ src/application/binaryDiagnostics/WindowsMinidumpService.test.ts (+80 -0)
➕ src/application/binaryDiagnostics/WindowsMinidumpService.ts (+131 -0)
📝 src/cli/binaryDiagnosticsCommands.ts (+38 -0)
📝 src/cliCommandNames.ts (+1 -0)
📝 src/composition/binaryDiagnostics.ts (+6 -0)
📝 src/contracts/native/binaryDiagnosticsToolContracts.ts (+19 -0)
📝 src/contracts/toolEffects.test.ts (+2 -0)
📝 src/contracts/toolEffects.ts (+1 -0)
📝 src/domain/artifactOperationError.ts (+1 -0)
📝 src/domain/investigationProviders.ts (+7 -0)
➕ src/domain/native/windowsMinidump.ts (+213 -0)
➕ src/native/minidump/WindowsMinidump.fixture.ts (+138 -0)

...and 8 more files

📄 Description

Summary

Fixes #2355

Adds inspect_windows_minidump / rea inspect-windows-minidump: offline inspection of a supplied Windows minidump (MDMP) as recorded crash evidence, with no live target, no attach, no debugger and no symbol/module download. The existing inspect_recorded_crash ELF core profile and schema are unchanged.

Problem and expected behavior

inspect_recorded_crash declares an ELF core result and only admits Linux profiles. A caller holding a Windows minidump had no way to get its stream directory, recorded threads, exception, modules and present memory ranges as Evidence. Now the caller gets a complete, range-validated report, or a typed failure with no partial success.

Change and scope

  • Spec/plan/tasks/verification: docs/specs/2355-windows-minidump-inspection/.
  • Domain schema src/domain/native/windowsMinidump.ts; pure TypeScript parser src/native/minidump/WindowsMinidumpParser.ts. It follows the portable PE resource parser/provider pattern: stable artifact read, typed failures, owned resource scope and cleanup.
  • Interpreted subset: Header, stream directory, SystemInfo (7), ThreadList (3), Exception (6), ModuleList (4), MemoryList (5), Memory64List (9). Thread and exception contexts are always located. AMD64 contexts also report ContextFlags, MxCsr, segments, EFlags, the integer registers and Rip, each bound to its source bytes. Other architectures keep a located context that is not interpreted. Unknown and unused streams are listed with their original ranges.
  • Historical thread IDs and recorded module names are metadata only. Undescribed memory, absent streams and uninterpreted streams stay explicitly unknown.
  • Rejected as caller input errors: truncated ranges, wrong signature or version, duplicate interpreted streams, non-identical overlapping stream or memory-content ranges, list count/size mismatch (4- or 8-byte count padding is accepted) and incomplete fixed-size streams.
  • Bounds: max_file_bytes (default 256 MiB, max 1 GiB) and max_entries (default 65536). The parser yields cooperatively and honors cancellation.
  • Not included: x86/ARM/ARM64 register interpretation, other stream types (MiscInfo, HandleData, UnloadedModules, ThreadInfo…), CodeView parsing and symbol resolution.

Contract and boundary impact

  • Semantic owner and earliest changed stage: new domain schema windowsMinidump.ts → parser/provider → WindowsMinidumpService.
  • Contribution scope fit and linked maintainer decision: no separate scope decision is required. This is a recorded-file reader with no execution, attach or mutation authority. The new parser provider identity (rea-windows-minidump) follows the existing rea-pe-resources pattern and adds no new authority class, so it is covered by normal review.
  • CLI and MCP/tool-catalog contract: additive tool inspect_windows_minidump and CLI inspect-windows-minidump. Both share WindowsMinidumpService, and the contract is registered in BINARY_DIAGNOSTICS_TOOL_CONTRACTS.
  • Provider, bridge, target-format, or platform compatibility: portable Node, with no external tools.
  • Evidence, artifact, provenance, or reconstruction contract: Evidence subject format: "file" with architecture from SystemInfo when known. Confidence is observed, and every fact carries a file range.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): explicit path only, and historical IDs never select processes. The stable read uses ArtifactResourceScope, and cleanup failures are reported.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact: catalog builder maps the new contract to its provider identity; metadata:check passes.

Expected effects:

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated: src/native/minidump/WindowsMinidumpParser.test.ts (valid AMD64 dump; non-AMD64 context; absent streams; bad signature/truncated; RVA beyond file; overlapping streams; overlapping memory; incomplete thread/exception and duplicate streams; budget and cancellation), src/application/binaryDiagnostics/WindowsMinidumpService.test.ts (Evidence publication, malformed provider output, relative path, cancellation), tests/boundary/filesystem/windowsMinidump.test.ts (real file read, non-file/symlink/truncated/missing, budget, cancellation), tool-effects and acceptance input table entries.
  • Base reproduction or other evidence: source-derived. Fixtures are hand-authored from the documented MINIDUMP_* layouts.
  • User-visible CLI/MCP output (if applicable): rea inspect-windows-minidump ./crash.dmp --json / { "path": "/artifacts/crash.dmp" } returns the Evidence with normalized_result.format: "windows-minidump".
  • Remaining proof gaps: no producer-generated dumps (dbghelp/WER/procdump) yet. No stdio MCP acceptance test for this tool yet; the compiled CLI was only smoke-tested by hand.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

Merged current main (23de10bb2), Node 24.22.1, Linux x64:

  • npx tsc --noEmit -p .: passed
  • npm run check:fast (typecheck + lint): passed
  • npx vitest run src/native/minidump src/application/binaryDiagnostics/WindowsMinidumpService.test.ts tests/boundary/filesystem/windowsMinidump.test.ts src/contracts: 26 files, 244 passed, 3 skipped
  • npx vitest run src/application/CapabilityInventory: passed
  • npm run test:prepare then npx vitest run tests/acceptance/tools/localToolContracts.test.ts: 6 passed
  • npm run metadata:check: passed
  • Compiled CLI smoke: rea inspect-windows-minidump crash.dmp --json with a relative path returns complete Evidence; --max-entries 2 returns resource_constraint with resource: "capacity" and max_entries remediation

Compatibility, safety, and release

  • Breaking changes or migration steps: none; additive tool.
  • Real Hopper/Ghidra, browser, or OS coverage: Linux x64 / Node 22 only.
  • Package or release metadata impact: new tool in catalog.
  • Security, privacy, process, or containment review: reads one file within bounds. No process, network, symbol server or writes.

Author readiness

Human owner: @Kizuno18

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/3770 **Author:** [@Kizuno18](https://github.com/Kizuno18) **Created:** 10/15/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/windows-minidump-inspect` --- ### 📝 Commits (5) - [`c1fa26d`](https://github.com/morluto/rea/commit/c1fa26d50f39bf57a3755ba8e2bb3d9eacb2c9eb) feat(native): inspect Windows minidump streams offline - [`3674e7f`](https://github.com/morluto/rea/commit/3674e7f09df685438847d0bd7427cc6a05cb89c7) Merge remote-tracking branch 'upstream/main' into feat/windows-minidump-inspect - [`da0754c`](https://github.com/morluto/rea/commit/da0754cae88f642ecc8de1297eeedad80d84c839) fix(native): bound minidump decoding and close review gaps - [`87db6a3`](https://github.com/morluto/rea/commit/87db6a313330676f29d7ca9e483682e3ef9d92ec) Merge remote-tracking branch 'upstream/main' into feat/windows-minidump-inspect - [`798b00c`](https://github.com/morluto/rea/commit/798b00c22af82590e2b069bf22999b863cee0219) fix(native): classify minidump budget refusals by boundary ### 📊 Changes **28 files changed** (+1782 additions, -1 deletions) <details> <summary>View changed files</summary> 📝 `docs/recorded-crashes.md` (+26 -0) ➕ `docs/specs/2355-windows-minidump-inspection/plan.md` (+13 -0) ➕ `docs/specs/2355-windows-minidump-inspection/spec.md` (+66 -0) ➕ `docs/specs/2355-windows-minidump-inspection/tasks.md` (+9 -0) ➕ `docs/specs/2355-windows-minidump-inspection/verification.md` (+14 -0) 📝 `scripts/lib/catalog-builders.mjs` (+7 -0) 📝 `src/application/CapabilityInventory.ts` (+5 -1) ➕ `src/application/binaryDiagnostics/WindowsMinidumpPort.ts` (+20 -0) ➕ `src/application/binaryDiagnostics/WindowsMinidumpService.test.ts` (+80 -0) ➕ `src/application/binaryDiagnostics/WindowsMinidumpService.ts` (+131 -0) 📝 `src/cli/binaryDiagnosticsCommands.ts` (+38 -0) 📝 `src/cliCommandNames.ts` (+1 -0) 📝 `src/composition/binaryDiagnostics.ts` (+6 -0) 📝 `src/contracts/native/binaryDiagnosticsToolContracts.ts` (+19 -0) 📝 `src/contracts/toolEffects.test.ts` (+2 -0) 📝 `src/contracts/toolEffects.ts` (+1 -0) 📝 `src/domain/artifactOperationError.ts` (+1 -0) 📝 `src/domain/investigationProviders.ts` (+7 -0) ➕ `src/domain/native/windowsMinidump.ts` (+213 -0) ➕ `src/native/minidump/WindowsMinidump.fixture.ts` (+138 -0) _...and 8 more files_ </details> ### 📄 Description ## Summary Fixes #2355 Adds `inspect_windows_minidump` / `rea inspect-windows-minidump`: offline inspection of a supplied Windows minidump (`MDMP`) as recorded crash evidence, with no live target, no attach, no debugger and no symbol/module download. The existing `inspect_recorded_crash` ELF core profile and schema are unchanged. ## Problem and expected behavior `inspect_recorded_crash` declares an ELF core result and only admits Linux profiles. A caller holding a Windows minidump had no way to get its stream directory, recorded threads, exception, modules and present memory ranges as Evidence. Now the caller gets a complete, range-validated report, or a typed failure with no partial success. ## Change and scope - Spec/plan/tasks/verification: `docs/specs/2355-windows-minidump-inspection/`. - Domain schema `src/domain/native/windowsMinidump.ts`; pure TypeScript parser `src/native/minidump/WindowsMinidumpParser.ts`. It follows the portable PE resource parser/provider pattern: stable artifact read, typed failures, owned resource scope and cleanup. - Interpreted subset: Header, stream directory, SystemInfo (7), ThreadList (3), Exception (6), ModuleList (4), MemoryList (5), Memory64List (9). Thread and exception contexts are always located. AMD64 contexts also report ContextFlags, MxCsr, segments, EFlags, the integer registers and Rip, each bound to its source bytes. Other architectures keep a located context that is not interpreted. Unknown and unused streams are listed with their original ranges. - Historical thread IDs and recorded module names are metadata only. Undescribed memory, absent streams and uninterpreted streams stay explicitly unknown. - Rejected as caller input errors: truncated ranges, wrong signature or version, duplicate interpreted streams, non-identical overlapping stream or memory-content ranges, list count/size mismatch (4- or 8-byte count padding is accepted) and incomplete fixed-size streams. - Bounds: `max_file_bytes` (default 256 MiB, max 1 GiB) and `max_entries` (default 65536). The parser yields cooperatively and honors cancellation. - Not included: x86/ARM/ARM64 register interpretation, other stream types (MiscInfo, HandleData, UnloadedModules, ThreadInfo…), CodeView parsing and symbol resolution. ## Contract and boundary impact - Semantic owner and earliest changed stage: new domain schema `windowsMinidump.ts` → parser/provider → `WindowsMinidumpService`. - Contribution scope fit and linked maintainer decision: no separate scope decision is required. This is a recorded-file reader with no execution, attach or mutation authority. The new parser provider identity (`rea-windows-minidump`) follows the existing `rea-pe-resources` pattern and adds no new authority class, so it is covered by normal review. - CLI and MCP/tool-catalog contract: additive tool `inspect_windows_minidump` and CLI `inspect-windows-minidump`. Both share `WindowsMinidumpService`, and the contract is registered in `BINARY_DIAGNOSTICS_TOOL_CONTRACTS`. - Provider, bridge, target-format, or platform compatibility: portable Node, with no external tools. - Evidence, artifact, provenance, or reconstruction contract: Evidence subject `format: "file"` with architecture from SystemInfo when known. Confidence is `observed`, and every fact carries a file range. - Target selection, authority, upstream behavior, and cleanup details (if applicable): explicit path only, and historical IDs never select processes. The stable read uses `ArtifactResourceScope`, and cleanup failures are reported. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: catalog builder maps the new contract to its provider identity; `metadata:check` passes. Expected effects: - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: `src/native/minidump/WindowsMinidumpParser.test.ts` (valid AMD64 dump; non-AMD64 context; absent streams; bad signature/truncated; RVA beyond file; overlapping streams; overlapping memory; incomplete thread/exception and duplicate streams; budget and cancellation), `src/application/binaryDiagnostics/WindowsMinidumpService.test.ts` (Evidence publication, malformed provider output, relative path, cancellation), `tests/boundary/filesystem/windowsMinidump.test.ts` (real file read, non-file/symlink/truncated/missing, budget, cancellation), tool-effects and acceptance input table entries. - Base reproduction or other evidence: source-derived. Fixtures are hand-authored from the documented `MINIDUMP_*` layouts. - User-visible CLI/MCP output (if applicable): `rea inspect-windows-minidump ./crash.dmp --json` / `{ "path": "/artifacts/crash.dmp" }` returns the Evidence with `normalized_result.format: "windows-minidump"`. - Remaining proof gaps: no producer-generated dumps (dbghelp/WER/procdump) yet. No stdio MCP acceptance test for this tool yet; the compiled CLI was only smoke-tested by hand. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed Merged current `main` (23de10bb2), Node 24.22.1, Linux x64: - `npx tsc --noEmit -p .`: passed - `npm run check:fast` (typecheck + lint): passed - `npx vitest run src/native/minidump src/application/binaryDiagnostics/WindowsMinidumpService.test.ts tests/boundary/filesystem/windowsMinidump.test.ts src/contracts`: 26 files, 244 passed, 3 skipped - `npx vitest run src/application/CapabilityInventory`: passed - `npm run test:prepare` then `npx vitest run tests/acceptance/tools/localToolContracts.test.ts`: 6 passed - `npm run metadata:check`: passed - Compiled CLI smoke: `rea inspect-windows-minidump crash.dmp --json` with a relative path returns complete Evidence; `--max-entries 2` returns `resource_constraint` with `resource: "capacity"` and `max_entries` remediation ## Compatibility, safety, and release - Breaking changes or migration steps: none; additive tool. - Real Hopper/Ghidra, browser, or OS coverage: Linux x64 / Node 22 only. - Package or release metadata impact: new tool in catalog. - Security, privacy, process, or containment review: reads one file within bounds. No process, network, symbol server or writes. ## Author readiness Human owner: @Kizuno18 - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#5888
No description provided.