MCP-取证工具包

Name: MCP-取证工具包
Author: axdithyaxo

作者：axdithyaxo2 星标更新：2025-06-11

安装使用来源：spider==github.com

项目介绍

MCP 法证工具包

MCP 法证工具包 是一个安全且支持AI的本地服务器，用于数字法证分析，基于模型上下文协议 (MCP) 构建。它提供了语义上明确的工具来分析日志、验证文件完整性并生成符合审计标准的法证报告。该工具包既适用于分析师也适用于大型语言模型（LLMs），能够实现精确且安全的自动化调查。

功能

使用基于关键词扫描的方法进行结构化日志筛选 (scan_syslog)
文件元数据提取及SHA-256哈希计算 (file_metadata)
带目录哈希的递归完整性扫描 (hash_directory)
将文件修改与日志事件关联的引擎 (correlate_file_and_logs)
人类可读的法证报告生成 (generate_forensic_report)
通过 SAFE_BASE 和沙箱环境的安全访问控制
内置的LLM提示，用于引导推理和法证任务

屏幕截图

此示例展示了使用 generate_forensic_report 工具成功地将文件与系统日志条目进行关联分析：

示例关联报告

快速开始

先决条件

Python 3.10+
Poetry 或 pip
MCP CLI (pip install modelcontext 或遵循安装指南)
包含定义了 SAFE_BASE 的 .env 文件

安装

依赖项

Python >= 3.10
Poetry（推荐）或 pip 用于依赖管理
自动安装的关键Python包：
- modelcontext
- fastapi
- uvicorn
- python-dotenv
- typing-extensions

使用Poetry（推荐）

# 克隆仓库
git clone https://github.com/axdithyaxo/mcp-forensic-toolkit.git
cd mcp-forensic-toolkit

# 如果尚未安装，请安装Poetry
curl -sSL https://install.python-poetry.org | python3 -

# 自动安装依赖项并创建虚拟环境
poetry install

# 激活Poetry shell
poetry shell

# 创建并配置环境变量
cp .env.example .env
# 编辑 .env 并设置你的 SAFE_BASE（例如：/Users/yourname/Desktop）

使用Python venv和pip（替代方案）

# 克隆仓库
git clone https://github.com/axdithyaxo/mcp-forensic-toolkit.git
cd mcp-forensic-toolkit

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在Windows中使用 .venv\Scripts\activate

# 安装依赖项
pip install -r requirements.txt

# 创建并配置环境变量
cp .env.example .env
# 编辑 .env 并设置你的 SAFE_BASE（例如：/Users/yourname/Desktop）

注意事项（针对Windows用户）：

# 使用 .venv\Scripts\activate 来激活虚拟环境，而不是 source .venv/bin/activate。

使用方法

启动服务器

确保已安装MCP CLI (pip install modelcontext) 和依赖项 (poetry install 或 pip install -r requirements.txt)。

然后启动服务器：

mcp dev mcp_forensic_toolkit/server.py

---

### 通过MCP Inspector访问

使用MCP Inspector或访问：

http://127.0.0.1:6274


你可以：

* 运行工具（如 `scan_syslog`, `file_metadata` 等）
* 执行分析提示
* 查看和检查结构化的输出

---

## CLI演示（可选）

你可以按照以下方式运行命令行演示：

```bash
python cli_demo.py ~/Desktop/test_hit.txt correlation

如果找到关联，输出包括：

文件: /Users/...
在日志中搜索的关键词: 'correlation'
文件修改时间: ...
匹配的日志条目:
  - ...
  - ...
发现关联: 是

否则：

发现关联: 否

示例工作流程

修改或检查位于 SAFE_BASE 内的文件。
运行 generate_forensic_report 或CLI工具。
使用MCP Inspector或LLM解释结果。
示例匹配：

{
  "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桌面

给定提示

使用investigate-file提示来分析位于"/Users/username/Desktop/test_hit.txt"的文件。提供文件大小、创建和修改时间以及SHA-256哈希值。评估是否有篡改迹象或其他可疑特征。

示例响应

文件调查报告

基本文件信息

文件路径: /Users/username/Desktop/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桌面应用程序活动

安全性评估：

没有明显的篡改或可疑特征：

文件大小：9字节大小与一个小文本文件一致
时间戳：尽管修改时间略早于创建时间，但这是一种已知的文件系统行为，并非篡改的迹象
哈希完整性：SHA-256哈希为未来的完整性验证提供了基准
系统日志：在创建时间附近未检测到可疑的文件系统活动或安全事件
位置：文件位于标准用户的桌面目录中，这是用户文件的正常位置

建议：

文件看起来是合法的，没有篡改迹象
存储SHA-256哈希以便未来进行完整性验证
通过定期检查其哈希值来监控任何意外变化

额外示例提示

1. 筛选系统日志提示

使用triage-system-logs提示来搜索系统日志中的关键词“error”。总结最相关的警告或安全事件日志条目。如有必要，提出立即行动建议。

2. 关联日志和文件提示

使用correlate-log-and-file提示来分析文件“/Users/username/Desktop/test_hit.txt”，并在系统日志中搜索关键词“correlation”。确定文件修改时间是否与可疑日志事件相符。解释关联及其法证意义。

3. 解释关联提示

使用explain-correlation提示，针对文件“/Users/username/Desktop/test_hit.txt”和关键词“correlation”。解释日志命中和文件元数据。提供简洁的法证推理摘要（少于100字）。

法证分析报告

一份详细的法证分析报告，展示工具包的使用和输出，如下所示：

法证分析报告（Markdown）

此报告提供了工具包工具和提示生成的结构化输出示例。

与Claude桌面连接

要将MCP法证工具包与Claude桌面连接：

创建一个配置文件，例如 claude_config.json，内容如下（根据需要调整路径）：

{
  "mcpServers": {
    "MCP法证工具包": {
      "command": "/path/to/your/venv/bin/mcp",
      "args": ["run", "/path/to/mcp_forensic_toolkit/server.py"]
    }
  }
}

演示视频

观看MCP法证工具包的演示视频：

演示视频在Google Drive

许可证

MIT许可证

致谢

模型上下文协议 (MCP) 团队和社区，他们创造了一个创新的标准，使AI工具集成成为可能。
FastMCP Python SDK 开发者，他们提供了一个强大且易于使用的框架来构建MCP服务器。
更广泛的开源和数字法证社区，他们激发了安全有效的AI驱动调查工具的灵感。
关注安全AI代理接口和基础设施自动化的项目和倡议，它们塑造了这个工具包背后的愿景。