AgentDFIR

module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 1, 2026 License: MIT

README

🔍 AgentDFIR

Open-source digital forensics and incident response for AI agents.

Collect, preserve, reconstruct and investigate activity from Claude Code, Codex CLI, Cursor, Gemini CLI, Copilot and other AI agents.

CI Go Zero deps

Website · Quick start · Evidence format · Contributing

AI coding agents execute shell commands, edit files, spawn subagents, call MCP servers and push code. When something goes wrong — a prompt injection, a poisoned MCP tool, a rogue subagent, quiet data exfiltration — the transcripts and configs they leave on the endpoint are primary forensic evidence. Almost no tooling exists to acquire and analyze them properly.

AgentDFIR is that tooling. Think KAPE / Velociraptor for the agentic-AI layer. It lets an incident responder answer:

Who instructed which AI agent/subagent to perform what action, through which tool/MCP/identity, against which resource — and what evidence proves it?

⚖️ Evidence vs. claims — the core principle

AI-generated text is never automatically treated as proof of execution. Every action gets a corroboration state:

State Meaning
REQUESTED a human asked for it
REPORTED the model said it happened — narrative, not proof
OBSERVED a tool-call record exists in the transcript
CORROBORATED independent endpoint/network evidence confirms it
CONTRADICTED endpoint evidence shows it did not occur
UNKNOWN insufficient evidence

An agent claiming "I executed curl example.com" with no matching tool call stays REPORTED — and AgentDFIR shows you exactly that.

⚡ Quick start

go build -trimpath -o agentdfir ./cmd/agentdfir

# Discover installed AI tooling — never executes suspect binaries
./agentdfir detect

# Forensic acquisition (lossless, sealed, hash-chained)
./agentdfir collect --product claude --operator "Your Name"

# From an offline image / copied home directory
./agentdfir collect --product claude --path /mnt/image/Users/suspect \
    --case-id CASE-2026-042 --authorization "IR-TICKET-123"

# Tamper-evident verification — one flipped byte anywhere fails
./agentdfir verify CASE-2026-042.adfir

# Investigate
./agentdfir timeline CASE-2026-042.adfir     # unified, evidence-linked timeline
./agentdfir triage   CASE-2026-042.adfir     # detections + IR-ready findings

# Train / test / demo with synthetic incidents
./agentdfir simulate --scenario orphan-agent --out demo-profile

# Live watch, interactive exploration, session replay
./agentdfir monitor
./agentdfir investigate CASE-2026-042.adfir
./agentdfir replay --session 9b2d CASE-2026-042.adfir

# Org rule packs + honeytokens
./agentdfir triage --rules ./rules --honeytokens canaries.txt CASE-2026-042.adfir

Example finding:

HIGH — Unexpected Agent Activity [ORPHAN_AGENT]
  Session: 9b2d7e3a-…
  Agent:   adad4e2c    Parent: UNKNOWN
  Finding: Agent appeared without a verified parent invocation.
  Related: SendMessage/resume interaction with agent a7c3f19b
  Evidence: .claude/projects/…/agent-adad4e2c.jsonl:1 (artifact 6443bed58e63)
  Status: OBSERVED    Endpoint corroboration: UNKNOWN

No auto-escalation to "compromise" or "exfiltration" — findings state exactly what the evidence shows, with clickable references to the raw artifact behind every claim.

📦 The .adfir evidence package

Every acquisition produces a sealed, self-describing, independently parseable package:

case.adfir/
├── raw/<sha256>            content-addressed evidence bytes (deduped)
├── manifest.json           per-artifact metadata + logical paths
├── collection.jsonl        hash-chained collection log
├── chain-of-custody.jsonl  hash-chained custody log
├── case.json               case, operator, timezone/clock metadata
├── SHA256SUMS              covers the sealed zone exactly
├── normalized/             events / entities / relationships (regenerable)
└── detections/             findings.json

