Metadata-Version: 2.4
Name: frida-mcp-re
Version: 0.3.7
Summary: Model Context Protocol implementation for Frida
License: MIT
License-File: LICENSE
Requires-Python: >=3.8
Requires-Dist: frida>=16.0.0
Requires-Dist: mcp>=1.5.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Description-Content-Type: text/markdown

# Frida MCP

A Model Context Protocol (MCP) implementation for Frida dynamic instrumentation toolkit.

## 🆕 Kernel Backend Support (proyecto.sys)

This fork includes **kernel backend support** for accessing protected processes that are blocked by anti-cheats (EAC, BattlEye, Vanguard, etc.).

### Features
- ✅ **Read/Write memory** of protected processes via kernel driver
- ✅ **Attach to protected games** (Fortnite, PUBG, Valorant, Apex, etc.)
- ✅ **Manual Map DLL injection** (bypass anti-cheat detection)
- ✅ **Pattern scanning** for finding addresses
- ✅ **Automatic detection** - uses kernel if driver loaded, fallback to native Frida

### Quick Start
```bash
# 1. Load the kernel driver
kdmapper.exe proyecto.sys

# 2. Use Frida MCP normally - it auto-detects the driver
# All tools now work with protected processes!
```

### New Memory Tools for Kernel Backend
| Tool | Description |
|------|-------------|
| `read_memory` | Read bytes from process memory (kernel or native) |
| `write_memory` | Write bytes to process memory |
| `read_pointer` | Read a pointer value (8 bytes on x64) |
| `read_float` | Read a 32-bit float value |
| `read_vector3` | Read X, Y, Z position (3 floats) |
| `follow_pointer_chain` | Follow multi-level pointers |
| `scan_memory_pattern` | AOB scan with wildcard support |

### Example: Read Player Position
```python
# Attach to protected game
session = create_interactive_session(pid, device_id="local")

# Read Vector3 position
pos = read_vector3(session_id, "0x12345678")
# Returns: {"x": 123.45, "y": 67.89, "z": 100.00}

# Follow pointer chain
addr = follow_pointer_chain(session_id, base, [0x10, 0x20, 0x30])
```

## Overview

This package provides an MCP-compliant server for Frida, enabling AI systems to interact with mobile and desktop applications through Frida's dynamic instrumentation capabilities. It uses the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) to enable seamless integration with AI applications like Claude Desktop.

## Demo

https://github.com/user-attachments/assets/5dc0e8f5-5011-4cf2-be77-6a77ec960501

## What's New in 0.3.7

- **84 tools total** — 3 new VMProtect post-processing tools + 3 advanced variants
- **`vmp_deep_clean`** — removes all VMProtect traces: renames .vmp sections, zeros DataDirectories, disables ASLR, fixes section flags
- **`vmp_fix_pdata`** — fixes high-entropy .pdata caused by VMP encryption (eliminates 'packed data' warnings in PE-bear/DiE)
- **`vmp_verify_strings`** — verifies dump integrity by scanning .rdata for readable strings and game engine keywords
- **Enhanced `vmp_full_unpack`** — full 7-step pipeline: OEP → dump → patch → deep clean → fix pdata → rebuild IAT → verify strings
- **`list_sessions_detailed`** — extended session listing with PID, timestamp and persistent script count
- **`close_session_force`** — force-close with error recovery (reports warnings instead of failing)
- **`follow_pointer_chain_detailed`** — step-by-step pointer chain trace with dereferenced values at each level

## What's New in 0.3.2

- **7 new VMProtect Unpacker tools** — full runtime unpacking pipeline: OEP detection, PE dump, IAT reconstruction, section header fixing and all-in-one `vmp_full_unpack`
- **xrefs fixed** — rebuilt `.idata` section with proper `IMAGE_IMPORT_DESCRIPTOR` entries so IDA Pro and x64dbg resolve all API calls and string xrefs correctly
- **GetProcAddress hooking** — `vmp_resolve_imports` captures every import VMP resolves at runtime for 100% accurate IAT reconstruction

## What's New in 0.3.1

- **8 new VMProtect tools** — full VMProtect v2/v3 analysis: detection, section parsing, SDK hooking, anti-debug bypass, string decryption, handler AOB scan and dispatcher analysis
- **VMProtect integrated in `detect_embedded_vm`** — auto-detected alongside Mono, IL2CPP, Lua, Python, V8
- **Improved `publish.py`** — handles `400 File already exists` gracefully instead of crashing

## What's New in 0.3.0

- **7 new tools** — typed memory read/write, hex dump, pointer chain, address watcher, session list/close
- **Full async refactor** — all tools now use `threading.Event` instead of fixed `time.sleep` delays (up to 10× faster responses)
- **Central `_run_script` helper** — eliminates ~250 lines of duplicated boilerplate across all modules
- **Bug fix** — `read_memory` was missing its `@mcp.tool()` decorator and was never registered
- **Better error reporting** — all tools now return structured `timed_out` errors with clear messages

