ProcmonMCP

ProcmonMCP

ProcmonMCP 是一个 Model Context Protocol (MCP) 服务，可让大模型自主分析 Process Monitor (Procmon) XML 日志文件。它向所有兼容 MCP 的客户端提供一套全面的分析工具，包括 Claude Code、Claude Desktop、Cline 等。

已包含在 REMnux 中 随 REMnux® 恶意软件分析发行版一同提供，并已预配置为供 OpenCode 使用的 procmon MCP 服务。

概述

Process Monitor 会捕获详细的系统活动，包括文件访问、注册表操作、网络连接、进程创建等。ProcmonMCP 会将这些 XML 日志解析为经过优化的内存表示，并将其作为 MCP 工具提供，使大模型无需手动整理数据即可调查系统行为。

主要功能：

• 在运行时加载文件 — 分析不同的捕获文件时无需重启服务
• 解析后捕获数据缓存 — 重新加载未更改的文件几乎可瞬间完成（跳过解析）
• 字符串驻留，降低大型日志的内存占用
• 按进程名称、操作、PID 和文件路径进行索引查找，加快筛选速度
• 多种传输协议 — stdio（推荐）、Streamable HTTP 和 SSE（已弃用）
• 通过 MCP 通知在加载文件期间提供进度反馈

本项目的灵感来自 GhidraMCP 所采用的方法。

安全警告

Process Monitor 日志可能包含极其敏感的系统信息（击键记录、命令行中的密码、文件内容、网络流量详情等）。

• 此工具会加载运行脚本的用户有权读取的任何文件路径。没有目录沙箱限制。
• 仅在可信环境中运行此服务。
• 除非您充分了解并接受相关风险，否则切勿使用包含敏感生产或个人数据的系统所捕获的 Procmon 日志运行此服务。
• 使用此工具前，请检查您打算加载的日志，确认其中不含敏感信息。

安装

当前版本：v0.5.0，需要 MCP SDK v2 (mcp[cli]>=2.0.0)。早期版本请参阅发布页面；重要变更记录在 CHANGELOG.md 中。

前置条件

• Python 3.10 或更高版本（MCP SDK 的要求；开发和测试使用的版本为 3.10-3.13）
• pip（Python 包安装程序）

从源代码安装

git clone https://github.com/JameZUK/ProcmonMCP
cd ProcmonMCP
pip install -r requirements.txt

这会跟踪默认分支的最新状态。若要固定安装当前版本：

git clone --branch v0.5.0 --depth 1 https://github.com/JameZUK/ProcmonMCP
cd ProcmonMCP
pip install ".[all]"

或者安装软件包本身（会提供 procmon-mcp 控制台脚本）：

pip install .            # core only (mcp[cli])
pip install ".[all]"     # core + optional lxml and psutil
pip install -e ".[dev]"  # editable install with test tooling

依赖项

Package	Required	Purpose
mcp[cli]>=2.0.0	是	带有 CLI 工具和 Streamable HTTP 支持的 MCP SDK
lxml>=4.9.0	推荐	更快地解析 XML（若未安装，则回退到标准库 ElementTree）
psutil>=5.9.0	可选	文件加载后报告内存用量
google-re2	可选	适用于用户筛选正则表达式的线性时间、可防范 ReDoS 的引擎（pip install ".[re2]"；若未安装，则回退到标准库 re）

一次性安装所有依赖：

pip install "mcp[cli]>=2.0.0" lxml psutil

MCP SDK v2： SDK 将 FastMCP 重命名为 MCPServer，并在 v2 中将其移至 mcp.server.mcpserver。ProcmonMCP 面向 v2，同时通过兼容性回退机制支持 mcp<2。如果你之前安装时未固定 mcp[cli] 版本，并看到 "the MCP SDK could not be loaded"，请使用 pip install --upgrade "mcp[cli]>=2" 升级。

使用 Claude Code 快速入门

推荐通过 stdio 传输方式搭配 Claude Code 使用 ProcmonMCP。服务启动时不会加载任何文件——之后你（或大模型）可以使用 load_file 工具打开 Procmon 捕获文件。

选项 1：通过 Claude Code CLI 添加

# Add ProcmonMCP as a stdio server (user-wide)
claude mcp add procmon --scope user -- python -m procmon_mcp

# Or with a file pre-loaded at startup
claude mcp add procmon --scope user -- python -m procmon_mcp --input-file /path/to/capture.xml.gz

# Or scoped to the current project only
claude mcp add procmon --scope project -- python -m procmon_mcp