Acquisition guarantees:

  • 🔒 Lossless — nothing redacted or rewritten at collection time
  • #️⃣ Hash-while-copy — hashes describe exactly the preserved bytes; torn-read detection for files a live agent is still writing
  • 🔗 Symlinks never followed — a planted symlink can't pull ~/.ssh into evidence
  • 📝 Every failure recorded — access denied, size bounds, irregular files
  • 🧾 Tamper-evident — hash-chained logs detect edits, deletions and forged appends; verify catches a single flipped byte

🛡️ Built for hostile evidence

AI incident evidence may intentionally contain prompt injection and anti-analysis payloads. Therefore:

  • Suspect binaries are never executed — not even for --version
  • Transcript parsers are size-bounded; malformed regions become TRACE_GAP findings, never silent skips
  • ANSI escapes and invisible Unicode (bidi overrides, zero-width, tag smuggling) are neutralized in all evidence-derived output — your terminal is part of the attack surface
  • Model text is data, never instructions

🚀 Deploy with your existing stack

Ships with wrappers for tools IR teams already run:

🗺️ Roadmap

Status Capability
✅ Sealed .adfir packages, hash-chained custody, verify
✅ Claude Code: detect, collect, normalize, timeline, triage
✅ Detections: orphan agents, cross-agent messaging, destructive commands, trace gaps
✅ simulate — synthetic incident generation (adversary emulation for AI agents)
✅ Codex CLI parser; collector manifests for Cursor, Gemini CLI, Copilot, Cline, Roo, OpenClaw
✅ Endpoint correlation (pluggable adapters; shell-history reference adapter)
✅ Reports: network-silent HTML, JSON, CSV, STIX 2.1, OTel export
✅ monitor live watch · replay session step-through · investigate explorer
✅ Declarative rule packs (agentdfir-rules) + signed knowledge packs
✅ Package signing (ed25519), full-package encryption (AES-256-GCM)
✅ Injection-surface detections: prompt-injection indicators, invisible-Unicode smuggling, honeytokens
🔜 More parsers (Cursor, Gemini, Copilot session formats), raw-NTFS/VSS fallback, fleet integrations

🤝 Contributing

Adding a new AI agent product = one PR: detection entry + collector manifest + synthetic fixtures + a docs page. No core changes needed. See CONTRIBUTING.md.

Zero third-party runtime dependencies in the collector core, by policy — a forensic tool should be auditable in an afternoon.

📄 License

MIT — free forever. Use it, embed it, build on it.

Directories

Path Synopsis
cmd
agentdfir command
agentdfir — open-source digital forensics and incident response for AI agents.
 agentdfir — open-source digital forensics and incident response for AI agents.
internal
baseline
Package baseline implements org known-good profiles and package diffing — the deterministic mechanism behind every *_CHANGED and UNEXPECTED_* detection ("unexpected relative to what?").
 Package baseline implements org known-good profiles and package diffing — the deterministic mechanism behind every *_CHANGED and UNEXPECTED_* detection ("unexpected relative to what?").
casepkg
Package casepkg implements the sealed zone of the .adfir evidence package: content-addressed artifact storage, manifest, hash-chained collection and custody logs, and SHA256SUMS sealing/verification.
 Package casepkg implements the sealed zone of the .adfir evidence package: content-addressed artifact storage, manifest, hash-chained collection and custody logs, and SHA256SUMS sealing/verification.
cli
Package cli wires the agentdfir subcommands.
 Package cli wires the agentdfir subcommands.
collector
Package collector implements manifest-driven forensic acquisition.
 Package collector implements manifest-driven forensic acquisition.
correlate
Package correlate raises agent-reported/observed activity to corroborated (or contradicted) by comparing it against independent endpoint evidence (plan §16).
 Package correlate raises agent-reported/observed activity to corroborated (or contradicted) by comparing it against independent endpoint evidence (plan §16).
detect
Injection-surface detections (plan §14): prompt-injection indicators, invisible-Unicode instruction smuggling, and honeytoken access.
 Injection-surface detections (plan §14): prompt-injection indicators, invisible-Unicode instruction smuggling, and honeytoken access.
