dfireballz

════════════════════════════════════════════════════════╗ ║ ║ ║ █╗ ███████╗██╗██████╗ ███████╗██████╗ █████╗ ██╗ ██╗ ███████╗ ║ ║ ██╔══██╗██╔════╝██║██╔══██╗ ██╔════╝██╔══██╔══██╗██║ ██║╚══███╔╝ ║ ██║ ██║╗ ██║██████╔╝ █████╗ ██████╔╝███████║██ ██║ █╝ ║ ║║ ██║══╝ ██╔══██╗ ══╝ ══██╗██╔══██║██║ ███╔ ║ ║ █╔╝██║║██║║ ███████╗██████╔╝██ ██║███████╗███████╗█╗ ║ ║ ╚═════╝ ╚═╝ ╚═╝╚ ╚═╝ ╚══════╝╚═════╝═╝ ╚═╝╚══════╝╚══════╝══╝ ║ ║ ╠═════════════════════════════════════════════════╣ ║ 取证与网络犯罪调查平台 ║ 证据链 · 物证分析 · MCP 支持 ║ ╠═════════════════════════════════════════════════════════════════╣ ║ ITino · Docker · Python · FastMCP · Ollama ║ ╚═════════════════════════════════════════════════════════════════════════════════╝> [](https://www.python.org/downloads/) [](LICENSE) [](https://www.docker.com/) [](https://modelcontextprotocol.io) **基于 MCP 的 AI 原生取证调查框架 — 所有内容均在 Docker 中运行。** > 本平台**不**用于渗透测试。它是一个专业的取证平台，旨在生成可用于法庭的证据。 --- ## 目录 **概述** - [工作原理](#工作原理) - [架构](#架构) - [组件](#组件) **快速入门** - [前提条件](#前提- [快速启动) **** - [Docker 中的 Claude Code（推荐）](#教程-1--docker-中的-claude-code推荐) 主机上的 Claude Code-2--主机上的-claude-code) - [Claude Desktop](#教程--claude-desktop [ChatGPT](#4--chatgpt) - [MCPHost + Ollama](#教程-5--ost--oll- [Open Web Ollama](#教程-6--open-webuiama) **技能** - [调查技能杠命令）](#调查技能) - [](#技能工作原理) ** - [提示如何系统](#提示如何流经系统) - [主机目录布局](#主机目录- [MCP 服务器参考](#mcp-) - [调查剧本](#调查剧本 [API 密钥-密钥) - [捷方式](#-快捷方式) 证据链](#证据链) ** - [ 和教程](#高级--教程) -排除](#故障排除 [项目结构](#) - [安全安全说明) -/CD 流水线d-流水线 [贡献](#贡献) - [许可证](#许可证) --- ## 工作原理 您的 AI 客户端（Cl、Claude DesktopGPT 或 MCPHostllama）**是编排器**： **您输入提示 或使用 `/skill斜杠命令（例如ware-analysis /.exe`） 2. **AI 选择工具**7 个 MCP 服务器+ 取证工具） 3. **每个工具在 Docker 容器中执行** 通过 `docker exec -i`（stdio 传输） **AI 相关结果** — 时间线、MITRE ATT&CK 映射、IoC 提取 5. **AI 编写取证报告** 整个过程中维护证据链 所有内容均在 Docker 中运行。主机上没有取证工具。所有发现结果均存放在 `./output/` 中。 --- ## 架构 ``` ┌──────────────────────────────────────────────────────────────┐ │ AI 主机（选择一个） │ │ Claude Code │ Claude Desktop │ Chat │ MCPHost/WebUI│ └──────┬────────┴────────┬─────────┴─────┬─────┴────────┬──────┘ │ docker exec -i │ │ HTTP/SSE │ ▼ ▼ ▼ ▼ ┌──────────────────────────────────────────────────────────────┐ │ MCP 服务器（stdio） │ │ │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │ │ kali-forensics │ │ winforensics │ │ osint │ │ │ │ Volatility3 │ │ MFT, Registry │ │ Maigret │ │ │ │ YARA, tshark │ EVTX, Prefetch │ │ │ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │ │ threat-intel │ │binary-analysis │ │network-forensic│ │ │ │ VT, │ │ Ghidra, r2 │ │ 18 tshark tools││ │ AbuseIPDB │ │ Capa, YARA │ │ tcpdump, PCAP │ │ │ └────────────────┘ └────────────────┘ ┘ ┌────────────────┐ │ │ 文件系统 │都在 dfire-net 上 │ │ │ /cases /evidence│ 证据卷：只读 │ │ └────────────────┘└──────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ 基础设施 │ │ ┌──────────────┐ ┌───────────┐ ┌───────────┐ │ │ │ 编排器 │ │ PostgreSQL│ │ Redis │ │ │ │ FastAPI │ │ pgcrypto │ │ Cache │ │ │ │ :8800 │ : │ │ :6379 │ │ │ └──────────────┘ └───────────┘ └────────── │ └──────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ 主机（您的计算机） │ │evidence/ — 证据文件（容器中只读） ./cases/ — 工作案例文件 │ │ ./reports/ — 生成的取证 │ │ ./output/ — 调查结果、日志、导出 │ └──────────────────────────────────────────────────────── ``` >：** stdio。每个 MCP 服务器均运行 `m(transport="stdio")`。AI 主 `docker exec -i <container> <command>` 连接。 > > **例外：** ChatGPT 使用 HTTP/SSE — mcpo 代理将 MCP 服务器作为 OpenAPI 端点桥接。 --- ## 组件 | 容器 | 功能 | 端口 | 配置文件 | |:--|:--|:--:|:--:| | **kali-forensics** | Volatility3, bulk_extractor, tshark, YARA, dc3dd, Sleuthkit, foremost, binwalk, exiftool | — | default | | **winforensics** | MFT, ShellBags, LNK, Registry, EVTX, Prefetch, Chainsaw | — | default | | **osint** | Maigret, Sherlock, Holehe, theHarvester, DNSTwist, subfinder | — | default | | **threat-intel** | VirusTotalodan, AbuseIP MalwareBazaarFox, URLScan | default | | **binary-analysis** | Ghidra headless, Radare2, CRE ATT& YARA, pe lief | — | | **network-for | 18hark/tshark, tcpdump, PCAP 合并/拆分/切割, JA3/JA3S | — | default | | **filesystem** | 对 /cases, /evidence (只读), /reports, /output 的范围文件访问 | default | orchestrator** | FastAPI — 案例,, 剧本, 证据链8800` | default | | **db PostgreSQL with pgcrypto (加密 API ) | — | default | | **redis** | Redis 缓存 | — | default | | **claude-code** | Docker 中的 Anthropic CLI（无需主机安装） | —aude-code` | | **ollama** | 本地 LLM 推理（Open WebUI 场景） | `114 | `openweb | | **open-webui** | Ollama Web UI | `8080` |webui` | mcpo** 到 OpenAPI 的 Open WebUI / Chat `8812 `openwebui` | --- ## 前提条件 | 需求 | 详情 | |:--|:--| | **Docker** | 25带 Docker Compose | | **RAM** | 推荐 （最低 8 GB） | | **磁盘** | 50 GB+（Docker 镜像 | | **Docker** | 通过验证：`get docker \| cut - -f3 必须与 `. 中的 `DOCKER`（默认 `999`）匹配 | | **GPU** *(可选 NVIDIA GPU + [](https.nvidia.com/dat-native/container-toolkit/install-guide.html)，用于 | ### API（免费层可用| 服务 | 免费层 | 注册 | |:--|:-- **Virus | 4 请求 | [virustotal.com/gui/my-apikey](https://wwwustotal.com/my-apikey) | Shodan** | 有限查询 |.shodan.io](https://account.shodan.io/) | | **AbuseIPDB** | 1,000 请求/天 | [abuseipdb.com/account/api](https://www.abuseipdb.com/account/api) | | **URLScan.io** | 50 次扫描/天 | [urlscan.io/user/signup](https://urlscan.io/user/signup) | | **VulnCheck** | 免费层 | [vulncheck.com](https://vulncheck.com/) | > **在 Docker 中使用 Claude Code？** 您还需要一个 **Anthropic API 密钥**：[console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys) ```bash bash scripts/check-requirements.sh # 验证前提条件 ``` --- ## 快速启动 所有镜像均已在 [Docker Hub](https://hub.docker.com/r/crhacky/dfireballz) 上预构建。无需本地构建。 ```bash git clone https://github.com/valITino/dfireballz.git cd dfireballz make setup # 交互式向导：.env、镜像、MCP 配置 make start # 启动 10 个容器 ``` ### 验证 ```bash make status # 容器健康状态表 make health # MCP 服务器响应检查 ``` --- ## 教程 1 — Docker 中的 Claude Code（推荐） 在 Docker 中完全运行 Claude Code — 直接连接到内部网络上的 MCP 服务器。 ```bash make setup # 选择 "Docker 中的 Claude Code" make start make claude-code 交互式 Claude Code ``` 入口点验证7 个 MCP 服务器启动。一旦 ``` /malware/sample.exe aude Code 自主调用二进制分析（Ghidra、Radare2、Capa）、kali-forensics（YARA、ExifTool）和威胁情报（VirusTotal），然后编写完整的取证报告。 ### 查看结果 ```bash lsings/ # 分析结果 lsexports/ # 提取的工件/ # 取证报告 ``` --- ## 教程 2 — 主机上的 Claude Code 如果您已经在本地安装了 Claude Code。 ```bash make setup # 选择 "主机上的 Claude Code" make start ``` 在 DFIReballz 目录中打开 Claude Code。MCP 工具从 `.mcp.json` 自动发现。会话启动钩子（`.claude/hooks/session-start.sh`）自动验证 Docker 堆栈健康状况。 --- ## 教程 3 — Claude Desktop ```bash make setup # 选择 "Claude Desktop" make start bash scripts/install-claude-desktop.sh # 自动合并 MCP 配置 ``` 重启 Claude Desktop。MCP 工具出现在工具选择器中。 **手动配置？** 将 `.mcp.json` 合并到您的 Claude Desktop 配置 | 操作系统 | 配置路径 | |:--|:--| | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | | Linux | `~/.config/Claude/claude_desktop_config.json` | --- ## 教程 4 — ChatGPT ChatGPT 使用 HTTP/SSE，而非 stdio。mcpo 代理将 MCP 服务器桥接到 HTTP 端点。 ```bash make setup # 选择 "ChatGPT" -openwebui # 在 8812启动 mcpo 代理 ``` 将您的 mcpo 代理暴露给互联网（ChatGPT 需要访问它）： ```bash ngrok8812 # 选项 A cloudflared tunnel --url http://localhost:8812 # 选项 B ``` 在 **ChatGPT** →** → **连接器** → **开发者模式**，添加您的隧道 URL点： `/kali-forensics/`、`/osint/`、`/threat-intel/`、`/winforensics/`、-analysis/`、`/network-forensics/`、`/filesystem/`。 --- ## 教程 5 — MCPHost + Ollama Ollama 没有原生的 MCP 支持。[MCPHost](https://github.com/mark3labs/mcphost) 弥补了这一空白。 ```bash curl -fsSL https://ollama.ai/install.sh | sh go install github.com/mark3labs/mcphost@latest ollama pull qwen3:8b make setup # 选择 "MCPHost + Ollama" make start mcphost -m ollama/qwen3:8b --config ~/.mcphost.yml ``` | 模型 | RAM | 工具调用 | 备注 | |:--|:--|:--|:--| | `qwen3:8b` | 8 GB | 优秀 | **推荐** | | `qwen3:14b` | 16 GB | 优秀 | 推理更好 | | `llama3.1:8b` | 8 GB | 良好 | 广泛测试 | | `llama3.3:70b` | 48 GB+ | 优秀 | 质量最佳 | --- ## 教程 6 — Open WebUI + Ollama ```bash make setup make start-openwebui ``` 打开 **http://localhost:8080** → **管理员面板** → **设置** → **外部工具**。在 `http://mcpo:8000/<server-name>/` 注册每个服务器。 --- ## 调查技能 DFIReballz 包含 10 种 **Claude Code 技能** — 斜杠命令，启动结构化调查工作流。每种技能加载相应的调查模板，用您的输入替换 `[TARGET]`，并执行完整工作流。 ### 可用技能 | 技能 | 功能 | 示例 | |:--|:--|:--| | `/complete-investigation` | 跨所有服务器的完整 11 阶段调查 | `/complete-investigation /evidence/` | | `/full-investigation` | 6 阶段端到端取证调查 | `/full-investigation /evidence/case001/` | | `/malware-analysis` | 静态分析、YARA、Capa、VirusTotal | `/malware-analysis /evidence/sample.exe` | | `/ransomware-investigation` | 勒索软件分类、C2 检测、攻击链 | `/ransomware-investigation /evidence/encrypted-host/` | | `/phishing-investigation` | 电子邮件头、URL 分析、凭证检查 | `/phishing-investigation /evidence/phish.eml` | | `/network-forensics` | PCAP 分析、协议解剖、JA3 | `/network-forensics /evidence/capture.pcap` | | `/osint-person` | 用户名/电子邮件枚举、数字足迹 | `/osint-person suspect@example.com` | | `/osint-domain` | DNS、子域名、基础设施映射 | `/osint-domain suspicious-site.com` | | `/memory-forensics` | Volatility3 进程/网络/恶意软件分析 | `/memory-forensics /evidence/memdump.raw` | | `/incident-response` | 7 阶段 IR：分类到补救 | `/incident-response /evidence/compromised-host/` | ### 技能工作原理 技能位于 `.claude/skills/<name>/SKILL.md`。Claude Code 在项目目录中打开时自动发现它们。 ``` .claude/skills/ ├── complete-investigation/SKILL.md ├── full-investigation/SKILL.md ├── malware-analysis/SKILL.md ├── ransomware-investigation/SKILL.md ├── phishing-investigation/SKILL.md ├── network-forensics/SKILL.md ├── osint-person/SKILL.md ├── osint-domain/SKILL.md ├── memory-forensics/SKILL.md └── incident-response/SKILL.md ``` **技能 vs. 模板 vs. 剧本： | | 技能 | 模板 | 剧本 | |:--|:--|:--|:--| | **位置** | `.claude/skills/` | `dfireballz/prompts/templates/` | `playbooks/` | | **加载** | 由 Claude Code 自动 | 通过 MCP 或 CLI | 通过编排器 API | | **调用** | `/skill-name target` | `get_template(name, target)` | `POST /api/playbook/run` | | **用于** | Claude Code 用户 | 任何 MCP 客户端 | API 消费者 | | **UX** | 斜杠命令 | 函数调用 | REST API | 所有三种共享相同的调查工作流程 — 技能是 Claude Code 原生界面。 **Docker：** 技能被挂载到 `claude-code` 容器的 `/workspace/.claude/skills/`（只读），并作为后备编译到镜像中。 --- ## 提示如何在系统中流动 ``` 步骤 1 — 您输入提示（或 /技能） │ "/malware-analysis /evidence/sample.exe" │ ▼ 步骤 2 — AI 加载模板并选择工具 │ 技能加载恶意软件分析模板，AI 选择工具： · capa_analyze（二进制分析） → MITRE ATT&CK 映射 │ · yara_scan（kali-forensics） → 恶意软件签名匹配 │ · check_virustotal（报） → 哈希声誉查找 │ ▼ 3 — 工具在 Docker 中执行 │ docker exec -i dfireballz-binary-analysis-1 python3 -u /app/server.py 每个工具通过 stdio 返回结构化输出。 │ ▼ 步骤 4 — AI 关联和结构化结果 │ 时间线RE ATT&CK 技术C、严重性 │ 步骤 5 — AI取证报告 │ 执行证据分析、IoC 表、证据链 │ ▼ 6 — 主机输出 ./reports/ → HTML、PDF、Markdown ./output/ → 发现结果、日志、时间线 ``` --- ## 主机目录布局 ``` dfireballz/ ├── evidence/ — 在所有容器中只载 ├── cases/ 文件 — 容器可写 ├── reports/ 生成的取证报告 ├── results/ 会话 └── output/查输出（主机可见） ├── findings/ 分析结果和摘要 ├── screenshots/ 视觉证据捕获 ├── logs/ 活动和审计日志 ├── exports/ 提取的文件和对象 └── timelines/ 事件时间线重建 ``` > **为什么使用 `output/`？** 当 Claude Code 在容器中运行时，它创建的文件除非绑定挂载，否则在主机上不可见。`output/` 确保所有工件立即在主机上可访问。 --- ## MCP 服务器参考 | 服务器 | 工具 | 来源 | |:--|:--|:--| | **kali-forensics** | Volatility3, bulk_extractor, tshark, YARA, dc3dd, Sleuthkit, foremost, binwalk, exiftool | 自定义 | | **winforensics** | MFT, ShellBags, LNK, Registry, EVTX, Prefetch, browser history, Chainsaw | [x746b/winforensics-mcp](https://github.com/x746b/winforensics-mcp) | | **osint** | Maigret, Sherlock, Holehe, theHarvester, DNSTwist, subfinder, amass, h8mail | 自定义 | | **threat-intel** | VirusTotal, Shodan, AbuseIPDB, MalwareBazaar, ThreatFox, URLScan, NVD | 自定义 | | **binary-analysis** | Ghidra headless, Radare2, Capa, YARA, pefile, lief, entropy analysis | 适配自 [FuzzingLabs](https://github.com/FuzzingLabs/mcp-security-hub) | | **network-forensics** | 18 个 Wireshark/tshark 工具, tcpdump, PCAP 合并/分割/提取, JA3/JA3S, GeoIP | 适配自 [PreistlyPython](https://github.com/PreistlyPython/wireshark-mcp) | | **filesystem** | 有限文件访问（/cases, /evidence, /reports, /output）— 证据始终只读 | [@modelcontextprotocol/server-filesystem](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) | --- ## 调查手册 | 手册 | 描述 | |:--|:--| | `malware-analysis` | 恶意软件样本的完整静态分析 | | `ransomware-investigation` | 勒索软件工件分析和 C2 检测 | | `phishing-investigation` | 钓鱼邮件和基础设施调查 | | `network-forensics` | PCAP 分析与威胁检测 | | `osint-person-investigation` | 通过用户名/邮箱跟踪的人员调查 | | `osint-domain-investigation` | 域名/网站侦察 | | `dark-web-trace` | 黑网 IOC 跟踪和关联 | | `mobile-artifact-analysis` | 移动设备取证 | | `chain-of-custody` | 证据处理文档模板 | --- ## API 密钥 密钥在 `make setup` 期间输入并存储在 `.env` 中。 **后续添加或更改密钥：** ```bash make setup-keys # 交互式向导 — 显示状态，保存密钥，重启容器，验证 ``` 此操作处理所有操作：提示输入每个密钥，更新 `.env`，重启威胁情报容器，并验证连接性。 | 服务 | 使用方 | 获取密钥 | |:--|:--|:--| | **VirusTotal** | threat-intel | [virustotal.com/gui/my-apikey](https://www.virustotal.com/gui/my-apikey) | | **Shodan** | threat-intel | [account.shodan.io](https://account.shodan.io/) | | **AbuseIPDB** | threat-intel | [abuseipdb.com/account/api](https://www.abuseipdb.com/account/api) | | **URLScan.io** | threat-intel | [urlscan.io/user/signup](https://urlscan.io/user/signup) | | **VulnCheck** | threat-intel | [vulncheck.com](https://vulncheck.com/) | | **Anthropic** | claude-code 容器 | [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys) | > Anthropic 密钥仅在 `make claude-code` 时需要。主机安装的 Claude Code 和 Claude Desktop 自己处理身份验证。 --- ## Makefile 快捷方式 ### 设置与运行 ```bash make setup # 交互式首次运行向导 make setup-keys # 添加/更新威胁情报 API 密钥（带验证） make start # 启动所有服务（10 个容器） make stop # 停止所有服务 make restart # 重启所有服务 make claude-code # 在 Docker 中启动 Claude Code make start-openwebui # 启动 Open WebUI + Ollama make dev # 开发模式（热重载） ``` ### 状态与监控 ```bash make status # 容器健康状态 make health # MCP 服务器健康检查 make logs # 尾随所有日志 make log-<service> # kali, osint, netforensics, winforensics, # binary, threat, filesystem, orchestrator, db, redis ``` ### 测试与质量 ```bash make test # 运行所有测试 make test-smoke # 容器烟雾测试 make test-security # Trivy + Bandit 安全扫描 make lint # Ruff 静态代码分析 make format # 自动格式化 make typecheck # mypy 类型检查 ``` ### 实用工具 ```bash make configure-mcp # 重新生成 MCP 配置 make report # 从上一次会话生成报告 make shell-<service> # 调试 shell 进入任意容器 make clean # 删除容器 + 本地镜像 make nuke # 删除所有内容（容器，卷，镜像） ``` --- ## 证据链 每次证据交互都记录在不可变的 `chain_of_custody_log` 表中： | 操作 | 何时 | |:--|:--| | **获取** | 证据上传，计算哈希值 | | **访问** | 证据文件被任何工具读取 | | **分析** | MCP 工具调用证据 | | **导出** | 报告生成或证据转移 | 数据库触发器防止对证据链记录进行 `UPDATE` 和 `DELETE`，确保取证完整性。 --- ## 高级 FAQ 与教程 ### 如何创建自定义调查技能？ 在 `.claude/skills/` 中创建一个新目录，并包含一个 `SKILL.md` 文件： ```bash mkdir .claude/skills/my-investigation ``` 编写 `.claude/skills/my-investigation/SKILL.md`： ```markdown --- name: my-investigation description: 此技能执行的操作的简要描述 — Claude 使用此描述自动调用。 --- 当调用此技能时，Claude 的操作指令。 **用法：** `/my-investigation <目标>` ## 指令 1. Claude 应该首先执行的操作 2. 要使用的 MCP 服务器 3. 要生成的输出 ``` Claude Code 在下一次会话中自动发现它。无需更改配置。 ### 技能与 CLAUDE.md 有何不同？ **CLAUDE.md** = 被动规则。始终加载，始终强制执行。"如何行为。" **技能** = 主动工作流。按需通过 `/slash-command` 调用。"执行操作。" **子目录 CLAUDE.md** = 有范围的规则。仅在 Claude 处理该目录中的文件时加载。 本仓库同时使用这三种： - 根目录 `CLAUDE.md` — 全局取证规则（证据链，`shell=False` 等） - `mcp-servers/CLAUDE.md` — 编辑 MCP 服务器代码的规则 - `dfireballz/models/CLAUDE.md` — 编辑数据模型的规则 - `.claude/skills/` — 10 个调查工作流 ### 如何在 Docker 容器中运行技能？ 技能被映射到 claude-code 容器中。只需像平常一样使用它们： ```bash make claude-code # 在容器内： /malware-analysis /evidence/sample.exe ``` ### 可以同时使用技能和 MCP 模板吗？ 是的。技能是 Claude Code 接口。模板是 MCP 接口。它们共享相同的底层 Markdown 文件。根据您的客户端使用适合的： - **Claude Code** （主机或 Docker）：`/malware-analysis /evidence/sample.exe` - **Claude Desktop**：调用 `get_template(name="malware-analysis", target="/evidence/sample.exe")` - **ChatGPT**：通过 mcpo 代理调用相同的 MCP 函数 - **CLI**：`dfireballz templates show malware-analysis --target /evidence/sample.exe` ### 子目录 CLAUDE.md 文件如何工作？ Claude Code 在读取或编辑目录中的文件时加载该目录的 `CLAUDE.md`。本仓库中有 scoped 规则位于： ``` mcp-servers/CLAUDE.md — shell=False, Pydantic 验证，stdio 传输 dfireballz/models/CLAUDE.md — ForensicPayload 合同，向后兼容性 dfireballz/backends/CLAUDE.md — _TOOL_COMMANDS 映射，Docker 执行模式 dfireballz/reporting/CLAUDE.md — 报告格式要求，输出路径 ``` 这些规则使 Claude 关注特定目录的约束，避免膨胀根目录 CLAUDE.md。 ### 如何添加新的 MCP 服务器？ 1. 使用 `Dockerfile` + `server.py` 创建 `mcp-servers/new-server/` 2. 在 `docker-compose.yml` 中注册 3. 运行 `make configure-mcp` 更新 `.mcp.json` 4. 将工具添加到 `dfireballz/backends/docker.py` `_TOOL_COMMANDS` 映射 5. 添加到 `dfireballz/data/tools_catalog.json` 6. 可选地在 `.claude/skills/` 中创建技能 7. 添加测试 ### 没有技能如何调查？ 只需用自然语言描述您想要的操作： ``` 分析位于 /evidence/memdump.raw 的内存转储，寻找进程注入的迹象。 将任何可疑的哈希值与 VirusTotal 进行比对。 ``` Claude Code 会自动选择合适的 MCP 工具。技能是便捷的快捷方式，而不是必需品。 ### 如何查看所有可用的 MCP 工具？ ```bash dfireballz catalog # CLI：列出 90 多个工具 # 或在 Claude Code 中： /mcp # 检查 MCP 服务器状态和工具 ``` ### 如何导出调查结果？ 所有输出都在主机上绑定到目录中： ```bash ls reports/ # 取证报告（HTML，PDF，MD） ls output/findings/ # 分析摘要 ls output/exports/ # 提取的文件，提取的对象 ls output/timelines/ # 事件时间线 ls results/ # 原始 ForensicPayload JSON ``` --- ## 故障排除 ### 容器无法启动 ```bash make health # MCP 服务器健康检查 make status # 容器状态表 make restart-kali # 重启特定服务 ``` ### MCP 工具未出现在 Claude Code 中 1. `make health` — 确保所有容器都健康 2. `make configure-mcp` — 重新生成 MCP 配置 3. 重启 Claude Code ### Claude Code 容器问题 ```bash grep ANTHROPIC_API_KEY .env # 验证密钥是否设置 docker compose --profile claude-code logs claude-code # 检查日志 ``` ### SessionStart 钩子报告问题 ```bash bash .claude/mcp-health-check.sh # 完整诊断 bash .claude/mcp-health-check.sh --fix # 自动启动停止的容器 ``` ### MCP 服务器在 /mcp 中“失败” 1. 检查 Docker GID：`getent group docker | cut -d: -f3` 必须与 `.env` 中的 `DOCKER_GID` 匹配 2. `make restart` — 获取卷挂载的代码更改 3. `claude --debug` — 显示 MCP 连接错误 4. `make build && make restart` — 最后的手段：重建镜像 --- ## 项目结构 ``` dfireballz/ ├── .claude/ │ ├── settings.json Claude Code 钩子配置 │ ├── hooks/session-start.sh 自动验证 Docker 堆栈健康状况 │ ├── mcp-health-check.sh MCP 服务器健康检查器 │ └── skills/ 调查技能（10 个斜杠命令） │ ├── malware-analysis/SKILL.md │ ├── network-forensics/SKILL.md │ ├── osint-person/SKILL.md │ └── ... │ ├── mcp-servers/ │ ├── kali-forensics/ Volatility3, YARA, Sleuthkit │ ├── winforensics/ MFT, EVTX, Registry, Chainsaw │ ├── osint/ Maigret, Sherlock, theHarvester │ ├── threat-intel/ VirusTotal, Shodan, AbuseIPDB │ ├── binary-analysis/ Ghidra, Radare2, Capa │ ├── network-forensics/ tshark (18 个工具), tcpdump │ └── filesystem/ 有限文件访问 │ ├── dfireballz/ Python 包（CLI，MCP 服务器，报告） │ ├── backends/ 工具执行（Docker 执行） │ ├── models/ Pydantic 数据模型（ForensicPayload） │ ├── mcp/ MCP 服务器实现 │ ├── prompts/templates/ 调查模板（10 个） │ └── reporting/ HTML，PDF，Markdown 报告生成器 │ ├── orchestrator/ FastAPI 后端（案件，证据，工作流） ├── database/ PostgreSQL 初始化（pgcrypto，证据链） ├── docker/ Claude Code Dockerfile + 入口点 ├── playbooks/ 调查工作流定义（9 个） ├── scripts/ 设置向导，MCP 配置生成器 │ ├── evidence/ 证据文件（只读挂载） ├── cases/ 工作案例文件 ├── reports/ 生成的报告 ├── output/ 主机可见的调查输出 │ ├── docker-compose.yml 所有服务 ├── Makefile 50+ make 目标 ├── CLAUDE.md AI 指令（全局规则） └── .mcp.json 主机 Claude Code 的 MCP 配置 ``` --- ## 安全说明 | 关注点 | 处理方式 | |:--|:--| | **Docker 套接字** | 只读挂载。永远不要公开暴露 `8800` 端口。 | | **证据完整性** | MCP 容器中的只读卷。数据库级别的证据链。 | | **无 `shell=True`** | 所有子进程调用都使用 `subprocess.run(args_list, shell=False)`。 | | **API 密钥加密** | 通过 PostgreSQL pgcrypto 存储。 | | **非 root 容器** | 所有容器都运行 `no-new-privileges`（除了 network-forensics — 需要数据包捕获能力）。 | | **网络隔离** | 内部 `dfireballz-net` 桥。只有 orchestrator 暴露一个端口。 | --- ## CI/CD 流水线 | 工作流 | 触发器 | 操作 | |:--|:--|:--| | **CI** | 推送/拉取请求到 main | 静态代码分析，测试，pip-audit 依赖扫描 | | **Docker 构建与推送** | main 上的 CI 通过，版本标签 (`v*`)，手动 | 构建 + 推送所有镜像，Docker Scout CVE 扫描 | | **CodeQL** | 推送/拉取请求到 main + 每周 | 静态安全分析 | --- ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 --- ## 许可证 [MIT](LICENSE)