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 — 一键导出标准威胁情报包（含生产者 identity、TLP 2.0 标记、ATT&CK kill_chain_phases），可直接喂给 TIP / SIEM。ID 为确定性 UUIDv5，同一检材两次导出逐字节一致。
• False-positive control — --allowlist 抑制已知良性指标（精确值 / 主机名含子域 / CIDR 网段 / 正则），--defang 输出安全可分享的形式，抽取时自动识别 hxxp://、evil[.]com 这类 defang 写法。抑制从不静默：报告始终列出被移除的指标及其命中规则。
• Differential analysis — dfir diff 对比两次取证快照，找出新增 / 消失 / 严重度变化的 IOC。
• CI gating — --fail-on <severity> 命中即非零退出，--min-severity 收窄报告范围；dfir 可直接作为流水线里的 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
dfir analyze evidence/ --no-recursive     # 不递归子目录 / do not recurse

analyze 既能处理单个文件，也能处理整个目录（自动递归）；目录扫描按文件名排序，因此同一检材总是产出同一份报告。 analyze works on a single file or a whole directory (recursive by default); directory scans are sorted, so the same evidence always yields the same report.

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

CI 门禁 / CI gating

--min-severity 收窄报告范围，--fail-on 把 dfir 变成流水线闸门（两个参数 scan / analyze / report 均支持）。 --min-severity narrows the report; --fail-on turns dfir into a pipeline gate (both work on scan / analyze / report).

# 只报告 high 及以上 / report high and above only
dfir analyze evidence/ --min-severity high --format md

# 命中 high 及以上时退出码为 1 / exit 1 when anything is high or above
dfir analyze evidence/ --feed examples/feed.csv --fail-on high --format json --output analysis.json

# 典型 GitHub Actions 用法 / typical GitHub Actions usage
- run: dfir analyze evidence/ --feed feed.csv --fail-on high --format md

• --fail-on 始终基于过滤前的完整指标集判定，--min-severity 无法掩盖门禁命中。 --fail-on is always evaluated against the full, unfiltered indicator set, so --min-severity can never hide a hit.
• 门禁命中时报告照常输出到 stdout，原因写入 stderr —— 流水线日志里既有证据也有结论。 When the gate trips the report is still written to stdout and the reason goes to stderr, so CI logs keep both the evidence and the verdict.
• --fail-on info 等价于「只要检出任何关注指标即失败」。 --fail-on info means "fail if any indicator at all is found".
• 退出码 / exit codes：0 通过, 1 门禁命中, 2 用法或输入错误 (0 pass, 1 gate tripped, 2 usage/input error)。
• 门禁在 --allowlist 抑制之后判定 —— allowlist 的语义就是「这些是良性的」，被抑制的指标不应让构建失败。 The gate is evaluated after --allowlist suppression: an allowlist is a statement that those indicators are known-good, so they must not fail the build.

误报治理 / False-positive control

三个参数都是可选的：默认行为与 1.3.0 逐字节一致，取证场景下不应默认改写证据表示。 All three flags are opt-in: default output is byte-for-byte what 1.3.0 produced — a forensic tool should not silently rewrite how evidence is represented.

# 抑制已知良性指标 / suppress known-good indicators
dfir analyze evidence/ --allowlist allowlist.txt --format md

# 输出 defang 形式，便于贴到工单或聊天里 / safe-to-paste output
dfir analyze evidence/ --defang --format json --output share.json

# 合并仅靠追踪参数区分的 URL / collapse URLs differing only by tracking params
dfir analyze evidence/ --normalize-urls --format json

--allowlist 文件格式（一行一条，# 为整行注释）/ allowlist format:

# type:value     精确匹配，type 须为 IOC 类型之一 / exact match
md5:44d88612fea8a8f36de82e1278abb02f     # EICAR 测试串

# 裸值           匹配任意类型；若是主机名，还覆盖其子域、
#                托管其上的 URL 与使用该域的邮箱
protonmail.com

# cidr:A.B.C.D/N IPv4 网段 / IPv4 range
cidr:10.0.0.0/8

# re:<regex>     对取值做正则匹配（忽略大小写）/ regex, case-insensitive
re:^https?://[a-z0-9.-]*\.?akamai(?:hd)?\.net/

• 被抑制的指标会在报告的「Suppressed by allowlist」章节列出：类型、取值、严重度、命中规则。静默丢弃证据的工具比噪声更危险。 Suppressed indicators are listed in the report with their type, value, severity and the rule that matched — a tool that silently drops evidence is worse than a noisy one.
• --defang 会把取值改写成 hxxp://evil[.]com 形式，并丢弃 context 片段（context 是证据原文，通常会复述出活指标）。哈希等无网络语义的类型保持不变，改写了就不可用了。 --defang rewrites values as hxxp://evil[.]com and drops context snippets, which are verbatim evidence and normally restate the live indicator. Hashes are left alone: defanging them only makes them unusable.
• --normalize-urls 剔除 utm_* 等追踪/会话参数后再做分组，并保留 variants 列出被合并的原始 URL —— 分组只是展示便利，原始 URL 仍然是证据。 --normalize-urls strips tracking/session parameters before grouping and keeps a variants list of the originals: grouping is a display convenience, the underlying URLs are still evidence.

dfir analyze evidence/ --format stix --output bundle.json
dfir analyze evidence/ --format stix --tlp red --producer "Acme CERT" --output bundle.json
dfir report analysis.json --tlp clear --format stix --output bundle.json

导出的 bundle 除 indicator 与 relationship 外，还包含：

The bundle ships, besides indicator and relationship objects:

• identity —— 生产者身份，被所有对象以 created_by_ref 引用。名称取 --producer，其次取 --analyst。 Producer identity, referenced via created_by_ref. Name comes from --producer, else --analyst.
• TLP 2.0 marking-definition —— 使用 OASIS 官方固定 ID（CLEAR / GREEN / AMBER / AMBER+STRICT / RED），通过 object_marking_refs 引用。默认 amber（事故数据过度分享的风险更高）；--tlp 可放宽或收紧。 Standard OASIS marking ids. Defaults to amber (over-sharing incident data is the likelier risk); override with --tlp.
• kill_chain_phases —— 由 ATT&CK 映射得到的战术（kill_chain_name: mitre-attack）。 ATT&CK tactics derived from the technique mapping.

--tlp 与 --producer 只影响 --format stix；其他格式忽略它们。 --tlp and --producer only affect --format stix; other formats ignore them.

可复现性 / Reproducibility：对象 ID 为确定性 UUIDv5（由 type|value 派生），因此同一份检材每次导出得到相同的 ID，两份导出可以直接 diff，指标也能被稳定引用。设置 SOURCE_DATE_EPOCH 后整个 bundle 逐字节可复现。 Object ids are deterministic UUIDv5 values, so repeated exports of the same evidence are identical and diffable. Set SOURCE_DATE_EPOCH to make the whole bundle byte-reproducible.

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.