## Features

- Built with the official MCP Python SDK
- **84 tools** covering all major Frida capabilities
- Full VM support: Java/Android, Mono, IL2CPP (Unity), Lua, Python embedded, V8/Node.js
- Full VMProtect v2/v3 analysis, bypass and unpacking with deep cleanup
- Game engine reverse engineering support
- Event-driven synchronization — no wasted wait time

## Tool Categories

### 🔧 Process & Device Management (10 tools) - ⭐ Kernel Backend Support
| Tool | Description | Kernel |
|------|-------------|:------:|
| `enumerate_processes` | List all running processes | ✅ |
| `enumerate_devices` | List connected devices (includes kernel device) | ✅ |
| `get_local_device` | Get local device (auto-detects kernel driver) | ✅ |
| `get_process_by_name` | Find process by name | ✅ |
| `attach_to_process` | Attach to process (works with protected processes!) | ✅ |
| `create_interactive_session` | Create session for memory operations | ✅ |
| `list_sessions` | List all active sessions | ✅ |
| `close_session` | Close and cleanup a session | ✅ |
| `spawn_process` | Spawn a new process | ✅ |
| `kill_process` | Terminate a process | ✅ |

### 📦 Module & Symbol Analysis (6 tools)
| Tool | Description |
|------|-------------|
| `list_modules` | List all loaded modules/libraries |
| `find_module_by_name` | Find a module by name (partial match) |
| `list_exports` | List all exported symbols of a module |
| `list_imports` | List all imported symbols of a module |
| `resolve_symbol` | Resolve the absolute address of an export |
| `find_symbol_by_pattern` | Search exports by regex pattern |

### 💾 Memory Operations (12 tools) - ⭐ Kernel Backend Support
| Tool | Description | Kernel |
|------|-------------|:------:|
| `read_memory` | Read raw bytes from a memory address | ✅ |
| `write_memory` | Write bytes to a memory address | ✅ |
| `scan_memory_pattern` | AOB scan with wildcard support (`??`) | ✅ |
| `read_pointer` | Read a pointer-sized value | ✅ |
| `read_float` | Read a 32-bit float value | ✅ |
| `read_vector3` | Read X,Y,Z position (3 floats) | ✅ |
| `read_string_at` | Read null-terminated string (UTF-8/16/ANSI) | ✅ |
| `follow_pointer_chain` | Follow multi-level pointer chain | ✅ |
| `enumerate_memory_ranges` | List all memory regions with permissions | ❌ |
| `resolve_symbol` | Resolve the absolute address of an export | ❌ |
| `find_symbol_by_pattern` | Search exports by regex pattern | ❌ |
| `get_process_architecture` | Get arch, platform, pointer size, page size | ❌ |

### 🪝 Hooking & Tracing (4 tools)
| Tool | Description |
|------|-------------|
| `hook_function` | Persistent Interceptor hook (args + retval) |
| `enumerate_threads` | List all threads with state and context |
| `get_thread_backtrace` | Get backtrace for a specific thread |
| `stalker_trace_thread` | Trace a thread's execution with Stalker |

### ⚙️ Native Calls (2 tools)
| Tool | Description |
|------|-------------|
| `call_native_function` | Call a native function at an address |
| `install_native_callback` | Replace a function with a NativeCallback |

### ☕ Java / Android Bridge (6 tools)
| Tool | Description |
|------|-------------|
| `java_list_classes` | List all loaded Java classes (with filter) |
| `java_list_methods` | List all methods of a Java class |
| `java_hook_method` | Hook a Java method (persistent) |
| `java_get_field_value` | Get a Java field value (static or instance) |
| `java_set_field_value` | Set a Java field value |
| `java_call_method` | Call a Java method directly |

### 🎮 VM & Game Engine Support (16 tools)
| Tool | Description |
|------|-------------|
| `detect_embedded_vm` | Auto-detect embedded VMs (Lua, LuaJIT, Python, Mono, IL2CPP, V8, JVM, Chakra) |
| `mono_list_assemblies` | Detect Mono/.NET runtime and assemblies |
| `il2cpp_find_class` | Find an IL2CPP class by namespace and name |
| `il2cpp_find_method` | Find a method in an IL2CPP class |
| `il2cpp_read_field` | Read a field from an IL2CPP object at offset |
| `il2cpp_hook_method` | Hook an IL2CPP native method |
| `lua_list_globals` | List Lua global variables |
| `lua_exec` | Execute Lua code in the embedded runtime |
| `python_detect` | Detect embedded CPython runtime |
| `python_exec` | Execute Python code in the embedded interpreter |
| `python_hook_function` | Hook PyEval_EvalCode to trace Python execution |
| `python_import_module` | Import a Python module in the embedded interpreter |
| `v8_detect` | Detect V8 / Node.js engine |
| `v8_list_scripts` | List JavaScript scripts loaded in V8 |
| `v8_hook_script_compile` | Hook Node.js script compilation entry points |
| `v8_enumerate_exports` | Enumerate V8/Node.js module exports |

