Agentic-DFIR — Autonomous DFIR Agent for the SIFT Workstation

An autonomous DFIR agent that thinks like a senior analyst. Architecture-first, not prompt-first.

License: MIT Status: 🟢 Stable release line (2.0.0); runs end-to-end offline, self-correction path validated.

---

What it is

Agentic-DFIR is an autonomous AI agent that sits on top of the SANS SIFT Workstation, runs a senior-analyst-style reasoning loop with architectural evidence-integrity guarantees, and produces a courtroom-traceable report of its findings. It is not a replacement for Velociraptor, KAPE, Timesketch, Plaso, or any SIEM/EDR — those are the layers underneath. The agent is given exactly 48 typed, read-only native forensic functions plus 25 SIFT Workstation tool adapters through a custom MCP server; anything outside that surface — execute_shell, write_file, mount, eval — does not exist and cannot be called regardless of what the prompt says. Evidence integrity is a property of the system's shape, not a rule the agent is asked to follow. The full account — the pitch, the bet behind it, the target case class and the development approach — is docs/overview.md.

Architectural guarantees

Each of these is checkable from the repository; the long form is in docs/overview.md.

• The bypass test is in the demo. bash examples/demo-run.sh ends with the agent attempting to call execute_shell and getting ToolNotFound — the boundary is architectural, not promised. The adversarial version is tests/test_mcp_bypass.py.
• Every claim is auditable. Every finding carries the audit_ids of the MCP calls that produced it; python3 -m dfir_audit trace examples/out/ref-01/audit.jsonl F-013 resolves a finding in the reference run back to the exact call, source artifact and output hash.
• The senior-analyst loop is encoded methodology. Playbook v3 is a ten-phase YAML methodology whose every framework block cites its source — see dfir_playbook/README.md.
• The contradiction handler forces revision. When MFT timestamps disagree with EVTX events the agent halts, flags UNRESOLVED, and revises its hypothesis instead of picking a winner — see the pass-the-hash case study.
• 73 tools, full suite green, 0 destructive ops. 48 native forensic functions + 25 SIFT Workstation tool adapters = 73 typed read-only MCP tools; zero destructive operations possible by construction. bash examples/demo-run.sh and python3 -m pytest confirm it on a fresh clone.

Quick start

The full copy-paste, three-path guide is docs/QUICKSTART.md. The short version:

# 1. Install — Agentic-DFIR + the collector adapter (auto-detects your OS).
#    Also stages Velociraptor, yara, Volatility 3, Plaso and the Eric Zimmerman Tools; the only option is --help.
git clone https://github.com/Juwon1405/agentic-dfir.git
cd agentic-dfir
bash scripts/install.sh

# 2. Test it now — no API key, deterministic, ~5 s.
bash examples/demo-run.sh

# 3. Real analysis — add a key, then run a case.
export ANTHROPIC_API_KEY='sk-...'
python3 analyze.py --case self-evaluation/case-01

Downloading the external datasets, or analyzing your own disk image / host collection (collect → adapt → analyze), are in docs/QUICKSTART.md.

Architecture

The custom MCP server (dfir_mcp) is the primary enforcement layer — the agent has no execute_shell(), destructive commands are not refused but absent — and every call it makes is recorded by dfir_audit in a SHA-256-chained JSONL file that fails verification if rewritten. The agent loop (dfir_agent), the correlation engine (dfir_corr) and the playbook (dfir_playbook) sit on top of that boundary, and evidence is mounted read-only at the OS level before the agent is ever started; the five packages, the data flow between them and the design rationale are in docs/architecture.md.

Documentation

All long-form documentation lives under docs/; each package has its own README.

Group	Page	What it covers
Start here	Documentation index	Every page in docs/, grouped, with a one-line description each.
	Quick start	Three ways to run: the deterministic demo, the bundled benchmarks, your own evidence.
	Overview	What Agentic-DFIR is and is not, why it exists, the target case class, the guarantees, how it is developed.
	Operator guide	Install, requirements, evidence-mounting discipline, both run modes, reading and verifying the output, running the tests.
	Running on SIFT	SIFT-specific setup from a fresh VM to a verified run.
	Troubleshooting	Known issues and resolutions, grouped by install, runtime and evidence handling.
	FAQ	Short answers to the first questions, each linking to the page that goes deeper.
	Glossary	DFIR, agent and MCP terms as the project uses them.
