gregory-dean/email-breach-checker
GitHub: gregory-dean/email-breach-checker
一款 Python 命令行工具，通过 Have I Been Pwned API 批量查询邮箱泄露情况并生成结构化 CSV 报告。
Stars: 0 | Forks: 0
# 邮箱泄露检查器
从文件中读取邮箱地址，通过 [Have I Been Pwned](https://haveibeenpwned.com/) API 进行查询，并将分组汇总的结果写入 CSV。
## 环境要求
- Python 3.10+
- 网络连接
- HIBP API key（[在此申请](https://haveibeenpwned.com/API/Key)）
## 安装说明
```
pip install .
```
用于开发环境：
```
pip install -e ".[dev]"
```
## 配置
通过环境变量或 `.env` 文件设置你的 API key：
```
export HIBP_API_KEY=your_api_key
```
或者将 `.env.example` 复制为 `.env` 并进行编辑。
## 使用说明
```
email-breach-checker INPUT_FILE [options]
```
参数：
| 选项 | 描述 | 默认值 |
|--------|-------------|---------|
| `INPUT_FILE` | 包含邮箱的 `.txt` 或 `.csv` 文件路径 | 必填 |
| `--output PATH` | 汇总 CSV 输出路径 | `results.csv` |
| `--failed-log PATH` | 查询失败记录的日志文件 | `failed_emails.log` |
| `--delay SECONDS` | 请求之间的暂停时间 | `6.0` |
| `--api-key KEY` | 覆盖 `HIBP_API_KEY` | 取自环境变量 |
| `--quiet` | 隐藏单个邮箱的进度信息 | off |
| `--version` | 打印版本号并退出 | |
| `--help` | 显示帮助信息并退出 | |
示例：
```
email-breach-checker examples/emails.txt --output results.csv
```
你也可以作为模块运行：
```
python -m email_breach_checker examples/emails.txt
```
## 输入格式
**文本文件 (`.txt`)**：每行一个邮箱地址。
**CSV 文件 (`.csv`)**：通过模式匹配从所有单元格中提取邮箱。自动移除重复项。
请参阅 [examples/emails.txt](examples/emails.txt) 查看文本输入文件示例。
## 输出
汇总 CSV 文件中，每个邮箱占据一行，包含泄露次数、标题、域名、日期、验证状态、受影响次数、泄露的数据类型以及截断的描述。
查询失败的记录将追加到失败日志文件中，并包含 HTTP 状态码和错误详情。
退出码：
| 代码 | 含义 |
|------|---------|
| `0` | 所有查询均成功 |
| `1` | 一个或多个查询失败 |
| `2` | 用法错误（缺少文件、参数无效、缺少 API key） |
## 开发
运行测试和 lint：
```
pytest
ruff check src tests
```
## 许可证
MIT。详见 [LICENSE](LICENSE)。
标签：Atomic Red Team, Python, Retryablehttp, 反取证, 安全规则引擎, 安全评估, 数据泄露检测, 无后门, 逆向工具