Sift Mcp

SIFT MCP

[](https://github.com/AppliedIR/sift-mcp/actions/workflows/ci.yml) [](https://github.com/AppliedIR/sift-mcp/blob/main/LICENSE)

Monorepo for all SIFT-side Valhuntir components. 11 packages: forensic-mcp (23 tools), case-mcp (15 tools), report-mcp (6 tools), sift-mcp (5 tools), sift-gateway, forensic-knowledge, forensic-rag (3 tools), windows-triage (13 tools), opencti (8 tools), sift-common, and case-dashboard. With optional opensearch-mcp (17 tools) for evidence indexing and querying at scale. Part of the Valhuntir platform.

Documentation · Getting Started · CLI Reference · MCP 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 is a forensic investigation platform that connects AI to structured MCP tools, enforces human-in-the-loop review, and maintains a complete audit trail from evidence to finding to report.

The platform 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.

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. OpenSearch integration is optional but recommended for investigations at scale.

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

What You Get

• Gateway with auth + lifecycle management (up to 90 tools across 8 backends)
• Evidence indexing — 15 parsers (evtx, EZ tools, Volatility, JSON, CSV, W3C, and more) with deterministic dedup and full provenance (via opensearch-mcp)
• Structured querying — case summary, search, aggregation, timeline, field enumeration, detection listing (via opensearch-mcp)
• Programmatic enrichment — triage baseline validation and threat intelligence stamping at index scale, zero LLM tokens (via opensearch-mcp)
• Examiner Portal — 8-tab browser UI for review, approval, and commit (findings, timeline, hosts, accounts, evidence, IOCs, TODOs, overview) with keyboard shortcuts, search, provenance chain display, and challenge-response authentication
• IOC auto-extraction from findings with approval cascade
• Evidence provenance chain linking findings back to registered evidence through audited tool executions
• RAG search — 22K+ forensic records (Sigma, MITRE ATT&CK, LOLBAS, Atomic Red Team, and more)
• Windows baseline validation — offline file/process/service validation against 2.6M known-good records
• Case management — init, activate, close, backup with SHA-256 manifest and verification
• Structured JSON case files with integrity verification
• Formal report generation (6 profiles) with Zeltser IR Writing guidance
• Audit trail — JSONL logs with SHA-256 hashes for every MCP tool call and Bash command
• Optional add-ons — OpenCTI threat intelligence, REMnux malware analysis, Microsoft Learn, Zeltser IR Writing

When Claude Code is the client, additional controls are deployed:

• Bubblewrap sandbox — kernel-level filesystem isolation, Bash restricted to project directory
• 41 permission deny rules — Edit/Write blocked on case data files (findings.json, timeline.json, approvals.jsonl, etc.)
• PreToolUse guard hook — blocks Bash redirections (>, >>, tee) to protected case files
• HMAC-signed findings — password-gated approval with PBKDF2-derived cryptographic signing
• Provenance enforcement — rejects findings that lack an evidence trail in the audit log
• PostToolUse audit hook — every Bash command logged to JSONL with SHA-256 hashes
• Prompt hook — forensic discipline reminders injected on every prompt

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.

Investigation Workflow

The recommended workflow uses OpenSearch for evidence indexing, enabling structured queries across millions of records. Without OpenSearch, the same investigation tools are available through direct file-based analysis via run_command — OpenSearch adds scale, not capability.

1. case_init("Ransomware Investigation")     → Create case, set examiner
2. evidence_register(path, description)       → SHA-256 hash, chain of custody
3. idx_ingest(case_dir, hostname)             → Parse + index into OpenSearch
4. idx_case_summary(case_id)                  → Hosts, artifacts, fields, time range
5. idx_search / idx_aggregate / idx_timeline  → Structured queries (~500 tokens each)
6. idx_enrich_triage + idx_enrich_intel       → Programmatic enrichment (zero tokens)
7. record_finding / record_timeline_event     → Stage as DRAFT with provenance
8. Examiner Portal or vhir approve            → Human review → APPROVED/REJECTED
9. generate_report(profile="full")            → IR report from approved findings

Without OpenSearch, steps 3-6 are replaced by direct tool execution (run_command) and manual analysis. The investigation workflow, findings, timeline, and reporting are identical either way.

Architecture

Each MCP backend runs as a stdio subprocess of the sift-gateway, aggregated behind a single HTTP endpoint. opensearch-mcp connects to a local or remote OpenSearch instance for evidence indexing and querying. The Examiner Portal is served by the gateway for browser-based review and approval. See the Valhuntir README for the full deployment topology including REMnux and Windows VMs.

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

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/windows-triage-mcp
http://localhost:4508/mcp/forensic-rag-mcp
http://localhost:4508/mcp/opencti-mcp
http://localhost:4508/mcp/opensearch-mcp

When the LLM client runs on a different machine, install with --remote to generate TLS certificates and a bearer token. The gateway binds to all interfaces and requires Authorization: Bearer on every request.

Deployment Configurations

All configurations run on a SIFT Workstation (Ubuntu-based) with Python 3.10+.

| Configuration | What runs on SIFT | RAM (min) | RAM (recommended) | Best for | |---|---|---|---|---| | Valhuntir | Gateway + 8 backends + OpenSearch (Docker) | 24 GB | 32 GB | Solo analyst, lab environments | | Valhuntir (remote OpenSearch) | Gateway + 8 backends; OpenSearch on separate host | 16 GB SIFT, 8 GB OS host | 16 GB SIFT, 16 GB OS host | Larger cases, persistent clusters | | Valhuntir + Windows | Above + wintools-mcp on Windows VM | +8 GB Windows | +8 GB Windows | Full artifact coverage | | Valhuntir + REMnux | Above + remnux-mcp on REMnux VM | +4 GB REMnux | +8 GB REMnux | Malware analysis | | [Valhuntir Lite](#valhuntir-lite) | No gateway, no OpenSearch — stdio MCPs only | 8 GB | 16 GB | Quick setup, smaller investigations |

Where the RAM goes (all-in-one Valhuntir):

• OpenSearch Docker: 4-12 GB heap (default 4 GB, increase for larger cases)
• Gateway + 8 MCP backends: ~2-3 GB (Python processes)
• RAG embedding model: ~2 GB (when forensic-rag is loaded)
• Evidence parsing during ingest: 1-4 GB (spikes during large ingests)
• OS + Docker overhead: ~2 GB

Disk space: ~14 GB for RAG + triage databases, plus evidence and OpenSearch indices.

Valhuntir Installation

Requires Python 3.10+ and sudo access. The installer handles everything: MCP servers, gateway, vhir CLI, HMAC verification ledger, examiner identity, and LLM client configuration. When you select Claude Code, the forensic controls listed above are deployed automatically.

Quick — Core platform only, no databases (~70 MB):

curl -fsSL https://raw.githubusercontent.com/AppliedIR/sift-mcp/main/quickstart.sh -o /tmp/vhir-quickstart.sh && bash /tmp/vhir-quickstart.sh

Recommended — Adds the RAG knowledge base (22,000+ records from 23 authoritative sources) and Windows triage databases (2.6M baseline records). Requires ~14 GB disk space:

• ~7 GB — ML dependencies (PyTorch, CUDA) required by the RAG embedding model
• ~6 GB — Windows triage baseline databases (2.6M rows, decompressed)
• ~1 GB — RAG index, source code, and everything else

curl -fsSL https://raw.githubusercontent.com/AppliedIR/sift-mcp/main/quickstart.sh -o /tmp/vhir-quickstart.sh && bash /tmp/vhir-quickstart.sh --recommended

Custom — Individual package selection, OpenSearch integration, OpenCTI, or remote access with TLS:

git clone https://github.com/AppliedIR/sift-mcp.git && cd sift-mcp
./setup-sift.sh

Adding OpenSearch — Add --opensearch to any install command to include evidence indexing. The installer clones the repo, installs the package, and sets up the OpenSearch Docker container automatically. Requires Docker.

bash /tmp/vhir-quickstart.sh --recommended --opensearch

If opensearch-mcp is already cloned alongside sift-mcp, the installer detects and installs it automatically — no flag needed.

Valhuntir Lite

In its simplest form, Valhuntir Lite provides Claude Code with forensic knowledge and instructions on how to enforce forensic rigor, present findings for human review, and audit actions taken. MCP servers enhance accuracy by providing authoritative information — a forensic knowledge RAG and a Windows triage database — plus optional OpenCTI threat intelligence and REMnux malware analysis.

Quick — Forensic discipline, MCP packages, and config. No databases ( DENY{"DenylistCheck"} DENY -->|"denied"| REJECT["Rejected"] DENY -->|"allowed"| EXEC["subprocess.run()shell=False"] EXEC --> PARSE["Parse Output"] PARSE --> CAT{"In Catalog?"} CAT -->|"yes"| ENRICH["FK Enrichment"] CAT -->|"no"| BASIC["Basic Envelope"] ENRICH --> RESP["Response Envelope"] BASIC --> RESP RESP --> AUDIT["Audit Entry"]

## MCP Tools

5 core tools on sift-mcp: 4 discovery + 1 generic execution.

### Discovery

| Tool | Description |
|------|-------------|
| `list_available_tools` | List cataloged tools (enriched) with availability status — uncataloged tools can also execute |
| `get_tool_help` | Usage info, flags, caveats, and FK knowledge for a tool |
| `check_tools` | Check which tools are installed and available |
| `suggest_tools` | Given an artifact type, suggest relevant tools with corroboration guidance |

### Generic Execution

| Tool | Description |
|------|-------------|
| `run_command` | Execute any forensic tool (denied binaries are blocked) |

All 30+ per-tool wrappers (Zimmerman suite, Sleuth Kit, Volatility, etc.) are consolidated into `run_command`. A small denylist blocks system-destructive binaries. Tools listed in the catalog get enriched responses with forensic-knowledge data. Uncataloged tools execute with basic response envelopes.

## What Can You Ask?

"Ingest all evidence from /cases/evidence/ into OpenSearch and give me a summary of the artifacts ingested"

"Show me all 4688 events where cmd.exe spawned from an unusual parent process"

"Aggregate the top 20 source IPs across all hosts and check them against threat intel"

"Run triage enrichment and show me anything flagged as suspicious"

"Parse the Amcache hive from workstation3"

"See if this registry value exists on any of the other hosts in OpenSearch"

"What tools should I use to investigate lateral movement artifacts?"

"Run hayabusa against the evtx logs and show critical/high alerts"

"Extract the $MFT and build a filesystem timeline"

"Analyze this memory dump with Volatility -- list processes and network connections"

"Check if svchost.exe with parent wsmprovhost.exe is normal"

"Look up this hash in threat intel"

"Upload this binary to REMnux and analyze it"

## Response Envelope

Every tool response is wrapped in a structured envelope enriched by forensic-knowledge (in `packages/forensic-knowledge/`). This ensures the LLM always receives artifact caveats, corroboration suggestions, and discipline reminders alongside tool output.

```json
{
  "success": true,
  "tool": "run_command",
  "data": {"output": {"rows": ["..."], "total_rows": 42}},
  "data_provenance": "tool_output_may_contain_untrusted_evidence",
  "audit_id": "sift-steve-20260220-001",
  "examiner": "steve",
  "caveats": [
    "Amcache entries indicate file presence, not execution"
  ],
  "advisories": [
    "This artifact does NOT prove: Program was executed by the user",
    "Amcache proves installation -- Prefetch is needed to confirm execution"
  ],
  "corroboration": {
    "for_execution": ["Prefetch", "UserAssist"],
    "for_timeline": ["$MFT timestamps", "USN Journal"]
  },
  "discipline_reminder": "Evidence is sovereign -- if results conflict with your hypothesis, revise the hypothesis, never reinterpret evidence to fit"
}

| Field | Description | |-------|-------------| | audit_id | Unique ID for referencing in findings (sift-{examiner}-YYYYMMDD-NNN) | | caveats | Tool-specific limitations from FK | | advisories | What the artifact does NOT prove, common misinterpretations | | corroboration | Suggested cross-references grouped by purpose | | field_notes | Timestamp field meanings and interpretation guidance | | discipline_reminder | Rotating forensic methodology reminder |

…

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
• Source: AppliedIR/sift-mcp
• License: MIT
• Homepage: https://appliedir.github.io/Valhuntir/

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