Forensic Artifact Investigator Server

A production-quality Model Context Protocol (MCP) server built with the NitroStack framework. It performs real, local forensic analysis of file bytes by orchestrating system forensic binaries (file, exiftool, GNU strings, and Volatility) via safe, shell-free subprocess execution.

---

Table of Contents

1. How It Works
2. Supported Platforms & Installation
   • Linux (Debian/Ubuntu/CentOS)
   • Windows (Native & WSL)
3. Configuration (.env)
4. MCP Protocol Surface Reference
   • Tools (Input & Output Examples)
   • Resources (Schema & Output Examples)
   • Prompts
   • Widgets
5. Setting Up in Client Harnesses
   • Claude Code
   • Cursor
   • Claude Desktop
6. Development, Build, and Testing
7. Security and Forensic Guidelines

---

How It Works

This server exposes local forensic tools as MCP primitives to LLM clients. The execution flow is strictly live:

1. Client Handshake: The MCP client establishes a JSON-RPC session over STDIO.
2. Tool Selection: When asked to inspect a file, the LLM calls extract-metadata or extract-strings.
3. Execution Safety: The server validates the path to ensure it remains inside the configured EVIDENCE_ROOT and blocks symlink/path traversal attacks.
4. Command Execution: The server spawns command-line forensic utilities directly (using execFile/spawn with shell: false). It enforces CPU timeouts and memory boundaries.
5. Chain-of-Custody Logging: Every command execution, success or failure, is appended to an audit log (data/analysis-log.jsonl).
6. Result Formatting: Results are returned to the client in structured JSON. The LLM can render the analysis-report widget to show a premium UI panel.

---

Supported Platforms & Installation

The server requires Node.js v18+ (v22 LTS recommended) and system forensic binaries.

Linux (Debian/Ubuntu/CentOS)

1. System Dependencies

On Debian/Ubuntu:

sudo apt-get update
sudo apt-get install -y file libimage-exiftool-perl binutils python3 python3-pip python3-venv

On CentOS/RHEL (EPEL required):

sudo dnf install epel-release
sudo dnf install -y file perl-Image-ExifTool binutils python3 python3-pip

2. Volatility 3 Installation

It is highly recommended to install Volatility 3 in a dedicated virtual environment inside or adjacent to the project directory:

python3 -m venv .venv-volatility
source .venv-volatility/bin/activate
pip install --upgrade pip
pip install volatility3

Determine the absolute path of the vol binary (usually .venv-volatility/bin/vol).

---

Windows (Native & WSL)

Option A: WSL2 (Recommended)

Follow the standard Linux installation instructions inside your WSL terminal (e.g. Ubuntu). Access Windows files via /mnt/c/.

Option B: Native Windows (PowerShell)

1. Node.js: Install Node.js LTS via the official installer.
2. File Utility: Install git-bash or downoad the native Win32 file command via Git for Windows, then add it to your System PATH.
3. ExifTool: Download the stand-alone Windows executable from exiftool.org, rename it to exiftool.exe, and place it in a folder in your System PATH.
4. GNU strings: Download strings.exe from Sysinternals Suite and add it to your PATH.
5. Volatility 3:
   • Install Python 3 via the Microsoft Store or Python website.
   • Install Volatility 3 using PowerShell:

     python -m venv .venv-volatility
     .venv-volatility\Scripts\activate
     python -m pip install --upgrade pip
     python -m pip install volatility3
     

   • The path to your binary will be .venv-volatility\Scripts\vol.exe.

---

Configuration (.env)

Configure your local environment by creating a .env file in the root of forensic-artifact-investigator:

# Absolute path to the folder containing your evidence files
EVIDENCE_ROOT=/Users/nambi/Documents/Forensic Open Source/evidence

# Volatility configuration
VOLATILITY_MAJOR_VERSION=3
VOLATILITY_BINARY=/Users/nambi/Documents/Forensic Open Source/.venv-volatility/bin/vol

# Optional: VirusTotal Reputation API Key (Leave empty to skip online reputation checks)
VIRUSTOTAL_API_KEY=

# Execution Limits
FILE_COMMAND_TIMEOUT_MS=60000
VOLATILITY_TIMEOUT_MS=300000
MAX_RETURNED_STRINGS=5000
MAX_STRING_OUTPUT_BYTES=2000000
VOLATILITY_MAX_OUTPUT_BYTES=5000000

---

MCP Protocol Surface Reference

Tools (Input & Output Examples)

1. extract-metadata

Extracts filesystem size, runs file --mime-type to detect the actual type, checks for MIME discrepancies using the signatures database, computes the SHA-256, and extracts camera, GPS, and timestamp metadata via ExifTool.

• Parameters:

  {
    "filePath": "/evidence/suspect_photo.jpg"
  }
  