encrypt
Package encrypt provides full-package encryption for .adfir packages (plan §19).
 Package encrypt provides full-package encryption for .adfir packages (plan §19).
export
Package export renders normalized findings and events into interoperability formats: STIX 2.1 bundles and OpenTelemetry (GenAI/agent semantic conventions).
 Package export renders normalized findings and events into interoperability formats: STIX 2.1 bundles and OpenTelemetry (GenAI/agent semantic conventions).
hashchain
Package hashchain implements tamper-evident, hash-chained JSONL logs.
 Package hashchain implements tamper-evident, hash-chained JSONL logs.
live
Package live acquires volatile evidence in RFC 3227 order of volatility (plan §6): clock state first, then logged-in users, running processes, and network state.
 Package live acquires volatile evidence in RFC 3227 order of volatility (plan §6): clock state first, then logged-in users, running processes, and network state.
normalize
Package normalize runs every registered parser over a sealed package and merges their output into one schema.Normalized result.
 Package normalize runs every registered parser over a sealed package and merges their output into one schema.Normalized result.
parsers/claudejsonl
Package claudejsonl parses Claude Code session transcripts (JSONL) out of a sealed .adfir package into normalized events, entities and relationships.
 Package claudejsonl parses Claude Code session transcripts (JSONL) out of a sealed .adfir package into normalized events, entities and relationships.
parsers/codexjsonl
Package codexjsonl parses OpenAI Codex CLI rollout transcripts (~/.codex/sessions/**.jsonl) from a sealed .adfir package into the unified schema.
 Package codexjsonl parses OpenAI Codex CLI rollout transcripts (~/.codex/sessions/**.jsonl) from a sealed .adfir package into the unified schema.
parsers/linereader
Package linereader reads JSONL transcripts one line at a time with a per-line size bound, recovering past over-long lines instead of aborting.
 Package linereader reads JSONL transcripts one line at a time with a per-line size bound, recovering past over-long lines instead of aborting.
products
Package products embeds the product-knowledge pack: which AI agent products exist, how to detect them, and their collector manifests.
 Package products embeds the product-knowledge pack: which AI agent products exist, how to detect them, and their collector manifests.
report
Package report renders a case into analyst-facing outputs.
 Package report renders a case into analyst-facing outputs.
rulepack
Package rulepack implements declarative, shareable detection rules (plan §14, killer feature #4 — Sigma-style shareability).
 Package rulepack implements declarative, shareable detection rules (plan §14, killer feature #4 — Sigma-style shareability).
sanitize
Package sanitize neutralizes hostile content in evidence-derived strings before they reach a terminal or log.
 Package sanitize neutralizes hostile content in evidence-derived strings before they reach a terminal or log.
schema
Package schema defines the unified, vendor-neutral agent forensic schema: normalized events, entities and relationships.
 Package schema defines the unified, vendor-neutral agent forensic schema: normalized events, entities and relationships.
seal
Package seal provides ed25519 detached signatures over a package's SHA256SUMS (plan §7, §19).
 Package seal provides ed25519 detached signatures over a package's SHA256SUMS (plan §7, §19).
simulate
Package simulate generates synthetic incident scenarios — adversary emulation for AI agents.
 Package simulate generates synthetic incident scenarios — adversary emulation for AI agents.
supportpkg
Package supportpkg derives a privacy-reduced "support" package from a sealed forensic package (plan §4, §17).
 Package supportpkg derives a privacy-reduced "support" package from a sealed forensic package (plan §4, §17).
version
Package version holds build/version identity for the agentdfir binary.
 Package version holds build/version identity for the agentdfir binary.
watch
Package watch implements live monitoring of agent session directories (killer feature #5): it tails growing transcript files and emits normalized event lines in real time.
 Package watch implements live monitoring of agent session directories (killer feature #5): it tails growing transcript files and emits normalized event lines in real time.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.