convez.ai
MCP Server
galvangabriel-web

agentropix-mcp

galvangabriel-web/agentropix-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

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-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.3.0
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Agentropix-SIFT

License: MIT Python 3.12+ MCP tools: 71 SIFT wrappers: 16 Tests: 4464 Disk recall: 72/72

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/mcp is tailnet-only — reachable through Tailscale, never the public internet. Before the steps below:

  1. Accept the invite and sign in with your Google / Microsoft identity → Tailscale invite (then ping the operator to approve your device).
  2. Install the Tailscale client — macOS brew install --cask tailscale · Windows MSI · Linux curl -fsSL https://tailscale.com/install.sh | sh && sudo tailscale up
  3. Verify: tailscale status lists siftworkstation … 100.85.162.82, and ping 100.85.162.82 succeeds.

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:

OSPath
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 health tool 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 engineerunderstand the architecture, build/test/extend itImplementation → Trinity Loop → Swarm & Blackboard → FastMCP Server → Testing → ADRs (decision contract)
🛡️ SOC analystrun a triage, hunt IOCs, push to the SIEMUser Guide (runbook) → Disk triage → Memory triage → Wazuh push → CLI Reference
⚖️ Evaluator / judgeverify the claims, soundness, chain of custodyCanonical Facts → Anti-Hallucination → Audit & Courtroom Seal → Recall methodology → Evaluation scorecard → SWOT
💬 End-user (non-technical)get answers by just asking Claudethe 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.

Diagram — rendered at high resolution

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) and agentropix-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.json entry) 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 + bounded raw_output snapshot 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 SwarmAgent subclass 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

CapabilityThe one-line valueCanonical figureSource-code home
Trinity LoopDeterministic Architect → Swarm → Critic control loop; halts on a convergence fingerprint, never on an LLM self-ratingCritic halt default 0.85trinity/architect.py, trinity/critic.py, orchestrator.py
71 MCP toolsOne FastMCP server exposes 71 distinct forensic tools over stdio + HTTP71 toolsmcp_server/fastmcp_app.py
16 SIFT wrappersHardened drivers (timeout, memory ceiling, retry, stderr capture, tracing) around the 16 trusted SIFT binaries16 wrappersmcp_server/wrappers/
7-agent Swarm + ATT&CK detectorsMemory, Timeline, Filesystem, Artifact, Discovery, Mail, Hunt specialists + 6 deterministic MITRE ATT&CK detectors7 specialists (13 SWARM classes)agents/, detectors/
Quorum BlackboardAn observation is promoted to a Correlation only when enough agents corroborate the same tokenquorum default 2agents/_blackboard.py
Thymus read-only policyEvery mcp_* call is checked against a path allowlist before any subprocess spawns — evidence is structurally read-only (no write tool exists)deny-by-defaultmcp_server/thymus_policy.py
Courtroom sealSHA-256 evidence byte-binding + HMAC-SHA256 report/audit-log seal → a report a judge can independently verifymode-0600 session keycourtroom.py
Provenance & groundingEvery Finding._source names the tool that produced it; inference_constraint = high; per-row HMAC chain validation3 grounding layersagents/_base.py, provenance/validate.py
Approval sidecar (HITL)Optional HMAC examiner sign-off: PBKDF2 key (600k iters) + nonce + append-only approval hash chain + browser form2 MCP toolsapproval_sidecar/
Wazuh SIEM pushPromote findings/IOCs into Wazuh behind default-deny kill switches + active-response CIDR guard5 Wazuh toolswazuh/
Chaos-tested resilienceFault-injection tests prove graceful degradation: a missing tool skips an agent, not the runchaos test markertests/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.

Diagram — rendered at high resolution

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:

