agentropix-mcp
galvangabriel-web/agentropix-mcp
Agentropix is a governed Model Context Protocol (MCP) server for digital forensics and incident response. It wraps battle-tested DFIR tooling—Plaso, Volatility 3, Sleuth Kit, YARA, EZ Tools—behind safety-gated, auditable AI-agent tools that map evidence to MITRE ATT&CK for autonomous, court-defensible analysis.
Instalação
npx convez-ai galvangabriel-web/agentropix-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Agentropix-SIFT
Autonomous DFIR triage on the SANS SIFT Workstation — that never lets the LLM rate its own findings.
Point it at a Windows disk or memory image. It drives 16 real SIFT forensic tools through one MCP server (71 tools), correlates across a 7-agent swarm on a quorum blackboard, and emits a cryptographically sealed, schema-validated JSON triage report — in minutes, on the local host, with no LLM ever in the halt path. (Source:
what-is-agentropix.md.)
A local, CLI-driven, bio-agentic DFIR triage engine for the SANS SIFT Workstation.
⚡ Connect in 60 seconds
🚀 Already have a SIFT host running on our tailnet? Point Claude at it right now — no install, no build. One command and you're driving 71 forensic tools from Claude. Full guide → docs/09-integrations/client-setup.md.
[!NOTE] First: join the tailnet (one-time). The server
http://100.85.162.82:8765/mcpis tailnet-only — reachable through Tailscale, never the public internet. Before the steps below:
- Accept the invite and sign in with your Google / Microsoft identity → Tailscale invite (then ping the operator to approve your device).
- Install the Tailscale client — macOS
brew install --cask tailscale· Windows MSI · Linuxcurl -fsSL https://tailscale.com/install.sh | sh && sudo tailscale up- Verify:
tailscale statuslistssiftworkstation … 100.85.162.82, andping 100.85.162.82succeeds.Full per-OS install + a combined token-and-reachability probe: Client Setup → Step 1.
You only need ONE client. Most people want the Claude Code CLI.
▶ Client A — Claude Code CLI (recommended — one line, all platforms)
claude mcp add --transport http agentropix-sift \
"http://100.85.162.82:8765/mcp" \
--header "Authorization: Bearer jlviTMFYAsAuxL1AiagDvFChIs4baYHe6OeRAdBzaLs"
Verify:
claude mcp list
# Expected: agentropix-sift http://100.85.162.82:8765/mcp ✓ Connected
▶ Client B — Claude Desktop App (via the mcp-remote shim)
Claude Desktop speaks stdio only, so it bridges to the HTTP server through the npx mcp-remote shim.
Prerequisite: Node.js ≥ 18 on PATH (node --version); install LTS from https://nodejs.org/ if missing.
1. Find your config file:
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
2. Edit it (create if absent). The command differs per OS — Windows uses npx.cmd, macOS/Linux use bare npx:
{
"mcpServers": {
"agentropix-sift": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://100.85.162.82:8765/mcp",
"--allow-http",
"--header",
"Authorization: Bearer jlviTMFYAsAuxL1AiagDvFChIs4baYHe6OeRAdBzaLs"
],
"env": {}
}
}
}
{
"mcpServers": {
"agentropix-sift": {
"command": "npx.cmd",
"args": [
"-y",
"mcp-remote",
"http://100.85.162.82:8765/mcp",
"--allow-http",
"--header",
"Authorization: Bearer jlviTMFYAsAuxL1AiagDvFChIs4baYHe6OeRAdBzaLs"
],
"env": {}
}
}
}
3. Restart Claude Desktop — fully quit (⌘Q / tray → Quit) and relaunch, not just close the window.
✅ Smoke-test it
Ask the model:
"Use the agentropix-sift MCP server. Run the
healthtool and tell me the tool_count."
Expected: tool_count: 72 (the live count is authoritative — this number may lag).
First time on the tailnet, or hit a
401/ timeout? The complete quickstart — Tailscale invite, per-OS install, token facts, and a full troubleshooting matrix — is in 📘 Client Setup — Install Quickstart.
Start here — pick your lane
Four audiences, four fast paths. Each row is an ordered reading trail; the full routing lives in the Documentation Index.
| You are a… | You want to… | Start here → then |
|---|---|---|
| 🧑💻 Software engineer | understand the architecture, build/test/extend it | Implementation → Trinity Loop → Swarm & Blackboard → FastMCP Server → Testing → ADRs (decision contract) |
| 🛡️ SOC analyst | run a triage, hunt IOCs, push to the SIEM | User Guide (runbook) → Disk triage → Memory triage → Wazuh push → CLI Reference |
| ⚖️ Evaluator / judge | verify the claims, soundness, chain of custody | Canonical Facts → Anti-Hallucination → Audit & Courtroom Seal → Recall methodology → Evaluation scorecard → SWOT |
| 💬 End-user (non-technical) | get answers by just asking Claude | the Two Paths table below → end-user lanes in the User Guide → Tool Capability Map |
👋 First time? The single best entry point is the User Guide — The Complete Operator Runbook: one complete case, end-to-end (pre-flight → connect/verify the MCP → init/activate the case → register evidence → the investigation tool chain → record findings → approve in the portal → seal the report → optional Wazuh push), documenting both execution paths (manual · autonomous) and both clients (Claude CLI · Claude Desktop), with the validated 2026-05-29 CFReDS run as a worked example.
What it is — and why
Agentropix-SIFT turns a SIFT Workstation into an autonomous-but-accountable triage operator. A Trinity Loop — an Architect that proposes which agents to run, a 7-agent Swarm that drives deterministic forensic tools, and a Critic that scores findings and halts on a deterministic convergence fingerprint (with no LLM self-rating) — orchestrates 71 MCP tools over a single FastMCP server. The result is a fast first pass over disk images, memory dumps, and Windows artifacts that produces an evidence-grounded, cryptographically sealed triage report a human examiner can trust and defend.
Its central claim is simple and load-bearing: the LLM never touches a fact. Every finding it records is produced by a deterministic forensic binary, fingerprinted with SHA-256, and tagged with a provenance tier — precisely so a human can verify it.
Important — this is a triage accelerator, not an oracle. Agentropix-SIFT is built to be checked, not believed. The LLM proposes and narrates; it never rates its own work and never becomes the source of a finding. You remain the examiner of record. Review the findings, confirm the underlying artifacts, and use the optional human-in-the-loop approval gate before anything is sealed or escalated. See Anti-Hallucination.
How AI drives Agentropix — the consumer model
The novel angle is where the AI sits. Agentropix-SIFT is deterministic layers with the stochastic LLM confined to the top. The LLM is not an oracle wired into the findings — it is simply a consumer of the same FastMCP tool surface that the CLI uses. From the MCP boundary down, everything is pure Python driving classical forensic binaries: no RNG, no LLM self-rating.
You drive it two ways from one engine: as a plain agentropix-sift run command, or by talking to an
LLM (Claude Desktop / Claude Code) that has the MCP server connected. A non-technical examiner can type
"open a case for this disk image and run the SIFT triage" and the session routes it to the real MCP
tools; an expert calls the exact tool. Adapt Agentropix to the user, not the user to Agentropix.

