valITino/dfireballz

``` ╔═════════════════════════════════════════════════════════════════════════════════╗ ║ ║ ║ ██████╗ ███████╗██╗██████╗ ███████╗██████╗ █████╗ ██╗ ██╗ ███████╗ ║ ║ ██╔══██╗██╔════╝██║██╔══██╗ ██╔════╝██╔══██╗██╔══██╗██║ ██║ ╚══███╔╝ ║ ║ ██║ ██║█████╗ ██║██████╔╝ █████╗ ██████╔╝███████║██║ ██║ ███╔╝ ║ ║ ██║ ██║██╔══╝ ██║██╔══██╗ ██╔══╝ ██╔══██╗██╔══██║██║ ██║ ███╔╝ ║ ║ ██████╔╝██║ ██║██║ ██║ ███████╗██████╔╝██║ ██║███████╗███████╗███████╗ ║ ║ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚══════╝╚═════╝ ╚═╝ ╚═╝╚══════╝╚══════╝╚══════╝ ║ ║ ║ ╠═════════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Digital Forensics & Cybercrime Investigation Platform ║ ║ Chain of Custody · Artifact Analysis · MCP-Powered ║ ║ ║ ╠═════════════════════════════════════════════════════════════════════════════════╣ ║ by valITino · Docker · Python · FastMCP · Ollama ║ ║ ║ ╚═════════════════════════════════════════════════════════════════════════════════╝ ```
[](https://www.python.org/downloads/) [](LICENSE) [](https://www.docker.com/) [](https://modelcontextprotocol.io) **基于 MCP 的 AI 原生取证调查框架 —— 一切均在 Docker 中运行。** ## 目录 **概述** - [工作原理](#how-it-works) - [架构](#architecture) - [组件](#components) **入门指南** - [前置条件](#prerequisites) - [快速开始](#quick-start) **设置指南** - [教程 1 — Docker 中的 Claude Code（推荐）](#tutorial-1--claude-code-in-docker--recommended) - [教程 2 — 主机上的 Claude Code](#tutorial-2--claude-code-on-host) - [教程 3 — Claude Desktop](#tutorial-3--claude-desktop) - [教程 4 — ChatGPT](#tutorial-4--chatgpt) - [教程 5 — MCPHost + Ollama](#tutorial-5--mcphost--ollama) - [教程 6 — Open WebUI + Ollama](#tutorial-6--open-webui--ollama) **参考** - [Prompt 在系统中的流转方式](#how-prompts-flow-through-the-system) - [主机目录布局](#host-directory-layout) - [MCP 服务器参考](#mcp-servers-reference) - [调查 Playbook](#investigation-playbooks) - [API Keys 设置](#api-keys-setup) - [Makefile 快捷方式](#makefile-shortcuts) - [证据链](#chain-of-custody) - [项目结构](#project-structure) **运维** - [故障排除](#troubleshooting) - [CI/CD 流水线](#cicd-pipeline) - [安全说明](#security-notes) - [贡献](#contributing) - [许可证](#license) ## 工作原理 您的 AI 客户端（Claude Code、Claude Desktop、ChatGPT 或 MCPHost+Ollama）**是编排器**： 1. **您输入一个 prompt** — 例如：“分析位于 /evidence/sample.exe 的恶意软件样本” 2. **AI 从 7 个 MCP 服务器中选择工具**（Kali 取证、Windows 取证、OSINT、threat-intel、二进制分析、网络取证、文件系统） 3. **每个 MCP 服务器执行** 均通过 `docker exec -i`（stdio 传输）在其 Docker 容器内进行并返回结果 4. **AI 关联发现** — 时间线、MITRE ATT&CK 映射、IoC 提取 5. **AI 撰写取证报告** 并始终保持证据链完整 一切均在 Docker 中运行。您的主机上无需安装取证工具。所有发现均存放在 `./output/` 中。 ## 架构 ``` ┌──────────────────────────────────────────────────────────────┐ │ AI Host (Choose One) │ │ Claude Code │ Claude Desktop │ ChatGPT │ MCPHost/WebUI│ └──────┬────────┴────────┬─────────┴─────┬─────┴────────┬──────┘ │ docker exec -i │ │ HTTP/SSE │ ▼ ▼ ▼ ▼ ┌──────────────────────────────────────────────────────────────┐ │ MCP Servers (stdio) │ │ │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │ │ kali-forensics │ │ winforensics │ │ osint │ │ │ │ Volatility3 │ │ MFT, Registry │ │ Maigret │ │ │ │ YARA, tshark │ │ EVTX, Prefetch │ │ Sherlock │ │ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │ │ threat-intel │ │binary-analysis │ │network-forensic│ │ │ │ VT, Shodan │ │ Ghidra, r2 │ │ 18 tshark tools│ │ │ │ AbuseIPDB │ │ Capa, YARA │ │ tcpdump, PCAP │ │ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │ ┌────────────────┐ │ │ │ filesystem │ All containers on dfireballz-net │ │ │ /cases /evidence│ Evidence volumes: READ-ONLY │ │ └────────────────┘ │ └──────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ Infrastructure │ │ ┌──────────────┐ ┌───────────┐ ┌───────────┐ │ │ │ Orchestrator │ │ PostgreSQL│ │ Redis │ │ │ │ FastAPI │ │ pgcrypto │ │ Cache │ │ │ │ :8800 │ │ :5432 │ │ :6379 │ │ │ └──────────────┘ └───────────┘ └───────────┘ │ └──────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ Host Machine (your computer) │ │ │ │ ./evidence/ — Evidence files (read-only in containers) │ │ ./cases/ — Working case files │ │ ./reports/ — Generated forensic reports │ │ ./output/ — Investigation findings, logs, exports │ │ ├── findings/ — Analysis results & summaries │ │ ├── screenshots/ — Visual evidence captures │ │ ├── logs/ — Activity & audit logs │ │ ├── exports/ — Carved files & extracted objects │ │ └── timelines/ — Event timeline reconstructions │ └──────────────────────────────────────────────────────────────┘ ``` ## 组件 | 容器 | 功能 | 端口 | 配置 | |:--|:--|:--:|:--:| | **kali-forensics** | Volatility3, bulk_extractor, YARA, dc3dd, Sleuthkit, foremost, exiftool | — | default | | **winforensics** | MFT, ShellBags, LNK, Registry, EVTX, Prefetch, Chainsaw | — | default | | **osint** | Maigret, Sherlock, Holehe, theHarvester, DNSTwist, subfinder | — | default | | **threat-intel** | VirusTotal, Shodan, AbuseIPDB, MalwareBazaar, ThreatFox, URLScan, IOC enrichment | — | default | | **binary-analysis** | Ghidra headless, Radare2, Capa (MITRE ATT&CK), YARA, pefile, binwalk | — | default | | **network-forensics** | 18 种 Wireshark/tshark 工具, tcpdump, PCAP merge/split/carve, JA3/JA3S | — | default | | **filesystem** | 作用域文件访问 /cases, /evidence (只读), /reports | — | default | | **orchestrator** | FastAPI 后端 — 案例、证据、playbook、证据链 | `8800` | default | | **db** | PostgreSQL with pgcrypto (加密 API key 存储) | — | default | | **redis** | Redis 缓存 | — | default | | **claude-code** | Docker 中的 Anthropic CLI 客户端 (无需主机安装) | — | `claude-code` | | **ollama** | 本地 LLM 推理 (Open WebUI 场景) | `11434` | `openwebui` | | **open-webui** | Ollama 模型的 Web UI | `8080` | `openwebui` | | **mcpo** | 用于 Open WebUI / ChatGPT 的 MCP-to-OpenAPI 桥接 | `8812` | `openwebui` | ## 前置条件 | 需求 | 详情 | |:--|:--| | **Docker** | 25+ 以及 Docker Compose v2 | | **RAM** | 推荐 16 GB（最低 8 GB —— 功能受限） | | **Disk** | 推荐 50 GB+（Docker 镜像较大） | | **Docker GID** | orchestrator 和 Claude Code 容器需要 `/var/run/docker.sock`。验证您的 Docker group ID 与 `.env` 中的 `DOCKER_GID` 匹配（默认 `999`）。检查命令：`getent group docker \| cut -d: -f3` | | **GPU** *(可选)* | NVIDIA GPU + [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) 用于 GPU 加速的 Ollama | ### 必需账户（提供免费层级） 威胁情报工具需要 API keys。**在运行设置之前创建账户**，以便准备好您的密钥： | 服务 | 功能 | 免费层级 | 注册 | |:--|:--|:--|:--| | **VirusTotal** | 文件/哈希/URL 信誉查询 | 4 次/分钟 | [virustotal.com/gui/my-apikey](https://www.virustotal.com/gui/my-apikey) | | **Shodan** | 互联网连接设备搜索 | 查询受限 | [account.shodan.io](https://account.shodan.io/) | | **AbuseIPDB** | IP 地址信誉检查 | 1,000 次/天 | [abuseipdb.com/account/api](https://www.abuseipdb.com/account/api) | | **URLScan.io** | URL 扫描和分析 | 50 次扫描/天 | [urlscan.io/user/signup](https://urlscan.io/user/signup) | | **VulnCheck** | 漏洞情报 | 免费层级 | [vulncheck.com](https://vulncheck.com/) | ``` # 验证前提条件 bash scripts/check-requirements.sh ``` ## 快速开始 所有镜像均已预构建并发布在 [Docker Hub](https://hub.docker.com/r/crhacky/dfireballz) 上。**无需本地构建。** ``` # 1. Clone the repo git clone https://github.com/valITino/dfireballz.git cd dfireballz # 2. 运行交互式设置（生成 .env，pulls images，配置 MCP —— 一站式完成） make setup # 3. 启动所有服务（10 个 containers） make start ``` 就这样。设置向导将： 1. 检查前置条件（Docker、Compose、RAM、磁盘） 2. 生成带有安全随机密钥的 `.env` 3. 要求您选择 AI 主机（Claude Code、Claude Desktop、ChatGPT、MCPHost 或 Open WebUI） 4. 收集您的 API keys（VirusTotal、Shodan、AbuseIPDB、URLScan.io） 5. 处理您所选主机的身份验证设置 6. 从 Docker Hub 拉取所有预构建的 Docker 镜像 7. 为您所选主机自动生成 MCP 配置 8. 创建用于主机可见发现的 `output/` 目录结构 ### 验证 ``` make status # Container status table make health # MCP server health check ``` 您应该看到 **10 个容器** 正在运行： - 7 个 MCP 服务器 —— kali-forensics, winforensics, osint, threat-intel, binary-analysis, network-forensics, filesystem - 3 个基础设施 —— orchestrator, db, redis Orchestrator API: **http://localhost:8800** ## 教程 1 — Docker 中的 Claude Code（推荐） 完全在 Docker 内运行 Claude Code —— 无需本地 Node.js 或 Claude Code 安装。该容器直接通过内部 Docker 网络连接到所有 MCP 服务器。 ### 第 1 步：启动 Stack ``` make setup # Select "Claude Code in Docker" when prompted make start ``` ### 第 2 步：启动 Claude Code ``` make claude-code ``` 入口点脚本检查每个 MCP 服务器（两层：运行中 + 响应），并在启动 CLI 之前显示状态。 ### 第 3 步：运行您的第一次调查 ``` Analyze the malware sample at /evidence/sample.exe — run static analysis, extract strings, check YARA rules, and look up the hash on VirusTotal. ``` Claude Code 将自主地： 1. 调用 binary-analysis 工具（Ghidra, Radare2, Capa, YARA） 2. 使用 kali-forensics 提取元数据（exiftool, strings, binwalk） 3. 通过 threat-intel 查找哈希（VirusTotal, MalwareBazaar） 4. 关联发现并映射到 MITRE ATT&CK 技术 5. 撰写包含完整证据链的取证报告 ### 第 4 步：在您的主机上查看结果 ``` ls output/findings/ # Analysis results ls output/exports/ # Extracted artifacts ls reports/ # Forensic reports ``` ### 监控（单独的终端） ``` make log-kali # Kali forensics activity make log-binary # Binary analysis activity make log-threat # Threat-intel lookups make log-orchestrator # Orchestrator API activity ``` ## 教程 2 — 主机上的 Claude Code 如果您已经在主机上安装了 Claude Code。 ### 第 1 步：启动 Stack ``` make setup # Select "Claude Code on host" when prompted make start # Also regenerates .mcp.json ``` ### 第 2 步：打开 Claude Code 在 DFIReballz 目录中打开 Claude Code。所有 MCP 工具均从 `.mcp.json`（在设置期间自动生成）自动发现。SessionStart hook（`.claude/hooks/session-start.sh`）自动验证 Docker stack 健康状况。 ### 第 3 步：调查 ``` Analyze the malware sample at /evidence/sample.exe — run static analysis, extract strings, check YARA rules, and look up the hash on VirusTotal. ``` ## 教程 3 — Claude Desktop ### 第 1 步：启动 Stack ``` make setup # Select "Claude Desktop" when prompted make start ``` ### 第 2 步：配置 Claude Desktop **选项 A —— 自动（推荐）：** ``` bash scripts/install-claude-desktop.sh ``` 这会将 DFIReballz MCP 配置自动合并到 Claude Desktop 的配置文件中（首先创建备份）。 **选项 B —— 手动：** 将 `.mcp.json` 的内容合并到 Claude Desktop 的配置文件中： | OS | 配置路径 | |:--|:--| | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | | Linux | `~/.config/Claude/claude_desktop_config.json` | ### 第 3 步：重启 Claude Desktop 重启应用程序。MCP 工具应出现在工具选择器中。 ## 教程 4 — ChatGPT ### 第 1 步：使用 OpenWebUI 配置文件启动 ``` make setup # Select "ChatGPT" when prompted make start-openwebui # Starts mcpo proxy on port 8812 ``` ### 第 2 步：使您的机器可被访问 ChatGPT 需要通过互联网访问您的 mcpo 代理： ``` # 选项 A：ngrok tunnel（最简单） ngrok http 8812 # 选项 B：cloudflared tunnel cloudflared tunnel --url http://localhost:8812 ``` ### 第 3 步：配置 ChatGPT 1. 转到 **ChatGPT** → **Settings** → **Connectors** → **Advanced** → **Developer Mode** 2. 使用您的公共 URL（来自 ngrok/cloudflared）添加新的 MCP 服务器 3. 每个服务器位于 `https://YOUR_TUNNEL_URL//` ### 可用端点 | 端点 | 服务器 | |:--|:--| | `/kali-forensics/` | Kali 取证工具 | | `/osint/` | OSINT 工具 | | `/threat-intel/` | 威胁情报 | | `/winforensics/` | Windows 取证 | | `/binary-analysis/` | 二进制分析 | | `/network-forensics/` | 网络取证 | | `/filesystem/` | 文件访问 | ## 教程 5 — MCPHost + Ollama ### 第 1 步：安装 Ollama 和 MCPHost ``` curl -fsSL https://ollama.ai/install.sh | sh go install github.com/mark3labs/mcphost@latest ``` ### 第 2 步：拉取支持工具调用的模型 ``` ollama pull qwen3:8b ``` ### 第 3 步：启动 DFIReballz ``` make setup # Select "MCPHost + Ollama" when prompted make start ``` ### 第 4 步：启动 MCPHost ``` mcphost -m ollama/qwen3:8b --config ~/.mcphost.yml ``` ### 模型选择指南 | 模型 | RAM | GPU VRAM | 工具调用 | 备注 | |:--|:--|:--|:--|:--| | `qwen3:8b` | 8 GB | 6 GB | 优秀 | **推荐默认** | | `qwen3:14b` | 16 GB | 12 GB | 优秀 | 推理能力更强 | | `qwen2.5:14b` | 16 GB | 12 GB | 优秀 | 擅长分析 | | `llama3.1:8b` | 8 GB | 8 GB | 良好 | 广泛测试 | | `llama3.3:70b` | 48 GB+ | 40 GB+ | 优秀 最佳质量，需高端硬件 | | `llama3.2:3b` | 4 GB | 4 GB | 有限 | 最低硬件要求 | 验证工具调用：`ollama show | grep capabilities` ## 教程 6 — Open WebUI + Ollama ### 第 1 步：启动所有服务 ``` make setup make start-openwebui ``` ### 第 2 步：配置 1. 打开 **http://localhost:8080** 2. 转到 **Admin Panel** → **Settings** → **External Tools** 3. 注册每个 MCP 服务器： | URL | 服务器 | |:--|:--| | `http://mcpo:8000/kali-forensics/` | Kali 取证 | | `http://mcpo:8000/osint/` | OSINT | | `http://mcpo:8000/threat-intel/` | 威胁情报 | | `http://mcpo:8000/winforensics/` | Windows 取证 | | `http://mcpo:8000/binary-analysis/` | 二进制分析 | | `http://mcpo:8000/network-forensics/` | 网络取证 | | `http://mcpo:8000/filesystem/` | 文件系统 | ### 第 3 步：调查 选择您的 Ollama 模型并开始聊天。mcpo 代理将 MCP 服务器桥接为 OpenAPI 端点。 ## Prompt 在系统中的流转方式 ``` STEP 1 ─ YOU TYPE A PROMPT │ "Analyze the memory dump at /evidence/memdump.raw for signs of injection" │ ▼ STEP 2 ─ AI DECIDES WHICH TOOLS TO USE │ The AI picks tools from the 7 MCP servers: │ · volatility3_analyze (kali-forensics) → process listing, DLL injection scan │ · yara_scan (kali-forensics) → match against malware signatures │ · check_virustotal (threat-intel) → hash lookup for suspicious processes │ · read_file (filesystem) → access evidence (chain of custody logged) │ ▼ STEP 3 ─ TOOLS EXECUTE IN DOCKER CONTAINERS │ AI host runs: │ docker exec -i dfireballz-kali-forensics-1 python3 -u /app/server.py │ Each tool runs inside its container and returns structured output via stdio. │ ▼ STEP 4 ─ AI STRUCTURES THE RESULTS │ The AI correlates findings across tools: │ · Timeline reconstruction │ · MITRE ATT&CK technique mapping │ · IoC extraction (hashes, IPs, domains) │ · Severity classification │ ▼ STEP 5 ─ AI WRITES THE FORENSIC REPORT │ Executive summary, evidence analysis, IoC table, timeline, │ MITRE ATT&CK mapping, remediation, chain of custody log. │ ▼ STEP 6 ─ OUTPUT AVAILABLE ON HOST ./reports/ → HTML, PDF, Markdown forensic reports ./results/ → Session JSON, structured forensic data ./output/ → Findings, screenshots, logs, exports, timelines ``` ## 主机目录布局 所有数据目录均在您的主机和容器之间绑定挂载： ``` dfireballz/ │ ├── evidence/ Evidence files — mounted READ-ONLY in all containers │ Place your disk images, memory dumps, PCAPs, etc. here. │ ├── cases/ Working case files — writable by containers │ Tool output, intermediate results, case metadata. │ ├── reports/ Generated forensic reports — writable by containers │ HTML, PDF, Markdown reports organized by date. │ ├── results/ Session data — writable by Claude Code container │ ForensicPayload JSON, session state. │ └── output/ Investigation output — visible on your host machine ├── findings/ Analysis results, summaries, IOC lists ├── screenshots/ Captured screenshots and visual evidence ├── logs/ Investigation activity and audit logs ├── exports/ Carved files, extracted objects, filtered PCAPs └── timelines/ Reconstructed event timelines ``` ## MCP 服务器参考 | 服务器 | 工具 | 来源 | |:--|:--|:--| | **kali-forensics** | Volatility3, bulk_extractor, tshark, YARA, dc3dd, Sleuthkit, foremost, binwalk, exiftool | Custom | | **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 | Custom | | **threat-intel** | VirusTotal, Shodan, AbuseIPDB, MalwareBazaar, ThreatFox, URLScan, NVD, IOC enrichment | Custom | | **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 merge/split/carve, JA3/JA3S, GeoIP | 改编自 [PreistlyPython](https://github.com/PreistlyPython/wireshark-mcp) | | **filesystem** | 作用域文件访问 (/cases, /evidence, /reports) —— 证据始终只读 | [@modelcontextprotocol/server-filesystem](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) | ## 调查 Playbook | Playbook | 描述 | |:--|:--| | `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 Keys 设置 API keys 在 `make setup` 期间输入并存储在 `.env` 中。它们作为环境变量注入到 MCP 服务器容器中。您可以随时直接编辑 `.env` —— 无需重新运行设置。 | 服务 | 使用方 | 免费层级 | 获取 Key | |:--|:--|:--|:--| | **VirusTotal** | threat-intel | 4 次/分钟 | [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 | 1,000 次/天 | [abuseipdb.com/account/api](https://www.abuseipdb.com/account/api) | | **URLScan.io** | threat-intel | 50 次扫描/天 | [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) | ## 故障排除 ### 容器未启动或不健康 ``` make health # Quick health check of all MCP servers make status # Container status table docker compose logs # Full logs ``` 如果服务显示不健康，请重启它： ``` make restart-kali # Restart Kali forensics docker compose restart osint # Or use docker compose directly ``` ### MCP 工具未出现在 Claude Code 中 1. 确保所有容器健康：`make health` 2. 重新生成 MCP 配置：`make configure-mcp` 3. 重启 Claude Code ### Claude Code 容器无法启动 ``` # 检查 ANTHROPIC_API_KEY 是否已设置 grep ANTHROPIC_API_KEY .env # 检查依赖服务是否健康 make health # 检查 container logs docker compose --profile claude-code logs claude-code ``` ### 证据无法访问 证据在容器内以只读方式挂载在 `/evidence`。确保主机上存在文件： ``` ls -la ./evidence/ ``` ### 输出未出现在主机上 检查 `output/` 目录是否存在并具有正确的权限： ``` ls -la ./output/ # 如果缺失，重新创建： mkdir -p output/{findings,screenshots,logs,exports,timelines} ``` ### 容器不断重启 检查其日志以查找特定错误： ``` docker compose logs # e.g. kali-forensics, orchestrator ``` 常见原因： - 内存不足（推荐 16 GB） - 主机上的端口冲突（`8800`） - 缺失或无效的 `.env` 配置 ### MCP 服务器在 Claude Code `/mcp` 中显示“failed” 如果 `make health` 显示所有容器健康，但 Claude Code 的 `/mcp` 显示服务器失败： 1. **检查 Docker GID** — 运行 `getent group docker | cut -d: -f3` 并确保它与 `.env` 中的 `DOCKER_GID` 匹配（默认 `999`） 2. **重启容器** — `make restart` 会获取卷挂载的 `server.py` 更改和环境变量 3. **使用 debug 运行** — `claude --debug` 显示实际的 MCP 连接错误日志 4. **重建镜像**（最后手段）— `make build && make restart` 使用固定的 `fastmcp<3` 重建 ### SessionStart hook 报告问题 当 Claude Code 打开项目时，`.claude/hooks/session-start.sh` hook 会自动运行： ``` bash .claude/mcp-health-check.sh # Full diagnostic output bash .claude/mcp-health-check.sh --quiet # Summary only bash .claude/mcp-health-check.sh --fix # Auto-start stopped containers ``` ## Makefile 快捷方式 ### 设置 ``` make setup # Interactive first-run setup wizard make pull # Pull pre-built images from Docker Hub make build # Build images locally (only if you modified Dockerfiles) ``` ### 运行 ``` make start # Start all services (10 containers) make stop # Stop all services make restart # Restart all services make claude-code # Launch Claude Code in Docker (interactive) make start-openwebui # Start with Open WebUI + Ollama (also for ChatGPT) make dev # Start in dev mode (hot reload) ``` ### 状态与监控 ``` make status # Container health status make health # MCP server health check make logs # Tail all logs make logs s= # Tail specific service logs make log- # Tail logs: kali, osint, netforensics, winforensics, # binary, threat, filesystem, orchestrator, db, redis ``` ### 单服务重启 ``` make restart- # Restart a specific service ``` ### 调试容器 ``` make shell-kali # Shell into Kali forensics make shell-osint # Shell into OSINT make shell-netforensics # Shell into network forensics make shell-winforensics # Shell into Windows forensics make shell-binary # Shell into binary analysis make shell-threat # Shell into threat-intel make shell-filesystem # Shell into filesystem make shell-orchestrator # Shell into orchestrator ``` ### 测试与安全 ``` make test # Run all tests make test-smoke # Container smoke tests make test-security # Trivy + Bandit security scan make lint # Run ruff linter make format # Auto-format code make typecheck # Run mypy type checking ``` ### 实用工具 ``` make configure-mcp # Generate MCP config for chosen host make report # Generate report from last session make case-new # Create a new case (interactive) make playbook-list # List available playbooks make check-gpu # Check NVIDIA GPU availability make clean # Remove containers and local images make nuke # Remove EVERYTHING (containers, volumes, images) ``` ## 证据链 每次证据交互都记录在不可变的 `chain_of_custody_log` 表中： | 操作 | 时间 | |:--|:--| | **Acquired** | 证据上传，计算哈希 | | **Accessed** | 任何工具读取证据文件 | | **Analyzed** | 对证据调用 MCP 工具 | | **Exported** | 报告生成或证据传输 | | **Transferred** | 证据在系统间移动 | 数据库触发器阻止对证据链记录的 `UPDATE` 和 `DELETE`，确保证证完整性。每次证据访问**必须**创建一条日志记录。 ## 项目结构 ``` dfireballz/ ├── mcp-servers/ │ ├── kali-forensics/ Volatility3, YARA, Sleuthkit, etc. │ │ ├── Dockerfile │ │ └── server.py │ ├── winforensics/ MFT, EVTX, Registry, Chainsaw │ ├── osint/ Maigret, Sherlock, theHarvester │ ├── threat-intel/ VirusTotal, Shodan, AbuseIPDB │ ├── binary-analysis/ Ghidra, Radare2, Capa │ ├── network-forensics/ tshark (18 tools), tcpdump │ └── filesystem/ Scoped file access │ ├── orchestrator/ FastAPI backend (cases, evidence, playbooks) ├── database/ PostgreSQL init (pgcrypto, chain of custody) │ ├── docker/ │ ├── claude-code.Dockerfile Containerized Claude Code client │ ├── claude-code-entrypoint.sh │ └── mcp.json MCP config for containerized Claude Code │ ├── dfireballz/ Python package (CLI, MCP server, reports) │ ├── config/ │ └── .env.example Environment variable template │ ├── scripts/ │ ├── setup.sh Interactive setup wizard │ ├── configure_mcp.sh MCP config generator │ ├── install-claude-desktop.sh Auto-merge MCP config into Claude Desktop │ ├── check-requirements.sh Prerequisite checker │ └── smoke-test.sh Container smoke tests │ ├── playbooks/ Investigation playbook definitions │ ├── cases/ Case files (created at runtime) ├── evidence/ Evidence files (mounted read-only) ├── reports/ Generated reports (bind-mounted) ├── results/ Session data (bind-mounted) ├── output/ Investigation output (bind-mounted) │ ├── findings/ Analysis results and summaries │ ├── screenshots/ Visual evidence captures │ ├── logs/ Activity and audit logs │ ├── exports/ Carved files and extracted objects │ └── timelines/ Event timeline reconstructions │ ├── .claude/ │ ├── settings.json Claude Code hooks config │ ├── hooks/ │ │ └── session-start.sh Auto-verify Docker stack health │ └── mcp-health-check.sh MCP server health checker │ ├── docker-compose.yml All services defined here ├── Makefile All commands via make ├── CLAUDE.md Project instructions for AI ├── DOCKER.md Docker Hub documentation └── .mcp.json MCP config for host-installed Claude Code ``` ## 安全说明 | 关注点 | 处理方式 | |:--|:--| | **Docker socket** | Orchestrator 和 Claude Code 以只读方式挂载 `/var/run/docker.sock`。切勿将端口 `8800` 暴露给公共互联网。 | | **证据完整性** | 证据卷在所有 MCP 容器中以只读方式挂载。在数据库层面强制执行证据链。 | | **无 `shell=True`** | 所有子进程调用均使用 `subprocess.run(args_list, shell=False)` 以防止命令注入。 | | **API key 加密** | 威胁情报 API keys 通过 PostgreSQL pgcrypto 加密存储。 | | **非 root 容器** | 所有 MCP 服务器以非 root 身份运行，并启用 `no-new-privileges`（network-forensics 除外 —— 需要数据包捕获权限）。 | | **网络隔离** | 所有容器位于内部 `dfireballz-net` 桥接网络。只有 orchestrator（`8800`）向主机暴露端口。 | | **输出卷** | `output/` 可由 Claude Code 写入。包含调查发现，而非证据。证据始终是只读的。 | ## CI/CD 流水线 | 工作流 | 触发器 | 操作 | |:--|:--|:--| | **CI** | 推送 / PR 到 main 或 develop | 包 lint/测试、orchestrator 测试、Docker 构建、Trivy 扫描 | | **Docker Build & Push** | 版本标签（`v*.*.*`） | 构建多架构镜像，推送到 Docker Hub | | **CodeQL** | 推送 / PR 到 main + 每周 | 静态安全分析 | | **Dependabot** | 每周 | 自动更新 pip, npm, Docker, GitHub Actions 依赖 | ## 贡献 开发指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE)

标签：AI安全, AI风险缓解, Chat Copilot, ChatGPT, Claude, CVE检测, DAST, DevSecOps, Docker, ESC4, Ghidra, HTTP工具, IP 地址批量处理, LLM评估, MCP服务器, NIDS, Ollama, OSINT, Promptflow, SecList, SOAR, Volatility3, Wireshark, 上游代理, 云资产清单, 人工智能, 内存取证, 句柄查看, 大模型编排, 威胁情报, 安全防御评估, 容器化, 开发者工具, 恶意软件分析, 搜索引擎查询, 数字取证, 法庭可采性, 测试用例, 用户模式Hook绕过, 网络安全, 网络安全审计, 网络犯罪调查, 自动化应急响应, 自动化脚本, 证据链保全, 请求拦截, 逆向工具, 逆向工程, 隐私保护