内容
# 🦖 迅猛龙取证 MCP 服务器
**将 Claude Desktop 转变为数字取证工作站。**
一个统一的模型上下文协议（MCP）服务器，连接 Claude Desktop 到您的迅猛龙实例和本地取证工具。远程终端调查 + 本地证据分析，全部在一个服务器中。包含迅猛龙的 Docker 部署。
    
---
## 功能概述
不再需要在迅猛龙 GUI、终端 VQL 会话和取证脚本之间切换，您可以直接与 Claude 对话，它会为您执行这些操作。询问 Claude：
- *"查找 workstation-01 并告诉我它最后一次出现在什么时间"* → 查询迅猛龙获取客户端信息
- *"从该终端收集用户列表"* → 启动 `Linux.Sys.Users` 构件收集并检索结果
- *"哈希 /evidence/malware-samples/ 目录中的所有文件"* → 递归 SHA-256 哈希本地目录
- *"检查 syslog 中是否提到了该二进制文件"* → 使用关键词搜索扫描系统日志
- *"将文件元数据与日志条目进行交叉引用"* → 将时间戳、哈希值和日志命中关联到取证报告中
- *"运行一个 VQL 查询，显示终端上所有正在运行的进程"* → 直接执行自定义 VQL
所有结果都通过聊天返回。无需复制粘贴。无需切换选项卡。从终端到证据的完整取证链。
---
## 🛠️ 集成工具（12）
### 远程 — 迅猛龙（vr_*）
| 工具 | 描述 |
|------|-------------|
| **vr_authenticate** | 测试与迅猛龙的 gRPC 连接 |
| **vr_get_agent_info** | 按主机名查找客户端 → 客户端 ID、操作系统、代理版本、最后一次出现 |
| **vr_run_vql** | 在服务器上执行任意 VQL 查询 |
| **vr_list_artifacts** | 列出所有可用的客户端构件及其描述 |
| **vr_artifact_details** | 获取特定构件的完整规格 |
| **vr_collect_artifact** | 在远程终端上启动构件收集（返回 flow_id） |
| **vr_get_collection_results** | 轮询和检索已完成的收集结果（带有重试逻辑） |
### 本地取证（local_*）
| 工具 | 描述 |
|------|-------------|
| **local_file_metadata** | 文件的 SHA-256、大小、时间戳（沙盒到 SAFE_BASE） |
| **local_hash_directory** | 递归哈希目录中的每个文件 |
| **local_scan_syslog** | 按关键词搜索 Linux syslog 或 macOS 统一日志 |
| **local_correlate** | 将文件元数据与日志条目进行交叉引用 |
| **local_forensic_report** | 结合文件 + 日志数据生成结构化取证报告 |
### 主要功能
- **双模式**：任一工具包独立工作 — 仅部署迅猛龙、仅本地工具或两者兼有
- **路径沙盒**：所有 local_* 工具验证路径保持在 SAFE_BASE 内
- **异步流程轮询**：收集结果自动重试直到流程完成
- **多源构件**：自动处理具有多个数据源的构件
- **工具过滤**：通过 DISABLED_TOOLS 环境变量禁用个别工具
- **只读模式**：通过 READ_ONLY=true 阻止写入操作（构件收集）
---
## 🚀 快速开始
### 前提条件
- Docker 及 Docker Compose
- Python 3.11+
- Claude Desktop
### 1. 部署迅猛龙（Docker）
```bash
cd docker/
docker compose up -d
# 等待 ~30 秒初始化
docker logs velociraptor --tail 10
# 应该看到： "Starting gRPC API server" 和 "Frontend is ready"
```
默认 GUI： https://localhost:9889 （admin/admin — 修改此项！）
### 2. 生成 API 密钥
```bash
chmod +x generate-api-key.sh
./generate-api-key.sh
```
这会创建包含 gRPC 凭证的 `api.config.yaml` 并自动修复主机访问的连接字符串。
### 3. 安装 MCP 服务器
```bash
cd ../
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```
### 4. 配置
```bash
cp .env.example .env
# 编辑 .env — 设置您的路径：
# VELOCIRAPTOR_API_KEY=/path/to/api.config.yaml
# SAFE_BASE=/home/youruser/evidence
```
### 5. 配置 Claude Desktop
将以下内容添加到 `~/.config/Claude/claude_desktop_config.json` （Linux）或 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）：
```json
{
"mcpServers": {
"velociraptor-forensic": {
"command": "/path/to/velociraptor-forensic-mcp/.venv/bin/python",
"args": ["-m", "velociraptor_forensic_mcp"],
"cwd": "/path/to/velociraptor-forensic-mcp",
"env": {
"VELOCIRAPTOR_API_KEY": "/path/to/api.config.yaml",
"VELOCIRAPTOR_SSL_VERIFY": "false",
"SAFE_BASE": "/home/youruser/evidence",
"LOG_LEVEL": "INFO"
}
}
}
}
```
### 6. 重启 Claude Desktop
工具将自动出现。开始调查。
---
## 🔑 环境变量
| 变量 | 描述 | 默认值 | 必需 |
|----------|-------------|---------|----------|
| `VELOCIRAPTOR_API_KEY` | api.config.yaml 的路径 | — | 远程工具必填 |
| `VELOCIRAPTOR_SSL_VERIFY` | 验证 gRPC TLS 证书 | `true` | |
| `VELOCIRAPTOR_TIMEOUT` | gRPC 超时（秒） | `30` | |
| `SAFE_BASE` | 本地取证工具的根目录 | — | 本地工具必填 |
| `MCP_SERVER_HOST` | SSE 传输的绑定主机 | `127.0.0.1` | |
| `MCP_SERVER_PORT` | SSE 传输的绑定端口 | `8000` | |
| `LOG_LEVEL` | DEBUG/INFO/WARNING/ERROR | `INFO` | |
| `DISABLED_TOOLS` | 要禁用的工具名称，以逗号分隔 | — | |
| `READ_ONLY` | 阻止构件收集 | `false` | |
---
## 🐳 迅猛龙 Docker 设置
`docker/` 目录包含所有内容，以便在 Docker 中运行迅猛龙，并将端口映射到常见冲突之外：
| 主机端口 | 服务 | 目的 |
|-----------|---------|--------|
| 9000 | 客户端前端 | 迅猛龙代理检查 |
| 9001 | gRPC API | MCP 服务器连接此处 |
| 9889 | Web GUI | 您的浏览器 |
### 注册测试客户端
要将运行 Docker 的机器注册为迅猛龙客户端：
```bash
cd docker/
# 复制客户端二进制文件和配置
docker cp velociraptor:/velociraptor/clients/linux/velociraptor_client_repacked ./velociraptor_client
chmod +x velociraptor_client
docker exec velociraptor cat client.config.yaml > client.config.yaml
sed -i 's|https://VelociraptorServer:8000/|https://localhost:9000/|' client.config.yaml
# 运行客户端（Ctrl+C 停止）
sudo ./velociraptor_client --config client.config.yaml client -v
```
---
## 💡 使用示例
### 完整终端调查
> "查找终端 pop-os，收集其用户列表，并检查 syslog 中是否有可疑条目"
Claude 链：`vr_get_agent_info` → `vr_collect_artifact` → `vr_get_collection_results` → `local_scan_syslog`
### 文件完整性检查
> "哈希 /evidence/case-2024/ 目录中的所有文件，并检查它们是否出现在系统日志中"
Claude 链：`local_hash_directory` → `local_correlate`，用于每个可疑文件
### 自定义 VQL 调查
> "运行一个 VQL 查询，显示客户端 C.1393a876d1c48287 上所有正在监听的网络连接"
Claude 使用 `vr_collect_artifact` 和 `Linux.Network.Netstat` 或通过 `vr_run_vql` 编写自定义 VQL
### 快速分类
> "扫描 syslog 中的 'authentication failure' 并给我一个总结"
Claude 使用 `local_scan_syslog` 并综合结果
---
## 📁 项目结构
```
velociraptor-forensic-mcp/
├── velociraptor_forensic_mcp/
│ ├── __init__.py # 包元数据
│ ├── __main__.py # CLI 入口点
│ ├── config.py # 数据类配置（迅猛龙、取证、服务器）
│ ├── exceptions.py # 自定义异常层次结构
│ ├── vr_client.py # 迅猛龙 gRPC 客户端
│ ├── forensic_helpers.py # 本地取证函数
│ └── server.py # 具有所有工具/提示/资源的 FastMCP 服务器
├── docker/
│ ├── docker-compose.yaml # 迅猛龙 Docker 部署
│ └── generate-api-key.sh # API 密钥生成脚本
├── tests/
│ └── test_forensic.py # 单元测试
├── pyproject.toml # Python 打包
├── .env.example # 配置模板
└── README.md
```
---
## 🔒 安全
- **API 密钥保护**：`api.config.yaml` 包含私钥 — `chmod 600`
- **路径沙盒**：所有本地工具都限制在 SAFE_BASE 目录中
- **最小权限**：使用 `--role api,investigator` 而不是 `administrator` 生成 API 密钥
- **工具过滤**：通过 DISABLED_TOOLS 禁用不需要的工具
- **只读模式**：设置 `READ_ONLY=true` 以防止构件收集
- **永远不要提交** `api.config.yaml` 或 `.env` 到版本控制
---
## 🧪 运行测试
```bash
source .venv/bin/activate
pytest -v
```
---
## 🏗️ 架构
该服务器将两个开源项目组合成一个统一的 MCP 接口：
- **远程工具** 改编自 [socfortress/velociraptor-mcp-server](https://github.com/socfortress/velociraptor-mcp-server) （gRPC 操作）
- **本地工具** 改编自 [axdithyaxo/mcp-forensic-toolkit](https://github.com/axdithyaxo/mcp-forensic-toolkit) （沙盒文件分析）
两个工具包根据设置的哪些环境变量独立激活。您可以仅运行迅猛龙、仅本地工具或两者兼有。
---
## ⚠️ 法律免责声明
本工具仅用于**授权的数字取证和事件响应**。始终确保您在收集终端构件之前具有适当的授权。未经授权访问计算机系统是违法的。
---
## 🤝 贡献
欢迎拉取请求。要添加新工具：
1. 在 `forensic_helpers.py` （本地）或 `vr_client.py` （远程）中添加函数
2. 在 `server.py` 中创建 Pydantic 输入模型
3. 在 `_register_forensic_tools()` 或 `_register_velociraptor_tools()` 中注册工具
4. 添加测试
5. 提交 PR
---
## 📬 联系方式
- **Discord:** sgtwolf787
- **GitHub:** [@Hackerobi](https://github.com/Hackerobi)
白帽或无帽 🎩
---
*Built with Claude. Tested on live Velociraptor deployment. Stay legal.*
