Metadata-Version: 2.4
Name: dfir
Version: 0.2.0
Summary: A small, dependency-free command-line toolkit for quick digital forensics and incident response triage (hashes, file-type detection, entropy, strings, IOC extraction, hexdump).
Author-email: DyNooob <i@nooob.top>
Maintainer-email: DyNooob <i@nooob.top>
License-Expression: MIT
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: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

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

```bash
pip install dfir
```

从源码安装 / Install from source:

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

---

## Commands · 命令

### Hash a file or directory · 计算哈希

```bash
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 · 查看元数据与文件类型

```bash
dfir info suspicious.bin
```

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

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

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

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

### Calculate Shannon entropy · 计算香农熵

```bash
dfir entropy suspicious.bin
```

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

### Extract printable strings · 提取字符串

```bash
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 · 十六进制预览

```bash
dfir hexdump suspicious.bin --length 256
```

### Extract common IOCs · 提取常见 IOC

```bash
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 · 快速研判

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

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

安装后 / After installing:

```bash
pip install dfir
dfir --version
```

---

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

PowerShell 下 / On PowerShell:

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

---

## License · 许可证

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