• Response Example:

  {
    "tool": "extract-metadata",
    "targetFile": "/evidence/suspect_photo.jpg",
    "fileSizeBytes": 1717,
    "extension": ".jpg",
    "detectedMimeType": "image/jpeg",
    "expectedMimeTypes": ["image/jpeg"],
    "extensionKnown": true,
    "extensionMismatch": false,
    "sha256": "37751c11e6cc72ef0d39e31dcd4dfdf2252c8adab256be47e24b745499cf29fa",
    "metadata": {
      "camera": {
        "make": "TestCamera",
        "model": "Forensic-1000",
        "lens": "TestLens 35mm"
      },
      "gps": {
        "latitude": "37 deg 48' 0.00\" N",
        "longitude": "122 deg 25' 0.00\" W",
        "altitude": "10 m"
      },
      "software": "EvidenceGen v1.0",
      "timestamps": {
        "dateTimeOriginal": "2026:07:12 12:00:00"
      }
    }
  }
  

2. extract-strings

Extracts ASCII/Unicode characters with a minimum length of 6, and scans them for IP addresses, URLs, domains, and suspicious command-line keywords.

• Parameters:

  {
    "filePath": "/evidence/suspect_photo.jpg"
  }
  

• Response Example:

  {
    "tool": "extract-strings",
    "totalStringsCaptured": 23,
    "returnedCount": 23,
    "patternMatches": {
      "ipAddresses": [],
      "urlsAndDomains": [
        {
          "matchedValue": "http://malicious-site.com/payload.exe",
          "sourceString": "Download link http://malicious-site.com/payload.exe here.",
          "type": "url"
        }
      ],
      "suspiciousKeywords": [
        {
          "keyword": "powershell",
          "sourceString": "powershell -EncodedCommand AAAA"
        }
      ]
    }
  }
  

3. analyze-memory-dump

Invokes the configured Volatility binary to run sequentially: windows.info, windows.pslist, windows.netscan, and windows.malfind.

• Parameters:

  {
    "filePath": "/evidence/winmem.raw"
  }
  

• Response Example (Truncated):

  {
    "tool": "analyze-memory-dump",
    "volatilityVersion": 3,
    "volatilityBinary": "/path/to/vol",
    "osProfile": {
      "NTBuildLab": "14393.pc.release...",
      "SystemTime": "2026-07-12 12:00:00"
    },
    "processList": [
      {
        "PID": 4,
        "PPID": 0,
        "ImageFileName": "System"
      }
    ],
    "pluginResults": {
      "info": { "status": "success", "rowCount": 1 },
      "pslist": { "status": "success", "rowCount": 120 },
      "netscan": { "status": "success", "rowCount": 15 },
      "malfind": { "status": "success", "rowCount": 3 }
    }
  }
  

---

Resources (Schema & Output Examples)

1. signatures://magic-bytes

Returns the JSON sign-off references containing mapping tables.

• MIME: application/json

2. case://analysis-log

Returns the append-only logs compiled from data/analysis-log.jsonl.

• MIME: application/json

3. signatures://threat-intel/{hash}

Returns VirusTotal file hash summary statistics.

• Special offline path: Querying MD5 44d88612fea8a8f36de82e1278abb02f (EICAR) returns a local response without internet connection:

  {
    "status": "found",
    "source": "deterministic-eicar-fixture",
    "hash": "44d88612fea8a8f36de82e1278abb02f",
    "hashAlgorithm": "md5",
    "malicious": 1,
    "summary": "Known EICAR antivirus test-file hash; deterministic test response."
  }
  

---

Prompts

• full-file-analysis: An interactive prompt guiding LLMs to parse, check reputation, and organize findings under exact headers: Confirmed Anomalies, Possible Anomalies, and Clean.

---

Widgets

• analysis-report: Headless React interface. Renders structured results on a dark-mode optimized layout with interactive copy-pastes for analysts.

---

Setting Up in Client Harnesses

Claude Code

To add this server to Claude Code, run:

claude mcp add forensic-server node /path/to/forensic-artifact-investigator/dist/index.js

(Make sure to compile the project first using npm run build and populate the .env file.)

---

Cursor

To configure inside Cursor IDE:

1. Open Cursor Settings.
2. Go to Features -> MCP.
3. Click + Add New MCP Server.
4. Configure as follows:
   • Name: Forensic Investigator
   • Type: command
   • Command: node "/path/to/forensic-artifact-investigator/dist/index.js"
5. Save and check that the indicator turns green.

---

Claude Desktop

Add this configuration to your local config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "forensic-artifact-investigator": {
      "command": "node",
      "args": [
        "/path/to/forensic-artifact-investigator/dist/index.js"
      ],
      "env": {
        "EVIDENCE_ROOT": "/path/to/evidence",
        "VOLATILITY_BINARY": "/path/to/vol",
        "VOLATILITY_MAJOR_VERSION": "3"
      }
    }
  }
}

---

Development, Build, and Testing

• Install Dependencies:

  npm install
  

• Run Typechecking:

  npm run typecheck
  

• Run Tests (Vitest):

  npm test
  

• Build Server and Widgets:

  npm run build
  

• Run Server Locally:

  npm start
  

---

Security and Forensic Guidelines

• No Shell Interpolation: Evaluates arguments array in a shell-free execution context to prevent subprocess vulnerability exploits.
• Log Sanitation: The application guarantees that VIRUSTOTAL_API_KEY is not logged in files or included in errors.
• Path Restrictions: Every file validation requires canonical comparison against EVIDENCE_ROOT to prevent symlink traversal breakouts.
• Findings are Indicators: Discrepancies and strings are only indicators. They are designed to assist human validation and must not be used as final legal proof of malware.