# Self-Assembling Forensic MCP Server (FastMCP / Python)

A modular Digital Forensics and Incident Response (DFIR) **Model Context Protocol (MCP)** server built with Python and FastMCP (`mcp>=2.0.0`).

It dynamically discovers host & container forensic utilities at startup and automatically self-assembles functional tools, resources, and triage prompts for local LLMs and AI agents (Ollama, Claude, Cursor, Antigravity, etc.).

---

## 🌟 Features

- 🔍 **Dynamic Capability Discovery**: Probes host environment paths, installed binaries (`exiftool`, `strings`, `volatility3`, `binwalk`, `tshark`, `objdump`, `gdb`, `yara`), and Docker runtimes. Missing tools are gracefully reported without crashing.
- 🧩 **Self-Assembling Tool Primitives**: Automatically registers only the tools available in the host environment.
- 🛡️ **Air-Gapped & Offline Ready**: Built-in offline threat intelligence database with known sample signatures (EICAR, WannaCry, Mimikatz) for secure, zero-data-leakage incident response.
- 📋 **Tamper-Evident Chain of Custody**: Every tool execution, inspected artifact, SHA-256 checksum, and action parameter is cryptographically hashed and logged to an append-only ledger (`evidence/chain_of_custody.jsonl`).
- 🩺 **Self-Reporting Health & Resources**: Real-time capability matrix (`forensics://capabilities`), custody logs (`forensics://custody`), and system health (`forensics://health`).
- ⚡ **Dual Transport**: Supports standard STDIO for native MCP clients (Cursor, Claude, Antigravity) and SSE/HTTP for web LLM agents (Ollama, Open WebUI).

---

## 🚀 Quick Start

### 1. Prerequisites
- Python 3.10+ (or [uv](https://docs.astral.sh/uv/))

### 2. Run the Server

#### Option A: Native STDIO Transport (For Local Agents / Cursor / Claude)
```bash
cd /home/b47m4n/Projects/forensics-mcp-framework
uv run src/server.py
```

#### Option B: SSE / HTTP Transport (For Web / Remote LLMs)
```bash
cd /home/b47m4n/Projects/forensics-mcp-framework
uv run src/server.py --transport sse --port 8000
```

---

## 🔌 Connecting to Local LLMs & Agents

### 1. Antigravity / Claude / Cursor (`claude_desktop_config.json` / `mcp.json`)
```json
{
  "mcpServers": {
    "forensic-analyzer": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/b47m4n/Projects/forensics-mcp-framework",
        "run",
        "src/server.py"
      ]
    }
  }
}
```

### 2. Local LLM via Ollama + MCP
Connect your local model (e.g. `llama3.1`, `qwen2.5-coder`) via SSE endpoint:
`http://localhost:8000/sse`

---

## 🛠️ Discovered Tool Catalog

| Tool | Category | Dynamic Condition | Description |
|---|---|---|---|
| `extract_metadata` | Metadata & Files | Always Available | Computes hashes (MD5/SHA256), EXIF tags, and detects MIME mismatches |
| `extract_strings` | Static Analysis | Always Available | Extracts printable ASCII & Unicode strings |
| `scan_iocs` | Threat Detection | Always Available | Scans for C2 URLs, IP addresses, Base64 blobs, command execution |
| `check_threat_intel` | Threat Intel | Always Available | Checks hashes against offline signatures and optional live APIs |
| `system_health_check` | Diagnostics | Always Available | Health status, storage check, and tool readiness |
| `windows_image_info` | Memory Forensics | `vol` or Docker | Volatility 3 `windows.info` |
| `windows_pslist` | Memory Forensics | `vol` or Docker | Volatility 3 `windows.pslist` |
| `windows_pstree` | Memory Forensics | `vol` or Docker | Volatility 3 `windows.pstree` |
| `windows_netscan` | Memory Forensics | `vol` or Docker | Volatility 3 `windows.netscan` |
| `windows_malfind` | Memory Forensics | `vol` or Docker | Volatility 3 `windows.malfind` (injected code) |
| `binwalk_scan` | File Carving | `binwalk` present | Firmware signature and filesystem carving |
| `pcap_analyze` | Network Forensics| `tshark` present | Dissects PCAP network packet captures |
| `binary_disassemble` | Reverse Eng | `objdump` present | Disassembles binary machine instructions |
| `gdb_inspect` | Debugging | `gdb` present | Automated batch debugging inspection |
| `yara_scan` | Signature Match | `yara` present | Scans evidence against YARA rule files |

---

## 📂 Project Architecture

```
forensics-mcp-framework/
├── pyproject.toml
├── .env.example
├── README.md
├── evidence/                  # Evidence locker & chain of custody ledger
│   ├── suspect_photo.jpg
│   ├── eicar_test.com
│   └── chain_of_custody.jsonl
└── src/
    ├── server.py              # Master FastMCP bootstrap & dynamic assembler
    ├── core/
    │   ├── discovery.py       # Host & container capability scanner
    │   ├── custody.py         # Tamper-evident append-only chain of custody
    │   └── health.py          # System diagnostics & health reporter
    ├── tools/
    │   ├── metadata.py        # ExifTool & MIME mismatch detector
    │   ├── strings_ioc.py     # String & IOC scanner (IP, URL, Base64, shell)
    │   ├── threat_intel.py    # Offline/online threat intelligence
    │   ├── memory_vol.py      # Volatility 3 memory analysis engine
    │   └── dynamic_cli.py     # CLI wrappers (binwalk, tshark, objdump, gdb)
    ├── resources/
    │   └── system_resources.py# MCP Resources
    └── prompts/
        └── triage_prompts.py  # Structured DFIR workflows
```