flowchart TB
classDef stoch fill:#fff5e6,stroke:#f59f00,color:#222,stroke-width:2px
classDef det fill:#e6ffea,stroke:#2f9e44,color:#222,stroke-width:2px
classDef anchor fill:#eef2ff,stroke:#3b5bdb,color:#222,stroke-width:2px
classDef leak fill:#fff0f0,stroke:#e03131,color:#222,stroke-width:2px
LLM["<b>Consumer (LLM or CLI)</b><br/>Claude Code / Desktop / cli.py<br/><i>stochastic only when LLM-driven</i>"]:::stoch
subgraph TR["Trinity Loop — deterministic, no LLM authoring"]
ARCH["<b>Architect</b> · plan()<br/>order/prune SWARM<br/>trinity/architect.py"]:::det
CRIT["<b>Critic</b> · score()/halt<br/>convergence fingerprint<br/>trinity/critic.py"]:::det
end
subgraph SW["Swarm — 13 SwarmAgent classes"]
AGENTS["7 specialists + 6 ATT&CK detectors<br/>agents/ · detectors/"]:::det
BB[("Blackboard<br/>(agent, Finding) registry<br/>correlations() at quorum")]:::anchor
end
subgraph MCP["MCP boundary — the enforcement spine"]
TOOLS["71 MCP tools<br/>traced · rate-limited · Thymus-gated"]:::det
BIN["SIFT binaries<br/>vol3 / plaso / tsk / yara / EZ-Tools"]:::leak
end
LLM -- "args_hash + raw_output cross the boundary" --> ARCH
ARCH -- "ordered plan" --> AGENTS
AGENTS -- "publish Finding" --> BB
AGENTS -- "tools/call" --> TOOLS
TOOLS --> BIN
BB --> CRIT
CRIT -- "stable_agents (next iteration)" --> ARCH
📐 Rendered as a high-resolution PNG so it displays crisply on GitHub and GitLab — Open as SVG (vector, zoomable).
- One tool surface, two consumers. The same
@app.tool()functions the swarm calls are also exposed to an LLM client; the server is built by_build_app()/FastMCP("agentropix-sift")(mcp_server/fastmcp_app.py). The package installs two console scripts:agentropix-sift(triage CLI) andagentropix-sift-mcp(the MCP server). An LLM connects to the latter; the CLI bypasses it and drives the engine directly. See The FastMCP Server. - Two transports. The MCP server speaks stdio (default — paired with a Claude Desktop / Claude
Code
mcp.jsonentry) or HTTP+SSE under/mcp(tailnet-only, Bearer-gated, default port 8765). Both funnel into the same tool core. See Connect a Client. - The LLM proposes, never authors. The
args_hash+ boundedraw_outputsnapshot is captured at the MCP boundary, so a sealed report can prove the LLM phrased a request three ways but never authored — or touched — a fact. Agents are pure async coroutines over the MCP boundary, with no LLM coupling (agents/_base.py).
"Agent" means two different things here. The runtime DFIR swarm agent (a
SwarmAgentsubclass that investigates evidence) is unrelated to the build-time BMAD dev-crew persona. Section 10 disambiguates them — read The Agentic Architecture first whenever the word is ambiguous.
What you get — capability highlights
| Capability | The one-line value | Canonical figure | Source-code home |
|---|---|---|---|
| Trinity Loop | Deterministic Architect → Swarm → Critic control loop; halts on a convergence fingerprint, never on an LLM self-rating | Critic halt default 0.85 | trinity/architect.py, trinity/critic.py, orchestrator.py |
| 71 MCP tools | One FastMCP server exposes 71 distinct forensic tools over stdio + HTTP | 71 tools | mcp_server/fastmcp_app.py |
| 16 SIFT wrappers | Hardened drivers (timeout, memory ceiling, retry, stderr capture, tracing) around the 16 trusted SIFT binaries | 16 wrappers | mcp_server/wrappers/ |
| 7-agent Swarm + ATT&CK detectors | Memory, Timeline, Filesystem, Artifact, Discovery, Mail, Hunt specialists + 6 deterministic MITRE ATT&CK detectors | 7 specialists (13 SWARM classes) | agents/, detectors/ |
| Quorum Blackboard | An observation is promoted to a Correlation only when enough agents corroborate the same token | quorum default 2 | agents/_blackboard.py |
| Thymus read-only policy | Every mcp_* call is checked against a path allowlist before any subprocess spawns — evidence is structurally read-only (no write tool exists) | deny-by-default | mcp_server/thymus_policy.py |
| Courtroom seal | SHA-256 evidence byte-binding + HMAC-SHA256 report/audit-log seal → a report a judge can independently verify | mode-0600 session key | courtroom.py |
| Provenance & grounding | Every Finding._source names the tool that produced it; inference_constraint = high; per-row HMAC chain validation | 3 grounding layers | agents/_base.py, provenance/validate.py |
| Approval sidecar (HITL) | Optional HMAC examiner sign-off: PBKDF2 key (600k iters) + nonce + append-only approval hash chain + browser form | 2 MCP tools | approval_sidecar/ |
| Wazuh SIEM push | Promote findings/IOCs into Wazuh behind default-deny kill switches + active-response CIDR guard | 5 Wazuh tools | wazuh/ |
| Chaos-tested resilience | Fault-injection tests prove graceful degradation: a missing tool skips an agent, not the run | chaos test marker | tests/chaos/ |
Full capability matrix: What You Get.
Architecture
The shape: one deterministic loop over one tool server, with a safety spine.
A DFIR examiner drives Agentropix-SIFT from the CLI on a local SIFT host. The engine never reaches outside that host except for the optional Wazuh push of already-APPROVED findings.

