# procmem

An MCP server that gives a model full access to Windows process memory and crash dump analysis. Two tools: `procmem` for live process inspection and editing, `dumpfile` for offline crash dump analysis.

This is a Cheat Engine replacement built for LLMs. It was designed so a model can attach to a running process, scan for values, resolve pointer chains, patch bytes, disassemble code, and analyze crash dumps, all through structured tool calls instead of a GUI.

> **This is a Windows-only, security-sensitive tool.** It calls VirtualQueryEx, ReadProcessMemory, WriteProcessMemory, VirtualAllocEx, VirtualProtectEx, and can generate direct syscall stubs to bypass EDR hooks. Only run it on machines you own, attached to processes you have permission to inspect.

## Tools

### procmem (live process memory)

Attach to a running process and work with its memory directly.

**Core:**
- `list_processes` - list running processes (optional name filter)
- `attach` / `detach` - open/close a process handle by name or PID
- `status` - show current attachment, active freezes, snapshots, allocations
- `modules` - list loaded modules with base address and size
- `regions` - list memory regions with protection flags (VirtualQueryEx)
- `read` / `write` - read or write a typed value at an address
- `read_struct` - read multiple values at offsets in one call

**Scanning:**
- `scan` - wildcard AOB (array of bytes) pattern scan across a module or all regions
- `scan_value` - Cheat Engine-style value scan with comparison operators (eq, ne, gt, lt, changed, increased, decreased), multi-step narrowing with scan sessions
- `clear_scan` - reset a scan session
- `pointer` - resolve a pointer chain (base + offsets), raw or struct mode

**Memory management:**
- `protect` - change memory protection (VirtualProtectEx)
- `allocate` / `free` - allocate/free memory in the target process (VirtualAllocEx/VirtualFreeEx)
- `snapshot` / `diff` - save a memory region and compare it later to find changes
- `dump` - save a memory region to a file

**Threads:**
- `threads` - list threads with IDs and state
- `suspend` / `resume` - suspend or resume a thread by ID
- `freeze` / `unfreeze` - continuously write a value to an address in the background
- `kill_all_freezes` / `list_freezes` - manage active freeze loops

**PE analysis:**
- `get_exports` - list exported functions (Export Address Table)
- `get_imports` - list imported functions (Import Address Table)
- `get_sections` - list PE sections with entropy analysis (high entropy = packed/encrypted)

**Assembly:**
- `disassemble` - disassemble bytes at an address (Capstone, x86/x64)
- `assemble` - assemble x86/x64 instructions (Keystone), optionally write result to an address
- `signature` - generate an AOB signature from an address with smart wildcards on call/jmp offsets
- `aob_inject` - atomic scan + patch: find a pattern, flip protection, write replacement bytes or assembled instructions, verify, restore protection
- `watch` - poll an address until the value changes or a timeout is reached

**File editing (offline binary patching):**
- `file_open` - open a PE file for offline editing (creates an automatic backup)
- `file_close` - close the file, save changes, update PE checksum
- `file_read` / `file_write` - read/write bytes by RVA or file offset, with optional disassembly
- `file_patch` - AOB scan + replace in the file
- `file_find_cave` - find code caves (sequences of 0x00 or 0xCC) for injection
- `file_strings` - extract ASCII/Unicode strings from the file
- `file_scan` - AOB pattern scan across the file
- `file_list` - list currently open files

**Direct syscalls:**
- `syscall_resolve` - resolve the System Service Number for an NT function via Hell's Gate / Halo's Gate (falls back to a known-SSN table if the function is hooked)
- `syscall_check` - detect hooked ntdll functions (EDR detection)
- `syscall_stub` - generate raw syscall stub bytes for a function
- `syscall_gadget` - find a `syscall; ret` gadget in ntdll for indirect syscall techniques
- `syscall_mode` - enable/disable direct syscall mode for future memory operations

**Address format:** hex (`0x1234`) or module+offset (`game.exe+0x7A3B20`).
**Value types:** int, uint, int8, uint8, int16, uint16, int64, uint64, float, double, bytes, string, wstring, ptr.

### dumpfile (crash dump analysis)

Load and analyze crash dumps offline, without the original process running.

- `load` - load a dump file (auto-detects Windows minidump vs Linux ELF core)
- `close` - unload the current dump
- `status` - show what is loaded
- `info` - crash details: exception code/name, faulting address, crash module + offset, OS version
- `threads` - list threads in the dump
- `modules` - list loaded modules with base addresses
- `mappings` - list memory regions captured in the dump
- `registers` - show register values for a thread (defaults to the crashing thread)
- `stack` - show raw stack values from the stack pointer
- `read` - read a typed value from the dump's memory (same interface as procmem)
- `scan` - AOB pattern scan across dump memory
- `search_string` - search for ASCII or Unicode strings in the dump
- `disassemble` - disassemble code at an address in the dump

Supports Windows minidumps (.dmp, .mdmp) via the `minidump` package and Linux core dumps (ELF) via `pyelftools`.

## Install

