内容
# X-Ways MCP 服务器
用于 X-Ways Forensics 预处理、安装验证和受控自动化的 MCP 服务器。
本仓库遵循与 `bethington/ghidra-mcp` 相同的总体思路：将专业的桌面分析工具置于结构化的 MCP 接口后，以便代理可以检查状态、运行可重复的工作流程，并保留有用的审计轨迹。第一个版本是有意作为一个安全的控制平面。当命令行或脚本覆盖不足时，运行者应为特定的进程间隙生成一个小的 X-Tension 桥，并为未来的运行记录 API 来源。
## 当前功能
- 发现 X-Ways Forensics、WinHex、X-Ways Imager 和 XWFIM 可执行文件。
- 验证 XWFIM `Temp` 下载并检测损坏的 ZIP 文件，如损坏的 `viewer.zip`。
- 使用 MD5/SHA-1/SHA-256 对证据和下载的软件包进行哈希。
- 创建可重复的案例工作空间文件夹。
- 为挂载的文件夹或导出构建只读预处理清单。
- 运行一个法医工具，该工具写入案例清单、报告存根、状态 JSON 和与 `Donovoi/forensic-copilot` 兼容的审计日志。
- 为 Windows、Linux、macOS 和通用证据装置创建可丢弃的合成测试环境。
- 构建 X-Ways 启动命令而不执行它们。
- 在显式启用时可选地启动 X-Ways。
- 获取公共 X-Ways 版本信息以进行快速版本检查。
- 在本地缓存和搜索 X-Ways 手册，以获取命令行、脚本和无头工作流程语法。
- 使用无头优先、本地分布式 RVS、X-Tension-next、UI-last 策略规划 X-Ways 操作。
- 使用 API 注释和构建钩生成本地 X-Tension 桥脚手架。
- 清点 X-Ways 可执行文件导入、延迟导入、`XWF_*` 导出和 `XWF_*`/`XT_*` 字符串线索，并附有记录的 PowerShell 命令。
- 将 77 个已验证的 `XWF_*` 导出作为面向代理的 PowerShell 命令公开，这些命令创建了经过验证的 JSONL 请求，供进程内 X-Tension 桥使用。
- 使用本地手册规划并行 X-Ways 处理：首先进行本地分布式卷快照细化，只有在必要时才使用隔离的工作案例。
- 为容器优先的导出、手动/操作门控和同时记录提供可重用的 PowerShell 护栏模块。
- 通过命令行/脚本、导出列表元数据、X-Tensions、报告或有界 UI 查询优先进行 X-Ways 分析，然后再实现文件内容。
## 安全模型
默认行为是只读和干预运行。
`launch_xways` 除非同时满足以下两个条件，否则不会执行：
- `XWAYS_MCP_ALLOW_EXECUTE=1`
- 工具调用传递 `confirm=true`
这样可以避免在代理仍在规划时意外启动分析、映像或脚本工作流程。
自动化偏好：
0. 手动优先：在决定命令语法、API 行为、分布式处理、X-Tension 工作或 UI 回退之前，请检查最新的可用 X-Ways 手册、官方文档或批准的本地文档缓存。
1. X-Ways 命令行、脚本、保存的对话框选择、`Cfg:`、`XT:` 和 `XTParam:*`。
2. 当手册支持时，使用 X-Ways 原生分布式 RVS 处理同一个案例中的不同证据对象。
3. 当任务需要进程内 X-Ways 访问或 API 涵盖了无头界面无法实现的内容时，生成一个 X-Tension 桥。
4. 仅在必要时将 UI 自动化作为有限的最后手段。
如果运行者使用已文档化或未文档化的 X-Tensions API 行为，则必须在将桥应用于真实证据之前，在本地桥注释中记录符号、X-Ways 版本约束和来源。
X-Ways 分析是查询优先的。在可以使用命令行/脚本路由、导出列表元数据、报告、X-Tensions 或有限 UI 查询回答问题时，请勿实现文件内容。仅当字节必须离开 X-Ways 以供外部工具使用时，才将文件内容导出到容器中。元数据列表可以导出用于规划，但复制/恢复的文件内容必须首先放入 X-Ways 证据文件容器中。
## 要求
- Python 3.10+
- 单独安装 X-Ways Forensics、WinHex、X-Ways Imager 或 XWFIM
- 用于真正的 X-Ways 启动和可执行版本检查的 Windows
服务器本身可以在其他平台上运行，以进行存档验证、哈希和文件夹清单工作。
## 快速入门
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
pytest
python -m xways_mcp --transport stdio
```
在本地缓存当前 X-Ways 手册以进行离线模型查找：
```powershell
python -m pip install -e ".[dev]"
python -c "from xways_mcp.manual import cache_xways_manual; print(cache_xways_manual(source=r'<XWAYS_ROOT>\manual.pdf'))"
```
从公共 X-Ways 手册和官方脚本/设置页面刷新：
```powershell
python -c "from xways_mcp.manual import cache_xways_manual; print(cache_xways_manual(download_latest=True, fetch_official_docs=True, refresh=True))"
```
运行 MCP stdio 烟雾测试：
```powershell
python scripts\smoke_mcp.py --search-root "<XWFIM_ROOT>" --public-release
```
运行与法医副驾驶兼容的工具预飞行：
```powershell
python -m xways_mcp.harness xwfim-preflight `
--case-name CASE-001 `
--xwfim-root "<XWFIM_ROOT>" `
--staging-root artifacts `
--output-root reports `
--evidence-os Windows `
--evidence-mode portable-tooling
```
在不导出文件内容的情况下，对现有的 X-Ways 案例数据库运行本地查询优先的使用模式预处理：
```powershell
.\scripts\Invoke-XwfCaseDbPathStringTriage.ps1
```
脚本在本地案例工作空间报告文件夹下写入净化报告、结构化 JSON 和本地别名映射。
将本地 X-Ways 可执行文件表面与提交的 XWF/XT 参考基准进行比较：
```powershell
Import-Module .\powershell\XWaysForensicWorkflow\XWaysForensicWorkflow.psd1 -Force
Compare-XwfExternalSurface `
-XwfRoot "<XWF_ROOT>" `
-OutputDirectory ".\reports\xwf-external-surface"
```
比较写入导入、延迟导入、导出、类似 API 的字符串和看似未记录的字符串候选者的 Markdown、JSON 和 CSV 工件。
使用生成的 PowerShell 命令创建验证的 XWF API 桥请求：
```powershell
Import-Module .\powershell\XWaysForensicWorkflow\XWaysForensicWorkflow.psd1 -Force
Get-XwfItemName -Argument @{ nItemID = 42 }
Add-XwfComment `
-Argument @{ nItemID = 42; lpComment = 'Reviewed'; nFlagsHowToAdd = 0 } `
-OutboxPath ".\case-workspaces\CASE-001\xwf-api-requests.jsonl" `
-AllowMutating
```
这些命令不直接从 PowerShell 调用 X-Ways 导出。它们为进程内 X-Tension 桥生成 `xwf-api-bridge-request/v1` 对象。
为所有支持的证据操作系统构建可丢弃的合成装置：
```powershell
python -m xways_mcp.testenv build --name CASE-001 --evidence-os all --root test-envs --force
python -m xways_mcp.testenv destroy --name CASE-001 --evidence-os all --root test-envs --missing-ok
```
使用以下配置您的 MCP 客户端：
```json
{
"mcpServers": {
"xways-mcp": {
"command": "python",
"args": ["-m", "xways_mcp", "--transport", "stdio"],
"env": {
"XWAYS_HOME": "C:\\xwf",
"XWAYS_MCP_SEARCH_ROOTS": "<XWAYS_ROOT>;<XWFIM_ROOT>",
"XWAYS_MCP_ALLOW_EXECUTE": "0",
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
## 有用的工具
- `environment`
- `public_xways_release`
- `manual_status`
- `cache_xways_manual`
- `search_xways_manual`
- `headless_xways_reference`
- `plan_xways_operation`
- `plan_parallel_xways_jobs`
- `create_xtension_scaffold`
- `discover_installations`
- `inspect_xwfim_cache`
- `validate_archive`
- `hash_file`
- `create_workspace`
- `triage_inventory`
- `build_launch_command`
- `launch_xways`
- `harness_init_case`
- `harness_xwfim_preflight`
- `harness_folder_triage`
- `testenv_create`
- `testenv_build`
- `testenv_run`
- `testenv_destroy`
- `testenv_list`
参见 [docs/TOOLS.md](docs/TOOLS.md) 获取详细信息。
参见 [docs/FORENSIC_COPILOT.md](docs/FORENSIC_COPILOT.md) 获取与 `Donovoi/forensic-copilot` 的集成。
参见 [docs/INTEGRATION_CONTRACT.md](docs/INTEGRATION_CONTRACT.md) 获取宽松的适配器合同和共享的案例运行清单。
参见 [docs/TEST_ENVIRONMENTS.md](docs/TEST_ENVIRONMENTS.md) 获取可丢弃的合成装置测试。
参见 [docs/MANUAL_FIRST.md](docs/MANUAL_FIRST.md) 获取优先使用手册的工具策略。
参见 [docs/HEADLESS_XWAYS.md](docs/HEADLESS_XWAYS.md) 获取本地手册索引和无头命令查找。
参见 [docs/PARALLEL_PROCESSING.md](docs/PARALLEL_PROCESSING.md) 获取基于手册的分布式处理策略。
参见 [docs/XTENSION_BRIDGE.md](docs/XTENSION_BRIDGE.md) 获取生成的 X-Tension 桥工作流程。
参见 [docs/EXTERNAL_SURFACE_ANALYSIS.md](docs/EXTERNAL_SURFACE_ANALYSIS.md) 获取 PE 导入/导出/字符串分析和 XWF 21.8 x64 基线。
参见 [docs/XWF_API_CMDLETS.md](docs/XWF_API_CMDLETS.md) 获取已验证的 `XWF_*` 导出的生成的 PowerShell 包装器。
参见 [docs/FORENSIC_SOUNDNESS.md](docs/FORENSIC_SOUNDNESS.md) 获取优先使用容器的导出策略和可重用的 PowerShell 模块。
参见 [docs/BEST_PRACTICES.md](docs/BEST_PRACTICES.md) 获取公共最佳实践目录和选择工作流程。
## XWFIM 验证示例
```text
inspect_xwfim_cache(path="<XWFIM_ROOT>")
```
这会报告 `Temp` 中的每个 ZIP 文件，是否可以打开，以及 ZIP 中央目录记录是否缺失。这是截断下载的信号。
## 路线图
1. 稳定 Python MCP 控制平面。
2. 添加用于重复预处理的更强大的 X-Ways 脚本模板。
3. 为多实例同案例运行添加原生分布式 RVS 协调。
4. 为进程间隙生成特定于操作的 X-Tension DLL 桥。
5. 在 X-Ways 打开时动态注册 X-Tension 支持的工具。
6. 为时间线、搜索命中和标记文件导出添加报告工作流程。
## 参考
- X-Ways X-Tensions API：<https://www.x-ways.net/forensics/x-tensions/api.html>
- X-Ways 手册：<https://www.x-ways.net/winhex/manual.pdf>
- X-Ways 脚本编写：<https://www.x-ways.net/winhex/scripting.html>
- X-Ways 命令行设置说明：<https://www.x-ways.net/winhex/setup.html>
- X-Ways 版本邮件列表：<https://www.x-ways.net/winhex/mailings/>
