# Forensic Artifact Investigator MCP 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](#how-it-works)
2. [Supported Platforms & Installation](#supported-platforms--installation)
   - [Linux (Debian/Ubuntu/CentOS)](#linux-debianubuntucentos)
   - [Windows (Native & WSL)](#windows-native--wsl)
3. [Configuration (.env)](#configuration-env)
4. [MCP Protocol Surface Reference](#mcp-protocol-surface-reference)
   - [Tools (Input & Output Examples)](#tools-input--output-examples)
   - [Resources (Schema & Output Examples)](#resources-schema--output-examples)
   - [Prompts](#prompts)
   - [Widgets](#widgets)
5. [Setting Up in Client Harnesses](#setting-up-in-client-harnesses)
   - [Claude Code](#claude-code)
   - [Cursor](#cursor)
   - [Claude Desktop](#claude-desktop)
6. [Development, Build, and Testing](#development-build-and-testing)
7. [Security and Forensic Guidelines](#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:
```bash
sudo apt-get update
sudo apt-get install -y file libimage-exiftool-perl binutils python3 python3-pip python3-venv
```
On CentOS/RHEL (EPEL required):
```bash
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:
```bash
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](https://nodejs.org/).
2. **File Utility:** Install git-bash or downoad the native Win32 `file` command via [Git for Windows](https://git-scm.com/download/win), then add it to your System PATH.
3. **ExifTool:** Download the stand-alone Windows executable from [exiftool.org](https://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](https://learn.microsoft.com/en-us/sysinternals/downloads/strings) and add it to your PATH.
5. **Volatility 3:**
   - Install Python 3 via the Microsoft Store or Python website.
   - Install Volatility 3 using PowerShell:
     ```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`:

```env
# 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:**
  ```json
  {
    "filePath": "/evidence/suspect_photo.jpg"
  }
  ```
* **Response Example:**
  ```json
  {
    "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:**
  ```json
  {
    "filePath": "/evidence/suspect_photo.jpg"
  }
  ```
* **Response Example:**
  ```json
  {
    "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:**
  ```json
  {
    "filePath": "/evidence/winmem.raw"
  }
  ```
* **Response Example (Truncated):**
  ```json
  {
    "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:
  ```json
  {
    "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:
```bash
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):

```json
{
  "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:**
  ```bash
  npm install
  ```
- **Run Typechecking:**
  ```bash
  npm run typecheck
  ```
- **Run Tests (Vitest):**
  ```bash
  npm test
  ```
- **Build Server and Widgets:**
  ```bash
  npm run build
  ```
- **Run Server Locally:**
  ```bash
  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.