# forensics-mcp

`forensics-mcp` 是一个面向 CTF / 电子取证比赛的本地 MCP Server。它把 Windows 上常用的取证命令行工具封装成可被 Codex 调用的 MCP 工具，适合处理磁盘镜像、内存镜像、流量包、SQLite 数据库、压缩包、图片隐写和混合证据材料。

项目定位是“取证胶水层”：不替代 Autopsy、Magnet AXIOM、IDA、JADX 这类大型工具，而是把比赛里最高频、最适合自动化的步骤统一接起来。

## 功能

- 文件基础画像：大小、时间戳、MIME 猜测、Magic 签名、样本熵、头部十六进制。
- 哈希计算：默认 `md5`、`sha1`、`sha256`，也支持其他 `hashlib` 算法。
- 字符串搜索：ASCII / UTF-16LE，可按关键字或正则过滤。
- SQLite 只读分析：表结构概览、行数统计、只读查询、CSV 导出。
- 压缩包：使用 7-Zip 列目录和显式解压。
- 文件雕刻和隐写辅助：`exiftool`、`binwalk`、`foremost`、`pngcheck`。
- 流量分析：`capinfos` 摘要、`tshark` 协议层级和字段提取。
- 内存取证：封装 Volatility 3 插件执行。
- 磁盘镜像：`img_stat`、`mmls`、`fsstat`、`fls`、`istat`、`icat` 导出。

## 已封装的 MCP 工具

- `tool_inventory`
- `forensic_triage`
- `file_profile`
- `hash_file`
- `strings_search`
- `sqlite_overview`
- `sqlite_query`
- `sqlite_export_query`
- `archive_list`
- `archive_extract`
- `exiftool_json`
- `binwalk_scan`
- `foremost_carve`
- `pngcheck`
- `pcap_info`
- `tshark_fields`
- `volatility_run`
- `disk_image_probe`
- `tsk_mmls`
- `tsk_fsstat`
- `tsk_fls`
- `tsk_istat`
- `tsk_icat_export`
- `run_known_tool`

## 安装

推荐使用 `uv`：

```powershell
uv run --with "mcp[cli]>=1.12.3" python server.py
```

如果作为 Python 包安装：

```powershell
pip install .
forensics-mcp
```

## Codex 配置示例

如果你把项目放在 `G:\meiyuelou\mcp\forensics-mcp`：

```toml
[mcp_servers.forensics]
command = "uv"
args = [
    "run",
    "--with",
    "mcp[cli]>=1.12.3",
    "python",
    'G:\meiyuelou\mcp\forensics-mcp\server.py',
]

[mcp_servers.forensics.env]
PYTHONIOENCODING = "utf-8"
PYTHONUTF8 = "1"
UV_CACHE_DIR = 'C:\Users\Meiyouqian\uv-cache'
```

更多示例见 `examples/`。

## 底层工具自动发现

服务会优先从 `PATH` 查找工具，然后尝试一些常见 Windows 取证工具目录，例如：

- `G:\tools\ctf工具箱\流量分析\WiresharkPortable\App\Wireshark\tshark.exe`
- `G:\tools\ctf工具箱\图片隐写\exiftools\exiftool.exe`
- `G:\tools\ctf-all-in-one-new\ctftools-all-in-one\libdll\misc\binwalk\binwalk.exe`
- `G:\tools\foremost-master\foremost-master\binary\foremost.exe`
- `G:\tools\PanelForensics.Windows\PanelForensics\lib\sqlite3.exe`
- `G:\meiyuelou\mcp\sleuthkit-4.4.0-win32\sleuthkit-4.4.0-win32\bin`

也可以用环境变量覆盖单个工具路径：

```powershell
$env:FORENSICS_MCP_TSHARK_PATH = "D:\Tools\Wireshark\tshark.exe"
$env:FORENSICS_MCP_VOLATILITY3_PATH = "C:\Python310\Scripts\vol.exe"
```

环境变量格式为：

```text
FORENSICS_MCP_<TOOL>_PATH
```

## 安全边界

- 工具执行不使用 shell，所有命令以参数列表方式调用。
- SQLite 查询默认只允许只读语句。
- 证据读取优先，只有显式导出、解压、雕刻类工具会写入输出目录。
- 本项目用于合法授权的 CTF、教学、应急响应和电子取证场景。

## 适合的比赛材料

- `.E01` / `.raw` / `.img` 磁盘镜像
- `.dmp` / `.lime` 内存镜像
- `.pcap` / `.pcapng` 流量包
- `.sqlite` / `.db` / `.db-wal` 数据库
- Android 应用数据目录和 APK 旁证
- ZIP / 7Z / RAR 等压缩包
- PNG / JPG / PDF / 固件等混合载体

## 开发

```powershell
python -m py_compile forensics_mcp\server.py forensics_mcp\triage.py
python -m pytest
```

Fast triage can also be run without MCP:

```powershell
python -m forensics_mcp.triage "<evidence file or folder>" --max-files 500 --max-depth 6 --output-dir triage
```

项目目前偏 Windows 取证环境，Linux/macOS 也可以运行，但需要自行保证底层 CLI 工具在 `PATH` 中。