dfir

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

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

它不是另一个通用工具箱（通用取证请用 dftk）；它只做一件事，并尽量做好：从证据里挖出 IOC，归一化、打标、关联、映射 ATT&CK、出报告。 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 / map to ATT&CK / report them.

处理管线 / Pipeline: extract → normalize → enrich → correlate → ATT&CK map → 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 哈希。
• Multi-format ingestion — 自动识别纯文本 / JSON / JSON-Lines / gzip 日志，从 message 等字段抽取文本再提取 IOC。
• Built-in heuristics — 私网/保留 IP、滥用型 TLD、URL 短链、持久化注册表键、临时目录中的可疑可执行文件、双扩展名诱饵等自动打标。
• Pluggable intel feeds — 加载你自己的黑名单/情报源（CSV 或 JSON），命中即标记并提升严重度。
• Correlation & risk scoring — 按域名聚合 URL/邮箱，给出整体风险等级与 Top 指标。
• MITRE ATT&CK mapping — 自动把 IOC 关联到 ATT&CK 技术（如注册表自启 → T1547.001），报告含 ATT&CK 章节。
• STIX 2.1 export — 一键导出标准威胁情报包，可直接喂给 TIP / SIEM。
• Differential analysis — dfir diff 对比两次取证快照，找出新增 / 消失 / 严重度变化的 IOC。
• Multiple report formats — Markdown / HTML / CSV / JSON / STIX 2.1，可带案件元数据（case-id / analyst）。
• 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 → ATT&CK → report)

dfir analyze evidence/            --feed examples/feed.csv --format html --output report.html
dfir analyze alert.log            --format json --output analysis.json
dfir analyze alert.log            --case-id IR-2026-001 --analyst "J. Doe"   # 案件元数据 / case metadata

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
dfir report analysis.json --format stix --output iocs.json     # STIX 2.1 bundle

diff — 对比两次取证快照 / compare two analysis snapshots

dfir diff baseline.json current.json --format md

Example · 示例

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

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

输出包含执行摘要（整体风险等级、按严重度统计、ATT&CK 覆盖数）、ATT&CK 技术映射、按域名聚合的关系，以及全部 IOC 明细。 Output includes an executive summary (overall risk, severity breakdown, ATT&CK coverage), the ATT&CK technique mapping, 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"])
print(result["attack"]["techniques"])   # MITRE ATT&CK mapping

也可以加载情报源 / 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)

导出 STIX 2.1 / Export a STIX 2.1 bundle:

from dfir import stix

print(stix.to_stix(result))

Design goals · 设计原则

• No runtime dependencies. 零运行时依赖。
• Safe by default: reads evidence but does not modify it. 默认只读：读取证据但不修改。
• Offline-first: enrichment runs locally, no network calls. 离线优先：富化在本地完成，不发任何网络请求。
• Standards-aware: STIX 2.1 and MITRE ATT&CK out of the box. 标准友好：内置 STIX 2.1 与 MITRE ATT&CK 支持。
• 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。版权信息见每个源文件头与 NOTICE。 Released under the Apache License 2.0 by DyNooob. Copyright notices appear in the header of every source file and in NOTICE.