Concepts	About the name	What the name says and the four-phase plan it is built to outlast.
	The Memex bet	Why the durable artifact is the analyst's reasoning, not the report.
	Architecture-first vs prompt-first	The central design claim, its failure mode in prompt-first systems, and the test that makes it executable.
	Threat model	What the read-only boundary makes impossible, what it does not address, what the audit chain proves.
	Comparison with adjacent tools	Where Agentic-DFIR sits relative to Velociraptor, KAPE, Plaso, Timesketch, SIEM/EDR and AI agent frameworks.
Architecture and tool surface	Architecture	The five packages, the repository layout, DuckDB and the audit chain, the three evidence-protection layers.
	MCP function catalog	Every one of the 48 native functions: artifact, purpose, MITRE mapping, reference.
	SIFT Workstation adapter layer	The 25 adapters over Volatility 3, Eric Zimmerman tools, YARA and Plaso, and the contract each must satisfy.
	Platform support	Host and target platforms, functions by platform, adapters by tool family, MITRE tactic coverage.
	Live mode	Claude driving dfir-mcp over stdio: authentication, the loop, outputs, token accounting, wire-level tests.
	dfir_mcp	The read-only MCP server: surface registration, guards, running it, the tests that hold the boundary.
	dfir_agent	The wrapper loop: CLI, iteration controller, deterministic and live modes, credentials, playbook wiring.
	dfir_audit	The SHA-256-chained audit log: entry format, integrity properties, verify / lookup / trace / summary.
	dfir_corr	The DuckDB correlation engine: timeline joins, UNRESOLVED contradictions, the rule pack.
	dfir_playbook	The senior-analyst playbooks: the three bundled YAMLs, the v3 schema, forking for a new case class.
	dfir_sigma	The versioned Sigma detection pack matched by match_sigma_rules.
Evaluation and case studies	Dataset	The bundled self-evaluation tier and the on-demand external tier, with licenses.
	Case study: IP-KVM remote-hands insider	The bundled executable case: finding → artifact → command → hash, on the committed reference run.
	Case study: Pass-the-Hash with timestomp	The conceptual walkthrough of a run, stage by stage, through a contradiction and a revision.
	Writing case studies	Adding a bundled case: layout, truth.json, validation, scoring, what a PR needs.
	Evidence and case studies	The examples/ tree: canonical evidence, case tiers, reference output.
	Evaluation suite	scripts/eval/: self and external measurement, dataset download, scoring, ground-truth validation.
Project	Roadmap	Phase 1 shipped and open items, Phases 2–4 directions, companion projects, what is not on the roadmap.
	The self-learning loop	Phase 2 design: improving analysis quality from execution traces without loosening read-only.
	External skill references	Anthropic-Cybersecurity-Skills candidates tracked for future absorption.
	Tests	The pytest suite: what each file covers, how CI runs it.
	Scripts	Repository tooling: install, health check, evaluation, asset regeneration.
	Changelog	Release history.

Companion projects

• agentic-dfir-collector-adapter (MIT) — converts Velociraptor offline-collector ZIPs into the evidence_root layout this engine reads and seeds the chain-of-custody (manifest.json + SHA-256 index).
• yushin-mac-artifact-collector (MIT, archived) — single-file bash collector for macOS hosts that cannot run Velociraptor; its supply-chain IOC patterns were ported into dfir_mcp._v05_supply_chain.

The collection layer is intentionally not part of this repository; the full table and the Phase 1 rollout status are in docs/roadmap.md.

Contributing and security

• Contribution policy, what is and is not accepted, and the PR checklist: CONTRIBUTING.md.
• Reporting a guardrail bypass (read-only surface, audit chain) or any other vulnerability: SECURITY.md.

Acknowledgments

Agentic-DFIR is authored and maintained by @Juwon1405. All architectural design, the typed MCP tool surface (native pure-Python + SIFT Workstation adapters), the senior-analyst playbook, audit chain, contradiction handler, agent loop, and test suite are original work.

Community contributions accepted:

• @Monibee-Fudgekins — PR #42, 1-line CI matrix expansion (added Python 3.13). Resolved good-first-issue #7. Thank you for the clean PR and the link back to the issue.

For the contribution policy, see CONTRIBUTING.md.

License

MIT — see LICENSE.

Author

Bang Juwon  ·  방주원  ·  優心 (ゆうしん, yushin)

DFIR practitioner & detection engineer based in Tokyo. Goes by yushin in shells, terminals, and most places that aren't legal documents.

• 🐙 GitHub   —   github.com/Juwon1405
• ✉️ Email   —   juwon1405.jp@gmail.com

This project is a personal, independent project. Built outside any employer relationship. All work, opinions, and code in this repository are my own and do not represent the views of any organization I am affiliated with.