ADRDecision
ADR-002 — Execution engineThe deterministic Trinity Loop as the execution model.
ADR-008 — Safety architectureThe deny-by-default Thymus boundary + evidence read-only invariant.
ADR-011 — Evidence gatesPre/post SHA-256 evidence-integrity gates.
ADR-016 — Courtroom audit / ADR-022 — Audit-log sealHMAC-SHA256 tamper-evident chain of custody.
ADR-017 — Tailnet MCP exposureHTTP transport is tailnet-only + Bearer-gated.
ADR-018 — Wazuh IOC push / ADR-019 — AR confirmation gateDefault-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.

Stage 1 doctor Stage 2 run Stage 3 review Stage 4 approve Stage 5 seal Stage 6 escalate

Six guarded stages of the Agentropix-SIFT investigation workflow — ① doctor (pre-flight) → ② run (triage) → ③ review (verify) → 🧑‍⚖️ human gate → ④ approve (HITL) → ⑤ seal (courtroom) → ⑥ escalate (SIEM), with a reject/re-run loop back to run

🔍 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 to case_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_sha256 so I can verify it myself." → routes to case_status / record_finding inspection.

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_export for 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 --print for 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

RequirementDetail
Python3.12+ (pyproject.toml: requires-python = ">=3.12"). Stock SIFT ships 3.10 — provide 3.12 via uv, pyenv, or the deadsnakes PPA.
HostA 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 PATHThe 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.
DegradationMissing 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-flightuv run agentropix-sift doctor"Check that my SIFT forensic tools are installed and ready."
Run a triageuv 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 processesMCP tool get_pslist"List the processes in the memory image and flag anything suspicious."
Approve a findingpromote 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.

FamilyExamplesReference
Forensic wrappers (16 SIFT tools)get_pslist, fls, get_evtx, yara_scan, get_partitions, get_evtTool Reference
Case & finding lifecyclerecord_finding, delete_finding, case_status, generate_reportTool Reference
Provenance & approvalretract_approval, IOC promotion (promote_iocs)Provenance
Executable-artifact registrybuild_executable_registry, promote_executable_registry, exec_registry_get, exec_registry_searchTool Reference
Wazuh integrationwazuh_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, basedpyright strict typing as a correctness gate (not a lint), ruff selectors E,F,W,I,UP,B,SIM, and asyncio_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).

HelpfulHarmful
InternalStrengths — 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.
ExternalOpportunities — 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.

FactValue
MCP tools71 distinct tool functions
SIFT forensic wrappers16
Tests collected4464
Disk recall (regression)72/72 (100%)
Memory recall (combined)108/118 (91.5%)
Core swarm specialists7 (Memory, Timeline, Filesystem, Artifact, Discovery, Mail, Hunt)
SWARM classes (incl. ATT&CK detectors)13
Critic halt threshold (default)0.85
Blackboard quorum (default)2
Python3.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/:

#SectionWhat it contains
1OverviewWhat Agentropix-SIFT is and why, the capability matrix, the 3-command Quickstart, the complete operator User Guide, and how it compares to alternatives.
2ArchitectureHow 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.
3DataThe data model — case/finding/report schemas, the data dictionary, the entity-relationship view, and what gets persisted to disk.
4MCP ToolsThe 71-tool MCP surface — the full tool reference, the typed Response Envelope, which agent invokes which tool, and the capability map.
5Safety & ForensicsWhy 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.
6Use CasesEnd-to-end worked runs — disk triage, memory triage, the approval gate, the Wazuh push, a guided demo walkthrough, and per-case attack-chain hypotheses.
7SDLC & OperationsHow to build, run, and operate it — implementation, testing, configuration, deployment, the security model, recovery/resilience, recall methodology, and the evaluation scorecard.
8ReferenceLook-up material — the full CLI reference, the glossary, the ADR index, and the design-decision rationale.
9IntegrationsConnecting to external systems — the Wazuh/SOC portal operator's guide and how to connect a remote client to a live internal MCP server.
10AgentsWhat "agent" means here — the agentic architecture, the build-time delegation model, the FastMCP tool-execution path, and the canonical runtime swarm roster.
11ADRsThe 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.

Ver o original no GitHub

Bom para

Relacionados