Metadata-Version: 2.4
Name: dfir
Version: 0.3.0
Summary: A dependency-free IOC analysis engine for DFIR: extract, normalise, enrich, correlate and report indicators of compromise from forensic artefacts.
Author-email: DyNooob <i@nooob.top>
Maintainer-email: DyNooob <i@nooob.top>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/DyNooob/DFIR
Project-URL: Repository, https://github.com/DyNooob/DFIR
Project-URL: Source, https://github.com/DyNooob/DFIR
Project-URL: Issues, https://github.com/DyNooob/DFIR/issues
Project-URL: Changelog, https://github.com/DyNooob/DFIR/blob/main/CHANGELOG.md
Keywords: dfir,digital-forensics,incident-response,forensics,triage,ioc
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# dfir

[![PyPI version](https://img.shields.io/pypi/v/dfir.svg)](https://pypi.org/project/dfir/)
[![Python versions](https://img.shields.io/pypi/pyversions/dfir.svg)](https://pypi.org/project/dfir/)
[![CI](https://github.com/DyNooob/DFIR/actions/workflows/ci.yml/badge.svg)](https://github.com/DyNooob/DFIR/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

> 由 **[DyNooob](https://github.com/DyNooob)** 创建并维护 · Authored and maintained by **[DyNooob](https://github.com/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 · 安装

```bash
pip install dfir
```

从源码 / From source:

```bash
python -m pip install .
```

---

## Commands · 命令

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

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

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

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

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

```bash
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

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

---

## Example · 示例

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

```bash
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 · 作为库使用

```python
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:

```python
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:

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

---

## Development · 开发

运行测试 / Run the tests:

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

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

```bash
PYTHONPATH=src python -m dfir --help
```

---

## License · 许可证

以 [Apache License 2.0](LICENSE) 发布，作者 **DyNooob**。
Released under the [Apache License 2.0](LICENSE) by **DyNooob**.