选项 2：通过 JSON 添加

claude mcp add-json procmon '{
  "type": "stdio",
  "command": "python",
  "args": ["-m", "procmon_mcp"]
}'

选项 3：直接编辑配置文件

Claude Code 会从以下位置读取 MCP 服务配置：

Scope	File	Description
项目（共享，受版本控制）	项目根目录中的 .mcp.json	与团队共享
项目（个人）	.claude/settings.local.json	你的本地覆盖配置
用户（全局）	~/.claude.json	可用于所有项目

共享项目的 .mcp.json 示例：

{
  "mcpServers": {
    "procmon": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "procmon_mcp"]
    }
  }
}

预加载文件并设置选项的示例：

{
  "mcpServers": {
    "procmon": {
      "type": "stdio",
      "command": "python",
      "args": [
        "-m", "procmon_mcp",
        "--input-file", "/path/to/capture.xml.gz",
        "--no-stack-traces"
      ]
    }
  }
}

选项 4：Streamable HTTP 传输

如需网络访问或多客户端场景，请使用 Streamable HTTP：

# Add as an HTTP server (start the server separately first)
claude mcp add --transport http procmon http://127.0.0.1:8081/mcp

然后启动服务：

python -m procmon_mcp --transport streamable-http --mcp-port 8081

验证连接

配置完成后，请确认 Claude Code 可以看到 ProcmonMCP：

claude mcp list

在 Claude Code 会话中，也可以输入 /mcp 查看已连接服务的状态。

用法

典型工作流

1. 启动服务（Claude Code 会自动为 stdio 服务执行此操作）
2. 检查状态：大模型调用 get_status 查看是否已加载文件
3. 加载文件：大模型调用 load_file 并传入 Procmon XML 捕获文件的路径
4. 分析：大模型使用分析工具调查日志数据

命令行参数

Argument	Default	Description
--input-file <path>	(none)	启动时预加载 Procmon XML 文件。如果省略，请通过 MCP 客户端使用 load_file。
--transport <mode>	stdio	传输协议：stdio、streamable-http 或 sse（已弃用）。
--mcp-host <ip>	127.0.0.1	主机地址（仅限 HTTP 传输）。
--mcp-port <port>	8081	端口号（仅限 HTTP 传输）。
--no-stack-traces	关闭	跳过加载堆栈跟踪以节省内存。
--no-extra-data	关闭	跳过加载未知或额外的事件字段以节省内存。
--no-cache	关闭	绕过已解析捕获文件的缓存（始终重新解析并刷新缓存）。
--clear-cache	关闭	删除所有已缓存的解析后捕获文件，然后退出。
--debug	关闭	启用详细调试日志。
--log-file <path>	(控制台)	将日志写入文件，而非控制台。
--profile	关闭	启用 cProfile 性能分析（用于开发）。

示例

通过 stdio 启动（不预加载文件——通过客户端使用 load_file）：

python -m procmon_mcp

预加载压缩的 XML 文件：

python -m procmon_mcp --input-file /path/to/capture.xml.gz

在自定义端口上通过 Streamable HTTP 启动：

python -m procmon_mcp --transport streamable-http --mcp-port 9000

处理超大文件时跳过堆栈跟踪：

python -m procmon_mcp --input-file /path/to/huge_capture.xml --no-stack-traces --no-extra-data

传输协议

传输方式	用例	状态
stdio	与 Claude Code、Claude Desktop 等配合进行本地使用	推荐
streamable-http	网络访问、多客户端、远程部署	支持
sse	尚不支持 Streamable HTTP 的旧版 MCP 客户端	已弃用（MCP 规范 2025-03-26）

stdio（推荐）

最简单、最可靠的传输方式。Claude Code 会将服务作为子进程启动，并通过 stdin/stdout 通信。无需配置网络。

python -m procmon_mcp --transport streamable-http --mcp-host 0.0.0.0 --mcp-port 8081

服务将在 http://<host>:<port>/mcp 上提供。

SSE（已弃用）

自 MCP 规范 2025-03-26 起已弃用。 SSE 为向后兼容而保留，但将在未来版本中移除。请迁移到 streamable-http 或 stdio。

python -m procmon_mcp --transport sse --mcp-port 8081

用户配置

ProcmonMCP 将用户偏好设置存储在 ~/.procmonmcp/config.json 中。该文件会自动创建，并保存：

• 上次加载的文件路径（未加载文件时，作为提示显示在 get_status 中）
• 加载偏好设置（no_stack_traces、no_extra_data）

无需 API 密钥或身份验证令牌——ProcmonMCP 是一款纯本地分析工具。

已解析捕获文件缓存

解析大型捕获文件的开销很大（需要几十秒到几分钟）。成功解析后， ProcmonMCP 会将优化后的内存表示形式（事件、驻留器、索引、进程表） 序列化到 ~/.procmonmcp/cache/，并以源文件路径、大小、修改时间以及加载选项为键。 之后重新加载同一未更改文件时会直接使用缓存，几乎瞬间完成——实际测试中， 20 秒的解析时间可缩短至不到 1 秒。

• 文件发生变化（修改时间/大小）或缓存格式版本变化时，缓存会自动失效。不同的 no_stack_traces/no_extra_data 选项会分别缓存。
• 使用 --no-cache（CLI）或 no_cache: true（load_file 工具）可绕过缓存；加载响应中的 from_cache 字段会指示是否使用了缓存。
• 使用 --clear-cache（CLI）或 clear_cache 工具可清除缓存。缓存大小受限，并采用 LRU 淘汰策略（默认 5 GiB；可通过 PROCMONMCP_CACHE_MAX_BYTES 环境变量覆盖）。
• **安全性：**缓存文件使用 Python 的 pickle 序列化，且只会从属于你的用户的 ~/.procmonmcp/cache 目录中读取（只会反序列化此工具自身生成的内容）。请勿将缓存目录指向其他用户可写入的位置。

可用的 MCP 工具

生命周期工具

工具	描述
get_status()	返回当前服务状态——是否已加载文件、加载进度、内存使用情况以及可用操作。请首先调用此工具。
load_file(file_path, no_stack_traces?, no_extra_data?, no_cache?)	加载 Procmon XML 文件（.xml、.gz、.bz2、.xz）进行分析。使用已解析捕获文件缓存，实现近乎瞬时的重新加载（响应中的 from_cache 会说明是否使用了缓存）。设置 no_cache: true 可绕过缓存。会提供进度反馈，并替换之前加载的所有数据。
close_file()	关闭（卸载）当前已加载的捕获文件并释放其占用的内存。使用 load_file 打开另一个文件之前，分析工具不可用。不会删除磁盘上的缓存。
clear_cache()	删除所有磁盘上的已解析捕获文件缓存。释放磁盘空间，并确保下次加载时重新解析。不会影响当前已加载的数据。

数据检索工具

工具	描述
get_loaded_file_summary()	返回已加载文件的详细摘要，包括文件名、计数、压缩情况、索引统计、驻留器统计以及选择性加载标志。
get_metadata()	返回基本元数据（文件名、类型、事件数／进程数）。
list_processes()	列出进程列表部分中的唯一进程（PID、名称、映像路径、父 PID）。
get_process_details(pid)	返回指定 PID 进程的详细属性。
query_events(...)	使用灵活的筛选条件查询事件，包括按进程、PID（filter_pid）、操作、结果、路径（包含／正则表达式）、详细信息（正则表达式）、时间戳范围和堆栈模块路径筛选。返回带索引的事件摘要。
get_event_details(event_index)	返回指定索引事件的所有属性。
get_event_stack_trace(event_index)	返回指定事件的调用堆栈（模块路径、位置、地址）。

分析工具

工具	描述
count_events_by_process()	按进程名称统计事件数。
summarize_operations_by_process(process_name_filter)	统计指定进程的操作数。
get_timing_statistics(group_by)	按进程或操作分组计算持续时间统计数据。
get_process_lifetime(pid)	查找给定 PID 的进程创建和进程退出时间戳。
find_file_access(path_contains, limit?)	查找路径子字符串匹配的文件系统事件（不区分大小写）。
find_network_connections(process_name)	返回进程访问过的远程端点的详细记录：端点、主机／IP／主机名／端口、操作、推断的方向（连接／发送／接收）、结果、事件数以及首次／最后出现的时间戳，并按数量排序。
list_network_connections(limit?)	全部捕获内容的网络排查：为所有进程中的每个（进程、PID、端点）生成一条详细记录，并按事件数排序。
get_network_top_talkers(limit?)	按事件数对整个捕获内容中的唯一远程端点排序，并列出访问过每个端点的不同进程数量及其名称。

导出工具

工具	描述
export_query_results(...)	将筛选后的事件导出到 CSV 或 JSON 文件。使用与 query_events 相同的筛选条件。

MCP 客户端

ProcmonMCP 适用于任何兼容 MCP 的客户端。以下是常用客户端的配置说明。

Claude Code（推荐）

请参阅上方的使用 Claude Code 快速开始部分。

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "procmon": {
      "command": "python",
      "args": ["-m", "procmon_mcp"]
    }
  }
}

Cline

若要让 Cline 使用 Streamable HTTP 传输，请先启动服务：

python -m procmon_mcp --transport streamable-http --mcp-port 8081

然后在 Cline 中选择 MCP Servers 并添加：

• 服务名称： ProcmonMCP
• 服务 URL： http://127.0.0.1:8081/mcp

恶意软件分析的 LLM 提示词示例

（假设已加载 Procmon XML 文件）

初步排查

• “获取已加载文件的摘要。”
• “列出日志中发现的唯一进程。”
• “按进程统计事件数。”（识别活动频繁的进程）
• “按进程分组计算持续时间统计数据。”（识别持续时间较长的事件）

调查可疑进程

• “获取进程 PID 4568 的详细信息。” （检查命令行、父 PID、映像路径）
• “汇总进程 suspicious.exe 的操作。”
• “查询满足以下条件的事件：filter_process 为 suspicious.exe，且 filter_operation 为 RegSetValue，限制为 10 条。”
• “查找进程 suspicious.exe 的网络连接。” （增强信息：方向、结果、计数、首次/最后出现时间）
• “列出整个捕获中的网络连接。” （针对整个捕获进行初步排查，按最繁忙的连接优先排列）
• “显示网络通信量最大的对象。” （按事件数排列远程端点）
• “查找包含 temp\\suspicious_data 的文件访问记录，限制为 50 条。”

查找持久化项

• “查询满足以下条件的事件：filter_operation 为 RegSetValue，且 filter_path_contains 为 CurrentVersion\\Run，限制为 20 条。”
• “查询满足以下条件的事件：filter_operation 为 CreateFile，且 filter_path_contains 为 StartUp，限制为 10 条。”

排查错误

• “查询 filter_result 为 ACCESS DENIED 的事件，限制为 10 条。”
• “查询 filter_result 为 NAME NOT FOUND 的事件，限制为 10 条。”
• “获取事件 987 的详细信息。”
• “获取事件 987 的堆栈跟踪。”

导出数据

• “将查询结果导出到 suspicious_reg_writes.csv，条件为 filter_process 是 suspicious.exe，且 filter_operation 包含 RegSet。”
• “以 json 格式将查询结果导出到 network_activity.json。”

性能与索引

ProcmonMCP 在加载文件时会构建四种索引，以便快速筛选查找：

索引	使用者	复杂度
进程名称（驻留 ID）	query_events、count_events_by_process	O(1) 查找
操作（驻留 ID）	query_events、summarize_operations_by_process	O(1) 查找
PID	query_events（filter_pid）、get_process_lifetime	使用集合交集进行 O(1) 查找
文件路径（驻留 ID）	find_file_access	O(unique_paths) 子字符串扫描

对于没有索引支持的筛选条件（例如正则表达式、路径包含、堆栈模块路径），ProcmonMCP 会退回到扫描所有事件的方式。请先使用有索引支持的筛选条件缩小结果范围，再应用开销更大的筛选条件。

限制

• 内存用量：虽然经过字符串驻留优化，但加载极大的 XML 文件（数百万条带堆栈跟踪的事件）仍可能占用大量 RAM。对于超大文件，请使用 --no-stack-traces 和 --no-extra-data。
• 加载时间：解析和优化大型 XML 文件需要时间，尤其是压缩文件。加载期间会报告进度。由于使用了已解析捕获缓存，重新加载未更改的文件几乎是瞬间完成；只有首次解析需要完整的处理时间。
• XML 结构：依赖标准的 Procmon XML 导出结构。格式错误或不符合标准的 XML 可能会导致解析错误。
• 非 ASCII 名称：Procmon 的 XML 导出会对非 ASCII 进程名称或路径名称进行双重编码（例如日文文件名）。ProcmonMCP 会在加载时检测并修复此问题，使名称可读且能按其真实值匹配；如果进程名称仍不便于准确输入，请改用 filter_pid 筛选。
• 堆栈跟踪：堆栈跟踪的质量取决于 Procmon 解析并包含在 XML 导出中的内容。需要正确配置符号后运行 Procmon。
• 一次只能加载一个文件：任何时候只能加载一个文件。加载新文件会替换之前的数据。

更新日志

重要变更记录在 CHANGELOG.md 中。

参与贡献

欢迎贡献！请随时在 GitHub 上提交拉取请求或创建问题。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。