dfir

由 DyNooob 创建并维护 · Authored and maintained by DyNooob.

dfir 是一个零依赖的命令行取证工具集，用于在引入重型取证平台之前，对文件和目录做快速、本地的初步研判（triage）。 dfir is a small, dependency-free command-line toolkit for quick, local digital forensics and incident-response triage — before you reach for heavier tooling.

它刻意保持小巧、只读、跨平台，方便在取证初期随手使用。 It is intentionally small, read-only by default, and cross-platform, so you can use it during the first minutes of triage.

Features · 特性

• No runtime dependencies — 纯标准库，Python 3.9+ 随处可跑。
• Read-only by default — 只读取证，绝不修改证据。
• Human-readable and JSON output — 既方便临场查看，也方便脚本自动化。
• Cross-platform — Windows / Linux / macOS。
• Magic-byte file-type detection — 不止看后缀，靠文件头识别真实类型（PE/ELF/Mach-O、PDF、ZIP/OOXML、OLE2、PNG/JPEG/GIF/BMP、RTF、SQLite、注册表 hive、EVTX 等）。
• Extra IOC coverage — URL、邮箱、IPv4/IPv6、MAC 地址、域名、Windows 路径、注册表路径、常见哈希。

Install · 安装

从 PyPI 安装 / Install from PyPI:

pip install dfir

从源码安装 / Install from source:

python -m pip install .

Commands · 命令

Hash a file or directory · 计算哈希

dfir hash suspicious.bin
dfir hash evidence/ --recursive
dfir hash evidence/ --recursive --json

一次性计算 MD5、SHA-1、SHA-256、SHA-512。 Calculates MD5, SHA-1, SHA-256, and SHA-512 in a single pass.

Inspect metadata & detected type · 查看元数据与文件类型

dfir info suspicious.bin

显示大小、时间戳、权限、后缀提示，以及基于文件头的真实类型识别。 Shows size, timestamps, permissions, extension hints, and the magic-byte detected type.

Verify a file against a known hash · 哈希校验

dfir verify suspicious.bin --algorithm sha256 --expected 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

匹配成功返回 0，不匹配返回 1（脚本可用退出码判断）。 Exits 0 on match, 1 on mismatch — handy in scripts.

Calculate Shannon entropy · 计算香农熵

dfir entropy suspicious.bin

高熵往往是压缩/加密/加壳数据的一个快速信号。 A quick signal for compressed, encrypted, or packed data.

Extract printable strings · 提取字符串

dfir strings suspicious.bin
dfir strings suspicious.bin --min-length 8
dfir strings suspicious.bin --with-offsets   # 带偏移 / with byte offsets

同时提取 ASCII 与 UTF-16LE 可打印字符串。 Extracts both ASCII and UTF-16LE printable strings.

Hex preview · 十六进制预览

dfir hexdump suspicious.bin --length 256

Extract common IOCs · 提取常见 IOC

dfir ioc logfile.txt
dfir ioc suspicious.bin --json

识别 URL、邮箱、IPv4/IPv6、MAC、域名、Windows 路径、注册表路径，以及 MD5/SHA-1/SHA-256 哈希。 Recognizes URLs, emails, IPv4/IPv6, MAC addresses, domains, Windows paths, registry paths, and MD5/SHA-1/SHA-256 hashes.

Quick triage · 快速研判

dfir triage suspicious.bin
dfir triage suspicious.bin --json
dfir triage evidence/ --recursive          # 目录级研判 / directory triage

组合元数据、哈希、熵、IOC 提取，并给出 notes（熵与网络指标的提示）。 Runs metadata, hashing, entropy, and IOC extraction together, and emits notes (entropy and network-indicator hints).

Design goals · 设计原则

• No runtime dependencies. 零运行时依赖。
• Safe by default: reads evidence but does not modify it. 默认只读：读取证据但不修改。
• Cross-platform Python 3.9+. 跨平台，支持 Python 3.9+。
• Human-readable output plus JSON for automation. 既有人读的输出，也有 JSON 以便自动化。
• Small enough to use during initial triage without a large toolchain. 足够小，无需庞大工具链即可在初期研判使用。

Build & publish · 构建与发布

本仓库附带两个 GitHub Actions 工作流 / This repo ships two GitHub Actions workflows:

• ci.yml — 每次 push / PR 在 Python 3.9–3.13 上跑测试。Runs the test suite on every push/PR.
• publish.yml — 打 v* 标签或发 Release 时构建并发布到 PyPI，使用 Trusted Publishing (OIDC)，无需任何 secret。Builds and publishes to PyPI on tag/Release via Trusted Publishing (OIDC) — no secret required.

本地发布 / Publish locally:

python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*

安装后 / After installing:

pip install dfir
dfir --version

Development · 开发

运行测试 / Run the tests:

PYTHONPATH=src python -m unittest discover -s tests -v

直接试用 CLI（仓库内）/ Try the CLI from the repo:

PYTHONPATH=src python -m dfir --help

PowerShell 下 / On PowerShell:

$env:PYTHONPATH = "src"
python -m dfir --help

License · 许可证

以 Apache License 2.0 发布，作者 DyNooob。 Released under the Apache License 2.0 by DyNooob.