Requires Python 3.10 or newer and Windows (procmem uses the Windows API directly via ctypes). The dumpfile tool works on any OS for analyzing dumps collected elsewhere.

Install as a package:

```
pipx install git+https://github.com/cutlerbenjamin1-cmd/procmem
```

From a local checkout: `pip install .`

Or skip packaging entirely and run server.py directly:

```
pip install -r requirements.txt
```

### Optional dependencies

The core tool (attach, read, write, scan, pointer chains) needs only pymem. Everything else is optional and the server still boots without it:

```
pip install pymem              # required: process memory access
pip install pefile             # PE analysis: exports, imports, sections, file editing
pip install capstone           # disassembly
pip install keystone-engine    # assembly (assemble, aob_inject with asm mode)
pip install minidump           # dumpfile: Windows minidump support
pip install pyelftools         # dumpfile: Linux core dump support
```

Or install everything at once:

```
pip install "procmem[all]"
```

## Use it with an MCP client

procmem speaks MCP over stdio. Point your client at the `procmem` command (if installed as a package) or at `server.py` directly:

```json
{
  "mcpServers": {
    "procmem": {
      "command": "procmem"
    }
  }
}
```

Or with a direct path:

```json
{
  "mcpServers": {
    "procmem": {
      "command": "python",
      "args": ["/absolute/path/to/procmem/server.py"]
    }
  }
}
```

There is a ready-to-edit copy in `example_config.json`.

## Configuration

All optional, set as environment variables:

- `OUTPUT_MAX_CHARS` - hard cap on a single tool result before truncation (default: 15000).
- `MCP_DEBUG` - set to `true` for stderr debug logging.

## Examples

Attach to a process, scan for a health value, freeze it:

```
procmem(action="attach", process="game.exe")
procmem(action="scan_value", value=100, value_type="int", all_regions=true)
# change the value in-game, then narrow the scan:
procmem(action="scan_value", value=95, op="eq", scan_id="default")
# found it at 0x12345678 - freeze it at 999:
procmem(action="freeze", address="0x12345678", value=999, value_type="int", name="health")
```

Find and patch a conditional jump in a binary:

```
procmem(action="scan", pattern="74 0A 8B 45 ?? 89", module="game.exe")
# patch the JE (74) to JMP (EB):
procmem(action="aob_inject", pattern="74 0A 8B 45 ?? 89", replace="EB", pad="nop", module="game.exe")
```

Analyze a crash dump:

```
dumpfile(action="load", path="crash.dmp")
dumpfile(action="info")
# -> ACCESS_VIOLATION at 0x7ff612345678 in engine.dll+0x1A3B20
dumpfile(action="registers")
dumpfile(action="disassemble", address="0x7ff612345678")
dumpfile(action="search_string", search="error")
```

Check if ntdll is hooked (EDR detection):

```
procmem(action="syscall_check")
# -> hooked: ["NtReadVirtualMemory", "NtWriteVirtualMemory", ...], likely_edr: true
procmem(action="syscall_mode", value=true)
# future memory operations will use direct syscalls
```

## How it works

procmem is a ~3700-line Python module that wraps the Windows memory API through ctypes. There is no C extension and no DLL injection. It opens a handle to the target process with `OpenProcess` and uses the documented NT API surface: `ReadProcessMemory`, `WriteProcessMemory`, `VirtualQueryEx`, `VirtualProtectEx`, `VirtualAllocEx`, `VirtualFreeEx`, `CreateToolhelp32Snapshot`. Thread control uses `SuspendThread`/`ResumeThread`. Pattern scanning is parallelized across CPU cores using subprocess workers.

The direct syscall feature resolves System Service Numbers from ntdll.dll's export table using Hell's Gate (read the stub at the export address, extract the SSN from the `mov eax, <ssn>` instruction) with Halo's Gate as a fallback (walk neighboring stubs when a function is hooked). This lets you detect EDR hooks and optionally bypass them for memory operations, which is useful in game anti-cheat and malware analysis contexts.

The file editing subsystem (`file_open` through `file_list`) works offline on PE files using pefile. It creates a backup before any modification, maps between RVA and file offset automatically, and updates the PE checksum on close. Code cave finding scans for long runs of null bytes or INT3 instructions where you can place injected code.

dumpfile parses Windows minidumps (MDMP magic) via the `minidump` package and Linux ELF core dumps via `pyelftools`. It presents a read/scan interface that mirrors procmem so the same workflow (read values, scan for patterns, disassemble) works on both live processes and crash dumps.

## A word on what this is for

This was built for game modding, reverse engineering, malware analysis, and crash dump triage. It is the kind of tool that security researchers and game hackers use routinely, packaged so an LLM can drive it through structured calls instead of clicking through Cheat Engine or x64dbg.

It is not a rootkit, though it contains the building blocks of one. The direct syscall feature exists because EDR products and game anti-cheats hook ntdll, and if you are doing legitimate security research or game modding you need to be able to see that and work around it. If you are using this for unauthorized access to systems you do not own, that is on you.

## License

MIT. See LICENSE.