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-based AI-native forensic investigation framework — everything runs in Docker.

> This is not a pentesting tool. It is a professional forensic platform designed to produce court-admissible evidence.

---

Table of Contents

Overview

• [How It Works](#how-it-works)
• [Architecture](#architecture)
• [Components](#components)

Getting Started

• [Prerequisites](#prerequisites)
• [Quick Start](#quick-start)

Setup Guides

• [Claude Code in Docker (Recommended)](#tutorial-1--claude-code-in-docker-recommended)
• [Claude Code on Host](#tutorial-2--claude-code-on-host)
• [Claude Desktop](#tutorial-3--claude-desktop)
• [ChatGPT](#tutorial-4--chatgpt)
• [MCPHost + Ollama](#tutorial-5--mcphost--ollama)
• [Open WebUI + Ollama](#tutorial-6--open-webui--ollama)

Skills & Templates

• [Investigation Skills (Slash Commands)](#investigation-skills)
• [How Skills Work](#how-skills-work)

Reference

• [How Prompts Flow](#how-prompts-flow-through-the-system)
• [Host Directory Layout](#host-directory-layout)
• [MCP Servers Reference](#mcp-servers-reference)
• [Investigation Playbooks](#investigation-playbooks)
• [API Keys](#api-keys)
• [Makefile Shortcuts](#makefile-shortcuts)
• [Chain of Custody](#chain-of-custody)

Advanced

• [Advanced FAQ & Tutorials](#advanced-faq--tutorials)
• [Troubleshooting](#troubleshooting)
• [Project Structure](#project-structure)
• [Security Notes](#security-notes)
• [CI/CD Pipeline](#cicd-pipeline)
• [Contributing](#contributing)
• [License](#license)

---

How It Works

Your AI client (Claude Code, Claude Desktop, ChatGPT, or MCPHost+Ollama) is the orchestrator:

1. You type a prompt — or use a /skill slash command (e.g. /malware-analysis /evidence/sample.exe)
2. The AI selects tools from 7 MCP servers (90+ forensic tools)
3. Each tool executes inside its Docker container via docker exec -i (stdio transport)
4. The AI correlates findings — timelines, MITRE ATT&CK mappings, IoC extraction
5. The AI writes the forensic report with chain of custody maintained throughout

Everything runs in Docker. No forensic tools on your host. All findings land in ./output/.

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│                     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       │
└──────────────────────────────────────────────────────────────┘

> Transport: stdio only. Every MCP server runs mcp.run(transport="stdio"). The AI host connects via docker exec -i . No HTTP ports exposed for direct AI connections. > > Exception: ChatGPT uses HTTP/SSE — the mcpo proxy bridges MCP servers as OpenAPI endpoints.

---

Components

| Container | What It Does | Port | Profile | |:--|:--|:--:|:--:| | 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 | VirusTotal, Shodan, AbuseIPDB, MalwareBazaar, ThreatFox, URLScan | — | default | | binary-analysis | Ghidra headless, Radare2, Capa (MITRE ATT&CK), YARA, pefile, lief | — | default | | network-forensics | 18 Wireshark/tshark tools, tcpdump, PCAP merge/split/carve, JA3/JA3S | — | default | | filesystem | Scoped file access to /cases, /evidence (read-only), /reports, /output | — | default | | orchestrator | FastAPI — cases, evidence, playbooks, chain of custody | 8800 | default | | db | PostgreSQL with pgcrypto (encrypted API key storage) | — | default | | redis | Redis cache | — | default | | claude-code | Anthropic CLI in Docker (no host install needed) | — | claude-code | | ollama | Local LLM inference (Open WebUI scenario) | 11434 | openwebui | | open-webui | Web UI for Ollama models | 8080 | openwebui | | mcpo | MCP-to-OpenAPI bridge for Open WebUI / ChatGPT | 8812 | openwebui |

---

Prerequisites

| Requirement | Details | |:--|:--| | Docker | 25+ with Docker Compose v2 | | RAM | 16 GB recommended (8 GB minimum) | | Disk | 50 GB+ (Docker images are large) | | Docker GID | Verify with: getent group docker \| cut -d: -f3 — must match DOCKER_GID in .env (default 999) | | GPU (optional) | NVIDIA GPU + Container Toolkit for Ollama |

API Keys (Free Tiers Available)

| Service | Free Tier | Sign Up | |:--|:--|:--| | VirusTotal | 4 req/min | virustotal.com/gui/my-apikey | | Shodan | Limited queries | account.shodan.io | | AbuseIPDB | 1,000 req/day | abuseipdb.com/account/api | | URLScan.io | 50 scans/day | urlscan.io/user/signup | | VulnCheck | Free tier | vulncheck.com |

> Using Claude Code in Docker? You also need an Anthropic API key: console.anthropic.com/settings/keys

bash scripts/check-requirements.sh   # Verify prerequisites

---

Quick Start

All images are pre-built on Docker Hub. No local building required.

git clone https://github.com/valITino/dfireballz.git
cd dfireballz
make setup    # Interactive wizard: .env, images, MCP config
make start    # Starts 10 containers

Verify

make status   # Container health table
make health   # MCP server responsiveness check

---

Tutorial 1 — Claude Code in Docker (Recommended)

Run Claude Code entirely inside Docker — connects directly to MCP servers on the internal network.

make setup        # Select "Claude Code in Docker"
make start
make claude-code  # Launch interactive Claude Code

The entrypoint verifies all 7 MCP servers are responsive before launching. Once inside:

/malware-analysis /evidence/sample.exe

Claude Code autonomously calls binary-analysis (Ghidra, Radare2, Capa), kali-forensics (YARA, ExifTool), and threat-intel (VirusTotal), then writes a full forensic report.

View results

ls output/findings/   # Analysis results
ls output/exports/    # Extracted artifacts
ls reports/           # Forensic reports

---

Tutorial 2 — Claude Code on Host

If you already have Claude Code installed locally.

make setup    # Select "Claude Code on host"
make start

Open Claude Code in the DFIReballz directory. MCP tools are auto-discovered from .mcp.json. The SessionStart hook (.claude/hooks/session-start.sh) verifies Docker stack health automatically.

---

Tutorial 3 — Claude Desktop

make setup    # Select "Claude Desktop"
make start
bash scripts/install-claude-desktop.sh   # Auto-merge MCP config

Restart Claude Desktop. MCP tools appear in the tool picker.

Manual config? Merge .mcp.json into your Claude Desktop config:

| OS | Config Path | |:--|:--| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

---

Tutorial 4 — ChatGPT

ChatGPT uses HTTP/SSE, not stdio. The mcpo proxy bridges MCP servers as HTTP endpoints.

make setup              # Select "ChatGPT"
make start-openwebui    # Starts mcpo proxy on port 8812

Expose your mcpo proxy to the internet (ChatGPT needs to reach it):

ngrok http 8812                              # Option A
cloudflared tunnel --url http://localhost:8812   # Option B

In ChatGPT → Settings → Connectors → Developer Mode, add your tunnel URL. Endpoints: /kali-forensics/, /osint/, /threat-intel/, /winforensics/, /binary-analysis/, /network-forensics/, /filesystem/.

---

Tutorial 5 — MCPHost + Ollama

Ollama has no native MCP support. MCPHost bridges the gap.

curl -fsSL https://ollama.ai/install.sh | sh
go install github.com/mark3labs/mcphost@latest
ollama pull qwen3:8b

make setup    # Select "MCPHost + Ollama"
make start
mcphost -m ollama/qwen3:8b --config ~/.mcphost.yml

| Model | RAM | Tool Calling | Notes | |:--|:--|:--|:--| | qwen3:8b | 8 GB | Excellent | Recommended | | qwen3:14b | 16 GB | Excellent | Better reasoning | | llama3.1:8b | 8 GB | Good | Widely tested | | llama3.3:70b | 48 GB+ | Excellent | Best quality |

---

Tutorial 6 — Open WebUI + Ollama

make setup
make start-openwebui

Open http://localhost:8080 → Admin Panel → Settings → External Tools. Register each server at http://mcpo:8000//.

---

Investigation Skills

DFIReballz includes 10 Claude Code skills — slash commands that launch structured investigation workflows. Each skill loads the corresponding investigation template, replaces [TARGET] with your input, and executes the full workflow.

Available Skills

| Skill | What It Does | Example | |:--|:--|:--| | /complete-investigation | Full 11-phase investigation across all servers | /complete-investigation /evidence/ | | /full-investigation | 6-phase end-to-end forensic investigation | /full-investigation /evidence/case001/ | | /malware-analysis | Static analysis, YARA, Capa, VirusTotal | /malware-analysis /evidence/sample.exe | | /ransomware-investigation | Ransomware triage, C2 detection, attack chain | /ransomware-investigation /evidence/encrypted-host/ | | /phishing-investigation | Email headers, URL analysis, credential checks | /phishing-investigation /evidence/phish.eml | | /network-forensics | PCAP analysis, protocol dissection, JA3 | /network-forensics /evidence/capture.pcap | | /osint-person | Username/email enumeration, digital footprint | /osint-person suspect@example.com | | /osint-domain | DNS, subdomain, infrastructure mapping | /osint-domain suspicious-site.com | | /memory-forensics | Volatility3 process/network/malware analysis | /memory-forensics /evidence/memdump.raw | | /incident-response | 7-phase IR: triage to remediation | /incident-response /evidence/compromised-host/ |

How Skills Work

Skills live in .claude/skills//SKILL.md. Claude Code auto-discovers them when opened in the project directory.

.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

Skills vs. Templates vs. Playbooks:

| | Skills | Templates | Playbooks | |:--|:--|:--|:--| | Where | .claude/skills/ | dfireballz/prompts/templates/ | playbooks/ | | Loaded | Auto by Claude Code | Via MCP or CLI | Via orchestrator API | | Invoked | /skill-name target | get_template(name, target) | POST /api/playbook/run | | For | Claude Code users | Any MCP client | API consumers | | UX | Slash command | Function call | REST API |

All three share the same investigation workflows — skills are the Claude Code-native interface.

Docker: Skills are volume-mounted into the claude-code container at /workspace/.claude/skills/ (read-only), and also baked into the image as a fallback.

---

How Prompts Flow Through the System

STEP 1 ─ YOU TYPE A PROMPT (or /skill)
│  "/malware-analysis /evidence/sample.exe"
│
▼
STEP 2 ─ AI LOADS TEMPLATE & SELECTS TOOLS
│  Skill loads the malware-analysis template, AI picks tools:
│    · capa_analyze (binary-analysis)      → MITRE ATT&CK mapping
│    · yara_scan (kali-forensics)          → malware signature matching
│    · check_virustotal (threat-intel)     → hash reputation lookup
│
▼
STEP 3 ─ TOOLS EXECUTE IN DOCKER
│  docker exec -i dfireballz-binary-analysis-1 python3 -u /app/server.py
│  Each tool returns structured output via stdio.
│
▼

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [valITino](https://github.com/valITino)
- **Source:** [valITino/dfireballz](https://github.com/valITino/dfireballz)
- **License:** MIT

Install and usage instructions live in the source repository linked above.