MCP Forensic Toolkit

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 工具：

Example Correlation 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服务器。
- 更广泛的开源和数字取证社区，旨在激发安全有效的人工智能驱动调查工具。
- 项目和倡议侧重于安全的人工智能代理接口和基础设施自动化，这塑造了该工具包背后的愿景。