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：

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

如果作为 Python 包安装：

pip install .
forensics-mcp

Codex 配置示例

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

[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

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

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

环境变量格式为：

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 / 固件等混合载体

开发

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

Fast triage can also be run without MCP:

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

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