BrandonRoos/hashdetect
GitHub: BrandonRoos/hashdetect
一款基于长度和结构特征识别常见哈希类型的命令行工具，按置信度排序候选结果并输出对应的 hashcat 和 John the Ripper 格式信息。
Stars: 0 | Forks: 0
# hashdetect
一款命令行工具，通过长度和结构来识别常见的哈希类型，按置信度对候选结果进行排序，并支持将结果导出为 JSON。
给定一个未知的哈希值，`hashdetect` 会告诉你它最可能是什么 —— 并且，由于许多哈希类型具有相同的格式，它会显示*所有*合理的匹配项，并根据每种类型在实际中的常见程度进行排序。它还会为每个匹配项打印 [hashcat](https://hashcat.net/hashcat/) 模式和 [John the Ripper](https://www.openwall.com/john/) 格式，以便你可以直接从识别阶段过渡到破解工作流。
## 功能
- 检测 9 种常见的哈希类型：MD5、SHA-1、SHA-224、SHA-256、SHA-384、SHA-512、NTLM、MD4 和 bcrypt。
- 按置信度对有歧义的匹配项进行排序（例如，一个 32 字符的十六进制字符串可能是 MD5、NTLM 或 MD4 —— 这三种都会显示出来，并按可能性从高到低排序）。
- 默认输出人类可读格式；使用 `--json` 输出机器可读的 JSON。
- 接受单个哈希、包含哈希的文件，或通过 stdin 传入的管道输入。
- 为每个匹配项打印 hashcat 模式和 John the Ripper 格式。
- 提供正确的退出代码，可在 shell 脚本中使用。
## 安装说明
要求 Python 3.10 或更高版本。
```
# 克隆仓库
git clone https://github.com/BrandonRoos/hashdetect.git
cd hashdetect
# 创建并激活虚拟环境
python -m venv .venv
# Windows (PowerShell)：
.\.venv\Scripts\Activate.ps1
# macOS / Linux：
source .venv/bin/activate
# 安装依赖（仅在运行测试时需要）
pip install -r requirements.txt
```
该工具本身仅使用 Python 标准库，因此运行它不需要任何额外的依赖项。
## 用法
### 识别单个哈希
```
python -m hashdetect 5f4dcc3b5aa765d61d8327deb882cf99
```
```
Possible matches for 5f4dcc3b5aa765d61d8327deb882cf99:
- MD5 (confidence 60%, length 32, hashcat 0, john raw-md5)
- NTLM (confidence 30%, length 32, hashcat 1000, john nt)
- MD4 (confidence 10%, length 32, hashcat 900, john raw-md4)
```
### 从文件读取哈希
每行一个哈希：
```
python -m hashdetect -f hashes.txt
```
### 从 stdin 读取（管道）
```
# macOS / Linux
cat hashes.txt | python -m hashdetect
# Windows PowerShell
type hashes.txt | python -m hashdetect
```
### JSON 输出
在上述任何命令中添加 `--json` 以获取结构化输出：
```
python -m hashdetect 5f4dcc3b5aa765d61d8327deb882cf99 --json
```
```
[
{
"input": "5f4dcc3b5aa765d61d8327deb882cf99",
"matches": [
{ "name": "MD5", "confidence": 0.6, "length": 32, "hashcat_mode": 0, "john_format": "raw-md5" },
{ "name": "NTLM", "confidence": 0.3, "length": 32, "hashcat_mode": 1000, "john_format": "nt" },
{ "name": "MD4", "confidence": 0.1, "length": 32, "hashcat_mode": 900, "john_format": "raw-md4" }
]
}
]
```
### 帮助
```
python -m hashdetect --help
```
## 工作原理
检测通过两种方式进行：
1. **结构匹配。** 具有独特格式的哈希 —— 例如 bcrypt 的 `$2b$12$...` 格式 —— 会通过正则表达式进行匹配，以捕获其确切结构。这些匹配是明确无误的。
2. **长度和字符集匹配。** 大多数原始哈希只是固定长度的十六进制字符串。例如，一个 64 字符的十六进制字符串可能是 SHA-256，但也可能是 SHA3-256、BLAKE2s 等。`hashdetect` 会返回每一个符合特征的匹配项并对它们进行排序。
置信度是根据分配给每种哈希类型的*流行度*分数（即它在实际中出现的频率）计算得出的。每个匹配项的置信度是其流行度除以所有匹配类型的流行度总和，因此对于给定的输入，这些分数的总和始终为 100%。
## 退出代码
| 代码 | 含义 |
|------|---------|
| 0 | 找到至少一个匹配项（或 JSON 模式，该模式始终返回 0） |
| 1 | 没有已知的哈希类型与输入匹配（文本模式） |
| 2 | 未提供输入（无哈希、无 `-f`、无管道 stdin） |
## 限制
`hashdetect` 通过**格式而非内容**来识别哈希。它无法验证某个字符串是否真正是给定类型的哈希 —— 只能根据长度和模式判断它*可能*是。一个 32 字符的十六进制字符串会被报告为可能的 MD5，是因为它的格式正确，而不是因为工具已确认它是由 MD5 生成的。请将输出视为一组排序后的假设，而不是确切的答案。
## 运行测试
```
pytest
```
## 免责声明
本工具旨在用于合法的安全工作 —— 渗透测试、取证、CTF 和教育 —— 且仅限于您拥有或被授权测试的系统和数据。您有责任遵守所有适用的法律。
## 许可证
本项目基于 MIT 许可证授权 —— 有关详情，请参阅 [LICENSE](LICENSE) 文件。
标签：DOS头擦除, Python, 哈希识别, 安全规则引擎, 密码破解, 无后门, 逆向工具