MCP取证工具包
MCP取证工具包 是一个安全的、支持人工智能的本地服务器，用于数字取证，使用 模型上下文协议（MCP）它公开了语义上有意义的工具来分析日志、验证文件完整性和生成审计级取证报告。它专为分析师和LLM设计，可实现精确和安全的自动化调查。
______________________________________________________________________
特性
- 使用基于关键字的扫描进行结构化日志分类(
scan_syslog) - 文件元数据提取和SHA-256哈希(
file_metadata) - 使用目录哈希进行递归完整性扫描(
hash_directory) - 关联引擎将文件修改链接到日志事件(
correlate_file_and_logs) - 人类可读的法医报告(
generate_forensic_report) - 通过以下方式进行安全访问控制
SAFE_BASE沙盒环境 - 内置LLM提示，用于引导推理和取证任务
______________________________________________________________________
截图
此示例演示了使用 generate_forensic_report 工具：
______________________________________________________________________
入门指南
先决条件
- Python 3.10+
- 诗歌或pip
- MCP-CLI(
pip install modelcontext或遵循设置指南） .env提交SAFE_BASE定义的
______________________________________________________________________
安装
依赖项
- Python>=3.10
- Poetry（推荐）或pip用于依赖管理
- 自动安装的关键Python包：
- 模型上下文 - 快速 - 优维康 - python dotenv - 键入扩展名
使用诗歌（推荐）
# Clone the repo
git clone https://github.com/axdithyaxo/mcp-forensic-toolkit.git
cd mcp-forensic-toolkit
# Install Poetry if not already installed
curl -sSL https://install.python-poetry.org | python3 -
# Install dependencies and create virtual environment automatically
poetry install
# Activate the Poetry shell
poetry shell
# Create and configure environment variables
cp .env.example .env
# Edit .env and set your SAFE_BASE (e.g. /Users/yourname/Desktop)使用Python的venv和pip（可选）
# Clone the repo
git clone https://github.com/axdithyaxo/mcp-forensic-toolkit.git
cd mcp-forensic-toolkit
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
# Install dependencies
pip install -r requirements.txt
# Create and configure environment variables
cp .env.example .env
# Edit .env and set your SAFE_BASE (e.g. /Users/yourname/Desktop)Windows用户注意事项：
# Use .venv\Scripts\activate to activate the virtual environment instead of source .venv/bin/activate.用法
启动服务器
确保已安装MCP CLI(pip install modelcontext)已安装的依赖项(poetry install 或 pip install -r requirements.txt).
然后启动服务器：
mcp dev mcp_forensic_toolkit/server.py
---
### Access via MCP Inspector
Use the MCP Inspector or visit:
http://127.0.0.1:6274
You can then:
* Run tools (`scan_syslog`, `file_metadata`, etc.)
* Execute prompts for analysis
* View and inspect structured output
---
## CLI Demo (Optional)
You can run a command-line demo as follows:
python cli_demo.py ~/Desktop/test_hit.txt correlation
如果发现相关性，输出包括：
File: /Users/... Keyword searched in logs: 'correlation' File modified at: ... Matching log entries: - ... - ... Correlation found: Yes
否则：
Correlation found: No
______________________________________________________________________
## 工作流示例
1. 在中修改或检查文件 `SAFE_BASE`.
1. 跑 `generate_forensic_report` 或CLI工具。
1. 使用MCP检查器或LLM来解释结果。
1. 示例匹配：
{ "filename": "/Users/you/Desktop/test_hit.txt", "file_modified_time": "2025-06-08T00:26:04.714230", "log_hits": [ "logger: correlation test for test_hit.txt", "log run noninteractively, args: ..." ], "correlation_found": true }
______________________________________________________________________
## 环境变量
|变量|描述|
| ----------- | ------------------------------------------- |
| `SAFE_BASE` |将所有文件操作限制到此路径。 |
示例 `.env.example`:
SAFE_BASE=/Users/yourname/Desktop
______________________________________________________________________
## 安全考虑
- 所有工具都会根据以下条件验证路径 `SAFE_BASE`
- 系统日志以只读方式访问
- 工具优雅地处理权限错误和格式错误的输入
- CLI界面避免了不安全的全局搜索或目录遍历
______________________________________________________________________
## 测试
运行单元测试：
python test_server.py
或者使用pytest：
pytest test_server.py -v
______________________________________________________________________
## 使用示例
### 示例：Claude桌面中的“调查文件”提示
**提示给定**
使用调查文件提示分析“/Users/username/Destop/test_hit.txt”中的文件。
提供文件大小、创建和修改时间以及SHA-256哈希值。
评估是否有任何篡改或可疑特征的迹象。
**示例响应**
## 档案调查报告
### 档案基本信息
- 文件路径：/Users/用户名/桌面/test_hit.txt
- 文件大小：9字节
- 创建时间：2025年6月8日00:26:04.733792 UTC
- 修改时间：2025年6月8日00:26:04.714230 UTC
- SHA-256哈希：9b7729b1ccfe223076659db07b7f0bb888e139907bb8d7019560166176953fcb
### 分析及评估
文件特征：
- 这是一个非常小的文件（只有9个字节），可能包含最少的文本内容
- 文件几乎是同时创建和修改的，修改时间戳实际上比创建时间戳早约19毫秒——这是不寻常的，但可能是由于文件系统计时精度差异造成的
时间分析：
- 创建和修改发生在00:26:04 UTC
- 在系统日志中找不到与此文件的创建或修改相关的特定日志条目
- 日志显示了该时间段内的正常系统活动，主要是电源管理和Claude桌面应用程序活动
安全评估：
没有明显的篡改或可疑特征的迹象：
1. 文件大小：9字节大小与小文本文件一致
1. 时间戳：虽然修改时间略早于创建时间，但这是一种已知的文件系统行为，并不表示篡改
1. 哈希完整性：SHA-256哈希为未来的完整性验证提供了基准
1. 系统日志：在创建时间前后未检测到可疑的文件系统活动或安全事件
1. 位置：该文件位于标准用户桌面目录中，这是用户文件的正常位置
建议：
- 该文件似乎是合法的，没有被篡改的迹象
- 存储SHA-256哈希以备将来进行完整性验证
- 通过定期检查其哈希值来监视任何意外更改
### 其他示例提示
**1.分类系统日志提示**
使用分流系统日志提示在系统日志中搜索关键字“error”。
总结指示警告或安全事件的最相关日志条目。
建议是否立即采取行动。
**2.关联日志和文件提示**
使用相关日志和文件提示分析文件“/Users/username/Destop/test_hit.txt”，并在系统日志中搜索关键字“correlation”。
确定文件修改时间是否与可疑日志事件一致。
解释相关性及其法医学意义。
**3.解释相关提示**
使用带有文件“/Users/username/Destop/test_hit.txt”和关键字“correlation”的解释相关性提示。
解释日志点击和文件元数据。
提供一份简明的法医推理总结（不超过100字）。
## 法医分析报告
一份详细的法医分析报告展示了该工具包的使用和输出：
- [法医分析报告（Markdown）](docs/forensic_analysis_report.md)
此报告提供了一个由工具包的工具和提示生成的结构化输出的示例。
## 与Claude Desktop一起使用
要将MCP取证工具包与Claude Desktop连接，请执行以下操作：
1. 创建配置文件。， `claude_config.json`，内容如下（相应调整路径）：
{ "mcpServers": { "MCP Forensic Toolkit": { "command": "/path/to/your/venv/bin/mcp", "args": ["run", "/path/to/mcp_forensic_toolkit/server.py"] } } }
## 演示视频
在此处观看MCP取证工具包演示视频：
[Google Drive上的演示视频](https://drive.google.com/file/d/1MFaXzhFwMfLNfk5Ew_Sko5biDldXQTPb/view?usp=share_link)
## 许可证
MIT许可证
______________________________________________________________________
## 致谢
- 模型上下文协议（MCP）团队和社区创建了一个创新标准，实现了可互操作的人工智能工具集成。
- FastMCP Python SDK开发人员提供了一个强大且用户友好的框架来构建MCP服务器。
- 更广泛的开源和数字取证社区，旨在激发安全有效的人工智能驱动调查工具。
- 项目和倡议侧重于安全的人工智能代理接口和基础设施自动化，这塑造了该工具包背后的愿景。