DFTK — Digital Forensics Toolkit

DFTK is a Python toolkit that exposes read-only, structured forensic operations. You can call them from the CLI or compose them inside a higher-level Agent / TaskGraph runtime. Every operation returns one Observation that carries an explicit status, machine-readable facts, and evidence traced back to its source.

🇨🇳 中文文档：README.zh-CN.md

• Distribution name: dftk · Import package: dftk · CLI command: dftk
• Maintainer: DyNooob — DigiForensics · blog
• Organizations: DigiForensics · LLMCN
• License: Apache-2.0

What DFTK is (and isn't)

DFTK is not an autonomous forensic agent. It is a library of structured operations; you drive it, it does not investigate on its own. Each operation returns a normalized Observation so the calling system gets facts and sourced evidence instead of console text to parse.

Why DFTK

• Read-only by default. Read-only tools open evidence without modifying it. Operations that write derived output require the caller to select an explicit STATEFUL or DESTRUCTIVE safety level.
• Zero mandatory dependencies. The base package has no mandatory third-party runtime dependencies. Optional parsers (E01/TSK, Windows Registry/EVTX, DKIM/SPF, SSH) report unsupported when their dependency is missing, instead of guessing.
• One registry, 72 tools. Each tool declares its parameters, safety level, semantic tags, network needs, and produced-evidence types, so a planner can pick the right tool from an evidence requirement.
• Safety enforced in one place. READ_ONLY < STATEFUL < DESTRUCTIVE; no registered tool is DESTRUCTIVE. Network access is gated behind an explicit opt-in.

Contents

• Installation
• Quick start
• Native MCP for Agents
• Agent Skill
• Python / Agent API
• Observation contract
• Capability model
• Safety model
• Supported Python versions
• Development
• Documentation
• Contributing
• Security
• License
• Disclaimer

Installation

pip install dftk

Optional integrations install as extras:

pip install "dftk[email]"     # DKIM / SPF / DNS email authentication
pip install "dftk[ssh]"       # fixed-command read-only SSH inventory
pip install "dftk[windows]"   # Windows Registry / EVTX parsers
pip install "dftk[all]"       # every optional parser

The base package keeps zero mandatory runtime dependencies on purpose. E01 filesystem traversal additionally needs a forensic environment that provides pyewf / libewf bindings and pytsk3.

Quick start

List every registered capability:

dftk list

Inspect a tool's contract (parameters, safety level, tags, produced evidence):

dftk describe android.apk_manifest

Analyze an artifact:

dftk run artifact.inspect --params '{"path":"sample.apk"}'

Extract Android manifest evidence:

dftk run android.apk_manifest --params '{"path":"sample.apk"}'

Search an APK for network endpoints:

dftk run android.apk_endpoints --params '{"path":"sample.apk"}'

Extract protocol-level observations from a capture:

dftk run network.capture_protocols --params '{"path":"traffic.pcapng"}'

Search a SQLite database without opening it read/write:

dftk run database.sqlite_search --params '{"path":"app.db","query":"example"}'

Run a bounded first-pass recipe:

dftk recipe artifact.auto_triage --params '{"path":"unknown.bin"}'

Export the full tool manifest (agent-readable):

dftk export-manifest --out manifest.json

Check the current runtime and optional integrations:

dftk doctor

Build an investigation case and correlate its runs into one timeline:

dftk case new --name intake
dftk case run <case_id> timeline.file_metadata --params '{"root":"mnt/evidence"}'
dftk case timeline <case_id>

Native MCP for Agents

DFTK ships a native local stdio MCP adapter. It is a thin protocol layer over the existing Registry / Observation / CaseSession APIs, not a second Agent runtime.

Install the optional MCP dependency and start the server from the evidence root you intend to expose:

pip install "dftk[mcp]"
cd /path/to/authorized/evidence-root
dftk doctor
dftk mcp

The MCP server exposes six meta-tools: health check, capability search, describe, run, case management, and paged reading of persisted case runs. It defaults to READ_ONLY, network-off, stdio-only operation. The Agent cannot raise the safety ceiling or enable network access; --root, --max-safety, --allow-network, and timeout are set by whoever launches the server.

For multi-step investigations, create a normal DFTK case and pass its case_id to the MCP dftk_run tool; the Observation is persisted in the same CaseSession format the CLI uses.

Agent Skill

The standalone investigation guidance lives at DigiForensics/DFTK-skill. It is not shipped inside the pip package; dftk skill --install fetches the repository at the tag matching your installed DFTK version and installs the entire progressive-disclosure skill directory (not only SKILL.md):

dftk skill --install
dftk skill --install --target kimi,workbuddy,agents

The skill stays documentation and reasoning guidance; the executable capabilities remain in DFTK.

Python / Agent API

import dftk

registry = dftk.get_registry()

observation = dftk.run_tool(
    "artifact.inspect",
    {"path": "evidence.bin"},
)

print(observation.status)   # ok | partial | error | unsupported | blocked
print(observation.facts)    # machine-readable findings
print(observation.evidence) # source + locator + value + confidence

get_registry() and run_tool() are the stable public integration entry points. Callers do not need to import primitive modules for registration side effects.

Observation contract

Every tool returns one structured Observation with distinct execution states:

status       ok | partial | error | unsupported | blocked
facts        machine-readable findings
evidence[]   source + locator + value + confidence / method / source hash
warnings[]   limitations that do not erase useful evidence
errors[]     execution or parsing failures
meta         tool and run metadata

unsupported, error, blocked, and a genuine negative finding are deliberately different states. A missing parser is not the same as "no findings".

Capability model

DFTK 3.3.0 contains a registry of 72 tools (71 READ_ONLY, 1 STATEFUL) and 14 recipes spanning:

• artifact identification, hashing, strings, search and timeline;
• APK, DEX, binary AXML, Android app data and endpoint extraction;
• ELF and PE inventory plus native indicators;
• SQLite and SQL dump analysis;
• PCAP / PCAPNG, DNS, HTTP and TLS SNI extraction;
• Linux root filesystems, authentication and persistence artifacts;
• Docker metadata and logs;
• web configuration and access logs;
• Windows Registry, USB artifacts and EVTX through optional parsers;
• E01 / TSK filesystem inventory through specialist forensic bindings;
• Chromium / Edge and Firefox artifacts;
• MIME / email authentication analysis;
• BIP39, entropy and reversible encoding helpers;
• unified timeline correlation and investigation case sessions: merge event sources into one source-attributed timeline, and accumulate tool runs in an isolated dftk case workspace.

Case correlation & unified timeline

timeline.merge normalizes and correlates time-bearing events from multiple dftk tool outputs (or inline sources) into one sorted, source-attributed timeline. It correlates filesystem metadata, authentication logs, and browser history into a single source-attributed sequence.

dftk case wraps the read-only tools into an isolated investigation session. It records each run's Observation under a workspace (.dftk/cases/<id>/) and can correlate them into a single timeline or export a report:

dftk case new --name phishing-intake
dftk case run <case_id> timeline.file_metadata --params '{"root":"mnt/phone"}'
dftk case run <case_id> linux.auth_events      --params '{"root":"mnt/server"}'
dftk case timeline <case_id>     # unified, source-attributed timeline
dftk case export <case_id> --format md

See CAPABILITIES.md for the detailed map.

Safety model

DFTK separates execution safety from forensic reasoning:

The default policy allows only READ_ONLY operations. Network access is independently gated and must be enabled with --allow-network. Controlled archive extraction (archive.extract_safe) is STATEFUL and blocked unless the caller explicitly raises the ceiling:

dftk run archive.extract_safe \
  --max-safety STATEFUL \
  --params '{"path":"evidence.zip","output_dir":"workspace/extracted"}'

Full details on database access, archive guards, specialist-parser semantics and the legacy-script policy are in SAFETY.md.

Chain-of-custody audit log

Any capability run can append a record to a JSONL audit ledger, so the provenance of an analysis can be reconstructed afterwards:

dftk run file.hash --params '{"path":"evidence/disk.img"}' --audit case-01/audit.jsonl
dftk recipe recipe.triage.file --params '{"path":"evidence/sample.bin"}' --audit case-01/audit.jsonl
dftk case run 2026-0001 windows.prefetch --params '{"path":"C:/Windows/Prefetch"}' --audit case-01/audit.jsonl
dftk mcp --root ./evidence --audit          # defaults to .dftk/audit.jsonl

To log every run in a session without passing the flag each time, set the environment variable:

export DFTK_AUDIT_LOG=case-01/audit.jsonl

Each line records the UTC timestamp, tool name, caller, resolved parameters, safety level, network flag, status, summary, evidence SHA-256 hashes and errors. Parameter keys that look like secrets (password, token, api_key, …) are masked and oversized strings are truncated. The ledger is a side record only: it never modifies evidence, and a ledger write failure never interrupts the examination.

Supported Python versions

DFTK supports CPython 3.10+ on platform-independent builds. Verified on 3.10, 3.11, 3.12 and 3.13.

Development

git clone https://github.com/DigiForensics/DFTK.git
cd DFTK
python -m venv .venv
python -m pip install -e ".[dev]"
pytest -q

CI enforces a coverage floor. To reproduce that gate locally:

pytest -q --cov=dftk --cov-report=term-missing --cov-fail-under=60

Build distributions (for maintainers):

python -m build
python -m twine check --strict dist/*

Documentation

• ARCHITECTURE.md — public tool boundary, evidence contract, primitive-vs-recipe, promotion rules.
• CAPABILITIES.md — full capability map by domain.
• SAFETY.md — safety levels, network isolation, database/archive guards, specialist-parser semantics.
• AGENT_INTEGRATION.md — native stdio MCP and host-Agent integration examples.
• CONTRIBUTING.md — how to add a capability and open a PR.
• SECURITY.md — vulnerability disclosure policy.
• CHANGELOG.md — notable public changes.
• PUBLISHING.md — release / PyPI Trusted Publishing workflow.

Contributing

Small, deterministic forensic primitives are preferred over challenge-specific answer scripts. See CONTRIBUTING.md for the full guidelines, then open a pull request.

Security

Report vulnerabilities privately — do not open a public issue. See SECURITY.md.

License

Released under the Apache License 2.0. Copyright 2026 DyNooob @ DigiForensics.

Disclaimer

DFTK is a technical toolkit, not legal advice. It is built to support lawful, authorized examination of evidence you own or are explicitly permitted to analyze. You are responsible for complying with applicable laws, authorization requirements, and chain-of-custody practices in your jurisdiction. The maintainers accept no liability for misuse.