Content
<div align="center">
```text
██████╗ ███████╗██╗ ██╗ ██████╗ ██████╗ ██████╗ ███████╗
██╔══██╗██╔════╝██║ ██║ ██╔════╝██╔═══██╗██╔══██╗██╔════╝
██████╔╝█████╗ ██║ ██║ ██║ ██║ ██║██████╔╝█████╗
██╔══██╗██╔══╝ ╚██╗ ██╔╝ ██║ ██║ ██║██╔══██╗██╔══╝
██║ ██║███████╗ ╚████╔╝ ╚██████╗╚██████╔╝██║ ██║███████╗
╚═╝ ╚═╝╚══════╝ ╚═══╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚══════╝
```
### **Autonomous Reverse Engineering Engine & Model Context Protocol (MCP) Server in Systems Rust**
[](https://crates.io/crates/rev-core)
[](https://www.rust-lang.org)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](#-test-verification)
[](https://hits.sh/github.com/ronitgupta138/rev-core/)
[](https://github.com/sponsors/ronitgupta138)
**Reverse engineer anything with agents, from app behavior down to native binaries.**
A lightweight, zero-dependency, memory-safe native CLI and Model Context Protocol server that gives AI coding agents (Claude Code, Hermes Agent, Cursor, Codex) deep analytical capabilities over closed binaries, desktop packages, and live memory.
</div>
---
## 📌 Overview
Traditional reverse-engineering integrations rely on slow, multi-gigabyte runtime environments (Node.js wrappers, JVM-based Ghidra installations, or Python scripts). **`rev-core`** changes this paradigm by delivering an ultra-fast, zero-overhead systems engine in pure Rust:
1. **Sub-Millisecond Agent Latency (< 2ms):** Responds immediately over standard I/O via the Model Context Protocol (MCP) without spawning heavy runtime processes.
2. **Anti-Hallucination Evidence Ledger:** Replaces speculative LLM guesses with deterministic SHA-256 cryptographic provenance records and explicit **Residual Unknowns**.
3. **Multi-Format Polyglot Coverage:** Native zero-copy parsing for Linux ELF, Windows PE, Apple Mach-O / Universal FAT, WebAssembly (WASM), and Electron Chromium ASAR archives.
4. **Live Memory Forensics:** Scans `/proc/[pid]/maps` to reconstruct process memory layouts and flag dangerous writable-and-executable (`rwx`) pages.
---
## 🏗️ System Architecture
```text
┌────────────────────────────────────────────────────────────────────────┐
│ AGENT & OPERATOR CLIENTS │
│ Claude Code · Hermes Agent · Cursor · Codex · CLI Terminal │
└───────────────────────────────────┬────────────────────────────────────┘
│ stdio / JSON-RPC 2.0
▼
┌────────────────────────────────────────────────────────────────────────┐
│ MODEL CONTEXT PROTOCOL (MCP) SERVER │
│ - inspect_binary - inspect_mitigations - disassemble_slice │
│ - generate_cfg - analyze_entropy - scan_crypto │
│ - scan_electron - inspect_wasm - decompile_symbol │
│ - inspect_process_maps - get_evidence_ledger - tokio stdio loop │
└───────────────────────────────────┬────────────────────────────────────┘
│
┌───────────────────────────────────┴────────────────────────────────────┐
│ EVIDENCE & INTEGRITY LEDGER │
│ - Deterministic SHA-256 hashing (RFC 8785 canonical data payloads) │
│ - Residual Unknown Registry (tracks unverified targets & gaps) │
└───────────────────────────────────┬────────────────────────────────────┘
│
┌───────────────┬─────────────────┼─────────────────┬───────────────┐
▼ ▼ ▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌─────────────┐ ┌───────────────┐
│ NATIVE BINARY │ │ CONTROL FLOW │ │ CRYPTO/ENTROPY│ │ APPLICATION │ │ LIVE PROCESS │
│ - ELF (Linux) │ │ - Leaders │ │ - Shannon H(X)│ │ - ASAR unpack│ │ - /proc/maps │
│ - PE (Windows)│ │ - Basic Blocks│ │ - AES/SHA/MD5 │ │ - Electron │ │ - RWX scanner │
│ - Mach-O (Mac)│ │ - Mermaid/Tree│ │ - Magic tables│ │ IPC audit │ │ - Drift check │
└───────────────┘ └───────────────┘ └───────────────┘ └─────────────┘ └───────────────┘
```
---
## ⚡ Core Capabilities
### 1. Zero-Copy Native Binary Engine
* **Linux ELF:** Headers, class (32/64-bit), endianness, machine architecture, segment/section tables, and `DT_NEEDED` library dependencies.
* **Windows PE:** Machine architecture, entrypoint, section count, Windows subsystem, and imported DLL dependencies.
* **Apple Mach-O:** 64-bit Mach-O and Universal FAT archives supporting x86_64 and Apple Silicon (`arm64`), segment load commands, and `LC_CODE_SIGNATURE` verification.
* **Security Mitigation Scanner:**
- **NX / DEP:** Verified via `PT_GNU_STACK` executable flag bitmask.
- **PIE:** Position-independent executable verification (`ET_DYN` vs `ET_EXEC`).
- **RELRO:** Differentiates Full RELRO (`PT_GNU_RELRO` + `DT_BIND_NOW`), Partial RELRO, and No RELRO.
- **Stack Canaries:** Probes dynamic and static symbol tables for `__stack_chk_fail`.
- **macOS Protections:** Hardened Runtime, restricted segment attributes, and library validation.
- **Windows Protections:** ASLR (`DYNAMIC_BASE`), DEP (`NX_COMPAT`), Control Flow Guard (CFG), and SEH.
### 2. In-Process Multi-Architecture Disassembly & CFG Engine
* **Instruction Decoder:** Decodes raw machine code into Intel assembly with hex opcodes across **x86_64**, **ARM64 / AArch64**, and **RISC-V**.
* **Recursive Descent Control Flow Graphs:** Partitions linear instructions into interconnected basic blocks based on leaders and jump/call branch targets.
* **Mermaid & ASCII Export:** Emits visual flowcharts (`graph TD`) directly into markdown, Cursor, or terminal displays.
* **Cyclomatic Complexity:** Calculates McCabe complexity ($M = E - N + 2P$) per code region.
### 3. Cryptographic & Entropy Intelligence
* **Shannon Entropy ($H(X) = -\sum P(x) \log_2 P(x)$):** Scans file bytes to instantly detect packed, obfuscated, or encrypted payloads (>7.2 score).
* **Cryptographic Constant Matcher:** Pattern-matches hardware and software crypto constants:
- AES forward & inverted Rijndael S-Boxes
- ChaCha20 quarter-round state (`"expand 32-byte k"`)
- SHA-256 round constant sequence ($K_0..K_3$)
- MD5 state buffer initialization words ($A, B, C, D$)
### 4. Pure-Rust Electron & ASAR Unpacker
* Zero Node/npm runtime dependency Chromium Pickle and ASAR archive reader.
* Scans extracted Electron applications for IPC channels (`ipcRenderer.send`, `ipcRenderer.invoke`, `ipcMain.handle`, `contextBridge.exposeInMainWorld`).
* Audits `webPreferences` vulnerability risks (`nodeIntegration: true`, `contextIsolation: false`, `webSecurity: false`).
### 5. WebAssembly (WASM) Diagnostics
* Pure-Rust LEB128 decoder parsing standard WebAssembly (`\0asm`) modules.
* Extracts initial/maximum linear memory page allocations, declared functions, and exported/imported API signatures.
### 6. Live Process Virtual Memory Forensics
* Reconstructs virtual memory space from `/proc/[pid]/maps`.
* Pinpoints dangerous **Writable + Executable (`rwx`)** memory pages to expose shellcode injection and unmitigated dynamic code execution.
---
## 🚀 Installation & CLI Quickstart
### Install via Cargo
```bash
cargo install rev-core
```
### Inspect a Binary
```bash
rev-core inspect /bin/ls
```
### Check Security Mitigations
```bash
rev-core mitigations /bin/ls
```
### Generate Control Flow Graph
```bash
rev-core cfg /bin/ls --offset 0x6d30 --format mermaid
```
### Calculate Shannon Entropy & Scan Cryptographic Signatures
```bash
rev-core entropy /bin/ls
rev-core crypto /bin/ls
```
### Disassemble Instructions (Multi-Arch)
```bash
rev-core disasm /bin/ls --offset 0x6d30 --count 10 --arch x86_64
```
### Unpack & Audit Electron Applications
```bash
# Unpack ASAR archive
rev-core asar unpack app.asar -o ./unpacked_app
# Scan Electron IPC attack surface & webPreferences
rev-core electron ./unpacked_app
```
### Inspect WebAssembly Modules
```bash
rev-core wasm module.wasm
```
### Live Process Memory Forensics
```bash
rev-core proc $(pgrep -n bash)
```
---
## 🔌 Model Context Protocol (MCP) Integration
`rev-core` runs as a native stdio Model Context Protocol server. Add it to your agent settings (`claude_desktop_config.json`, Hermes profile, or Cursor config):
```json
{
"mcpServers": {
"rev-core": {
"command": "rev-core",
"args": ["mcp"]
}
}
}
```
### Registered Tools
| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `inspect_binary` | `path: string` | Parse ELF, PE, or Mach-O headers, architecture, entrypoint, sections, and dependencies. |
| `inspect_mitigations` | `path: string` | Scan binary protections: NX/DEP, PIE, Full/Partial RELRO, Canaries, and ASLR. |
| `disassemble_slice` | `path, offset, length, max_instructions, arch` | Decode machine code instructions into Intel assembly with hex opcodes. |
| `generate_cfg` | `path, offset, max_instructions` | Reconstruct basic blocks, control flow graph, cyclomatic complexity, and Mermaid diagram. |
| `analyze_entropy` | `path: string` | Calculate Shannon entropy across file bytes to detect packed or encrypted code. |
| `scan_crypto` | `path: string` | Match cryptographic state constants (AES S-Boxes, ChaCha20, SHA, MD5). |
| `scan_electron` | `dir: string` | Audit extracted Electron directory for IPC channels and `webPreferences` security risks. |
| `inspect_wasm` | `path: string` | Parse WebAssembly module sections, memory limits, and exported API signatures. |
| `inspect_process_maps`| `pid: number` | Inspect live process memory layout from `/proc/[pid]/maps` and flag RWX pages. |
| `decompile_symbol` | `path, symbol, timeout_secs` | Decompile symbol via local headless decompiler bridges (rizin, r2, ghidra). |
| `get_evidence_ledger` | *(none)* | Retrieve verified cryptographic Evidence records and open residual unknowns. |
---
## 📊 Benchmark Comparison: `rev-core` vs `rea`
| Metric | `morluto/rea` (TypeScript) | `rev-core` v1.0.0 (Rust) |
| :--- | :--- | :--- |
| **Runtime Dependencies** | Node 22+, npm, Python, JDK | **Zero (single native binary)** |
| **Startup / Tool Latency** | 1,200ms – 4,500ms | **< 2ms (sub-millisecond)** |
| **Binary Memory (RSS)** | 200MB – 1.2GB (V8 + JVM) | **< 15MB** |
| **Crash Protection** | High risk of V8 heap OOM | **Rust memory safety & zero panics** |
| **Disassembly Engine** | External process delegation | **In-process multi-arch decoder** |
| **Electron ASAR Extraction** | External npm scripts / slow | **Native Chromium Pickle parser** |
---
## 🧪 Test Verification
Run the automated test suite:
```bash
cargo test
```
All 14 integration test suites pass with 100% green status:
* `tests/elf_test.rs` — Live Linux system ELF parsing and mitigation validation.
* `tests/macho_test.rs` — 64-bit Apple Mach-O header and mitigation parsing.
* `tests/disasm_test.rs` — x86_64 instruction decoder verification.
* `tests/arch_test.rs` — Synthetic ARM64 and RISC-V machine code decoding.
* `tests/cfg_test.rs` — Branch target identification and Mermaid graph generation.
* `tests/analysis_test.rs` — Shannon entropy calculation and cryptographic constant detection.
* `tests/asar_test.rs` — Synthetic Chromium Pickle & ASAR archive extraction roundtrip.
* `tests/electron_test.rs` — Electron IPC attack surface and `webPreferences` audit.
* `tests/wasm_test.rs` — WebAssembly header, memory limits, and export section decoding.
* `tests/process_test.rs` — Live `/proc/[pid]/maps` memory parsing and RWX detection.
* `tests/bridge_test.rs` — Headless decompiler bridge detection and error handling.
* `tests/evidence_test.rs` — Deterministic SHA-256 evidence hashing and ledger lifecycle.
---
## 📜 License
Distributed under the [MIT License](LICENSE). Copyright (c) 2026 Ronit Gupta.
Connection Info
You Might Also Like
No recommendations available