Metadata-Version: 2.4
Name: dftk
Version: 3.4.0
Summary: Evidence-preserving digital forensics primitives and composable workflows for analysts, automation systems, and autonomous agents
Author-email: DyNooob <i@digiforensics.cn>
Maintainer-email: DyNooob <i@digiforensics.cn>
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.digiforensics.cn
Project-URL: Documentation, https://www.digiforensics.cn
Project-URL: DigiForensics, https://www.digiforensics.cn
Project-URL: LLMCN, https://www.llmcn.org
Project-URL: Blog, https://buno.dev
Project-URL: Source, https://github.com/DigiForensics/DFTK
Project-URL: Issues, https://github.com/DigiForensics/DFTK/issues
Keywords: digital-forensics,forensics,dfir,incident-response,android-forensics,network-forensics,windows-forensics,linux-forensics,agent-tools,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: email
Requires-Dist: dkimpy>=1.1; extra == "email"
Requires-Dist: dnspython>=2.4; extra == "email"
Requires-Dist: pyspf>=2.0; extra == "email"
Provides-Extra: ssh
Requires-Dist: paramiko>=3.4; extra == "ssh"
Provides-Extra: yara
Requires-Dist: yara-python>=4.5; extra == "yara"
Provides-Extra: windows
Requires-Dist: python-registry>=1.3; extra == "windows"
Requires-Dist: python-evtx>=0.8; extra == "windows"
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.0.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: dkimpy>=1.1; extra == "all"
Requires-Dist: dnspython>=2.4; extra == "all"
Requires-Dist: pyspf>=2.0; extra == "all"
Requires-Dist: paramiko>=3.4; extra == "all"
Requires-Dist: yara-python>=4.5; extra == "all"
Requires-Dist: python-registry>=1.3; extra == "all"
Requires-Dist: python-evtx>=0.8; extra == "all"
Requires-Dist: mcp<3,>=2.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: mcp<3,>=2.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-cov>=5; extra == "test"
Dynamic: license-file

# DFTK — Digital Forensics Toolkit

[![CI](https://github.com/DigiForensics/DFTK/actions/workflows/ci.yml/badge.svg)](https://github.com/DigiForensics/DFTK/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
[![PyPI](https://img.shields.io/pypi/v/dftk.svg)](https://pypi.org/project/dftk/)

DFTK is a Python toolkit for evidence-preserving digital-forensics operations. It
provides structured results for files, archives, mobile artifacts, databases,
captures, browser data, email, host artifacts, and timelines.

中文说明见 [README.zh-CN.md](README.zh-CN.md).

## Install

```bash
pip install dftk
```

Optional integrations:

```bash
pip install "dftk[email]"    # DKIM / SPF / DNS
pip install "dftk[ssh]"      # read-only SSH inventory
pip install "dftk[windows]"  # Registry / EVTX parsers
pip install "dftk[yara]"     # YARA rule scanning
pip install "dftk[mcp]"      # local MCP server
pip install "dftk[all]"      # all optional Python integrations
```

The core package has no mandatory third-party runtime dependencies. E01 filesystem
traversal additionally requires `pyewf` / libewf bindings and `pytsk3`.

## Start here

```bash
# Discover available capabilities
dftk list

# Build an Agent-ready intake manifest and next-step plan
dftk run evidence.intake --params '{"path":"/evidence/acquisition"}'

# Inspect one capability before running it
dftk describe artifact.inspect

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

# Save related observations in a case
dftk case --workspace /cases/intake new --name intake
dftk case --workspace /cases/intake run <case_id> artifact.inspect --params '{"path":"sample.apk"}'
dftk case --workspace /cases/intake export <case_id> --format md
```

Each run returns an `Observation` with a status, facts, evidence, warnings, and
errors. `unsupported`, `error`, and `blocked` describe limitations or failures;
they are not negative findings.

## Agent and MCP use

For Agent use, the recommended entry point is this **DFTK repository**: give its
URL to the Agent. It installs DFTK first, then runs a single bounded bootstrap that
fetches the matching complete [DFTK-skill](https://github.com/DigiForensics/DFTK-skill)
bundle and emits a reviewable MCP configuration fragment:

```bash
dftk agent setup --root /evidence/acquisition --workspace /cases/intake --install-skill
```

See [INSTALL_AGENT.md](INSTALL_AGENT.md) for the paste-ready instruction and
[AGENT_INTEGRATION.md](AGENT_INTEGRATION.md) for the complete operating loop.

DFTK includes a local stdio MCP server. Keep acquired evidence read-only and use a
separate writable case workspace:

```bash
pip install "dftk[mcp]"
dftk mcp --root /evidence/acquisition --workspace /cases/intake --check
dftk mcp --root /evidence/acquisition --workspace /cases/intake
```

The server defaults to `READ_ONLY` with network access disabled. Its launch options
define the evidence root, safety ceiling, network access, and timeout. See the
[MCP guide](docs/mcp.md) for configuration and policy details.

For an existing host configuration, install the matching Skill bundle directly:

```bash
dftk skill --install  # auto-detect the current Agent host; portable fallback: agents
# Inspect all supported target paths before a broad installation:
dftk skill --install --target all --dry-run
```

## Documentation

- [User guide](docs/user-guide.md) — CLI, Python API, cases, observations, and audit logs.
- [MCP guide](docs/mcp.md) — local server policy and host configuration.
- [Capability map](CAPABILITIES.md) — domains and capability groups.
- [Architecture](ARCHITECTURE.md) — registry, evidence contract, and runtime boundaries.
- [Safety policy](SAFETY.md) — execution levels, network gates, and source-evidence protection.
- [Toolchain deployment](DEPLOY-TOOLCHAIN.md) — external forensic binaries.
- [Development guide](docs/development.md) — setup, tests, and contribution workflow.
- [Documentation policy](docs/documentation.md) — ownership, generated data, and translation rules.

## Project facts

- Distribution: `dftk`; Python package: `dftk`; CLI: `dftk`.
- Python: CPython 3.10+.
- License: [Apache-2.0](LICENSE).
- Maintainer: [DyNooob](https://github.com/DyNooob) · [DigiForensics](https://www.digiforensics.cn).

DFTK supports lawful, authorized examination of evidence. It is a technical toolkit,
not legal advice.
