Valhuntir

Valhuntir

[](https://github.com/AppliedIR/Valhuntir/actions/workflows/ci.yml) [](https://appliedir.github.io/Valhuntir/) [](https://github.com/AppliedIR/Valhuntir/blob/main/LICENSE)

Valhuntir turns a single incident response analyst into the manager of an agentic AI incident response team. A host of MCP tools allows the AI to quickly ingest, process, and analyze massive amounts of digital forensic artifacts while keeping the human in control of the investigation and decision making process. Curated forensic knowledge bases, guidance and context hints, and processing suggestions are built into the system, but ultimately the human examiner drives the response.

Platform Documentation · CLI Reference

> Important Note — While extensively tested, this is a new platform. > ALWAYS verify results and guide the investigative process. If you just > tell Valhuntir to "Find Evil" it will more than likely hallucinate > rather than provide meaningful results. The AI can accelerate, but the > human must guide it and review all decisions.

Valhuntir — AI-Assisted Forensic Investigation

Valhuntir ensures accountability and enforces human review of findings through cryptographic signing, password-gated approvals, and multiple layered controls.

Valhuntir is LLM client agnostic — connect any locally installed MCP-compatible client through the gateway. Supported clients include Claude Code, Claude Desktop, Cherry Studio, self-hosted LibreChat, and any client that supports Streamable HTTP transport with Bearer token authentication. The client must run on your machine or local network — cloud-hosted services cannot reach internal gateway addresses. Forensic discipline is provided structurally at the gateway and MCP layer, not through client-specific prompt engineering, so the same rigor applies regardless of which AI model or client drives the investigation.

> Looking for a simpler setup without the gateway or OpenSearch? See [Valhuntir Lite](#valhuntir-lite).

Evidence Indexing with OpenSearch (Optional)

With opensearch-mcp, evidence is parsed programmatically and indexed into OpenSearch, giving the LLM 17 purpose-built query tools instead of consuming billions of tokens reading raw artifacts. A 30-host triage collection with 50 million records becomes instantly searchable. Triage baseline and threat intelligence enrichment run programmatically — zero LLM tokens consumed.

15 parsers cover the forensic evidence spectrum: Windows Event Logs (evtx), 10 EZ Tool artifact types (Shimcache, Amcache, MFT, USN, Registry, Shellbags, Jumplists, LNK, Recyclebin, Timeline), Volatility 3 memory forensics, JSON/JSONL (Suricata, tshark, Velociraptor), delimited (CSV, TSV, Zeek, bodyfile, supertimelines), Apache/Nginx access logs, W3C (IIS, HTTPERR, Windows Firewall), Windows Defender MPLog, Scheduled Tasks XML, Windows Error Reporting, SSH auth logs, PowerShell transcripts, and Prefetch/SRUM (via Plaso or wintools-mcp).

Every parser produces deterministic content-based document IDs (re-ingest = zero duplicates), full provenance (host.name, vhir.source_file, vhir.ingest_audit_id), and proper @timestamp with timezone handling. Hayabusa auto-detection runs after EVTX ingest, applying 3,700+ Sigma rules and indexing alerts for structured querying.

Investigation Workflow

1. Create a case — set case name, examiner identity, case directory
2. Register evidence — hash files, establish chain of custody
3. Ingest and index — parse evidence into OpenSearch for structured querying (or analyze files directly without OpenSearch)
4. Scope the investigation — review what's indexed, identify hosts and artifact types, check for Hayabusa detection alerts
5. Enrich programmatically — validate files/services against known-good baselines, check IOCs against threat intelligence (zero LLM tokens with opensearch-mcp)
6. Search and analyze — query across millions of records, aggregate patterns, build timelines
7. Record findings — LLM stages findings and timeline events as DRAFT with full evidence provenance
8. Human review — examiner approves or rejects each finding via the Examiner Portal or CLI (HMAC-signed)
9. Generate report — produce IR report from approved findings with MITRE mappings and IOC aggregation

Without OpenSearch, steps 3-6 are replaced by the LLM doing direct tool execution and analysis. Still very effective, but slower and with much higher token cost. Findings, timeline, approval workflow, and reporting are identical either way.

Required Resources

| Component | Role | RAM (min) | RAM (rec) | Disk | Notes | |-----------|------|-----------|-----------|------|-------| | Valhuntir with sift-mcp | Gateway + 8 MCP backends | 16 GB | 16 GB | 50 GB + evidence/extractions | SIFT Workstation (Ubuntu). Gateway capped at 4 GB. 24 GB for memory analysis with Volatility 3. | | Valhuntir + OpenSearch | Above + evidence indexing | 32 GB | 32 GB | 100 GB + evidence/extractions/indices | OpenSearch JVM 6 GB, container 8 GB. Can run on separate host. | | Valhuntir Lite | Stdio MCPs only, no gateway | 8 GB | 16 GB | 30 GB + evidence/extractions | No OpenSearch. Direct MCP from LLM client. | | OpenSearch (remote) | Dedicated indexing host | 12 GB | 16 GB | 100 GB + indices | Alternative to co-located. Connects via HTTPS. | | wintools-mcp | Windows forensic tools | 8 GB | 16 GB | 60 GB | Separate Windows VM to run Windows-only tools. | | REMnux | Malware analysis | 4 GB | 8 GB | 100 GB | Optional. Separate VM. Docs. | | OpenCTI | Threat intelligence | 16 GB | 32 GB | 50 GB SSD | Optional. Separate host. Docs. |

Platform Architecture

The examiner interacts with Valhuntir through three interfaces: the LLM client (AI-assisted investigation), the Examiner Portal (browser-based review and approval), and the vhir CLI (case management, evidence handling, and verification).

Deployment Overview

The typical deployment runs three VMs on a single host: SIFT (primary workstation), REMnux (malware analysis), and Windows (forensic tool execution). The examiner works on the SIFT VM — running the LLM client, the Examiner Portal in a browser, and the vhir CLI. REMnux and Windows are headless worker VMs. All three communicate over a VM-local network. Internet access is through NAT for external MCP services.

graph TB
    subgraph host ["Host Machine"]
        subgraph sift ["SIFT VM"]
            CC["LLM Client(human interface)"]
            BR["Browser(Examiner Portal)"]
            CLI["vhir CLI"]
            GW["sift-gateway :4508"]
            OSD["OpenSearch :9200(optional)"]
            CASE["Case Directory"]

            CC -->|"streamable-http"| GW
            BR -->|"HTTP"| GW
            GW -.->|"via opensearch-mcp"| OSD
            CLI --> CASE
        end

        subgraph remnux ["REMnux VM (optional)"]
            RAPI["remnux-mcp :3000"]
        end

        subgraph winbox ["Windows VM (optional)"]
            WAPI["wintools-mcp :4624"]
        end

        CC -->|"streamable-http"| RAPI
        GW -->|"HTTPS"| WAPI
        WAPI -->|"SMB"| CASE
    end

    subgraph internet ["Internet"]
        ML["MS Learn MCP"]
        ZE["Zeltser IR Writing MCP"]
        OCTI["OpenCTI (if external)"]
    end

    CC -->|"HTTPS"| ML
    CC -->|"HTTPS"| ZE
    GW -.->|"HTTP(S)"| OCTI

REMnux, Windows, and OpenSearch are optional. SIFT alone provides 73 MCP tools across 7 backends (90 with opensearch-mcp, 100 with wintools-mcp), the Examiner Portal, and full case management.

SIFT Platform Components

The sift-gateway aggregates up to 8 MCP backends as stdio subprocesses behind a single HTTP endpoint. Each backend is also available individually. The Examiner Portal is served by the gateway for browser-based review and approval. opensearch-mcp connects to a local or remote OpenSearch instance for evidence indexing and querying at scale.

graph LR
    GW["sift-gateway :4508"]

    FM["forensic-mcp23 tools · findings, timeline,evidence, discipline"]
    CM["case-mcp15 tools · case management,audit queries, backup"]
    RM["report-mcp6 tools · report generation,IOC aggregation"]
    SM["sift-mcp5 tools · Linux forensictool execution"]
    RAG["forensic-rag3 tools · semantic search22K records"]
    WT["windows-triage13 tools · offline baselinevalidation"]
    OC["opencti8 tools · threatintelligence"]
    OS["opensearch-mcp17 tools · evidence indexing,query, enrichment"]
    CD["Examiner Portalbrowser review + commit"]
    FK["forensic-knowledgeshared YAML data"]
    CASE["Case Directory"]
    OSD["OpenSearchDocker :9200"]

    GW -->|stdio| FM
    GW -->|stdio| CM
    GW -->|stdio| RM
    GW -->|stdio| SM
    GW -->|stdio| RAG
    GW -->|stdio| WT
    GW -->|stdio| OC
    GW -->|stdio| OS
    GW --> CD
    FM --> FK
    SM --> FK
    FM --> CASE
    CM --> CASE
    RM --> CASE
    CD --> CASE
    OS --> OSD

Human-in-the-Loop Workflow

All findings and timeline events are staged as DRAFT by the AI. Only a human examiner can approve or reject them — via the Examiner Portal (browser) or the vhir CLI. Both paths produce identical HMAC-signed approval records. The AI cannot approve its own findings. MCP guidance provides reminders to the LLM to check in with the human frequently for review and guidance.

sequenceDiagram
    participant AI as LLM + MCP Tools
    participant Case as Case Directory
    participant Human as Examiner(Portal or CLI)

    AI->>Case: record_finding() → DRAFT
    AI->>Case: record_timeline_event() → DRAFT
    Note over Case: Staged for review

    Human->>Case: Review, edit, approve/reject
    Human->>Case: Commit (password + HMAC signing)

    Note over Case: Only APPROVED itemsappear in reports
    Human->>Case: vhir report --full

The Examiner Portal (vhir portal) is the primary review interface — an 8-tab browser UI where examiners review, edit, approve, and reject findings and timeline events. The Commit button requires the examiner's password. The CLI's vhir approve provides the same capability from the terminal.

Examiners review findings in the Examiner Portal — validating artifacts, observations, and interpretations, with the full command audit trail from original evidence to final result.

The timeline view places findings and other observables in chronological context across the investigation.

Forensic Knowledge Reinforcement

Valhuntir reinforces forensic discipline through multiple layers built into the MCP servers, client configuration, and gateway — not through a single system prompt that the LLM can drift from during long sessions.

• Forensic Knowledge (FK) package — When a forensic tool is executed, the response is enriched with tool-specific caveats, corroboration suggestions, and field interpretation guidance. Delivered at the MCP response level, not in the system prompt, so it arrives exactly when the LLM needs it.
• Discipline reminders — Each tool response includes a rotating forensic methodology reminder. Finding validation checks submissions against methodology standards and returns actionable feedback.
• MCP server instructions — Each backend provides structured instructions during session initialization. The gateway aggregates them into a single coherent briefing.
• Client configuration — For Claude Code, vhir setup client deploys forensic discipline docs, investigation rules, and tool reference guides as persistent context. Other clients receive guidance through MCP server instructions.
• Forensic RAG — Semantic search across 22,000+ records from 23 authoritative sources (Sigma, MITRE ATT&CK, LOLBAS, Atomic Red Team, and more). Grounds LLM analysis in authoritative references rather than training data.
• Windows triage baseline — Offline validation against 2.6 million known-good records. No network calls required.

These layers reinforce each other through consistent, contextual repetition across all interaction surfaces. See the Architecture documentation for full details.

Where Things Run

| Component | Runs on | Port | Purpose | |-----------|---------|------|---------| | sift-gateway | SIFT | 4508 | Aggregates SIFT-local MCPs behind one HTTP endpoint | | forensic-mcp | SIFT | (via gateway) | Findings, timeline, evidence, TODOs, IOCs, discipline (23 tools) | | case-mcp | SIFT | (via gateway) | Case management, audit queries, evidence registration, backup (15 tools) | | report-mcp | SIFT | (via gateway) | Report generation with profiles, IOC aggregation, MITRE mapping (6 tools) | | sift-mcp | SIFT | (via gateway) | Denylist-protected forensic tool execution on Linux/SIFT (5 tools) | | opensearch-mcp | SIFT | (via gateway) | Evidence indexing, structured querying, enrichment (17 tools). Optional. | | forensic-rag-mcp | SIFT | (via gateway) | Semantic search across Sigma, MITRE ATT&CK, Atomic Red Team, and more (3 tools) | | windows-triage-mcp | SIFT | (via gateway) | Offline Windows baseline validation (13 tools) | | opencti-mcp | SIFT | (via gateway) | Threat intelligence from OpenCTI (8 tools) | | OpenSearch | SIFT (Docker) | 9200 | Evidence search engine. Local or remote. Optional. | | Examiner Portal | SIFT | (via gateway) | Browser-based review and approval. Primary review UI. | | wintools-mcp | Windows | 4624 | Catalog-gated forensic tool execution on Windows (10 tools) | | vhir CLI | SIFT | -- | Human-only: case init, evidence management, verification, exec. Approval also available via Examiner Portal. Remote examiners need SSH only for CLI-exclusive operations. | | forensic-knowledge | anywhere | -- | Shared YAML data package (tools, artifacts, discipline) |

The gateway exposes each backend as a separate MCP endpoint. Clients can connect to the aggregate endpoint or to individual backends:

http://localhost:4508/mcp              # Aggregate (all tools)
http://localhost:4508/mcp/forensic-mcp
http://localhost:4508/mcp/case-mcp
http://localhost:4508/mcp/report-mcp
http://localhost:4508/mcp/sift-mcp
http://localhost:4508/mcp/opensearch-mcp
http://localhost:4508/mcp/windows-triage-mcp
http://localhost:4508/mcp/forensic-rag-mcp
http://localhost:4508/mcp/opencti-mcp

Multi-Examiner Team

graph LR
    subgraph e1 ["Examiner 1 — SIFT Workstation"]
        CC1["LLM Client(human interface)"]
        BR1["Browser(human interface)"]
        CLI1["vhir CLI"]
        GW1["sift-gateway:4508"]
        MCPs1["forensic-mcp · case-mcp · report-mcpsift-mcp · forensic-rag-mcp · opensearch-mcpwindows-triage-mcp · opencti-mcp"]
        CASE1["Case Directory"]

        CC1 -->|"streamable-http"| GW1
        BR1 -->|"HTTP"| GW1
        GW1 -->|stdio| MCPs1
        MCPs1 --> CASE1
        CLI1 --> CASE1
    end

    subgraph e2 ["Examiner 2 — SIFT Workstation"]
        CC2["LLM Client(human interface)"]
        BR2["Browser(human interface)"]
        CLI2["vhir CLI"]
        GW2["sift-gateway:4508"]
        MCPs2["forensic-mcp · case-mcp · report-mcpsift-mcp · forensic-rag-mcp · opensearch-mcpwindows-triage-mcp · opencti-mcp"]
        CASE2["Case Directory"]

        CC2 -->|"streamable-http"| GW2
        BR2 -->|"HTTP"| GW2
        GW2 -->|stdio| MCPs2
        MCPs2 --> CASE2
        CLI2 --> CASE2
    end

    CASE1 |"export / merge"| CASE2

Case Directory Structure

cases/INC-2026-0219/
├── CASE.yaml                    # Case metadata (name, status, examiner)
├── evidence/                    # Original evidence (lock with vhir evidence lock)
├── extractions/                 # Extracted artifacts
├── reports/                     # Generated reports
├── findings.json                # F-alice-001, F-alice-002, ...
├── timeline.json

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AppliedIR](https://github.com/AppliedIR)
- **Source:** [AppliedIR/Valhuntir](https://github.com/AppliedIR/Valhuntir)
- **License:** MIT
- **Homepage:** https://appliedir.github.io/Valhuntir/

Install and usage instructions live in the source repository linked above.