dfir

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

dfir 是一个零依赖的 IOC 分析引擎，专注于把杂乱的取证检材（日志、内存镜像、恶意样本、网页存档、注册表导出等）转化为结构化、可富化、可关联的失陷指标（IOC），并产出可执行的研判报告。 dfir is a dependency-free IOC analysis engine focused on turning messy forensic artefacts (logs, memory dumps, malware samples, saved web pages, registry exports, ...) into structured, enriched and correlated indicators of compromise (IOCs), then rendering actionable reports.

它不是另一个通用工具箱（通用取证请用 dftk）；它只做一件事，并尽量做好：从证据里挖出 IOC，归一化、打标、关联、出报告。 It is not a general-purpose toolbox (use dftk for that). It does one job and tries to do it well: pull IOCs out of evidence, normalise / tag / correlate them, and produce a report.

处理管线 / Pipeline: extract → normalize → enrich → correlate → report

Features · 特性

• Zero runtime dependencies — 纯 Python 标准库，Python 3.9+ 随处可跑。
• Read-only by default — 只读取证，绝不修改证据。
• Broad IOC coverage — URL、邮箱、IPv4/IPv6、MAC、域名、Windows 路径、注册表键、文件名（含可疑扩展名）、User-Agent，以及 MD5/SHA-1/SHA-256 哈希。
• Built-in heuristics — 私网/保留 IP、滥用型 TLD、URL 短链、持久化注册表键、临时目录中的可疑可执行文件、双扩展名诱饵等自动打标。
• Pluggable intel feeds — 加载你自己的黑名单/情报源（CSV 或 JSON），命中即标记并提升严重度。
• Correlation & risk scoring — 按域名聚合 URL/邮箱，给出整体风险等级与 Top 指标。
• Multiple report formats — JSON / CSV / Markdown / HTML。
• Cross-platform — Windows / Linux / macOS。

Install · 安装

pip install dfir

从源码 / From source:

python -m pip install .

Commands · 命令

extract — 仅抽取（不富化）/ extract only (no enrichment)

dfir extract evidence/alert.log
dfir extract evidence/alert.log --json
dfir extract - --stdin                 # 从标准输入读取 / read from stdin

scan — 扫描一个目录的检材 / walk a directory of evidence

dfir scan evidence/ --feed examples/feed.csv --format md
dfir scan evidence/ --no-recursive     # 不递归子目录 / do not recurse

analyze — 完整管线 / full pipeline (extract → enrich → correlate → report)

dfir analyze evidence/            --feed examples/feed.csv --format html --output report.html
dfir analyze alert.log            --format json --output analysis.json

analyze 既能处理单个文件，也能处理整个目录（自动递归）。 analyze works on a single file or a whole directory (recursive by default).

report — 用另一种格式重渲已保存的分析结果 / re-render a saved analysis

dfir report analysis.json --format csv --output iocs.csv

Example · 示例

随仓库附带示例检材与情报源 / The repo ships sample artefacts:

dfir analyze examples/evidence.log --feed examples/feed.csv --format md

输出包含整体风险等级、按严重度排序的 Top 指标、按域名聚合的关系，以及全部 IOC 明细。 Output includes an overall risk level, severity-ranked top indicators, domain-based relationships, and the full IOC list.

Library usage · 作为库使用

from dfir import analyze

result = analyze.analyze_file("evidence/alert.log")
for ind in result["indicators"]:
    print(ind["type"], ind["value"], ind["severity"], ind["tags"])
print(result["correlation"]["risk_level"])

也可以加载情报源 / You can also load an intel feed:

from dfir import enrich

feed = enrich.load_feed("examples/feed.csv")   # CSV or JSON
result = analyze.analyze_file("evidence/alert.log", feed=feed)

Design goals · 设计原则

• No runtime dependencies. 零运行时依赖。
• Safe by default: reads evidence but does not modify it. 默认只读：读取证据但不修改。
• Offline-first: enrichment runs locally, no network calls. 离线优先：富化在本地完成，不发任何网络请求。
• Pluggable intelligence: bring your own feed, no vendor lock-in. 可插拔情报：自带情报源，无厂商锁定。
• Cross-platform Python 3.9+. 跨平台，支持 Python 3.9+。

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.

本地构建校验 / Build & check locally:

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

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

License · 许可证

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