flowchart TB
classDef actor fill:#d0bfff,stroke:#7048e8,color:#2b1a52,stroke-width:2px
classDef core fill:#b2f2bb,stroke:#2f9e44,color:#15391f,stroke-width:2px
classDef ext fill:#e9ecef,stroke:#495057,color:#212529,stroke-width:1px
classDef sink fill:#ffec99,stroke:#f08c00,color:#5c4400,stroke-width:1.5px
Examiner(["DFIR Examiner<br/>runs triage · reviews · approves findings"]):::actor
subgraph Host["SANS SIFT Workstation — local host"]
Agentropix["Agentropix-SIFT<br/>Trinity Loop engine + FastMCP server (71 tools)"]:::core
Toolchain["SIFT Forensic Toolchain<br/>Volatility3 · Plaso · Sleuth Kit · EVTX · YARA · … (16 tools)"]:::ext
Evidence[("Evidence Store<br/>E01 / raw / memory — read-only")]:::ext
end
Wazuh["Wazuh / SIEM<br/>optional alert sink for APPROVED findings"]:::sink
Examiner -->|"agentropix-sift run / review / approve"| Agentropix
Agentropix -->|"invokes deterministic binaries (read-only)"| Toolchain
Agentropix -->|"reads + SHA-256 fingerprints, never mutates"| Evidence
Agentropix -->|"pushes APPROVED findings (optional)"| Wazuh
style Host fill:#f1f3f5,stroke:#868e96,color:#212529
📐 Rendered as a high-resolution PNG so it displays crisply on GitHub and GitLab — Open as SVG (vector, zoomable).
Internally, the Architect proposes which agents to spawn (by default it returns the canonical
SWARM tuple in priority order; a default-on Reflexion-lite step drops agents the Critic marked
stable). The 7-agent Swarm invokes the 16 wrapped SIFT forensic tools through the FastMCP server's
71-tool surface, writing Findings to a shared Blackboard; cross-agent agreement at a quorum of
2 becomes a Correlation. The Critic scores the accumulated findings with a closed-form rule —
score = min(1.0, max_confidence + 0.25 · len(correlations)) — and halts deterministically when the
findings stop changing (a convergence fingerprint), bounded by a hard max_iterations budget, never
on an LLM's self-assessed confidence. The Thymus read-only policy and the pre/post SHA-256
evidence invariant sit between every tool and the evidence store. Finally the Courtroom seals the
audit log with HMAC-SHA256 and validates the provenance chain.
📐 The validated architecture diagram — one page, source-verified
The complete picture lives in Main Architectural Agentropix Design — one validated diagram covering the agent layer → MCP server → SIFT Workstation tools → data sources → output pipeline, the architectural-pattern verdict (Custom MCP Server — and why it is not a Direct Agent Extension, Multi-Agent Framework, or Agentic IDE), and the full ARCHITECTURAL vs PROMPT-BASED guardrail split with every row cited to its enforcing source file. Every component was contrasted against the oracle source code; every documentation-vs-source disagreement is called out on the page.
📕 Full document as high-quality PDF (the complete design document — diagram, component narrative, pattern verdict, guardrail table) · 📄 Diagram-only HD PDF (vector) · 🖼️ PNG · 🔍 SVG
For the deeper layers: System Context & Containers · Component Architecture & Layer Map · The Trinity Loop · Sequence Diagrams.
Key design decisions (the decision contract)
The architecture is contracted in immutable Architecture Decision Records mirrored from the oracle. The load-bearing ones for newcomers:
| ADR | Decision |
|---|---|
| ADR-002 — Execution engine | The deterministic Trinity Loop as the execution model. |
| ADR-008 — Safety architecture | The deny-by-default Thymus boundary + evidence read-only invariant. |
| ADR-011 — Evidence gates | Pre/post SHA-256 evidence-integrity gates. |
| ADR-016 — Courtroom audit / ADR-022 — Audit-log seal | HMAC-SHA256 tamper-evident chain of custody. |
| ADR-017 — Tailnet MCP exposure | HTTP transport is tailnet-only + Bearer-gated. |
| ADR-018 — Wazuh IOC push / ADR-019 — AR confirmation gate | Default-deny SIEM push + active-response confirmation. |
Read the status column literally (Proposed ⇒ not shipped; Deferred ⇒ documented, not implemented). Full index: ADR Index · Section 11 — ADRs · rationale narratives in Design Decisions.
🌈 Recommended investigation workflow
🚀 One prompt. Six guarded stages. A sealed, court-ready report.
You don't need to memorise a single flag. Connect the Agentropix MCP to Claude, then say what you want in plain English — "open a case for this disk image and run the full SIFT triage" — and the session routes your words to real forensic tools. The six stages below run the same whether an expert types the command or a non-technical examiner just asks. Adapt Agentropix to the user, not the user to Agentropix.

