mcp-dfir 0.1.0__tar.gz

mcp_dfir-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: mcp-dfir
+Version: 0.1.0
+Summary: MCP Server for Performing Memory and Disk Forensics
+Requires-Python: >=3.11
+Requires-Dist: attrs
+Requires-Dist: loguru
+Requires-Dist: mcp
+Requires-Dist: python_on_whales
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: mcp[cli]; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: uv; extra == "dev"

mcp_dfir-0.1.0/README.md

@@ -0,0 +1,111 @@
+# MCP DFIR
+
+MCP DFIR (Digital Forensics Incident Response) is an MCP server that gives AI agents the tools to perform memory, disk, and artifact forensics. It runs forensics tools inside an isolated Docker container and exposes them over the MCP stdio transport.
+
+[Example report](/examples/tryhackme_volatility/analysis/analyst_notes/Case%20002%20-%20Complete%20Incident%20Analysis%20Report.md) based on the TryHackMe Volatility Essentials room.
+
+# Features
+
+- Memory forensics via [Volatility3](https://github.com/volatilityfoundation/volatility3)
+- Disk forensics via [The Sleuth Kit](https://www.sleuthkit.org/)
+- File search with `strings`, `grep`, and `find`
+- Archive extraction with `unzip` and `tar`
+- Automatic Windows symbol downloading and conversion
+- Linux symbol search and downloading from [Abyss-W4tcher/volatility3-symbols](https://github.com/Abyss-W4tcher/volatility3-symbols)
+- Persistent command history — the agent never re-runs commands already completed
+- Analyst notes — the agent records findings in structured markdown notes
+
+# Requirements
+
+- [Docker](https://www.docker.com/) must be installed and running
+
+# Installation
+
+```bash
+pip install mcp-dfir
+```
+
+# Setup
+
+## Claude Desktop config
+
+Add the following to your Claude Desktop `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-dfir": {
+      "command": "mcp-dfir"
+    }
+  }
+}
+```
+
+## Case directory layout
+
+The MCP server expects evidence and artifacts to be organized under a case directory:
+
+```
+my_case/
+├── evidence/    # Place memory dumps, disk images, etc. here (read-only)
+├── artifacts/   # Output location for extracted files (read-write)
+├── symbols/     # Volatility symbol files (auto-populated on download)
+└── analysis/    # Command history and analyst notes (auto-generated)
+```
+
+Place all evidence files (`.mem`, `.img`, `.e01`, etc.) inside the `evidence/` directory before starting a session.
+
+# Args
+
+```
+usage: mcp-dfir [-h] [--version] [-d CASE_DIR]
+
+options:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  -d, --case-dir CASE_DIR
+                        Working directory for the case, default: current directory
+```
+
+# MCP Tools
+
+| Tool                         | Description                                                          |
+| ---------------------------- | -------------------------------------------------------------------- |
+| `run_volatility_command`     | Runs Volatility3 (`vol`) for memory forensics                        |
+| `download_windows_symbol`    | Downloads and converts Windows PDB symbols for Volatility3           |
+| `download_linux_symbol`      | Downloads a Linux symbol file from Abyss-W4tcher/volatility3-symbols |
+| `search_linux_symbols`       | Searches the Linux symbol map by regex to find matching symbol files |
+| `run_sleuthkit_command`      | Runs any Sleuth Kit tool for disk forensics                          |
+| `run_strings`                | Runs `strings` on a file                                             |
+| `run_grep`                   | Runs `grep` on files                                                 |
+| `run_find`                   | Runs `find` to search for files                                      |
+| `list_files`                 | Lists files in `evidence`, `artifacts`, or `symbols`                 |
+| `unzip_file`                 | Extracts a zip archive into `/artifacts`                             |
+| `untar_file`                 | Extracts a tar archive into `/artifacts`                             |
+| `get_hash`                   | Computes a hash of a file                                            |
+| `get_command_history`        | Returns all previously run commands                                  |
+| `get_command_result`         | Returns the output of a specific past command                        |
+| `show_analyst_notes_summary` | Lists all analyst notes                                              |
+| `show_analyst_note`          | Retrieves the content of a specific analyst note                     |
+| `add_analyst_note`           | Creates a new analyst note                                           |
+| `update_analyst_note`        | Updates an existing analyst note                                     |
+
+# Build from source
+
+```bash
+# Create virtual environment
+python3 -m venv .venv
+
+# Activate (Linux/macOS)
+source .venv/bin/activate
+# Activate (Windows)
+.venv/Scripts/activate.ps1
+
+# Install dependencies
+pip install .[dev]
+
+# Run
+mcp-dfir --case-dir /path/to/your/case
+# or
+python3 -m mcp_dfir --case-dir /path/to/your/case
+```

mcp_dfir-0.1.0/mcp_dfir/config.py

@@ -0,0 +1,110 @@
+"""Defines the config object"""
+
+# Standard libraries
+from pathlib import Path
+
+# Third-party libraries
+from attrs import define, field, validators
+
+# Project libraries
+from mcp_dfir.constants import VERSION
+
+
+@define
+class DockerVolume:
+    name: str = field(validator=validators.instance_of(str))
+    internal_path: str = field(validator=validators.instance_of(str))
+    external_path: Path = field(validator=validators.instance_of(Path))
+    permissions: str = field(validator=validators.instance_of(str))
+
+
+@define
+class DockerConfig:
+    container_name: str = field(validator=validators.instance_of(str))
+    image_name: str = field(validator=validators.instance_of(str))
+
+
+@define
+class Config:
+    working_directory: Path = field(default=Path.cwd(), validator=validators.instance_of(Path))
+
+    # Directories
+    analysis_directory: Path = field(init=False, validator=validators.instance_of(Path))
+    artifact_directory: Path = field(init=False, validator=validators.instance_of(Path))
+    symbols_directory: Path = field(init=False, validator=validators.instance_of(Path))
+    evidence_directory: Path = field(init=False, validator=validators.instance_of(Path))
+
+    # Command history
+    command_history_json: Path = field(init=False, validator=validators.instance_of(Path))
+    command_record_directory: Path = field(init=False, validator=validators.instance_of(Path))
+
+    # Analyst notes
+    analyst_notes_list_json: Path = field(init=False, validator=validators.instance_of(Path))
+    analyst_notes_directory: Path = field(init=False, validator=validators.instance_of(Path))
+
+    # Symbols
+    windows_symbols_directory: Path = field(init=False, validator=validators.instance_of(Path))
+    linux_symbols_directory: Path = field(init=False, validator=validators.instance_of(Path))
+    linux_symbol_map_json: Path = field(init=False, validator=validators.instance_of(Path))
+
+    # Docker
+    docker_volumes: list[DockerVolume] = field(
+        init=False,
+        validator=validators.deep_iterable(
+            member_validator=validators.instance_of(DockerVolume), iterable_validator=validators.instance_of(list)
+        ),
+    )
+    docker_config: DockerConfig = field(init=False, validator=validators.instance_of(DockerConfig))
+
+    def load(self, working_directory: Path):
+
+        # Directories
+        self.working_directory = working_directory
+
+        self.analysis_directory = self.working_directory / "analysis"
+        self.analysis_directory.mkdir(mode=500, parents=False, exist_ok=True)
+
+        self.artifact_directory = self.working_directory / "artifacts"
+        self.artifact_directory.mkdir(mode=500, parents=False, exist_ok=True)
+
+        self.symbols_directory = self.working_directory / "symbols"
+        self.symbols_directory.mkdir(mode=500, parents=False, exist_ok=True)
+
+        self.evidence_directory = self.working_directory / "evidence"
+        self.evidence_directory.mkdir(mode=500, parents=False, exist_ok=True)
+
+        # Command history
+        self.command_history_json = self.analysis_directory / "command_history.json"
+        self.command_record_directory = self.analysis_directory / "command_history"
+
+        # Analyst notes
+        self.analyst_notes_list_json = self.analysis_directory / "analyst_notes.json"
+        self.analyst_notes_directory = self.analysis_directory / "analyst_notes"
+
+        # Symbols
+        self.windows_symbols_directory = self.symbols_directory / "windows"
+        self.linux_symbols_directory = self.symbols_directory / "linux"
+        self.linux_symbol_map_json = self.linux_symbols_directory / "symbol_map.json"
+
+        # Docker
+        self.docker_volumes = [
+            DockerVolume(
+                name="evidence", internal_path="/evidence", external_path=self.evidence_directory, permissions="ro"
+            ),
+            DockerVolume(
+                name="analysis", internal_path="/analysis", external_path=self.analysis_directory, permissions="ro"
+            ),
+            DockerVolume(
+                name="symbols", internal_path="/symbols", external_path=self.symbols_directory, permissions="rw"
+            ),
+            DockerVolume(
+                name="artifacts", internal_path="/artifacts", external_path=self.artifact_directory, permissions="rw"
+            ),
+        ]
+        self.docker_config = DockerConfig(
+            container_name=f"{self.working_directory.name.replace(' ', '_')}-forensics",
+            image_name=f"androsh7/forensics-docker:{VERSION}",
+        )
+
+
+config = Config()

mcp_dfir-0.1.0/mcp_dfir/constants.py

@@ -0,0 +1,11 @@
+"""Defines constants"""
+
+VERSION = "0.1.0"
+
+# Volatility symbols
+WINDOWS_SYMBOL_SERVER = "https://msdl.microsoft.com/download/symbols"
+LINUX_SYMBOL_REPO_BASE_URL = "https://raw.githubusercontent.com/Abyss-W4tcher/volatility3-symbols/refs/heads/master"
+LINUX_SYMBOL_MAP_SOURCE = f"{LINUX_SYMBOL_REPO_BASE_URL}/banners/banners_plain.json"
+
+# Command output limit
+COMMAND_MAX_OUTPUT_BYTES = 25 * 1024  # 2 KB

mcp_dfir-0.1.0/mcp_dfir/data_manager.py

@@ -0,0 +1,117 @@
+"""Defines the data manager class"""
+
+# Standard libraries
+import json
+
+# Third-party libraries
+from pydantic import BaseModel, Field
+
+# Project libraries
+from mcp_dfir.config import config
+from mcp_dfir.tools.models import AnalystNote, AnalystNoteSummary, CommandRecord, CommandRecordSummary
+
+
+class CommandHistoryManager(BaseModel):
+    command_summary_list: list[CommandRecordSummary] = Field(default_factory=list, init=False)
+
+    def model_post_init(self, __context):
+        # Load commands
+        if config.command_history_json.exists():
+            self.load()
+        config.command_record_directory.mkdir(mode=500, parents=True, exist_ok=True)
+
+    def dump(self, command: CommandRecord | None, command_number: int | None = None):
+        # Write to command history
+        with open(file=config.command_history_json, mode="w", encoding="utf-8") as command_summary_file:
+            json.dump(
+                [record.model_dump() for record in self.command_summary_list],
+                command_summary_file,
+                indent=4,
+            )
+
+        # Write to command file
+        if command is not None and command_number is not None:
+            with open(
+                file=config.command_record_directory / f"{command_number}.txt", mode="w", encoding="utf-8"
+            ) as command_file:
+                command_file.write(command.result)
+
+    def load(self):
+        with open(file=config.command_history_json, encoding="utf-8") as command_file:
+            for command_summary_dict in json.load(command_file):
+                self.command_summary_list.append(CommandRecordSummary.model_validate(command_summary_dict))
+
+    def add_command(self, command_record: CommandRecord) -> CommandRecordSummary:
+        number = len(self.command_summary_list) + 1
+        summary = command_record.summary(number=number)
+        self.command_summary_list.append(summary)
+        self.dump(command_record, number)
+        return summary
+
+    def get_command(self, command_number: int) -> CommandRecord:
+        for command in self.command_summary_list:
+            if command.number == command_number:
+                with open(file=config.command_record_directory / f"{command_number}.txt", encoding="utf-8") as file:
+                    return CommandRecord(
+                        command=command.command,
+                        date_run=command.date_run,
+                        result=file.read(),
+                        exit_code=command.exit_code,
+                    )
+        raise KeyError(f"Could not find command with number {command_number}")
+
+
+class AnalystNoteManager(BaseModel):
+    note_list: list[AnalystNoteSummary] = Field(default_factory=list, init=False)
+
+    def model_post_init(self, __context):
+        if config.analyst_notes_list_json.exists():
+            self.load()
+        config.analyst_notes_directory.mkdir(mode=500, exist_ok=True)
+
+    def dump(self, note: AnalystNote | None):
+        # Update note summary
+        with open(file=config.analyst_notes_list_json, mode="w", encoding="utf-8") as note_summary_file:
+            json.dump(
+                [note.model_dump() for note in self.note_list],
+                note_summary_file,
+                indent=4,
+            )
+
+        # Write to note file
+        if note is not None:
+            with open(
+                file=config.analyst_notes_directory / f"{note.title}.md", mode="w", encoding="utf-8"
+            ) as note_file:
+                note_file.write(note.description)
+
+    def load(self):
+        with open(file=config.analyst_notes_list_json, encoding="utf-8") as note_file:
+            for note_dict in json.load(note_file):
+                self.note_list.append(AnalystNote.model_validate(note_dict))
+
+    def add_note(self, note: AnalystNote) -> AnalystNote:
+        self.note_list.append(note.summary())
+        self.dump(note)
+        return note
+
+    def update_note(self, title: str, note: AnalystNote) -> AnalystNote:
+        for index, note in enumerate(self.note_list):
+            if note.title == title:
+                self.note_list[index] = note.summary()
+                self.dump(note)
+                return note
+        raise KeyError(f"No note with title '{title}'")
+
+    def get_note(self, title: str) -> AnalystNote:
+        for note in self.note_list:
+            if note.title == title:
+                with open(file=config.analyst_notes_directory / f"{title}.md", encoding="utf-8") as note_file:
+                    return AnalystNote(
+                        title=note.title, status=note.status, tags=note.tags, description=note_file.read()
+                    )
+        raise KeyError(f"No note with title '{title}'")
+
+
+command_history_manager = CommandHistoryManager()
+analyst_note_manager = AnalystNoteManager()

mcp_dfir-0.1.0/mcp_dfir/docker_manager.py

@@ -0,0 +1,91 @@
+"""Defines all functions to run commands on the docker container"""
+
+# Third-party libraries
+from attrs import define, field, validators
+from loguru import logger
+from mcp.server.fastmcp import Context
+from python_on_whales import Container, DockerClient
+from python_on_whales.exceptions import DockerException, NoSuchContainer
+
+# Project libraries
+from mcp_dfir.config import config
+from mcp_dfir.data_manager import command_history_manager
+from mcp_dfir.tools.models import CommandRecord, CommandRecordSummary
+
+
+@define
+class DockerManager:
+    docker: DockerClient = field(validator=validators.instance_of(DockerClient), init=False)
+    container: Container = field(validator=validators.optional(validators.instance_of(Container)), init=False)
+
+    def __attrs_post_init__(self):
+        self.docker = DockerClient()
+        self.container = None
+
+    def start_forensic_container(self):
+        logger.info("Starting forensics docker container")
+
+        try:
+            self.container = self.docker.container.inspect(config.docker_config.container_name)
+
+            if self.container.state.running:
+                logger.info("Forensics container already running")
+                return
+
+            logger.info("Forensics container exists but is stopped, starting it")
+            self.docker.container.start(config.docker_config.container_name)
+            return
+
+        except NoSuchContainer:
+            logger.info("Forensics container does not exist, creating one")
+
+        volumes = [
+            (volume_mount.external_path, volume_mount.internal_path, volume_mount.permissions)
+            for volume_mount in list(config.docker_volumes)
+        ]
+        self.container = self.docker.run(
+            config.docker_config.image_name,
+            name=config.docker_config.container_name,
+            detach=True,
+            remove=False,
+            volumes=volumes,
+            networks=["none"],
+        )
+
+    def stop_forensic_container(self):
+        if self.container is not None:
+            logger.info("Stopping forensics docker container")
+            self.container.stop()
+
+    def clear_forensic_container(self):
+        if self.container is not None:
+            logger.info("Clearing forensics docker container")
+            self.container.stop()
+            self.container.remove()
+            self.container = None
+
+    def exec_stream(self, ctx: Context, command_list: list[str]) -> CommandRecordSummary:
+        if self.container is None:
+            raise RuntimeError("No docker container is currently running")
+
+        ctx.report_progress(f"Running command {' '.join(command_list)}")
+        output = []
+        exit_code = 0
+        try:
+            for stream, data in self.docker.execute(self.container, command_list, stream=True):
+                if stream == "stdout":
+                    output.append(data.decode())
+        except DockerException as ex:
+            exit_code = ex.return_code if ex.return_code is not None else 1
+            output.append(str(ex))
+        result = "".join(output)
+        return command_history_manager.add_command(
+            CommandRecord(
+                command=" ".join(command_list),
+                result=result,
+                exit_code=exit_code,
+            )
+        )
+
+
+docker_manager = DockerManager()

mcp_dfir-0.1.0/mcp_dfir/runner.py

@@ -0,0 +1,67 @@
+"""Runner for llm_forensics"""
+
+# Standard libraries
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+# Project libraries
+from mcp_dfir.config import config
+from mcp_dfir.constants import VERSION
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="mcp-dfir", description="MCP Server for Performing Memory and Disk Forensics")
+    parser.add_argument("--version", action="version", version=f"mcp-dfir v{VERSION}")
+    parser.add_argument(
+        "-d", "--case-dir", type=Path, default=Path.cwd(), help=f"Working directory for the case, default: {Path.cwd()}"
+    )
+    parser.add_argument("--init", action="store_true", help="Create case directories then exit")
+    parser.add_argument(
+        "--clear-case-dir", action="store_true", help="Clear the case directory before starting the server"
+    )
+    parser.add_argument(
+        "--clear-docker", action="store_true", help="Clear the forensics docker container before starting the server"
+    )
+    args = parser.parse_args()
+
+    if args.clear_case_dir:
+        user_input = input(
+            f"Are you sure you want to clear the case directory {args.case_dir}? This action cannot be undone. Type 'yes' to confirm: "
+        )
+        if user_input != "yes":
+            parser.exit(status=1, message="Case directory not cleared")
+        for path in "artifacts", "analysis", "evidence", "symbols":
+            shutil.rmtree(args.case_dir / path, ignore_errors=True)
+        print("Case directory cleared")
+        sys.exit(0)
+
+    # Load config
+    config.load(working_directory=args.case_dir)
+
+    if args.init:
+        sys.exit(0)
+
+    if args.clear_docker:
+        from mcp_dfir.docker_manager import docker_manager
+
+        docker_manager.clear_forensic_container()
+        sys.exit(0)
+
+    # Load MCP server
+    from mcp_dfir.docker_manager import docker_manager
+    from mcp_dfir.server import mcp
+
+    # Start the mcp server
+    docker_manager.start_forensic_container()
+    try:
+        mcp.run(transport="stdio")
+    except KeyboardInterrupt:
+        pass
+    finally:
+        docker_manager.stop_forensic_container()
+
+
+if __name__ == "__main__":
+    main()

mcp_dfir-0.1.0/mcp_dfir/server.py

@@ -0,0 +1,75 @@
+"""Defines the MCP server"""
+
+# Third-party libraries
+from mcp.server.fastmcp import FastMCP
+
+# Project libraries
+from mcp_dfir.tools.file_search import list_files, run_find, run_grep, run_strings
+from mcp_dfir.tools.file_tools import untar_file, unzip_file
+from mcp_dfir.tools.hash import get_hash
+from mcp_dfir.tools.history import get_command_history, get_command_result
+from mcp_dfir.tools.notes import (
+    add_analyst_note,
+    show_analyst_note,
+    show_analyst_notes_summary,
+    update_analyst_note,
+)
+from mcp_dfir.tools.sleuthkit import run_sleuthkit_command
+from mcp_dfir.tools.volatility import (
+    download_linux_symbol,
+    download_windows_symbol,
+    run_volatility_command,
+    search_linux_symbols,
+)
+
+# Create MCP server
+mcp = FastMCP(
+    "llm-forensics",
+    auth=None,
+    instructions="""\
+You are a host forensics agent tasked with performing memory, disk, and artifact forensics.
+
+Before beginning analysis always perform the following tasks:
+1. Perform an inventory of all evidence, ask the user for specific details on how, when, and where the evidence was acquired
+2. Review all previous commands that have already been run, commands should never be re-run unless the evidence has been updated or the commands were run incorrectly
+3. Review all analyst notes to not perform duplicate analysis
+
+While performing analysis follow these rules:
+1. Create an analyst note (markdown format) after every finding whether benign, malicious, or if additional research is needed
+2. Never make any assumptions, if a conclusion cannot be reached on whether a finding is benign or malicious explicitly mark it as needing additional research
+3. Never use custom bash or python scripts to parse files, only use the built-in head/tail/regex/truncate options when going through command results
+4. All artifacts should be saved under /artifacts
+""",
+)
+
+# File search
+mcp.add_tool(list_files)
+mcp.add_tool(run_strings)
+mcp.add_tool(run_grep)
+mcp.add_tool(run_find)
+
+# File tools
+mcp.add_tool(unzip_file)
+mcp.add_tool(untar_file)
+
+# Hash
+mcp.add_tool(get_hash)
+
+# Records
+mcp.add_tool(get_command_history)
+mcp.add_tool(get_command_result)
+
+# Volatility
+mcp.add_tool(run_volatility_command)
+mcp.add_tool(download_windows_symbol)
+mcp.add_tool(download_linux_symbol)
+mcp.add_tool(search_linux_symbols)
+
+# Sleuthkit
+mcp.add_tool(run_sleuthkit_command)
+
+# Notes
+mcp.add_tool(show_analyst_notes_summary)
+mcp.add_tool(show_analyst_note)
+mcp.add_tool(add_analyst_note)
+mcp.add_tool(update_analyst_note)

mcp_dfir-0.1.0/mcp_dfir/tools/file_search.py

@@ -0,0 +1,59 @@
+"""File search mcp functions"""
+
+# Standard libraries
+from pathlib import Path
+from typing import Literal
+
+# Third-party libraries
+from mcp.server.fastmcp import Context
+
+# Project libraries
+from mcp_dfir.config import config
+from mcp_dfir.docker_manager import docker_manager
+from mcp_dfir.tools.models import CommandRecordSummary, FileDetails
+
+
+def list_files(path: Literal["artifacts", "symbols", "evidence"]) -> list[FileDetails]:
+    valid_paths = [volume.name for volume in config.docker_volumes]
+
+    # Select volume
+    selected_volume = None
+    for volume in config.docker_volumes:
+        if volume.name == path:
+            selected_volume = volume
+            break
+    if selected_volume is None:
+        raise RuntimeError(f"Invalid path {path}, valid paths are {valid_paths}")
+
+    out_list = []
+    for dir_path, _, file_name_list in selected_volume.external_path.walk():
+        for file_name in file_name_list:
+            external_file_path = Path(dir_path / file_name)
+            internal_file_path = (
+                f"/{path}/{str(external_file_path.relative_to(selected_volume.external_path)).replace('\\', '/')}"
+            )
+            out_list.append(
+                FileDetails(
+                    name=file_name,
+                    path=internal_file_path,
+                    size=external_file_path.stat().st_size,
+                )
+            )
+    return out_list
+
+
+def run_strings(ctx: Context, arguments: list[str]) -> CommandRecordSummary:
+    """Runs: strings <arguments>"""
+    return docker_manager.exec_stream(ctx=ctx, command_list=["strings", *arguments])
+
+
+def run_grep(ctx: Context, arguments: list[str]) -> CommandRecordSummary:
+    """Runs: grep <arguments>"""
+    return docker_manager.exec_stream(ctx=ctx, command_list=["grep", *arguments])
+
+
+def run_find(ctx: Context, arguments: list[str]) -> CommandRecordSummary:
+    """Runs: find <arguments>"""
+    if " ".join(arguments).find("-exec") != -1:
+        raise RuntimeError("Cannot run exec in find")
+    return docker_manager.exec_stream(ctx=ctx, command_list=["find", *arguments])