Boti-Ormandi/memscope-mcp

# memscope-mcp [](https://github.com/Boti-Ormandi/memscope-mcp/actions/workflows/test.yml) [](https://www.python.org/) [](LICENSE) [](https://github.com/astral-sh/ruff) 一个用于底层 Windows 进程内存研究的 MCP 服务器。 AI 代理可以附加到进程、扫描字节模式、读取和写入类型化内存、跟踪指针链、执行远程 x64 代码、通过共享环形缓冲区捕获安装通用的内联函数钩子，甚至可以读取服务器未附加进程的进程环境块 (PEB)——这一切都通过 10 个 MCP 工具实现。服务器端的 Lua 环境将多步操作批量处理为一次往返过程，因此代理可以在不承担逐调用延迟成本的情况下，解引用指针链、解码结构体、挂钩 API 并报告结果。 ## 运行效果 所有操作都通过 MCP 工具调用完成。一个典型的探索会话： **查找并附加到进程：** ``` > processes(filter="notepad") {processes: [{pid: 1234, name: "notepad.exe", threads: 6, path: "C:\\Windows\\System32\\notepad.exe"}]} > attach("notepad.exe") {pid: 1234, key_modules: {"notepad.exe": {base: "0x7FF6A0000000", size: 245760}, ...}, ...} ``` **查找哪个 svchost 托管了某个服务：** ``` > processes(service="EventLog") {processes: [{pid: 1820, name: "svchost.exe", services: [{name: "EventLog", state: "RUNNING"}]}]} ``` **扫描模式，跟踪指针：** ``` > scan(pattern="48 8B 05 ?? ?? ?? ??", module="target.dll") {data: [{address: "target.dll+0x1A208D8"}], _pagination: {total: 1}} > chain(base="0x183C13300", offsets=["0x50", "0x18", "0x100"], read_final="float") {final_address: "0x184A52118", final_value: 100.0} ``` **在一次调用中运行多步 Lua 脚本：** ``` > lua(script=""" local matches = AOBScanModule("target.dll", "48 8B 05 ?? ?? ?? ??") for i, addr in ipairs(matches) do local ptr = readPointer(addr + 3) local val = readFloat(ptr + 0x100) addResult("match_" .. i, {address = toHex(ptr), value = val}) end """) {results: {"match_1": {address: "0x183C13300", value: 100.0}}, output: []} ``` ## 工具 地址支持十六进制字符串（`"0x1234"`）、模块+偏移量（`"module.dll+0x1234"`）或十六进制算术（`"0xBASE+0xOFFSET"`）。 | 工具 | 用途 | |------|---------| | `processes` | 列出/过滤正在运行的进程。可按名称、PID、父 PID 或托管服务进行过滤。通过 Windows SCM 自动枚举 svchost 进程的服务 | | `attach` | 附加到进程，缓存模块基址。如果目标重启则自动重新连接 | | `modules` | 列出已加载的模块及其基址、大小和路径 | | `read` | 读取类型化内存（int8-64, uint8-64, float, double, bool, ptr, cstring, vector2/3/4, quaternion, color, rect, bounds, matrix4x4）。支持 `count` 参数以读取连续值 | | `write` | 写入类型化内存，带有可选的页保护预验证 | | `dump` | 智能内存转储，具有自动类型检测（指针、字符串、整数、浮点数）和置信度评分 | | `chain` | 跟踪指针链：`[[base+off0]+off1]...`，具有可配置的最终读取类型 | | `scan` | 支持通配符（`??`, `?`, `**`）的 AOB 模式扫描。默认为模块扫描；有界扫描遍历已提交的可读区域 | | `lua` | 在服务器端执行 Lua 脚本以进行多步操作 | | `scripts` | 管理已保存的 Lua 脚本。操作：`list`（带路径），`run`（带参数） | ## Lua 脚本 一个服务器端 Lua 5.4 环境，具有约 110 个始终加载的函数，用于暴露 memscope 的原语。当某个操作需要循环、条件判断或链式读取（否则将需要多次 MCP 往返）时，请使用它。 ``` -- Find a RIP-relative singleton reference and read fields off it local matches = AOBScanModule("target.dll", "48 8D 0D ?? ?? ?? ?? E8 ?? ?? ?? ?? 48 8B D8") if #matches > 0 then local rip_offset = readInteger(matches[1] + 3) local singleton = matches[1] + 7 + rip_offset local ptr = readPointer(singleton) if ptr and ptr ~= 0 then addResult("address", toHex(ptr)) addResult("version", readUInt32(ptr + 0x10)) addResult("name", readString(ptr + 0x20, 64)) end end ``` 完整参考文档位于 [`docs/lua-reference.md`](docs/lua-reference.md)。Hooking 和 PEB 内省设计说明位于 [`docs/hooking.md`](docs/hooking.md) 和 [`docs/peb.md`](docs/peb.md)。类别： | 类别 | 函数 | |----------|-----------| | 内存读取（类型化 + 批量） | 20 | | 内存写入 | 13 | | 结构体辅助函数（向量、矩阵、声明式结构体读取） | 5 | | 模块 / 地址解析（包括 `resolveExport`） | 7 | | 扫描（AOB、字符串、指针交叉引用） | 4 | | 指针链 | 1 | | 代码执行（shellcode、alloc、callSequence） | 8 | | Hooking（内联钩子 + 环形缓冲区） | 8 | | 进程内省（附加前、PEB） | 10 | | 网络实用工具 | 1 | | 64 位安全比较 | 9 | | 按位操作 | 7 | | 实用工具 | 18 | 此外，在激活可选的 netcap 插件 (`contrib/plugins/netcap.py`) 后，还有约 38 个函数可用。 Lua 5.4 会拒绝超过 32 位的十六进制字面量；服务器在执行前会将像 `0x1F58E12ECF0` 这样的大字面量透明地重写为 `addr("0x1F58E12ECF0")`，因此脚本可以直接粘贴原始的 64 位地址。 ## 插件 无需触及核心的领域特定辅助工具。只需将 `.py` 文件放入 `plugins/` 目录并重启；加载器会实例化它找到的 `PluginBase` 子类，注册插件的 Lua 函数，并将其说明附加到面向 AI 的文档中。 ``` # 激活参考 IL2CPP 插件（Unity runtime helpers） cp contrib/plugins/il2cpp.py plugins/ # 或参考 netcap 插件（Winsock 捕获与分析，构建于 hooking layer 之上） cp contrib/plugins/netcap.py plugins/ ``` `il2cpp.py` 是用于遍历托管运行时对象布局的插件模板。`netcap.py` 是用于挂钩已知 API 接口并在其上添加协议感知解析的插件模板——它使用通用的 `HOOK_MANAGER` 来安装 Winsock 钩子，并通过约 38 个 Lua 函数暴露数据包捕获、流重组、帧解析、搜索和录制功能。有关接口和编写指南，请参见 [`plugins/README.md`](plugins/README.md)。 ## 脚本持久化 将可用的 Lua 脚本保存为 `.lua` 文件，按进程组织： ``` scripts/ target.exe/ find_struct.lua dump_vtable.lua ``` - 第一行注释将成为脚本的描述 - 对版本控制友好（纯文本） - AI 代理在附加时会发现已保存的脚本并自动重用它们 - 使用您的 MCP 客户端的文件工具创建脚本，并使用 `scripts` 工具运行它们 ASLR 会使跨重启的绝对地址失效。请保存查找器脚本，而不是地址。 ## 架构 ``` src/ server.py # MCP tool definitions (thin wrappers + session logging) session.py # Process attach/detach, memory primitives, threads, # VirtualProtect, allocate_near, suspend/resume, # lifecycle callbacks extensions/ # Generic LuaExtension contract + bootstrap base.py # LuaExtension ABC and ExtensionContext bootstrap.py # Core extension + user plugin registration core/ # Always-loaded extensions general.py memory.py module_scan.py execution.py hooking.py process.py network.py tools/ memory.py # Smart memory dump scanning.py # AOB pattern scanning pointers.py # Pointer chain resolution types.py # Typed memory read/write execute.py # Remote code execution hooking.py # HookManager: ring buffer + install/remove/cleanup lua_scripts.py # Script persistence lua/ # Lua engine and themed function modules plugins/ # PluginBase (specialization of LuaExtension) + loader instructions/ # AI context builder (base + extensions + plugins) utils/ shellcode.py # x64 codegen: native calls + hook trampolines disasm.py # Table-driven x64 length decoder + RIP-relative relocation pe.py # PE export resolver (resolveExport) peb.py # PEB reader: cmdline, env, debugger, remote modules memory_utils.py heuristics.py logger.py pointers.py plugins/ # Active plugins (user-curated, gitignored) contrib/plugins/ # Reference plugins (il2cpp, netcap) scripts/ # Saved Lua scripts per process (gitignored) logs/ # Session logs in JSONL format (gitignored) docs/ hooking.md # Inline hooking architecture peb.md # PEB introspection design lua-reference.md # Full Lua function reference ``` **设计选择：** - 通用核心，针对领域的插件：`src/` 中没有特定于目标的代码 - 最小的工具接口：10 个结构良好的 MCP 工具，对于需要组合的操作使用 Lua - 一个契约 (`LuaExtension`)，两条激活路径：核心扩展始终加载；用户插件通过 `plugins/` 中的文件存在与否进行控制，并在失败时隔离 - 插件说明仅在插件激活时加载（AI 上下文会消耗 token） - 脚本是持久的，地址则不然：ASLR 会改变一切，请保存查找器 ## 实现说明 ### 带有共享环形缓冲区的内联函数 Hooking 通过地址挂钩任何用户模式函数，捕获寄存器参数以及可选的缓冲区数据，并从 Lua 读取捕获流——无需 DLL 注入。`HookManager` ([`src/tools/hooking.py`](src/tools/hooking.py)) 通过表格驱动的 x64 指令长度解码器 ([`src/utils/disasm.py`](src/utils/disasm.py)) 读取目标函数的序言，并在目标地址的 ±2 GiB 范围内分配一个 RWX 蹦床页，从而使 5 字节的 `JMP rel32` 补丁就足够了；当近分配失败时，会退回到使用线程挂起 + IP 重定向的 14 字节 `JMP [RIP+0]`。与 RIP 相关的序言指令由重定位器重写，因此被替换的字节仍能解析到原始目标。蹦床 shellcode ([`src/utils/shellcode.py`](src/utils/shellcode.py)) 实现了带有可选结构体解引用（WSABUF 风格的缓冲区指针）和输出指针解引用的调用前和调用后捕获。所有钩子共享目标内存中的一个无锁环形缓冲区；写入操作使用 `lock cmpxchg` 声明槽位，溢出时丢弃而不阻塞，状态字段用于控制部分读取。完整架构请见 [`docs/hooking.md`](docs/hooking.md)。 ### 无需附加的 PEB 内省 `getProcessInfo`、`isBeingDebugged`、`getEnvironment` 和 `getModulesRemote` 可以读取服务器能够使用 `PROCESS_QUERY_INFORMATION | PROCESS_VM_READ` 打开的任何进程的进程环境块 (PEB)——无需调试会话，无需注入，无句柄泄露。读取器 ([`src/utils/peb.py`](src/utils/peb.py)) 是纯 ctypes 实现：`NtQueryInformationProcess(ProcessBasicInformation)` 返回 PEB 基址，然后 `ReadProcessMemory` 遍历 `ProcessParameters`（命令行、工作目录、环境变量）、`BeingDebugged` 字节以及 `Ldr.InLoadOrderModuleList` 链表。`processes` MCP 工具直接显示每个条目的命令行，这意味着像 `processes(filter="electron")` 这样的过滤器可以无需进一步操作即可区分渲染器 / GPU / 浏览器实例。完整结构布局请见 [`docs/peb.md`](docs/peb.md)。 ### x64 shellcode 生成 `executeCode` 和 `callSequence` 通过在目标进程中汇编原始 x64 机器代码来工作。代码生成器 ([`src/utils/shellcode.py`](src/utils/shellcode.py)) 端到端地实现了 Microsoft x64 调用约定：32 字节的影子空间、每次 `CALL` 前的 16 字节栈对齐、前四个整数参数使用 RCX/RDX/R8/R9，浮点数使用 XMM0-XMM3、第四个之后的参数使用栈溢出，并将 RAX（或浮点返回值的 XMM0）捕获到线程本地结果槽中。Lua 包装器智能检测参数类型：数字字符串成为整数参数，文本字符串在目标进程中作为缓冲区分配，并在调用后释放。 ### 扩展系统 核心功能和用户插件共享一个 ABC：`LuaExtension` ([`src/extensions/base.py`](src/extensions/base.py))。每个扩展拥有一个名称、一个描述、一个面向 AI 的说明片段、一个返回 Lua 函数绑定的 `register(ctx)` 方法，以及可选的 `on_process_attached` / `on_process_detaching` 生命周期回调。引导程序 ([`src/extensions/bootstrap.py`](src/extensions/bootstrap.py)) 按顺序实例化七个内置扩展，从 `plugins/` 加载任何用户插件（失败会被记录并隔离），将返回的函数字典连接到 Lua 引擎中，并组装说明包。正是这个契约使得 hooking、PEB 内省、netcap 以及任何未来的领域辅助工具能够在相同的结构上实现即插即用。 ### PE 导出解析 `resolveExport(module, name)` ([`src/utils/pe.py`](src/utils/pe.py)) 直接从目标内存读取 PE 导出目录，并对已排序的名称指针表进行二分查找。转发导出以最大深度 5 进行递归解析。Hooking 层使用此功能来查找像 `ws2_32!WSARecv` 这样的地址，而无需符号文件或对已知入口点进行 AOB 扫描。 ### 透明重连 逆向工程会话的生存时间通常比目标进程要长。`DebugSession.ensure_attached` ([`src/session.py`](src/session.py)) 在每次工具调用时使用 `GetExitCodeProcess` 轮询缓存的句柄；如果进程已退出，它会按名称透明地重新打开并重新缓存模块。工具在目标瞬态重启时绝不会抛出“进程已消失”的错误。 ### Lua 大型十六进制预处理器 Lua 5.4 支持 64 位整数，但其解析器仍然会拒绝超过 32 位的十六进制字面量——`local p = 0x1F58E12ECF0` 是一个语法错误。引擎的预处理器 ([`src/tools/lua/engine.py`](src/tools/lua/engine.py)) 将此类字面量重写为 `addr("0x...")` 调用，但仅在此前保护了长字符串、单引号和双引号字符串以及已包装的 `addr()` / `parseHex()` 调用免受意外重写之后进行。 ### 服务到 PID 枚举 识别哪个 `svchost.exe` 托管了给定的 Windows 服务通常是一个多步骤的繁琐任务。`processes` 工具通过服务控制管理器调用 `EnumServicesStatusExW`，并将结果连接到进程列表，因此 `processes(service="EventLog")` 在一次调用中就能返回正确的 PID。延迟加载：SCM 枚举仅在查询实际需要时运行。 ## 安装说明 **前置条件：** - Windows x64 - Python 3.10+ - 一个[兼容 MCP 的客户端](https://modelcontextprotocol.io/clients) **安装：** ``` git clone https://github.com/Boti-Ormandi/memscope-mcp.git cd memscope-mcp pip install -e . ``` **配置 MCP 客户端。**添加一个服务器条目；最简洁的形式是使用已安装的控制台脚本： ``` { "mcpServers": { "memscope": { "command": "memscope-mcp" } } } ``` 如果客户端在其 `PATH` 中找不到该脚本，则回退到模块形式： ``` { "mcpServers": { "memscope": { "command": "python", "args": ["-m", "src.server"] } } } ``` 该条目放置在您的客户端期望的 `mcpServers` 配置中——请参阅客户端的文档。 **验证：** ``` pytest tests/test_smoke.py -v ``` 冒烟测试套件会检查所有 10 个工具是否注册，Lua 引擎是否初始化，插件加载器是否干净运行，以及说明构建器是否生成输出。 ## 会话日志 每次工具调用都会记录到 `logs/sessions/.jsonl`——每次服务器会话对应一个 JSONL 文件，每次调用对应一行，包含工具名称、参数、成功状态和持续时间（以毫秒为单位）。超过两年的日志会被自动清理。这对于调试和重放会话非常有用。 ## 平台 仅支持 Windows x64。使用了 pymem，它封装了 Windows API（`ReadProcessMemory`、`WriteProcessMemory`、`CreateRemoteThread` 等）。pymem 依赖是无条件的；该软件包不会在非 Windows 主机上安装。 ## 安全 memscope-mcp 可以在附加的进程中读取和写入任意内存，并在其中执行代码。预期用途：恶意软件分析、漏洞研究、您拥有或被授权测试的软件的安全测试、离线软件的模组工具开发以及教育性逆向工程。只针对您被授权分析的进程和系统。 仅限用户模式访问。具有防篡改或调试器检测缓解措施的目标（商业混淆器、具有 EDR 钩子的二进制文件、内核级保护）可能会检测或阻止该工具。 插件在服务器启动时执行任意 Python 代码——请仅激活您已阅读过源码的插件。 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE)

标签：AI代理, AOB扫描, API钩子, Cheat Engine替代, inline hooking, Lua 5.4, MCP Server, MIT License, PEB解析, Process Environment Block, Python, Python 3.10, ruff, SSH蜜罐, Windows进程内存, x64内联Hook, 云资产清单, 低级操作, 内存修改器, 内存扫描, 内存操作, 内存研究, 内存读写, 外挂研究, 底层内存操作, 指针追踪, 指针链, 无后门, 模型上下文协议, 游戏安全, 特征码扫描, 编程工具, 调试插件, 进程注入, 远程代码执行, 逆向工具, 逆向工程