agentropix-mcp

A governed Model Context Protocol (MCP) server for digital-forensics and incident-response (DFIR) work, submitted to the SANS Find Evil! 2026 hackathon. The server exposes a curated set of Volatility 3, Plaso / log2timeline, RegRipper, Eric Zimmerman tools, and supporting forensic utilities through a single FastMCP HTTP endpoint, with:

• Bearer-token authentication on every HTTP /mcp request. Boot-time fail-closed if AGENTROPIX_MCP_AUTH_TOKEN is unset. Per-request enforcement verified end-to-end on 2026-05-23: missing/bad token → HTTP 401; valid token → MCP initialize succeeds. FastMCP version is pinned to <3.0 until the bearer-token middleware is migrated to FastMCP 3.x's native auth system — see docs/QUICKSTART.md §3.1.

• Tamper-evident audit log at /var/log/agentropix/http_audit.log — one JSON line per request, peer-sealed alongside the run report and cross-bound so post-run tampering of either is detectable

• Architectural read-only policy on evidence directories (no agent can write to evidence, even if it tries) — enforced before the tool subprocess is even spawned

• Structured JSON output from every tool — no raw terminal text flows out; all 46 tools serialize through Pydantic models so a client can reason over the result

The server is transport-agnostic (stdio for local use, HTTP for remote / Tailscale exposure) and runs as a normal Python process — no daemon infrastructure required.

Status

Architecture (one-line)

client (Claude Desktop / Cursor / Cline / Zed)
       ↓  Bearer-token-authenticated HTTP/MCP
   FastMCP app  ──  Audit middleware  ──  Read-only policy gate
       ↓
   Tool wrappers (Pydantic-typed)
       ↓
   External tools (vol3, plaso, regripper, ezcmd, exiftool, yara, ...)

The Custom MCP Server pattern is identified by the hackathon rules as "the most sound architecture in the evaluation" — this submission is the production-grade reference implementation.

Quickstart

(Placeholder — finalized after extraction completes.)

uv sync
uv run python -m agentropix_mcp.fastmcp_app --transport http --host 127.0.0.1 --port 8765

Documentation

The full submission documentation suite lives under docs/. Start at the index:

→ docs/INDEX.md — single navigation hub with reading orders per audience.

Direct links:

• PROJECT-DESCRIPTION.md — big-picture overview (start here for a 10-min scan)

• USER-GUIDE.md — operator-facing walkthrough, golden-path journey, anti-goals

• ARCHITECTURE.md — Devpost D4 Constraint Implementation deep dive, boundary catalogue + Mermaid diagram

• AGENTS.md — Devpost D1 Autonomous Execution Quality deep dive, planner/reviewer mechanics

• DESIGN-DECISIONS.md — ADR rollup, trade-offs, competitive positioning

• ACCURACY-REPORT.md — Devpost D2 IR Accuracy self-assessment

• AI-DISCLOSURE.md — AI models used + reproducibility + Anthropic-API data-handling boundary

• DATASET.md — Devpost D3 dataset documentation (7 disks + 22 SRL-2018 memory + 25 SRL-2015 memory + nromanoff PST + TeamSpy fixture)

• DEMO-NARRATION.md — ≤5-min demo video narration script + shot list + production checklist (operator-facing)

• SANS-PRESENTATION.md — judge-facing 12-slide presentation of features + qualities + independent 10-persona evaluation (77.95/100 ADEQUATE)

• POC-VIDEOS-PLAN.md — 5 ≤4-min proof-of-concept video plan (one per Devpost dimension; real SRL-2018 / SRL-2015 evidence; production checklists)

• QUICKSTART.md — battle-tested 10-minute walkthrough on a clean SIFT Workstation 2024.x VM

• MAINTENANCE.md — dual-repo sync mechanics for maintainers

• adr/, runbooks/ — placeholder directories; canonical content lives in the private source-of-truth repo

Recommended reading orders are in docs/INDEX.md under "Reading orders (by audience)".

Submission components (Devpost D2 §4)

• Code repository — this repo

• Architecture diagram

• Demo video (≤5 min, hosted on YouTube/Vimeo/Youku, ≥1 self-correction sequence)

• Written Project Description

• Accuracy Report

• Dataset documentation

• AI-disclosure / reproducibility statement

• Submission form on Devpost portal

License

Apache 2.0 — see LICENSE.