🔍 Rendered as PNG so it shows inline on every browser — Open as SVG (full size, zoomable).
The vivid lane below is the load-bearing part: each stage shows both ways to reach the same result — the 🖥️ expert command and the 💬 plain-language prompt a non-technical examiner types into a Claude session that has the Agentropix MCP connected. Every prompt maps to a real MCP tool (verify against the Tool Capability Map).
🟣 ① doctor — pre-flight the toolchain
🖥️ Expert (command):
uv run agentropix-sift doctor💬 End-user (prompt): "Check that my Agentropix forensic environment is ready — are all the SIFT tools installed and on PATH?" → routes to
doctor/health.
Confirms the 16 SIFT forensic binaries resolve before you spend time on an image. Missing tools degrade gracefully (the agent is skipped, not the run) — but recall drops, so always start here.
🔵 ② run — Trinity Loop triages the image end-to-end
🖥️ Expert (command):
uv run agentropix-sift run /cases/INC-0605/disk.E01 -o report.json💬 End-user (prompt): "Open a high-severity case for the image at
/cases/INC-0605/disk.E01, register it as evidence, and run the full SIFT triage end-to-end — acquisition → examination → analysis → findings — staging everything as DRAFT." → routes tocase_init→case_activate→evidence_register→ the forensic tool chain →record_finding.
The Architect proposes which agents to run → the 7-agent Swarm drives deterministic tools → the Critic scores findings and halts on a convergence fingerprint, never on an LLM self-rating.
🟠 ③ review — the examiner verifies every finding
💬 End-user (prompt): "Show me the findings so far, and for each one tell me which exact tool produced it and the artifact path /
raw_stdout_sha256so I can verify it myself." → routes tocase_status/record_findinginspection.
A human reads the findings and checks them against the underlying artifacts. The LLM proposes and narrates — you remain the examiner of record.
🟢 ④ approve (optional HITL gate) — DRAFT → APPROVED
🖥️ Expert (command): promote DRAFT → APPROVED in the Approval Portal (HMAC examiner sign-off). 💬 End-user (prompt): "Show me the findings waiting for review so I can approve them." → the approval is a human HMAC hard-stop (
approve_finding); the examiner signs off in the browser form.
Findings stay in DRAFT until a human approves them. This is the one place a person — not a model — must act before anything is sealed or escalated.
🔴 ⑤ seal — Courtroom emits the audit seal
💬 End-user (prompt): "Generate the full report for this case and seal it — then confirm the seal hasn't been tampered with." → routes to
report_generate→ the HMAC-SHA256 audit seal + provenance-chain validation (report_exportfor the shareable artifact).
A tamper-evident chain of custody a judge can independently verify.
🟦 ⑥ escalate (optional) — push to the SIEM
🖥️ Expert (command): push APPROVED findings/IOCs to Wazuh behind default-deny kill switches. 💬 End-user (prompt): "Dry-run the Wazuh push of the approved IOCs and tell me what would be sent before anything goes out." → routes to
wazuh_index_findings/wazuh_publish_iocs(default-deny, dry-run first).
💬 Drive the entire investigation with a single prompt
Paste this into a Claude Desktop / Claude CLI session that has the Agentropix MCP attached — the agent runs the whole sequence itself, handling OS quirks (e.g. Windows XP has no Amcache /
.evtx):"You are a DFIR analyst with the Agentropix MCP. Investigate case
<case_id>on image<path>. Run the full SIFT sequence — acquisition → examination → analysis → findings — staging findings as DRAFT. For memory images, pull processes, network connections, injected code and services. Do not approve findings (a human owns that gate). Finish by generating the full report and summarising the attack chain."🖥️ Expert note: the same prompt works in
claude --printfor a one-shot headless run. The full validated end-to-end runbook — both clients (CLI · Desktop), both lanes (manual · autonomous) — is the User Guide — Complete Operator Runbook.
Each step is a worked use case: Disk triage · Memory triage · Approval gate · Wazuh push.
Installation / Quickstart
uv sync # 1. install the orchestration layer
uv run agentropix-sift doctor # 2. pre-flight the toolchain
uv run agentropix-sift run samples/sample.dd -o report.json # 3. first triage
The package installs two console scripts — agentropix-sift (the triage CLI) and agentropix-sift-mcp
(the MCP server). The full step-by-step, including pip install and example doctor output, is in the
Quickstart. Every CLI command and flag is enumerated in the
CLI Reference.
Deployment & requirements
| Requirement | Detail |
|---|---|
| Python | 3.12+ (pyproject.toml: requires-python = ">=3.12"). Stock SIFT ships 3.10 — provide 3.12 via uv, pyenv, or the deadsnakes PPA. |
| Host | A SANS SIFT Workstation (or Ubuntu host with the GIFT PPA toolchain). Runs fully local — no API keys, no cloud dependency for the forensic path. |
Toolchain on PATH | The 16 SIFT forensic binaries: Volatility3, log2timeline, Sleuth Kit (fls/icat/mmls), ewf-tools, YARA, bulk_extractor, RegRipper, EVTX, EZ-Tools, mail parsers. Agentropix-SIFT drives these — it does not ship them. |
| Degradation | Missing tools degrade gracefully (the agent is skipped, not the run) — but recall drops, so run doctor first. |
See Deployment for SIFT install + tailnet exposure, and Recovery & Resilience for the failure-mode catalogue.
Two Paths: Operator (Expert) and End-User
The same triage capability is reachable two ways — the expert command, or the plain-language prompt a non-technical examiner types into Claude (with the Agentropix MCP connected), which routes to a real MCP tool. Every operational page in the portal documents both lanes side by side.
| 🖥️ Operator / Expert (command) | 💬 End-user (prompt) | |
|---|---|---|
| Pre-flight | uv run agentropix-sift doctor | "Check that my SIFT forensic tools are installed and ready." |
| Run a triage | uv run agentropix-sift run /cases/INC-0605/disk.E01 -o report.json | "Open a case for the image at /cases/INC-0605/disk.E01, register it as evidence, run the full SIFT triage, and save the report." |
| List memory processes | MCP tool get_pslist | "List the processes in the memory image and flag anything suspicious." |
| Approve a finding | promote DRAFT → APPROVED in the Approval Portal | "Show me the findings waiting for review so I can approve them." |
End-user prompts map to real MCP tools (verify against the Tool Capability Map). The gold-standard treatment of both lanes — manual ↔ autonomous × expert ↔ non-expert — is the User Guide.
MCP surface
Agentropix-SIFT exposes 71 distinct MCP tools over a single FastMCP server (verified live via
tools/list and health.tool_count; see Canonical Facts). Of
these, 16 are SIFT forensic tools — deterministic binaries wrapped under mcp_server/wrappers/ so
each call captures the binary's raw stdout and fingerprints it with SHA-256. The remainder cover case
lifecycle, finding records, reporting, provenance, approval, executable-artifact registry, and Wazuh.
| Family | Examples | Reference |
|---|---|---|
| Forensic wrappers (16 SIFT tools) | get_pslist, fls, get_evtx, yara_scan, get_partitions, get_evt | Tool Reference |
| Case & finding lifecycle | record_finding, delete_finding, case_status, generate_report | Tool Reference |
| Provenance & approval | retract_approval, IOC promotion (promote_iocs) | Provenance |
| Executable-artifact registry | build_executable_registry, promote_executable_registry, exec_registry_get, exec_registry_search | Tool Reference |
| Wazuh integration | wazuh_hunt_ioc (+ wrappers) | Wazuh push · Operator's guide |
Full enumeration: MCP Tool Reference · who calls what: Tools by Agent · per-tool breakdown: Tool List.
Response envelope (example)
Every tool returns a typed Pydantic model serialized with model_dump() — never a free-form dict. A
successful get_pslist against a memory image:
{
"image_path": "/cases/INC-2026-0605/mem.raw",
"process_count": 2,
"processes": [
{ "pid": 4732, "ppid": 624, "name": "powershell.exe" },
{ "pid": 624, "ppid": 4, "name": "services.exe" }
],
"tool": "volatility3.windows.pslist.PsList",
"raw_stdout_sha256": "9f2c…<64 hex>…1ab0",
"tool_available": true,
"skipped_reason": "",
"status": "ok"
}
The load-bearing field is raw_stdout_sha256 — the SHA-256 of the binary's raw stdout bytes, the
provenance fingerprint that ties the finding back to the exact tool output. Soft failures return the same
model with tool_available: false and a skipped_reason; handled errors return a structured
ToolError. Full field tables: Response Envelope.
Safety & anti-hallucination
Agentropix-SIFT is engineered so that the LLM cannot become the source of a forensic claim:
- Deterministic-tools-only findings — a finding may only be recorded from the output of a deterministic forensic binary; the LLM narrates and proposes but never authors evidence.
- No LLM self-rating — the Critic halts on a deterministic convergence fingerprint (default
threshold 0.85,
trinity/critic.py), not on a model's self-assessed confidence. - Pre/post SHA-256 evidence invariant — evidence is hashed before and after every run; any mutation aborts the run. The engine reads but never alters the image.
- Thymus read-only policy — deny-by-default boundary (
mcp_server/thymus_policy.py) blocking write/exec paths before a tool executes; no write tool exists in the surface. - Courtroom HMAC-SHA256 seal — the audit log (JSONL) is sealed and the provenance chain validated
(
courtroom.py,provenance/), giving a tamper-evident chain of custody. - Human-in-the-loop — the optional approval sidecar (
approval_sidecar/) holds findings in DRAFT until an examiner APPROVES them.
Deep dives: Anti-Hallucination · Provenance & Grounding · Audit & Courtroom Seal · Security Model.
Engineering & evaluation (SDLC depth)
For the advanced engineer and the evaluator/judge. The SDLC + quality spine: how the system is tested, deployed, hardened, kept resilient, scored, and how its decisions are contracted. Every number tracks Canonical Facts.
Quick links: Testing · Recall corpus · Eval scorecard · Security model · Recovery & resilience · Deployment · Implementation · ADR index
- Testing — 4464 collected tests (
pytest --collect-only -q) in two tiers. Fast / always-run (mock-based, CI + pre-commit):tests/unit/,chaos/,provenance/,evidence_gate/,approval_sidecar/,secrets_gate/,wazuh/. Host-gated (skip-with-reason when the fixture is absent):integration/(SIFT binaries + a staged E01),wazuh_live,real_corpus. A missing E01 or unreachable Wazuh is a skip naming every searched path — never a false failure. - Correctness gates wired into CI:
pytest-cov, basedpyrightstricttyping as a correctness gate (not a lint), ruff selectorsE,F,W,I,UP,B,SIM, andasyncio_mode = "auto"(fitting — every agent is an async coroutine over the MCP boundary). - Forward-drift gate (for evaluators): the test count is CI-enforced — a doc quoting the count without citing the canonical fact file fails the build, and known-stale literals are actively rejected. See Canonical Facts.
- Ground-truth recall you can audit: 72/72 (100%) disk recall (regression) and 108/118 (91.5%) combined memory recall. Methodology, including the post-hoc ground-truth caveat: Dataset Recall · scoring rubric: Evaluation Scorecard.
SWOT — strategic assessment
A structured strategic assessment for evaluators, engineers, and adopters. Each cell is grounded in the
repository corpus (docs/COMPETITIVE-DFIR.md oracle, Canonical Facts,
Competitive Positioning).
| Helpful | Harmful | |
|---|---|---|
| Internal | Strengths — Structural evidence safety, not a policy promise: agents have no write tool; the Thymus policy refuses every write call before the subprocess spawns. Real SANS DFIR tools driven inside the agent loop (16/16 wrappers, 71 MCP tools) — rivals explain JSON after collection. Deterministic, auditable execution: a fingerprint no-progress detector halts the Trinity Loop with no LLM in the halt path, backed by a hash-chained decision ledger. | Weaknesses — A triage engine, not a case-management product: no HTML report generator, no commercial case-file UX (vs Magnet AXIOM, CADO); output is JSON + the audit ledger. Read-only consumer, no host-collection ecosystem (vs Velociraptor's agent fleet) — caps it at post-collection triage. Memory-forensics recall (108/118) trails disk (72/72) and is the active improvement front. |
| External | Opportunities — The MCP consumer model means any MCP-speaking LLM client becomes a forensic front-end with zero retraining. Default-local, no-API-key posture fits air-gapped / sovereign SOCs. The ATT&CK detector lane is extensible — deferred detectors (W051/W052/W054) are wired and unit-tested, ready to promote into live recall. | Threats — Forensic admissibility scrutiny of any AI-assisted pipeline raises the documentation bar (mitigated by the courtroom seal + provenance chain). Upstream SIFT tool drift (binary flags / output format) can silently shift wrapper parsing — covered by host-gated integration tests. Commercial incumbents move fast on AI features. |
Full competitive analysis: Competitive Positioning.
Configuration
Behavior is tuned through the AGENTROPIX_* environment surface — Critic halt threshold, Blackboard
quorum, status taxonomy, tool-path overrides, and more — with safe defaults so the engine runs out of the
box. See Configuration and the
env-var table.
Canonical facts
Single source of truth for every numeric claim — never state a number that contradicts it.
| Fact | Value |
|---|---|
| MCP tools | 71 distinct tool functions |
| SIFT forensic wrappers | 16 |
| Tests collected | 4464 |
| Disk recall (regression) | 72/72 (100%) |
| Memory recall (combined) | 108/118 (91.5%) |
| Core swarm specialists | 7 (Memory, Timeline, Filesystem, Artifact, Discovery, Mail, Hunt) |
SWARM classes (incl. ATT&CK detectors) | 13 |
| Critic halt threshold (default) | 0.85 |
| Blackboard quorum (default) | 2 |
| Python | 3.12+ |
Full table with per-row sources and verification dates: Canonical Facts.
Documentation map
Start at the routed master table of contents, which maps every chapter to its audience and
the question it answers. The portal is organized into eleven numbered sections under docs/:
| # | Section | What it contains |
|---|---|---|
| 1 | Overview | What Agentropix-SIFT is and why, the capability matrix, the 3-command Quickstart, the complete operator User Guide, and how it compares to alternatives. |
| 2 | Architecture | How the engine is built — the validated architecture diagram (pattern + guardrails, HD PDF), system context, internal components, the Trinity Loop, the Swarm + Blackboard, the FastMCP server (and the Thymus boundary), and sequence diagrams. |
| 3 | Data | The data model — case/finding/report schemas, the data dictionary, the entity-relationship view, and what gets persisted to disk. |
| 4 | MCP Tools | The 71-tool MCP surface — the full tool reference, the typed Response Envelope, which agent invokes which tool, and the capability map. |
| 5 | Safety & Forensics | Why you can trust the output — anti-hallucination guarantees, provenance grounding, the Courtroom audit seal, the human-in-the-loop gate, the Approval Portal, and the AI disclosure. |
| 6 | Use Cases | End-to-end worked runs — disk triage, memory triage, the approval gate, the Wazuh push, a guided demo walkthrough, and per-case attack-chain hypotheses. |
| 7 | SDLC & Operations | How to build, run, and operate it — implementation, testing, configuration, deployment, the security model, recovery/resilience, recall methodology, and the evaluation scorecard. |
| 8 | Reference | Look-up material — the full CLI reference, the glossary, the ADR index, and the design-decision rationale. |
| 9 | Integrations | Connecting to external systems — the Wazuh/SOC portal operator's guide and how to connect a remote client to a live internal MCP server. |
| 10 | Agents | What "agent" means here — the agentic architecture, the build-time delegation model, the FastMCP tool-execution path, and the canonical runtime swarm roster. |
| 11 | ADRs | The decision contract — the immutable Architecture Decision Records mirrored from the oracle (001–024 + milestone/defer records). Read the status column literally. |
The portal's documentation-QA working notes (render audits, case-guide sweeps) live under
docs/issues/ — maintainer-facing, not reader chapters.
Acknowledgments
Built on the shoulders of the open-source DFIR ecosystem: the SANS SIFT Workstation and the forensic
tools it bundles — Volatility3, Plaso/log2timeline, The Sleuth Kit, python-evtx,
YARA, bulk_extractor, RegRipper, the EZ-Tools family, and the mail-parsing libraries
(libpff, extract-msg). The MCP surface is served by FastMCP.
License
Released under the MIT License.