AgentDFIR

module
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 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"

# From a KAPE / Velociraptor / CyLR tree: every product, every user, one package
./agentdfir collect --import /cases/host42/kape-output --case-id CASE-2026-042

# 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
./agentdfir report   CASE-2026-042.adfir --format pdf   # one-file PDF: findings, timeline, custody, integrity

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

# Live watch — or a real-time sensor: detections pushed to your SOC within one poll interval
./agentdfir monitor
./agentdfir monitor --detect --alert https://soc.example/hook --honeytokens canaries.txt
./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

# Second witness: corroborate the transcript against OS telemetry (auditd / Sysmon / EDR exports)
./agentdfir correlate CASE-2026-042.adfir /var/log/audit/audit.log
./agentdfir triage    CASE-2026-042.adfir --endpoint sysmon.xml

# MCP supply-chain audit: every server, every agent, read-only — plus gateway-log correlation
./agentdfir mcp audit
./agentdfir mcp audit CASE-2026-042.adfir --gateway-log gw.jsonl --gateway-server gateway

# Add a brand-new AI agent product with one signed JSON file — no Go
./agentdfir packs init foo-agent --config-dir .foo && ./agentdfir packs add foo-agent.product.json

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:

  • KAPE — deploy/kape/: Target (raw files) + Module (sealed .adfir package)
  • Velociraptor — deploy/velociraptor/: client artifact invoking agentdfir collect
  • Triage-tree import — collect --import <tree> turns any KAPE/Velociraptor/CyLR output or mounted image into one sealed package (all products, all users)
  • Timesketch / Plaso — report --format timesketch|l2tcsv puts the agent timeline next to your host timeline (docs)

🗺️ Roadmap

Status Capability
✅ Sealed .adfir packages, hash-chained custody, verify
✅ Claude Code: detect, collect, normalize, timeline, triage
✅ 36 deterministic detections (full plan set): rogue/orphan agents, exfiltration, context/tool/MCP poisoning, secret & sensitive-file access, self-modification, log deletion, timestomping, session tampering… with MITRE ATLAS/ATT&CK mapping
✅ simulate — synthetic incident generation (adversary emulation for AI agents)
✅ Full parsers for 12 products: Claude Code, Codex, Gemini CLI, Cursor, Copilot CLI, Copilot Chat (VS Code), Cline, Roo, OpenClaw, OpenCode, Aider, Warp
✅ Endpoint corroboration — auditd, Sysmon XML, Velociraptor/osquery/eslogger/EDR exports: tool calls → CORROBORATED / CONTRADICTED, unlogged agent processes and connections surfaced
✅ Reports: network-silent HTML, self-contained PDF (stdlib writer, no renderer deps), JSON, CSV, STIX 2.1, OTel · OCSF 1.3, SARIF 2.1, Sigma export for SIEM/SOC pipelines
✅ monitor live watch · --detect --alert real-time sensor (webhook / syslog / file) · 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
✅ MCP supply-chain audit — inventory of every MCP server across 9 hosts (JSON/JSONC/TOML), unpinned packages, plaintext transports, auto-approve, tool-description poisoning, baseline drift, gateway-log corroboration
✅ Product packs — add any new AI agent with one signed JSON file (detect + collect + parse), no Go
🔜 Raw-NTFS/VSS locked-file fallback, EDR/DNS adapters, fleet integrations

🤝 Contributing

Adding a new AI agent product = one product pack (JSON: detection + collector manifest + parser binding) plus a synthetic fixture. 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, context/tool poisoning, invisible-Unicode instruction smuggling, and honeytoken access.
 Injection-surface detections (plan §14): prompt-injection indicators, context/tool poisoning, 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).
endpoint
Package endpoint loads independent operating-system telemetry — the second witness for what an agent did on a machine.
 Package endpoint loads independent operating-system telemetry — the second witness for what an agent did on a machine.
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.
mcpaudit
Package mcpaudit inventories every MCP server an agent host is configured to load and raises supply-chain / configuration findings.
 Package mcpaudit inventories every MCP server an agent host is configured to load and raises supply-chain / configuration findings.
netdest
Package netdest extracts network destinations from agent-invoked shell commands so timeline, exports and detections can reason about where an agent reached out to.
 Package netdest extracts network destinations from agent-invoked shell commands so timeline, exports and detections can reason about where an agent reached out to.
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/genericchat
Package genericchat normalizes session evidence from the remaining supported AI agent products — Gemini CLI, Cursor, Copilot CLI, Cline, Roo Code and OpenClaw — into the unified schema.
 Package genericchat normalizes session evidence from the remaining supported AI agent products — Gemini CLI, Cursor, Copilot CLI, Cline, Roo Code and OpenClaw — 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.
productpack
Package productpack implements declarative product packs: one signed JSON file that teaches AgentDFIR a new AI agent product — how to detect it, what to collect, and how to normalize its transcripts — with no Go change.
 Package productpack implements declarative product packs: one signed JSON file that teaches AgentDFIR a new AI agent product — how to detect it, what to collect, and how to normalize its transcripts — with no Go change.
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.
realtime
Package realtime turns the read-only transcript tail into a live sensor: new lines are normalized by the product's line parser, run through the streaming detection rules, and findings are pushed to alert sinks within one poll interval.
 Package realtime turns the read-only transcript tail into a live sensor: new lines are normalized by the product's line parser, run through the streaming detection rules, and findings are pushed to alert sinks within one poll interval.
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.