rev-core

<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.