hashscanner/hashscanner-python
GitHub: hashscanner/hashscanner-python
该项目是 HashScanner API 的官方 Python 客户端及命令行工具，帮助用户免下载数百 GB 数据集即可快速查询超 15 亿条 NIST NSRL 已知文件哈希。
Stars: 0 | Forks: 0
# HashScanner Python 客户端
用于 **[HashScanner](https://www.hashscanner.com) API** 的 Python 客户端 —— 通过 API 查询 **超过 15 亿条 NIST NSRL 已知文件哈希**（MD5 / SHA-1 / SHA-256），支持单个或批量查询。
HashScanner 将 NIST National Software Reference Library 放到了线上，这样您就可以从数据中过滤掉**已知**的部分，专注于未知的内容 —— 而无需您自己下载和维护约 700 GB 的 RDS。
## 安装
```
pip install hashscanner
```
## 快速开始
```
from hashscanner import Client
hs = Client("hs_xxxx_sk_xxxx") # or set HASHSCANNER_API_KEY
result = hs.lookup("d41d8cd98f00b204e9800998ecf8427e")
if result.found:
print(result.type, result.file_name, result.product, "via", result.source)
else:
print("not in NSRL — worth a closer look")
```
匹配成功意味着该文件是**已知的**（已编目在 NSRL 中）—— 并不代表它是安全的、无害的或恶意的。您可以使用它来筛除您已经识别的文件。
### 批量查询（异步）
对于大型数据集 —— 每个任务最多支持 100,000 个哈希 —— 请提交批量任务。客户端会为您处理 提交 → 轮询 → 下载 的整个流程：
```
hashes = ["d41d8cd9...", "da39a3ee...", ...]
# JSON: 返回结果字典列表
for record in hs.bulk(hashes):
print(record["hash"], record["found"])
# CSV: 返回原始 CSV 文本
csv_text = hs.bulk(hashes, format="csv")
```
更倾向于自己执行这些步骤？
```
job = hs.submit_bulk(hashes, format="json") # -> BulkJob (queued)
job = hs.wait(job, poll_interval=3) # poll until completed/failed
for record in hs.iter_results(job): # stream NDJSON results
...
```
### 并发执行少量查询
```
results = hs.lookup_many(["", "", ""])
```
## 命令行
该包安装了一个 `hashscanner` 命令：
```
export HASHSCANNER_API_KEY="hs_xxxx_sk_xxxx"
# 单个查询
hashscanner lookup d41d8cd98f00b204e9800998ecf8427e
hashscanner lookup d41d8cd9... --json
# 批量：每行一个哈希值（使用 '-' 表示 stdin），JSON (NDJSON) 或 CSV
hashscanner bulk hashes.txt
hashscanner bulk hashes.txt --format csv -o results.csv
cat hashes.txt | hashscanner bulk -
```
## 错误
所有错误均派生自 `hashscanner.HashScannerError`：
| 异常 | 何时触发 |
|---|---|
| `AuthenticationError` | 401 —— 密钥缺失/无效 |
| `SubscriptionInactiveError` | 403 —— 需续订/升级 |
| `RateLimitError` | 429 —— 触发每分钟速率限制或每月配额限制（`.retry_after`, `.reset`） |
| `BadRequestError` | 400 —— 无效哈希 / 任务过大 |
| `NotFoundError` | 404 —— 未知的/已过期的批量任务 |
| `JobFailedError` | 批量任务状态为 `failed` |
| `APIError` | 其他非 2xx 状态码 |
单次查询未命中**不是**错误 —— 它会返回 `LookupResult(found=False)`。
## 链接
- API 文档：
- 价格与限制：
- 注册（免费）：
## 许可证
MIT
标签：API客户端, NIST NSRL, Python, 哈希查询, 数字取证, 文档结构分析, 无后门, 自动化脚本, 逆向工具