# Dfireballz

> AI-native digital forensics & cybercrime investigation platform. 7 MCP servers (Volatility3, Ghidra, Wireshark, OSINT, threat-intel & more) orchestrated by Claude, ChatGPT, or Ollama — fully containerized, chain-of-custody enforced, court-admissible output.

- **Type:** MCP server
- **Install:** `agentstack add mcp-valitino-dfireballz`
- **Verified:** Pending review
- **Seller:** [valITino](https://agentstack.voostack.com/s/valitino)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [valITino](https://github.com/valITino)
- **Source:** https://github.com/valITino/dfireballz

## Install

```sh
agentstack add mcp-valitino-dfireballz
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

```
╔═════════════════════════════════════════════════════════════════════════════════╗
║                                                                                 ║
║  ██████╗ ███████╗██╗██████╗   ███████╗██████╗  █████╗ ██╗     ██╗     ███████╗  ║
║  ██╔══██╗██╔════╝██║██╔══██╗  ██╔════╝██╔══██╗██╔══██╗██║     ██║     ╚══███╔╝  ║
║  ██║  ██║█████╗  ██║██████╔╝  █████╗  ██████╔╝███████║██║     ██║       ███╔╝   ║
║  ██║  ██║██╔══╝  ██║██╔══██╗  ██╔══╝  ██╔══██╗██╔══██║██║     ██║      ███╔╝    ║
║  ██████╔╝██║     ██║██║  ██║  ███████╗██████╔╝██║  ██║███████╗███████╗███████╗  ║
║  ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝  ╚══════╝╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝  ║
║                                                                                 ║
╠═════════════════════════════════════════════════════════════════════════════════╣
║              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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) for Ollama |

### API Keys (Free Tiers Available)

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

> **Using Claude Code in Docker?** You also need an **Anthropic API key**: [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)

```bash
bash scripts/check-requirements.sh   # Verify prerequisites
```

---

## Quick Start

All images are pre-built on [Docker Hub](https://hub.docker.com/r/crhacky/dfireballz). No local building required.

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

### Verify

```bash
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.

```bash
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

```bash
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.

```bash
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

```bash
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.

```bash
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):

```bash
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](https://github.com/mark3labs/mcphost) bridges the gap.

```bash
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

```bash
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-valitino-dfireballz
- Seller: https://agentstack.voostack.com/s/valitino
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.