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.
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.
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.shends with the agent attempting to callexecute_shelland gettingToolNotFound— the boundary is architectural, not promised. The adversarial version istests/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-013resolves 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.shandpython3 -m pytestconfirm it on a fresh clone.
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-01Downloading the external datasets, or analyzing your own disk image / host
collection (collect → adapt → analyze), are in
docs/QUICKSTART.md.
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.
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. |
- agentic-dfir-collector-adapter (MIT) — converts Velociraptor offline-collector ZIPs into the
evidence_rootlayout 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.
- 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.
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.
MIT — see LICENSE.
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.