AppliedIR/wintools-mcp

GitHub: AppliedIR/wintools-mcp

面向 Windows 取证工作站的 MCP 服务,为 LLM 客户端提供安全可控的取证工具执行与知识增强响应封装。

Stars: 0 | Forks: 0

# Windows Tools MCP [![CI](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/e0d8c5878e205523.svg)](https://github.com/AppliedIR/wintools-mcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/AppliedIR/wintools-mcp/blob/main/LICENSE) 具备目录门控与知识增强响应封装的 Windows 取证工具执行环境。 **[平台文档](https://appliedir.github.io/aiir/)** · [部署指南](https://appliedir.github.io/aiir/deployment/) ## 架构 wintools-mcp 在 Windows 取证工作站上独立运行,在端口 4624 上暴露一个 Streamable HTTP 端点。LLM 客户端和 aiir CLI 是两个面向用户的工具。aiir CLI 始终在 SIFT 工作站上运行 —— 它需要直接访问案例目录的文件系统。当 LLM 客户端在单独的机器上运行时,检查员必须拥有对 SIFT 的 SSH 访问权限以进行所有 CLI 操作。LLM 客户端通过网络连接到 wintools-mcp。 ``` graph LR subgraph sift ["SIFT Workstation"] CC["LLM Client
(human interface)"] CLI["aiir CLI
(human interface)"] CASE["Case Directory"] CLI --> CASE end subgraph winbox ["Windows Forensic Workstation"] WAPI["wintools-mcp API
:4624"] WM["wintools-mcp
Windows tool execution"] FK["forensic-knowledge"] WAPI --> WM WM --> FK end CC -->|"streamable-http"| WAPI WM -->|"SMB"| CASE ``` ### 执行流水线 每个工具执行都经过相同的安全和增强流水线。 ``` graph LR REQ["MCP tool call"] --> DENY{"Hardcoded
Denylist"} DENY -->|"blocked binary"| BLOCK["BLOCKED"] DENY -->|"pass"| CAT{"YAML Catalog
Allowlist"} CAT -->|"not cataloged"| REJECT["REJECTED"] CAT -->|"cataloged"| SANITIZE{"Argument
Sanitization"} SANITIZE -->|"dangerous flag
or metachar"| REJECT SANITIZE -->|"clean"| RESOLVE["Resolve
Binary Path"] RESOLVE --> EXEC["subprocess.run
shell=False"] EXEC --> PARSE["Parse Output
CSV / JSON / text"] PARSE --> ENRICH["FK Enrichment
caveats, corroboration,
field notes, discipline"] ENRICH --> RESP["Response Envelope"] ``` ### 安全模型 **此 MCP 会引入攻击向量,使得连接的 LLM 客户端可以在该系统上执行工具。** 它只能安装在专用的取证工作站上,这些工作站应在受信任的网络段中通过防火墙进行隔离。切勿安装在个人笔记本电脑、生产系统或包含调查范围之外数据的机器上。 安装程序需要输入 `security_hole` 或传递 `-AcknowledgeSecurityHole` 才能继续。这是一个故意的摩擦点。 所采取的额外控制措施(目录白名单、危险二进制文件黑名单、参数清洗、`shell=False` 执行)是纵深防御措施,而非预防性控制。该 MCP 未经过加固,绝不应面向互联网或其他不受信任的系统部署。 ``` graph TB INPUT["Tool Execution Request"] --> D{"Hardcoded Denylist
20 binaries + .exe variants"} D -->|"cmd, powershell, pwsh,
wscript, cscript, mshta,
rundll32, regsvr32, certutil,
bitsadmin, msiexec, bash,
wsl, sh, msbuild, installutil,
regasm, regsvcs, cmstp, control"| BLOCKED["BLOCKED"] D -->|"pass"| A{"YAML Catalog
Allowlist"} A -->|"unknown binary"| REJECTED["REJECTED"] A -->|"cataloged"| S{"Argument
Sanitization"} S -->|"shell metacharacters,
execution flags, or
@file response-file"| REJECTED S -->|"clean"| E["EXECUTE
subprocess.run(shell=False)"] ``` 所有执行均使用 `subprocess.run(shell=False)`。只有 YAML 目录文件中定义的工具才能运行。危险二进制文件(cmd、powershell、wscript 等)被硬编码黑名单无条件阻止。参数会经过检查,以筛选 shell 元字符、危险标志(与执行相关:`-e`、`--exec`、`--command`、`-enc`)以及响应文件语法(`@filename`)。 ## 快速开始 在 Windows 取证工作站上,克隆仓库: ``` git clone https://github.com/AppliedIR/wintools-mcp.git; cd wintools-mcp ``` 或者如果未安装 git,下载并解压 ZIP: ``` Invoke-WebRequest https://github.com/AppliedIR/wintools-mcp/archive/refs/heads/main.zip -OutFile wintools.zip Expand-Archive wintools.zip -DestinationPath .; cd wintools-mcp-main ``` 然后运行安装程序: ``` .\scripts\setup-windows.ps1 ``` 有关详细的部署选项和 SMB 配置,请参阅 [SETUP.md](SETUP.md)。 ## MCP 工具(共 7 个) ### 发现(6 个工具) | 工具 | 描述 | |------|-------------| | `scan_tools` | 扫描所有目录中的取证工具,报告可用性和安装指南 | | `list_available_tools` | 列出所有目录中的工具及其安装状态,可按类别筛选 | | `list_missing_tools` | 列出未安装的工具,提供安装指南和替代方案 | | `check_tools` | 按名称检查特定工具的可用性 | | `get_tool_help` | 获取特定工具的帮助、标志、注意事项和解释指南 | | `suggest_tools` | 根据工件类型,建议相关工具并检查可用性 | ### 通用执行(1 个工具) | 工具 | 描述 | |------|-------------| | `run_command` | 执行任何目录中的工具及其参数(受目录门控) | 所有特定工具的封装(Zimmerman 套件、Hayabusa、mactime)已整合到 `run_command` 中。工具目录仍定义每个二进制文件的输入标志、输出格式和 FK 知识映射。 ## 工具目录 工具在 `data/catalog/` 下的 YAML 目录文件中定义。该目录当前包含跨 7 个文件的 **31 个工具条目**: - `zimmerman.yaml` -- 14 个工具 (AmcacheParser, AppCompatCacheParser, EvtxECmd, JLECmd, LECmd, MFTECmd, PECmd, RBCmd, RECmd, SBECmd, SQLECmd, SrumECmd, WxTCmd, bstrings) - `sysinternals.yaml` -- 5 个工具 (autorunsc, sigcheck, strings, handle, procdump) - `memory.yaml` -- 4 个工具 (winpmem, dumpit, moneta, hollows_hunter) - `timeline.yaml` -- 3 个工具 (Hayabusa, chainsaw, mactime) - `analysis.yaml` -- 3 个工具 (capa, yara, densityscout) - `collection.yaml` -- 1 个工具 (KAPE) - `scripts.yaml` -- 1 个工具 每个条目定义了二进制文件名称、输入样式、输出格式、超时、FK 知识名称、安装方法和搜索路径: ``` # data/catalog/zimmerman.yaml (摘录) category: zimmerman tools: - name: AmcacheParser binary: AmcacheParser.exe description: "Parse Amcache.hve for program execution evidence" input_flag: "-f" output_format: csv timeout_seconds: 300 fk_tool_name: AmcacheParser install_methods: - method: direct url: "https://ericzimmerman.github.io/#!index.md" - method: dotnet command: "dotnet tool install --global AmcacheParser" install_paths: - "C:\\Tools\\ZimmermanTools" ``` ## 响应信封 每个工具响应都封装在带有取证知识增强的结构化信封中: ``` { "success": true, "tool": "run_command", "data": {"output": {"rows": ["..."], "total_rows": 42}}, "data_provenance": "tool_output_may_contain_untrusted_evidence", "output_format": "parsed_csv", "evidence_id": "wintools-steve-20260220-001", "examiner": "steve", "caveats": [ "Amcache entries indicate installation, not necessarily execution", "Timestamps reflect installation time, not last run" ], "advisories": ["Cross-reference with Prefetch for execution confirmation"], "corroboration": { "artifacts": ["prefetch", "shimcache"], "tools": ["PECmd", "AppCompatCacheParser"] }, "field_notes": {"KeyLastWriteTimestamp": "Last time the registry key was modified"}, "discipline_reminder": "Evidence is sovereign -- if results conflict with your hypothesis, revise the hypothesis, never reinterpret evidence to fit" } ``` | 字段 | 来源 | 描述 | |-------|--------|-------------| | `evidence_id` | 审计 | 唯一标识符 (`wintools-{examiner}-{YYYYMMDD}-{NNN}`) | | `caveats` | forensic-knowledge | 特定工件的限制和解释警告 | | `advisories` | forensic-knowledge | 使用指南和常见误解纠正 | | `corroboration` | forensic-knowledge | 建议的交叉引用工件和工具 | | `field_notes` | forensic-knowledge | 来自工件定义的时间戳字段含义 | | `discipline_reminder` | 内置 | 轮换的取证方法论提醒(共 14 条,每次调用循环) | ## 配置 ### 环境变量 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `WINTOOLS_TIMEOUT` | `600` | 默认命令超时时间(秒) | | `WINTOOLS_HOST` | `127.0.0.1` | HTTP 服务器绑定地址 | | `WINTOOLS_PORT` | `4624` | HTTP 服务器端口 | | `WINTOOLS_TOOL_PATHS` | (无) | 额外的二进制文件搜索目录(以路径分隔符分隔) | | `WINTOOLS_CATALOG_DIR` | (自动) | 覆盖目录 YAML 目录的路径 | | `AIIR_CASE_DIR` | (无) | 活动案例目录;启用按案例的审计跟踪 | | `AIIR_AUDIT_DIR` | (无) | 本地审计目录(覆盖 AIIR_CASE_DIR/audit/) | | `AIIR_SHARE_ROOT` | (无) | 用于证据读取和提取写入的 SMB 挂载根目录(例如 `E:\cases\SRL2\`) | | `AIIR_ACTIVE_CASE` | (无) | 记录在审计条目中的案例标识符 | | `AIIR_EXAMINER` | OS 用户 | 检查员身份(小写 slug) | ### YAML 配置文件 通过 `--config path/to/config.yaml` 传递。环境变量优先于 YAML 值。 | 键 | 默认值 | 描述 | |-----|---------|-------------| | `default_timeout` | `600` | 子进程超时时间(秒) | | `max_output_bytes` | `52428800` | 子进程捕获限制 (50MB) | | `response_byte_budget` | `10240` | MCP 响应信封中的最大字节数 (10KB) | | `http_host` | `127.0.0.1` | HTTP 绑定地址 | | `http_port` | `4624` | HTTP 端口 | | `hayabusa_dir` | `C:\Tools\Hayabusa` | Hayabusa 安装目录 | | `tool_paths` | `[]` | 额外的二进制文件搜索目录 | | `api_keys` | `{}` | 用于 Bearer token 认证的 API 密钥 | ### Bearer Token 认证 所有 API 请求都需要有效的 bearer token。Token 在安装期间生成,具有 `aiir_wt_` 前缀(24 个十六进制字符,96 位熵)。Token 存储在 `config.yaml` 的 `api_keys` 下,并在安装后显示,供检查员复制到其 SIFT 网关配置中。 ``` # config.yaml (在 Windows 上) api_keys: aiir_wt_a1b2c3d4e5f6a1b2c3d4e5f6: examiner: "default" role: "examiner" ``` 每个请求都必须包含 `Authorization: Bearer ` 标头。没有有效 token 的请求将收到 401 响应。仅在开发期间使用 `--no-auth`。 ### 从 SIFT 网关连接 要通过 SIFT 网关路由工具调用,请在 SIFT 工作站上的 `gateway.yaml` 中添加一个 wintools 后端条目: ``` backends: wintools-mcp: type: http url: "http://WIN_IP:4624/mcp" bearer_token: "aiir_wt_..." ``` 或者,`aiir setup` 会在交互式配置期间提示输入 Windows VM 地址和 token。 LLM 客户端也可以在其 MCP 客户端配置中使用相同的 bearer token 直接连接到 wintools-mcp,而无需通过网关。 ### 审计跟踪 每次工具执行都会记录到审计目录。解析顺序:显式的 `audit_dir` 构造函数参数 > `AIIR_AUDIT_DIR` 环境变量 > `AIIR_CASE_DIR/audit/`。证据 ID 遵循格式 `wintools-{examiner}-{YYYYMMDD}-{NNN}`,并在进程重启后恢复序列编号。 ## 安全注意事项 假定所有 AIIR 组件都运行在隔离的取证网络上,受防火墙保护,且不暴露于互联网或不受信任的系统。wintools-mcp 接受来自该网络内 SIFT 网关和 LLM 客户端的传入连接。这些组件间的连接是预期且有意为之的。该系统绝不得暴露于取证环境之外的网络。 所有 API 请求都需要有效的 bearer token(`aiir_wt_` 前缀)。Token 在安装期间生成,必须安全地传输到 SIFT 网关配置或 LLM 客户端设置。`--no-auth` 标志仅用于开发,绝不得在任何包含真实证据的环境中使用。 加载到系统中的任何数据都面临暴露给底层 AI 的风险。请仅将您愿意发送给 AI 提供商的数据放置在这些系统上。 wintools-mcp 解析可能包含攻击者精心制作的恶意内容的取证工件(注册表配置单元、事件日志、预取文件、内存转储)。工具以 `shell=False` 的子进程形式运行,并通过目录门控执行以限制攻击面。硬编码黑名单、目录白名单和参数清洗是纵深防御措施,而非预防性控制。 通过 SMB 共享的案例目录访问应使用经过身份验证的连接。共享应限制为需要访问的 AIIR 组件。对于证据文件,只读访问即可;提取和审计条目需要写入权限。 ## 证据处理 切勿将原始证据放置在任何 AIIR 系统上。仅使用已存在经过验证的原始件或备份的工作副本。AIIR 工作站通过连接 AI 的工具处理证据,加载到这些系统中的任何数据都可能传输给配置的 AI 提供商。将所有 AIIR 系统视为分析环境,而非证据存储。 证据完整性通过注册时记录的 SHA-256 哈希进行验证。检查员可以选择通过 `aiir evidence lock` 将证据锁定为只读。适当的证据完整性依赖于经过验证的哈希、写保护器和本平台之外存在的监管链程序。 案例目录可以位于外部或可移动介质上。首选 ext4 以获得完整的权限支持。NTFS 和 exFAT 可以接受,但文件权限控制(只读保护)将失效。由于 4 GB 文件大小限制,不建议使用 FAT32。 ## 负责任的使用 本项目展示了 AI 辅助事件响应的能力。尽管已采取措施强制执行人在回路控制,但最终需由每位检查员负责确保其调查结果准确且完整。最终责任在于人。AI 就像十六进制编辑器一样,是供受过适当培训的事件响应专业人员使用的工具。用户有责任确保其使用符合适用的法律、法规和组织政策。 ## 致谢 架构和指导由 Steve Anson 完成。实现由 Claude Code (Anthropic) 完成。设计灵感来自 Lenny Zeltser 的 [REMnux MCP](https://github.com/REMnux/remnux-mcp-server)。 ## 许可证 MIT 许可证 - 详见 [LICENSE](LICENSE)
标签:FTP漏洞扫描, HTTP API, HTTP工具, LLM 客户端集成, MCP 服务器, Python, SIFT 工作站, Windows 取证, 人工智能安全, 参数清洗, 合规性, 后渗透, 安全编排, 工具执行网关, 数字取证, 无后门, 无线安全, 流量嗅探, 白名单校验, 网络安全工具集, 自动化取证, 自动化脚本, 逆向工具, 防御性安全