### 🛡️ VMProtect Analysis (8 tools) ⭐ New in 0.3.1
| Tool | Description |
|------|-------------|
| `vmp_detect` | Detect VMProtect presence, version (v2/v3), confidence level, sections and SDK exports |
| `vmp_list_sections` | Parse PE headers in memory and list all .vmp0/.vmp1/.vmp2 sections with VA, size and flags |
| `vmp_list_sdk_functions` | Find all 22 known VMProtect SDK exports across loaded modules |
| `vmp_hook_antidebug` | Hook and bypass `IsDebuggerPresent`, `IsVirtualMachinePresent`, `IsValidImageCRC` |
| `vmp_decrypt_strings` | Hook `VMProtectDecryptStringA/W` to capture decrypted strings at runtime |
| `vmp_scan_handlers` | AOB scan .vmp sections for VM entry stubs, CPUID, RDTSC, indirect JMP patterns |
| `vmp_analyze_dispatcher` | Locate and analyze the VM dispatcher region with hex context |
| `vmp_hook_sdk` | Hook any VMProtect SDK function by name (license, HWID, activation tracing) |

### 🔓 VMProtect Unpacker (10 tools) ⭐ Enhanced in 0.3.7
| Tool | Description |
|------|-------------|
| `vmp_full_unpack` | **All-in-one 7-step pipeline**: OEP → dump → patch → deep clean → fix pdata → IAT rebuild → verify strings |
| `vmp_find_oep` | Find Original Entry Point via prolog scan + dispatcher exit hook |
| `vmp_dump_pe` | Dump decrypted PE from memory to disk with fixed section headers |
| `vmp_rebuild_iat` | Scan live IAT thunks, build `IMAGE_IMPORT_DESCRIPTOR` entries, append `.idata` section |
| `vmp_fix_section_headers` | Fix `PointerToRawData`/`SizeOfRawData` alignment for IDA Pro / x64dbg |
| `vmp_resolve_imports` | Hook `GetProcAddress` to capture every runtime import (most accurate IAT method) |
| `vmp_scan_iat_region` | Scan and map all IAT thunks with reverse API lookup |
| `vmp_deep_clean` | Deep clean all VMProtect traces: rename .vmp sections, zero DataDirs, disable ASLR, fix flags |
| `vmp_fix_pdata` | Fix high-entropy .pdata (Shannon entropy check + zero encrypted RUNTIME_FUNCTION entries) |
| `vmp_verify_strings` | Verify dump integrity: scan .rdata for readable strings + game engine keywords |

### 🔧 Advanced Session & Memory (7 tools)
| Tool | Description |
|------|-------------|
| `list_sessions_detailed` | List sessions with extended metadata (PID, timestamp, persistent script count) |
| `close_session_force` | Force-close session with error recovery (reports warnings instead of failing) |
| `read_memory_typed` | Read a typed scalar value (int8…double…pointer) |
| `write_memory_typed` | Write a typed scalar value |
| `dump_memory_region` | Hex editor-style dump: offset + hex + ASCII |
| `follow_pointer_chain_detailed` | Follow pointer chain with full step-by-step trace (dereferenced values at each level) |
| `watch_address` | Poll a memory address and report value changes |


## Installation

### Prerequisites

- Python 3.8 or later
- pip package manager
- Frida 16.0.0 or later

### Quick Install

```bash
pip install frida-mcp-re
```

### Development Install

```bash
git clone https://github.com/yourusername/frida-mcp.git
cd frida-mcp
pip install -e ".[dev]"
```

## Claude Desktop Integration

