SIFTAgent

A typed, audited MCP server that turns Claude Code into an autonomous DFIR analyst on the SANS SIFT Workstation.

Built for the SANS FIND EVIL! hackathon. SIFTAgent is the Custom MCP Server architecture — the approach the hackathon's own materials call "the most architecturally sound" — designed specifically to beat Protocol SIFT's hallucination baseline.

Why this design wins on the judging criteria

Criterion	How SIFTAgent addresses it
Autonomous execution quality	A playbook (playbooks/INVESTIGATION.md) drives a hypothesize → run → verify → self-correct loop. The agent retracts unsupported findings instead of asserting them.
IR accuracy	Findings cannot be recorded without citing real execution_ids that exist in the audit log — fabricated evidence is rejected at the API. Confidence levels separate confirmed from inferred.
Breadth & depth	Typed tools across disk (Sleuth Kit), memory (Volatility 3), timeline (plaso), registry (RegRipper), strings/IOCs, YARA, hashing.
Constraint implementation	Architectural, not prompt-based guardrails: a binary allowlist of read-only forensic tools, no shell=True anywhere, no generic "run command" path, write-flag rejection. Evidence cannot be modified.
Audit trail quality	Append-only JSONL log; every execution has a timestamp, exact argv, runtime, and SHA-256 output hash. Any finding links back to a specific tool execution.
Usability	One-command install, mock mode for offline testing, full test suite.

Architecture

See docs/ARCHITECTURE.md (diagram + security boundaries). In short:

Claude Code  ──MCP(stdio)──►  SIFTAgent server
                                  │
            ┌─────────────────────┼───────────────────────┐
            ▼                     ▼                       ▼
     runner.py (guardrails)   case.py (findings)     iocs.py (parsing)
       binary allowlist        evidence-cited           pure python
       no shell, read-only     verify/retract
            │                     │
            ▼                     ▼
   SIFT binaries  ───────►  audit.jsonl (timestamped, hashed)
   (tsk, vol3, plaso,            ▲
    regripper, yara)             │
                          incident-report.md (cites execution_ids)

Install on the SIFT Workstation

# On the SANS SIFT Workstation (Ubuntu-based; sleuthkit, volatility3,
# plaso, regripper, yara are pre-installed):
git clone <your-repo-url> siftagent && cd siftagent
python3 -m pip install -r requirements.txt   # installs the `mcp` SDK

Connect to Claude Code

Add to your Claude Code MCP config (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "siftagent": {
      "command": "python3",
      "args": ["-m", "siftagent.server"],
      "cwd": "/home/sansforensics/siftagent",
      "env": { "SIFTAGENT_LOG_DIR": "/cases/host01/logs" }
    }
  }
}

Then in Claude Code, paste playbooks/INVESTIGATION.md as your system steer (or reference it) and say: "Investigate /cases/host01.E01 and /cases/host01.mem."

Run an investigation

Live (on SIFT):

export SIFTAGENT_LOG_DIR=/cases/host01/logs
# Claude Code drives the MCP tools per the playbook.

Offline / mock mode (Windows, macOS, CI — no SIFT needed):

SIFTAGENT_MODE=mock python -m siftagent.investigate
# Prints an evidence-cited incident report from synthetic fixtures.

SIFTAGENT_MODE=mock serves canned tool output from siftagent/fixtures/, so the whole agent loop is reproducible without a disk image. Setting SIFTAGENT_ALLOW_MOCK_FALLBACK=1 falls back to fixtures only when a binary is absent — useful for partial environments.

Tools exposed

Case layer: open_case, add_hypothesis, update_hypothesis, add_finding, verify_finding, retract_finding, generate_report, get_audit_entry.

Forensics: disk_partitions, disk_fs_info, disk_list_files, disk_file_metadata, disk_read_file, timeline_bodyfile, timeline_plaso, timeline_query, memory_analyze, registry_analyze, extract_strings, extract_iocs, hash_file, file_type, yara_scan.

Tests

python -m pytest -q        # 18 tests, all offline via fixtures

Covers guardrail enforcement, anti-hallucination citation checks, IOC parsing, and the full investigation pipeline including a self-correction/retraction case.

License

Apache-2.0. See LICENSE.