Skip to main content
Glama
resc
by zney295
README.md
# resc — MCP data recovery engine and AI recovery skills

**resc is an open-source, read-only disk-image recovery toolkit for MCP-compatible AI assistants.**
It combines a Rust JSON-RPC engine, Python command-line tools and five recovery skills
for Codex and Antigravity/Gemini. It inspects disk images, tests filesystem repairs
in a durable virtual overlay, and exports supported files with SHA-256 provenance.

**Tiếng Việt:** Bộ skill cứu dữ liệu cho AI: chẩn đoán ảnh đĩa USB/SSD/HDD,
thử sửa metadata trong overlay và xuất file NTFS/FAT vào vị trí riêng.

[What resc does and FAQ](docs/discover-resc.md) · [Download Windows toolkit](https://github.com/zney295/resc/releases/latest) · [Installation guide](docs/recovery-guide.vi.md) · [Current capabilities](docs/engine-capabilities.md)

> **Implementation status:** See [implemented capabilities and limitations](docs/engine-capabilities.md)
> for the hardened engine's actual behavior: 512/4096-byte sectors, durable overlay WAL,
> asynchronous extraction, paginated hits and SHA-256 provenance manifests. Native NTFS/FAT reads use the overlay;
> unsupported features return explicit errors. Historical feature claims below are
> not a substitute for this capability reference or the live MCP tool schema.

<div align="center">

## 🛡️ resc
**Low-Level Disk Forensics & Data Recovery MCP Engine in Rust**

[![Rust](https://img.shields.io/badge/Built_with-Rust_&_SIMD-orange?logo=rust)](https://www.rust-lang.org/)
[![MCP](https://img.shields.io/badge/Protocol-MCP_(JSON--RPC)-blue)](https://modelcontextprotocol.io/)
[![Safety](https://img.shields.io/badge/Source_I/O-read--only-blue)](#safety-architecture-in-memory-virtual-overlay)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)

*Use an MCP agent to inspect disk images and test recovery patches in a virtual overlay.*

Reviewed v5 additions: [unified CLI, installer, header/driver diagnostics and limitations](docs/v5-integration-review.vi.md).

[Architecture](#hybrid-brain--muscle-architecture) • [Safety Guarantee](#safety-architecture-in-memory-virtual-overlay) • [Quick Start](#quick-start) • [MCP Tools](#mcp-tools-catalog) • [Forensic Playbooks](#built-in-forensic-skills--playbooks)

</div>

---

![Illustrated resc recovery workflow](./assets/demo.gif)

This animation is a simulated illustration, not a recorded recovery session. Consult the capability reference for implemented operations.

## Setup and recovery workbench

Read the **[Vietnamese step-by-step recovery guide](docs/recovery-guide.vi.md)**
for installation, selecting raw source images, diagnosing multiple failure types,
MP4/MOV box analysis, exact byte-range reconstruction and FFmpeg verification.
The workbench does not require choosing a failure hypothesis in advance.
The [recovery skills](docs/skill-upgrade.vi.md) route 17 case types,
including USB No Media, reader disagreement, 00/FF-dominant images, zero-hit and
persistence failures. They include a streaming read-only image audit/comparison
helper; they do not claim to repair hardware or create bytes missing from a source.
For a computer that cannot boot its OS, start with the
[two-computer / Linux Live rescue guide](docs/two-computer-rescue.vi.md).
`scripts/rescue.py` adds Linux device inventory, GNU ddrescue acquisition with
resume/retry, an existing-Live-USB toolkit bundle, authenticated SSH control and
resumable hash-verified transfer of sealed acquisitions. SSH acquisition stages
the image on a healthy destination disk at the source computer before transfer;
it does not make a powered-off computer accessible through an ordinary USB cable.
Read the [professional literature review and research roadmap](docs/research/literature-review-and-roadmap.vi.md)
for 14 examined works and the distinction between implemented capabilities and
proposed metadata-, codec- and validation-guided reconstruction.
The [controlled deep-evidence study](docs/research/deep-evidence-study.vi.md)
records reproducible negative cases: two structurally valid PNG candidates can
conflict, and an MP4 can probe/decode all frames while containing wrong video data.
See the [three-case integration guide](docs/three-cases.vi.md) and independently
researched implementations for partition/boot damage, deleted FAT32 metadata and
fragmented content. Added tools include `analyze_partition_recovery` and
`analyze_file_candidate`; FAT32 deleted-entry discovery is an asynchronous job.

```bash
bash scripts/setup.sh
python scripts/recovery.py doctor
python scripts/recovery.py triage /path/to/source.img --deep
python scripts/recovery.py mcp-config --session-root /path/to/persistent-state
```

New MCP tools: `diagnose_recovery`, `analyze_video_candidate`. Scan jobs include
`ISO_BMFF_BOX_SCAN` and `METADATA_WITHOUT_VBR`. Open a Windows raw-device session
with `storage_diagnostics: true` to report capacity and write state. New export mode: `CARVE_BY_BYTE_RANGES`. These add evidence-led
triage and exact extent reconstruction; they do not infer arbitrary fragment order
or regenerate missing video metadata. See [algorithm provenance](docs/open-source-engines.md).

## Why `resc`?

When a USB drive or hard disk turns `RAW`, loses its partition table, or suffers from corrupted `$MFT` / `FAT` headers, users face a painful choice:
1. **Commercial GUI tools ($70–$100+):** Expensive, black-box scanners that often fail on complex structural corruption or fragmented media (`moov` atom separation in MP4s, broken SQLite B-trees).
2. **Open-source CLI forensics (`TestDisk`, `The Sleuth Kit`, `ddrescue`, Hex Editors):** Extremely powerful, but require deep knowledge of LBA offsets, Boot Sector byte structures, and manual hex patching.

**`resc` bridges this gap.** However, you cannot simply feed a 500GB raw disk image into an LLM's context window. 

`resc` implements a **Hybrid Brain & Muscle Architecture**:
* **The Rust engine:** Provides read-only image I/O, Windows physical I/O, streaming signature discovery, entropy measurements, MBR/GPT validation, native NTFS/FAT traversal and bounded MP4/MOV structure inspection. Actual throughput depends on the source and hardware.
* **The Brain (AI Agent via MCP):** Receives ultra-compact **< 5KB JSON Anomaly Reports**, diagnoses structural corruption, tests hex patches safely in **RAM (Copy-on-Write Overlay)**, and orchestrates file extraction.

---

## Hybrid "Brain & Muscle" Architecture

```text
┌─────────────────────────────────────────────────────────────────────────┐
│                    AI AGENT (Claude / Cursor / Gemini)                  │
│  • Reads Forensic Playbooks (.agents/skills/)                           │
│  • Analyzes <5KB JSON Anomaly Maps & formulates recovery strategies     │
└───────────────────────────────────▲─────────────────────────────────────┘
                                    │ Model Context Protocol (JSON-RPC stdio)
┌───────────────────────────────────▼─────────────────────────────────────┐
│                        resc MCP SERVER (crates/mcp-server)              │
│  • Async Job Queue (Prevents MCP timeouts on multi-terabyte scans)      │
│  • Virtual Disk Overlay (512/4096-byte sectors and durable WAL)        │
└───────────────────────────────────▲─────────────────────────────────────┘
                                    │ Rust Internal API / Zero-Copy Structs
┌───────────────────────────────────▼─────────────────────────────────────┐
│                 NATIVE ENGINE (core-io / disk-parsers)                  │
│  • Layer 0: Read-only image and Windows physical-device I/O            │
│  • Layer 1: Signature scanning and entropy analysis                    │
│  • Layer 2: MBR/GPT and native NTFS/FAT validation                    │
│  • Layer 3: Background image extraction and cloning                    │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## Safety Architecture: In-Memory Virtual Overlay

Source media are opened read-only by resc. Virtual patches are applied to an in-memory overlay and recorded in a session WAL; they are never written to the source by resc. This is **not a hardware write blocker**: the OS or another application may still modify shared media. Native NTFS/FAT validation checks root traversal and a file entry; it does not certify the whole filesystem. See [capabilities](docs/engine-capabilities.md) and [SECURITY.md](SECURITY.md) for the boundaries.

---

## Quick Start

### 1. MCP Client Configuration

Copy [mcp_config.example.json](mcp_config.example.json) into your MCP client configuration and replace its placeholders with absolute paths. The launcher requires a locally built or otherwise trusted native binary; it does not download one. It uses `RESC_MCP_BIN`, or the legacy `RECOVERYAI_MCP_BIN` fallback, when set.

If `resc-mcp` is available on npm, the equivalent package-based configuration is:

```json
{
  "mcpServers": {
    "resc": {
      "command": "npx",
      "args": ["-y", "resc-mcp"],
      "env": { "RESC_MCP_BIN": "<absolute-path-to-trusted-mcp-server-binary>" }
    }
  }
}
```

The npm package is named `resc-mcp`; its `resc`, `resc-mcp` and legacy
`recoveryai-mcp` commands all use `bin/resc-mcp.js`. To select the `resc` alias
explicitly, use `npx --package resc-mcp resc`. Bare `npx resc` resolves the npm
package named `resc` and requires that package to be published separately. Package publication and release availability must be verified separately; the npm package does not include the native binary.

### 2. Build from Source (Rust Workspace)

Prerequisites: **current Rust stable** (Cargo), **Node >=18**, and **Python >=3.11**. For physical drive access on Windows, run your terminal/client as **Administrator**.

```bash
git clone https://github.com/psy-zney/resc.git
cd resc

# External legacy forensic adapters are currently disabled; no companion downloads are needed.

# Build the release binary
cargo build --release --locked

# Run disposable synthetic corruption / reconstruction tests
python ./tests/test_e2e_recovery.py
python ./tests/test_recovery_workbench.py
python ./tests/test_deleted_recovery.py
python ./tests/test_three_cases.py
python ./tests/test_rescue.py
```

Windows supports image files and physical-drive inspection. CI also exercises image workflows on Ubuntu; raw devices on non-Windows platforms return `NotImplemented`. macOS is not covered by CI. Raw-device extraction and cloning are currently unavailable even on Windows. See [capabilities](docs/engine-capabilities.md).

### 3. Set up Codex and Antigravity

After building the engine, use Python 3.11+ to preview and apply the configuration
and five bundled skills. Use `--client codex` or `--client antigravity` for one client,
and `--root PATH` to select a configuration home.

```powershell
python scripts/setup_clients.py --client both
python scripts/setup_clients.py --client both --apply
```

The installer stages changed files, creates backups, replaces each file
atomically, verifies readback, and rolls back on handled failures.
Codex uses `.codex/config.toml` and `.agents/skills/` under the selected home.
With the default home, `CODEX_HOME` can override the Codex config directory.
Antigravity uses `.gemini/config/mcp_config.json` and `.gemini/config/skills/`.
An existing unmanaged Codex `resc` entry that differs from the proposed
settings needs a manual merge.

---

## MCP Tools Catalog

`tools/list` exposes **18 tools** including four legacy aliases. The live schema
and [AGENTS.md tool matrix](AGENTS.md#mcp-tools) are the parameter reference.
The server reports MCP protocol version `2024-11-05` at initialization.

The main workflow is open → diagnose → inspect/scan → validate an evidence-based
repair or reconstruction → export asynchronously → verify provenance/content.
`scan_filesystem_journals` remains an explicit NotImplemented endpoint. New video
box scanning and byte-range exports supplement native NTFS/FAT allocated-file
extraction. They do not automatically reconstruct arbitrary fragmented files.

---

## Built-in Forensic Skills & Playbooks

`resc` ships with five version-4.1 skills (inspired by [REA](https://github.com/morluto/rea)). They route by evidence and distinguish implemented operations from external handoffs; use the [capability reference](docs/engine-capabilities.md) and live MCP schema:

* **`disk-forensics/`**: Device/media and reader checks, MBR/GPT and NTFS/FAT boot proposals, acquisition and unbootable-host workflows.
* **`file-carving-and-defrag/`**: Bounded discovery, heuristic fragment candidates, JPEG/PNG/MP4 validation and external SQLite salvage handoff.
* **`filesystem-repair/`**: Overlay-only NTFS/FAT proposals and explicit limits for deleted records, exFAT and Ext4.
* **`mcp-disk-automation/`**: Actual asynchronous job states, cancellation, cursor pagination, quotas and artifact preservation.
* **`recovery-triage/`**: Seventeen case routes, including No Media, reader disagreement, 00/FF, zero-hit and persistence; regular-image audit/comparison helpers.

For an MBR USB previously formatted outside resc, verify captures made before
format (T0), after flush (T1), and after reconnect (T2). Supply separate readback
files for the two canary observations and the expected digest of the original
canary. The verifier reads regular files and reports which metadata and canary
bytes agree. The operator supplies the capture provenance.

Windows USB reuse has a separate preview-first execution path:
`python scripts/usb_format_verify.py format --drive D: --filesystem exfat`
or `python scripts/usb_format_verify.py write-canary --drive D:`. After approving
the displayed device identity, pass its `--confirm` token. Formatting additionally
requires `--data-loss-accepted` and erases the entire selected disk. Both commands
enforce USB/system/pagefile guards and require Administrator for execution.
Formatting automatically writes four 1 MiB canary files and checks their SHA-256
after flush. External audit manifests are stored under `%LOCALAPPDATA%/resc/usb-lab`.
Reconnect verification and full-capacity testing remain separate observations.

```powershell
python scripts/usb_format_verify.py --filesystem exfat --t0 t0.img --t1 t1.img --t2 t2.img --canary-t1 t1.bin --canary-t2 t2.bin --canary-sha256 EXPECTED_SHA256
```

---

## Project Structure

```text
resc/
├── .agents/skills/          # 5 Specialized AI Forensic Skill Modules & 13 Playbooks
├── ai-context/              # Decision trees & tool catalogs for LLM context injection
├── bin/                     # Node.js NPX wrapper (resc-mcp.js) for instant MCP integration
├── crates/
│   ├── core-io/             # 4KB-aligned DMA buffers, SCSI watchdog, RAM Virtual Overlay
│   ├── disk-parsers/        # Zero-copy MBR/GPT/NTFS/FAT structs, SIMD carver, Defrag matcher
│   ├── external-bridges/    # Headless wrappers for The Sleuth Kit, PhotoRec, GNU ddrescue
│   └── mcp-server/          # Tokio JSON-RPC stdio server & Async Job Manager
└── tests/                   # Synthetic disk corruption generator & E2E verification suite
```

## Reliability, Verification & OS Boundaries

`resc` applies defensive checks when handling untrusted, corrupted disk media:

* **Verified test results:** Local Windows validation passed **46 unit tests**, **16 synthetic E2E groups**, and **1,000,000 deterministic malformed-input cases** across MBR, GPT, NTFS boot-sector and FAT32 parsers with no observed panics. This regression corpus is not a completed libFuzzer campaign or proof of safety for every input.
* **Persistent CoW overlay:** Patches for **512-byte and 4096-byte logical sectors** are synced to a session Write-Ahead Log (`.wal`) before changing RAM. Retained image sessions can replay verified records after restart when source identity and geometry match. Preserve `RESC_SESSION_ROOT`; interrupted jobs do not resume automatically.
* **TOCTOU and overwrite protection:** Background extraction uses no-follow flags and platform handle identity checks before writes. Exclusive `.part` files, `sync_all`, metadata-first publication and rollback protect clone/mapfile and file/manifest pairs. This is a recoverable protocol, not one atomic transaction across power loss. Completed extractions include SHA-256 provenance manifests (`.manifest.json`).
* **Kernel I/O boundaries:** Windows overlapped reads request `CancelIoEx` after a 500 ms timeout or job cancellation. Buffers remain alive until kernel completion; an unresponsive driver can still delay cancellation. There is no guaranteed hard deadline when the driver does not complete its request.
* **Panic boundaries:** Release builds require `panic = "unwind"`; handler and worker boundaries report caught panics as errors. `catch_unwind` does not isolate memory corruption, OOM aborts or non-terminating parser execution. Safe Rust and passing tests reduce risk without eliminating these boundaries.

[CI](.github/workflows/ci.yml) runs on Windows and Ubuntu. For commit [`19cb436`](https://github.com/psy-zney/resc/commit/19cb436651b660b7616be20aeb0c4d6e0d0be484), [Ubuntu CI](https://github.com/psy-zney/resc/actions/runs/40133458988/job/120989912337) passed release build, unit tests, Clippy and E2E. Local Windows release compilation was blocked by Application Control (OS error 4551); the local E2E results above used the debug binary. See the [verification report](docs/hardening-verification.md) and [implemented capabilities](docs/engine-capabilities.md) for evidence and limits.

## Disclaimer & Safety Notice

Data recovery on failing hardware carries inherent physical risks. If a drive is making mechanical clicking noises, **unplug it immediately** and seek a cleanroom lab. `resc` is strictly read-only at the software layer, but scanning a dying NAND flash chip or degraded platter can accelerate hardware failure—always use the `DD_RESCUE_CLONE` workflow first when `bad_sectors_count > 0`.

## License

Licensed under the [Apache License 2.0](./LICENSE).

TDQS

B3/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of confusing it with another operation. Its purpose is explicitly limited to read-only disk header inspection, so selection is unambiguous.

Naming Consistency5/5

The single tool name inspect_disk_headers follows a clear verb_noun snake_case pattern. There are no competing conventions to create inconsistency.

Tool Count3/5

A single tool is defensible for a strictly narrow read-only header-evidence server, but it feels thin for a server named resc and offers no broader lifecycle. The tool count is borderline rather than clearly well-scoped.

Completeness2/5

The surface only reads regular-image header evidence and samples at most eight volumes. It explicitly lacks repair, extraction, and broader disk recovery operations, leaving significant gaps for a rescue-oriented domain.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues