IkerPagoaga/OpenProcessGuard-mcp
GitHub: IkerPagoaga/OpenProcessGuard-mcp
为 Claude Desktop 提供只读 Windows 进程取证能力的 MCP 服务器，通过自然语言即可调用 17 个覆盖六个狩猎阶段的取证工具。
Stars: 0 | Forks: 0
# ProcessGuard MCP
ProcessGuard 通过 17 个工具提供实时进程遥测、持久化检查、网络分析和 Sysmon 取证功能，这些工具跨越五个狩猎阶段组织，外加始终开启的原生阶段 0 —— 所有这些都可以由 Claude 使用自然语言调用。
**建立在安全工具应当开放、可审计且免费的信念之上。**
## 原则
**开源，完全可审计。** 每一行代码都是公开的。没有遥测，没有回传，没有隐藏行为。如果你不信任它，你可以阅读它的代码。
**安全设计。** ProcessGuard 不打开任何监听端口。它完全通过 `stdin`/`stdout` 与 Claude Desktop 进行通信。来自操作系统的字符串在到达 Claude 之前会被去除控制字符并限制长度——这可以抵御终端转义和零宽度/bidi 技巧，但**无法**中和语义注入，因此工具输出被视为证据，而非指令。环境变量值在默认拒绝的允许列表下呈现（只有经过筛选的非敏感名称会显示其值）。VirusTotal API 密钥绝不会出现在工具输出或日志中。
**只读。** ProcessGuard 仅进行观察——它不会修改文件、注册表项、网络设置或任何系统状态。
**负载下的高响应性。** 请求并发分派（限制为最多 16 个在途请求），因此耗时数分钟的 `run_full_hunt` 永远不会阻塞快速的 `list_processes`；`initialize` 握手始终优先得到响应。如果客户端断开连接，在途的工具调用将被取消，其子进程将被终止——孤立的提权服务器永远不会为无人运行扫描。
**自由如自由。** 采用 MIT 许可证。你可以分叉它、扩展它并回馈社区。
**Microsoft Sysinternals 注意事项。** 可选的阶段 2 (Autoruns) 和阶段 4 (Sysmon) 与 Microsoft 在[单独许可证](https://learn.microsoft.com/en-us/sysinternals/license-terms)下发布的 Sysinternals 工具集成。这些工具不包含在内——你需要直接从 Microsoft 下载。由于该许可证的规定，**当启用 Sysinternals 集成时，ProcessGuard 不能作为商业或货币化产品的一部分使用。** 阶段 0、1、3 和 5（原生进程枚举、内置 Authenticode 签名、网络分析和 VirusTotal）不受此限制。请参阅 [§15 许可证](#15-licence)。
## 快速开始
**选项 A —— 签名发布（推荐）。** 从
[Releases](https://github.com/IkerPagoaga/OpenProcessGuard-mcp/releases) 下载最新的签名构建版本，验证它（见下文），然后：
```
.\install.ps1 -BinaryPath .\processguard-mcp.exe
```
**选项 B —— 从源码构建**（Go 自动选择固定的 `go1.25.12` 工具链）：
```
git clone https://github.com/IkerPagoaga/OpenProcessGuard-mcp.git
cd OpenProcessGuard-mcp
.\install.ps1
```
`install.ps1` 将二进制文件安装在 `%ProgramFiles%\ProcessGuard` 下——这是一个仅管理员可写的
位置，因此非提权的攻击者无法植入特洛伊木马二进制文件以供提权服务器
运行——并将其注册到 Claude Desktop。重启 Claude Desktop 并要求它运行 `list_processes`。**原生工具无需任何配置文件即可
立即工作**——添加 `config.json`（复制 `config.example.json`）仅用于启用
可选的 Autoruns / Sysmon / VirusTotal / GeoIP 阶段。
### 验证发布版本
每个发布版本都附带一个使用 [cosign](https://docs.sigstore.dev/) 无密钥
签名的 `SHA256SUMS` 文件——没有长期密钥；签名绑定到本仓库的 GitHub Actions 身份：
```
sha256sum -c processguard-mcp__SHA256SUMS
cosign verify-blob \
--certificate-identity-regexp 'https://github.com/IkerPagoaga/OpenProcessGuard-mcp/.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--signature processguard-mcp__SHA256SUMS.sig \
--certificate processguard-mcp__SHA256SUMS.pem \
processguard-mcp__SHA256SUMS
```
每次发布都会附带 CycloneDX SBOM，用于供应链审计。
## 目录
1. [前置条件](#1-prerequisites)
2. [克隆仓库](#2-clone-the-repository)
3. [构建二进制文件](#3-build-the-binary)
4. [创建 config.json](#4-create-configjson)
5. [注册到 Claude Desktop](#5-register-with-claude-desktop)
6. [以管理员身份运行 Claude Desktop](#6-run-claude-desktop-as-administrator)
7. [验证安装](#7-verify-the-installation)
8. [可选工具](#8-optional-tools)
9. [故障排除](#9-troubleshooting)
10. [工具参考](#10-tools-reference)
11. [推荐提示词](#11-recommended-prompts)
12. [安全](#12-security)
13. [架构](#13-architecture)
14. [贡献](#14-contributing)
15. [许可证](#15-licence)
## 1. 前置条件
开始之前，请确保你的 Windows 机器上安装了以下内容。
### 必需项
| 软件 | 版本 | 下载 |
|---|---|---|
| Windows | 10 或 11 (64 位) | — |
| Go | 1.25 或更新版本 | https://go.dev/dl/ |
| Git | 任何最新版本 | https://git-scm.com/download/win |
| Claude Desktop | 最新版 | https://claude.ai/download |
**验证 Go 是否已安装** —— 打开终端（`Win + R` → 输入 `cmd` → 回车）并运行：
```
go version
```
你应该看到类似 `go version go1.25.12 windows/amd64` 的输出。如果没有，请重新安装 Go 并在设置过程中勾选“添加到 PATH”。
## 2. 克隆仓库
```
git clone https://github.com/IkerPagoaga/OpenProcessGuard-mcp.git
cd OpenProcessGuard-mcp
```
## 3. 构建二进制文件
在 `OpenProcessGuard-mcp` 文件夹内运行：
```
go build -o processguard-mcp.exe .
```
Go 会自动下载所有依赖项。首次运行大约需要 30 秒。
**验证是否成功：**
```
dir processguard-mcp.exe
```
你应该看到一个大小在 10 MB 左右的文件（发布管道的 `-s -w` 标志会进一步缩减其大小）。如果构建失败，请确认已安装 Go 1.25 或更新版本（`go version`）。
## 4. 创建 config.json
在**与 `processguard-mcp.exe` 相同的文件夹中**创建一个名为 `config.json` 的文件。
你可以复制模板：
```
copy config.example.json config.json
```
### 最小配置（无可选工具）
这将使所有 6 个阶段 0 工具立即工作——无需额外软件。
```
{
"autoruns_path": "",
"sysmon_log": "Microsoft-Windows-Sysmon/Operational",
"vt_api_key": "",
"geoip_db": "",
"audit_log": true
}
```
### 完整配置（配置所有可选工具）
```
{
"autoruns_path": "C:\\Tools\\SysinternalsSuite\\autorunsc.exe",
"sysmon_log": "Microsoft-Windows-Sysmon/Operational",
"vt_api_key": "your_virustotal_api_key_here",
"geoip_db": "C:\\Tools\\GeoIP\\GeoLite2-City.mmdb",
"audit_log": true
}
```
### 配置字段参考
| 字段 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `autoruns_path` | 否 | `""` | `autorunsc.exe` 的完整路径。启用阶段 2 持久化扫描。 |
| `sysmon_log` | 否 | `"Microsoft-Windows-Sysmon/Operational"` | Sysmon 的 Windows 事件日志通道。仅允许字母数字、空格、连字符、斜杠、下划线和点。 |
| `vt_api_key` | 否 | `""` | 免费的 VirusTotal API 密钥。启用 `lookup_hash` 和阶段 5 哈希升级。绝不会在输出或日志中回显。 |
| `geoip_db` | 否 | `""` | MaxMind `GeoLite2-City.mmdb` 的路径。为外部连接启用国家/城市数据。 |
| `audit_log` | 否 | `true` | 将 JSONL 审计日志写入 `%APPDATA%\ProcessGuard\audit.log`。 |
## 5. 注册到 Claude Desktop
打开文件资源管理器并导航至：
```
%APPDATA%\Claude\
```
打开（或创建）`claude_desktop_config.json` 并添加 ProcessGuard 条目：
```
{
"mcpServers": {
"processguard": {
"command": "C:\\path\\to\\OpenProcessGuard-mcp\\processguard-mcp.exe"
}
}
}
```
如果该文件已经有其他 MCP 服务器，请将 `processguard` 块添加到现有的 `mcpServers` 对象中。
## 6. 以管理员身份运行 Claude Desktop
ProcessGuard 需要管理员权限才能枚举所有正在运行的进程并读取 Sysmon 事件日志。
1. 在桌面或开始菜单中找到 Claude Desktop 快捷方式。
2. 右键点击它 → **“以管理员身份运行”**。
3. 在 UAC 提示符下点击“是”。
要将此设为永久设置：
1. 右键点击快捷方式 → **属性**。
2. 点击 **高级**。
3. 勾选 **“以管理员身份运行”**。
4. 点击确定 → 应用。
## 7. 验证安装
一旦 Claude Desktop 打开（以管理员身份），输入：
```
Run list_processes and show me the top 5 by memory usage.
```
如果你看到带有 PID 和内存数据的正在运行的进程列表，则说明安装成功。
然后运行完整的基线扫描：
```
Run run_full_hunt and summarise all findings by severity.
```
工具未配置或未安装的阶段（Autoruns、Sysmon、VirusTotal）将显示为 `INFO / TOOL_UNAVAILABLE` 结果，并附带如何启用它们的说明——Sysmon 的可用性是针对事件日志通道进行实时探测的，因此没有 Sysmon 的机器会被如实报告，而不是被计为干净的阶段。
## 8. 可选工具
每个可选工具都能解锁额外的狩猎阶段。你可以按任何顺序安装它们。将每个工具的路径添加到 `config.json` 后，**请重启 Claude Desktop** 以使更改生效。
### 阶段 1 —— 签名（无需下载）
启用：`get_process_tree`、`get_unsigned_processes`
阶段 1 从内置的 Windows `Get-AuthenticodeSignature` 获取 Authenticode 签名状态——**无需下载 Sysinternals**，也无需配置：这些工具开箱即用。
### Sysinternals Autoruns (阶段 2)
启用：`get_autoruns_entries`、`flag_autoruns_anomalies`、`run_full_hunt` 中的阶段 2
1. 从以下地址下载：https://learn.microsoft.com/en-us/sysinternals/downloads/autoruns
2. 解压到一个永久文件夹（例如 `C:\Tools\SysinternalsSuite\`）。
3. 在 `config.json` 中设置：
```
"autoruns_path": "C:\\Tools\\SysinternalsSuite\\autorunsc.exe"
```
4. 重启 Claude Desktop。
**验证是否有效：** 以管理员身份打开终端并运行：
```
C:\Tools\SysinternalsSuite\autorunsc.exe -a * -c -nobanner -accepteula
```
你应该看到带有标题行的 CSV 输出。
### VirusTotal API 密钥（阶段 5）
启用：`lookup_hash`、`run_full_hunt` 中的 VT 哈希升级
1. 在 https://www.virustotal.com 创建一个免费账户。
2. 点击你的个人资料图标 → **API key**。
3. 复制密钥并在 `config.json` 中设置：
```
"vt_api_key": "paste_your_key_here"
```
4. 重启 Claude Desktop。
### MaxMind GeoIP 数据库（阶段 3 丰富）
为 `get_foreign_connections` 启用国家和城市数据。
1. 在以下地址创建一个免费的 MaxMind 账户：https://www.maxmind.com/en/geolite2/signup
2. 下载 `.mmdb` 格式的 **GeoLite2-City**。
3. 解压并将 `.mmdb` 文件放置在永久位置（例如 `C:\Tools\GeoIP\GeoLite2-City.mmdb`）。
4. 在 `config.json` 中设置：
```
"geoip_db": "C:\\Tools\\GeoIP\\GeoLite2-City.mmdb"
```
5. 重启 Claude Desktop。
### Sysmon (阶段 4)
启用：`query_sysmon_events`、`get_process_create_events`、`get_network_events`、`run_full_hunt` 中的阶段 4
1. 从以下地址下载 Sysmon：https://learn.microsoft.com/en-us/sysinternals/downloads/sysmon
2. 下载推荐的配置（SwiftOnSecurity 的配置是一个坚实的起点）：https://github.com/SwiftOnSecurity/sysmon-config ——下载 `sysmonconfig-export.xml`
3. **以管理员身份**打开终端并运行：
```
sysmon64.exe -accepteula -i sysmonconfig-export.xml
```
4. 验证 Sysmon 是否正在运行：
```
Get-Service Sysmon64
```
你应该看到 `Status: Running`。
## 9. 故障排除
**工具未在 Claude Desktop 中出现**
- 确认 `claude_desktop_config.json` 是有效的 JSON（没有多余的逗号，使用双反斜杠）。
- 确认路径指向 `processguard-mcp.exe` 并且文件存在。
- 每次更改配置后，请以管理员身份重启 Claude Desktop。
**`go build` 失败**
- 确认已安装 Go 1.25 或更新版本（`go version`）。
- 确认你在运行 `go build` 时处于 `OpenProcessGuard-mcp` 文件夹内。
**`list_processes` 返回的进程少于预期**
- Claude Desktop 未以管理员身份运行。请参阅[第 6 步](#6-run-claude-desktop-as-administrator)。
**Sysmon 工具返回空数组**
- 确认 Sysmon 正在运行：`Get-Service Sysmon64`。
- 如果已停止：`Start-Service Sysmon64`。
**Autoruns 返回错误**
- 确认 `autoruns_path` 指向 `autorunsc.exe`，而不是 `autoruns.exe`。
- 手动测试：在管理员终端中运行 `autoruns -a * -c -nobanner -accepteula`。
**VirusTotal 返回“达到速率限制”**
- 免费层级的限制为每分钟 4 次请求。请等待 60 秒后重试。
**config.json 更改未生效**
- 每次更改 `config.json` 后重启 Claude Desktop 服务器仅在启动时读取一次。
## 10. 工具参考
### 阶段 0 —— 原生（始终可用）
| 工具 | 描述 |
|---|---|
| `list_processes` | 所有正在运行的进程：PID、名称、PPID、CPU%、内存、exe 路径、用户。 |
| `get_process_detail` | 单个进程的深入视图：cmdline、CWD、环境变量（列出所有名称；仅显示允许列表中非敏感名称的值，其余全部脱敏）、线程数、句柄数。 |
| `get_network_connections` | 通过 `netstat -ano` 获取的所有 TCP/UDP 连接，并与进程名称关联。 |
| `get_loaded_modules` | 特定 PID 加载的 DLL/模块。检测注入和侧加载。 |
| `get_suspicious_processes` | 启发式扫描：名称欺骗、错误路径的系统进程、空壳进程模式、temp 目录中的未签名二进制文件、异常的父子链。 |
| `get_startup_entries` | 注册表 Run 键和启动文件夹条目（轻量级）。 |
### 阶段 1 —— 签名（内置，无外部工具）
| 工具 | 描述 |
|---|---|
| `get_process_tree` | 带有 Authenticode 签名状态的完整父子树。 |
| `get_unsigned_processes` | 所有没有受信任数字签名的正在运行的进程。 |
### 阶段 2 —— Autoruns（需要 `autoruns_path`）
| 工具 | 描述 |
|---|---|
| `get_autoruns_entries` | 所有持久化点：Run/RunOnce 键、计划任务、服务、驱动程序、BHO、编解码器等。 |
| `flag_autoruns_anomalies` | 仅过滤出高风险条目：未签名、可疑路径、VirusTotal 命中。 |
### 阶段 3 —— 网络
| 工具 | 描述 |
|---|---|
| `get_established_connections` | 仅限 ESTABLISHED TCP 连接（过滤掉 LISTENING/TIME_WAIT 噪声）。 |
| `get_foreign_connections` | 连接到非私有互联网 IP 的连接，带有可选的 GeoIP 国家数据。 |
### 阶段 4 —— Sysmon（需要 Sysmon 服务）
| 工具 | 描述 |
|---|---|
| `query_sysmon_events` | 查询过去 N 分钟内的任何 Sysmon 事件 ID。 |
| `get_process_create_events` | Sysmon 事件 1：cmdline、父映像、用户、哈希。取证时间线。 |
| `get_network_events` | Sysmon 事件 3：创建时的出站连接。C2 信标检测。 |
### 阶段 5 —— VirusTotal（需要 `vt_api_key`）
| 工具 | 描述 |
|---|---|
| `lookup_hash` | SHA256 哈希信誉检查。返回检测分数（例如 `5/72`）。结果缓存 24 小时。 |
### 编排
| 工具 | 描述 |
|---|---|
| `run_full_hunt` | 按顺序运行所有阶段。返回结构化的 `HuntReport`，包含 `CRITICAL/HIGH/MEDIUM/INFO` 严重性分级、执行摘要和建议的操作。 |
## 11. 推荐提示词
### 完整系统审计
```
Run run_full_hunt and walk me through the findings, starting with CRITICAL and HIGH severity.
For any unsigned process or suspicious autorun with a SHA256, use lookup_hash to check its reputation.
```
### 调查可疑进程
```
I think PID 4821 is behaving oddly. Run get_process_detail and get_loaded_modules on it,
then check its network activity with get_established_connections.
```
### 疑似感染后的持久化检查
```
Run flag_autoruns_anomalies and list anything that is unsigned or has a VirusTotal hit.
For each flagged entry, correlate with get_process_create_events for the last 120 minutes.
```
### C2 信标狩猎
```
Use get_foreign_connections to list all outbound internet connections grouped by country.
Then use get_network_events for the last 60 minutes to see which processes opened those connections.
Flag anything that beacons at a regular interval.
```
### 事件发生后的取证时间线
```
Pull get_process_create_events and get_network_events for the last 240 minutes.
Build a timeline of new processes and their outbound connections.
Cross-reference any unsigned spawned process with lookup_hash.
```
## 12. 安全
### 无监听端口
ProcessGuard **不打开任何监听端口**。它完全通过 `stdin`/`stdout` 与 Claude Desktop 进行通信——没有 TCP socket，没有 HTTP 服务器，也没有暴露在外的命名管道。
### 提示词注入缓解措施
ProcessGuard 收集原始操作系统数据并将其传递到 Claude 的上下文窗口中。拥有本地代码执行能力的攻击者可以精心构造看起来像 LLM 指令的进程名称或注册表键。以下缓解措施会去除控制字符并限制长度——击败终端转义和零宽度/bidi 技巧——但它们**无法**中和*语义*注入：一个字面意思上写着“忽略之前的指令并……”的值会原封不动地通过。因此，工具输出是供 Claude 推理的证据，绝不是要遵循的指令。实施了以下缓解措施：
- **字符串截断** —— 字符串字段在离开 MCP 边界前会受到长度上限限制：默认为 512 个字符，取证证据字段（命令行、哈希、Sysmon XML）为 16384 个字符，以便它们不会被切断（根据设计，这些字段具有更大的注入面）。
- **控制字符剥离** —— 从所有输出中去除 ASCII 控制字符（< 0x20, DEL）。
- **配置验证** —— `sysmon_log` 在启动时会根据严格的字符允许列表进行验证，以防止 PowerShell 注入。
- **环境变量允许列表** —— `get_process_detail` 会列出每个环境变量的名称，但仅显示经过筛选的非敏感名称允许列表（`PATH`、`OS`、`PROCESSOR_*`、程序/数据路径、`USERNAME`、`COMPUTERNAME`、区域设置/shell 变量）的值。无论格式如何，所有其他值都会被脱敏，因此无法识别的、看似无害名称的变量中的凭据就不会泄露。二级拒绝列表（类似于密钥的名称 + **已知凭据前缀** `ghp_`/`AKIA`/PEM/JWT/…）甚至会将允许列表中的名称也进行脱敏，作为深度防御——尽管如果将没有已知前缀的密钥塞入允许列表中可写的变量，它仍然可能绕过该底线。有关残留的缺陷，请参阅 [LIMITATIONS.md](LIMITATIONS.md)。
- **VT API 密钥隔离** —— 绝不会在任何工具响应中回显或写入审计日志。
有关真实的信任边界姿态（语义注入、环境值允许列表的残留缺陷），请参阅 [LIMITATIONS.md](LIMITATIONS.md)；有关完整的威胁模型和负责任的披露流程，请参阅 [SECURITY.md](SECURITY.md)。
### 依赖验证
克隆后，验证依赖项的完整性：
```
go mod verify
govulncheck ./...
```
## 13. 架构
```
processguard-mcp.exe (stdio JSON-RPC 2.0 — MCP protocol)
├── internal/config Config load, validation, and tool availability matrix
├── internal/audit Append-only JSONL audit log (%APPDATA%\ProcessGuard\audit.log)
├── internal/geoip MaxMind GeoLite2 wrapper + private-IP CIDR detection
└── internal/tools
├── tools.go Registry + Call() dispatcher + output sanitisation boundary
└── handlers/
├── processes.go list_processes, get_process_detail, get_network_connections
├── modules.go get_loaded_modules
├── heuristics.go get_suspicious_processes
├── startup.go get_startup_entries
├── procex.go get_process_tree, get_unsigned_processes
├── autoruns.go get_autoruns_entries, flag_autoruns_anomalies
├── network.go get_established_connections, get_foreign_connections
├── sysmon.go query_sysmon_events, get_process_create_events, get_network_events
├── virustotal.go lookup_hash (24h cache + 4 req/min rate limiter)
└── hunt.go run_full_hunt orchestrator
```
### 数据流
```
Claude Desktop ──stdin──► processguard-mcp.exe
│
tools.go (dispatch)
│
handler (OS call)
│
sanitiseJSON() ◄── all output passes through here
│
Claude Desktop ◄──stdout──
```
## 14. 贡献
欢迎贡献力量。请：
1. Fork 本仓库并创建功能分支。
2. 遵循现有的代码风格——未经讨论不要引入新的外部依赖。
3. 如果你要添加新工具，请添加处理器测试。
4. 提交 pull request，并清晰描述更改的内容和原因。
有关与安全相关的贡献，请参阅 [SECURITY.md](SECURITY.md) 以了解负责任的披露流程。
## 15. 许可证
ProcessGuard MCP 在 [MIT 许可证](LICENSE)下发布。
**重要的第三方限制：** ProcessGuard 不包含任何 Microsoft 二进制文件。如果你启用了可选的由 Sysinternals 支持的阶段（通过配置 `autoruns_path` 或安装 Sysmon），[Microsoft Sysinternals 许可条款](https://learn.microsoft.com/en-us/sysinternals/license-terms)将适用于这些工具——该许可证禁止在未与 Microsoft 达成单独协议的情况下用于商业产品。不包含 Sysinternals 的核心阶段不受此限制。有关完整详细信息，请参阅 [LICENSE](LICENSE)。
标签：Claude Desktop, EVTX分析, MCP服务器, Mr. Robot, Sysmon, Windows 调试器, 数据包嗅探, 无线安全, 日志审计, 流量嗅探, 端点可见性, 自动化扫描, 进程取证