Add to your Claude Desktop config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "frida": {
      "command": "frida-mcp"
    }
  }
}
```

## Game Reverse Engineering

Frida MCP is specifically designed for reverse engineering games that use embedded VMs or custom scripting engines:

### Supported Engines & VMs
- **Unity (Mono)** — Hook managed methods, read/write fields
- **Unity (IL2CPP)** — Native compiled code, class/method finder, field reader
- **Android (Java)** — Full Java bridge: class listing, method hooking, field access
- **Lua-based games** — Execute Lua code inside the game's Lua state
- **Python embedded** — Execute and trace CPython runtimes embedded in games/apps
- **V8 / Node.js** — Detect, enumerate and hook embedded V8 runtimes
- **Custom VM detection** — Auto-detects Lua, LuaJIT, Python, V8, Chakra, Mono, IL2CPP, JVM

### Typical Game RE Workflow

```
1. attach to game process     → attach_to_process
2. create session             → create_interactive_session
3. detect VM / engine         → detect_embedded_vm
4. map loaded modules         → list_modules
5. AOB scan                   → scan_memory_pattern  (ViewMatrix, EntityList…)
6. follow pointer chain       → follow_pointer_chain (static base → offsets)
7. read typed values          → read_memory_typed    (health, ammo, position)
8. watch address changes      → watch_address        (live monitoring)
9. hook game logic            → hook_function / java_hook_method / il2cpp_hook_method
10. dump struct layout        → dump_memory_region
11. patch values              → write_memory_typed
12. close when done           → close_session
```

### VMProtect Unpack Workflow (xrefs + IAT fixed)

```python
# One-liner: full 7-step pipeline with deep cleanup
vmp_full_unpack(session_id, output_path="C:/dumps/unpacked.exe")
# Pipeline: OEP → dump → patch → deep_clean → fix_pdata → rebuild_IAT → verify_strings

# Or step by step for maximum control:
vmp_find_oep(session_id)                                    # find real entry point
vmp_resolve_imports(session_id, duration_ms=15000)          # hook GetProcAddress
# ... interact with the game to trigger more imports ...
get_session_messages(session_id)                            # collect captured imports
vmp_dump_pe(session_id, output_path="C:/dumps/raw.exe")     # dump from memory
vmp_deep_clean(dump_path="C:/dumps/raw.exe")                # remove VMP traces
vmp_fix_pdata(dump_path="C:/dumps/raw.exe")                 # fix encrypted .pdata
vmp_rebuild_iat(session_id, dump_path="C:/dumps/raw.exe",
                output_path="C:/dumps/unpacked.exe")        # fix imports + xrefs
vmp_verify_strings(dump_path="C:/dumps/unpacked.exe")       # confirm data integrity
# Load C:/dumps/unpacked.exe in IDA Pro → all xrefs, strings, API names work
```

### VMProtect RE Workflow

```
1. detect VMProtect           → vmp_detect           (version, confidence, sections)
2. list VMP sections          → vmp_list_sections    (VA, size, flags of .vmp0/.vmp1/.vmp2)
3. find SDK functions         → vmp_list_sdk_functions
4. bypass anti-debug          → vmp_hook_antidebug   (bypass=True)
5. capture strings            → vmp_decrypt_strings  + get_session_messages
6. scan VM handlers           → vmp_scan_handlers    (CPUID, RDTSC, indirect JMP…)
7. analyze dispatcher         → vmp_analyze_dispatcher
8. trace license validation   → vmp_hook_sdk("VMProtectSetSerialNumber")
9. capture HWID               → vmp_hook_sdk("VMProtectGetCurrentHWID")
```

### New Tools in Action

```python
# Read player health (float at known address)
read_memory_typed(session_id, "0x7FF12340", type="float")

# Follow pointer chain: base → +0x0 → +0x58 → +0x1A0 (player struct)
follow_pointer_chain(session_id, "0x14B8C2A0", offsets=[0x0, 0x58, 0x1A0])

# Watch ammo counter live (poll every 200ms for 10 seconds)
watch_address(session_id, "0x7FF12344", type="int32", interval_ms=200, duration_ms=10000)

# Hex dump 256 bytes of a struct
dump_memory_region(session_id, "0x7FF12300", size=256)

# Patch: set health to 9999
write_memory_typed(session_id, "0x7FF12340", type="float", value="9999.0")

# Clean up
close_session(session_id)
```

## Architecture

```
frida_mcp/
├── server.py          # FastMCP instance + shared state + _run_script helpers
├── cli.py             # STDIO entrypoint for Claude Desktop
└── tools/
    ├── processes.py   # Device & process management (10 tools)
    ├── sessions.py    # Interactive REPL sessions (5 tools)
    ├── modules.py     # Module & symbol analysis (4 tools)
    ├── memory.py      # Memory read/write/scan/symbols (12 tools)
    ├── hooks.py       # Hooking, tracing, Stalker (4 tools)
    ├── native.py      # NativeFunction / NativeCallback (2 tools)
    ├── java_bridge.py # Java/Android bridge (6 tools)
    ├── vm_support.py  # Mono, IL2CPP, Lua, Python, V8 (16 tools)
    ├── advanced.py    # Advanced session & memory variants (7 tools)
    ├── vmprotect.py   # VMProtect v2/v3 analysis and bypass (8 tools)
    └── vmp_dumper.py  # VMProtect unpacker + cleanup + IAT rebuild (10 tools)
                                                            ─────────
                                                            84 tools total
```

## License

MIT
