KatrielMoses/MailAccess

███╗   ███╗ █████╗ ██╗██╗      █████╗  ██████╗ ██████╗███████╗███████╗███████╗

████╗ ████║██╔══██╗██║██║     ██╔══██╗██╔════╝██╔════╝██╔════╝██╔════╝██╔════╝

██╔████╔██║███████║██║██║     ███████║██║     ██║     █████╗  ███████╗███████╗

██║╚██╔╝██║██╔══██║██║██║     ██╔══██║██║     ██║     ██╔══╝  ╚════██║╚════██║

██║ ╚═╝ ██║██║  ██║██║███████╗██║  ██║╚██████╗╚██████╗███████╗███████║███████║

╚═╝     ╚═╝╚═╝  ╚═╝╚═╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝╚══════╝╚══════╝╚══════╝

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/)

[![Docker](https://img.shields.io/badge/Docker-Compose-blue.svg)](docker-compose.yml)

[![PyPI version](https://img.shields.io/static/v1?label=PyPI&message=0.5.1&color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/mailaccess/)

[![PyPI Downloads](https://img.shields.io/pypi/dm/mailaccess)](https://pypi.org/project/mailaccess/)

可自托管的开源情报（OSINT）平台，用于调查电子邮件地址。涵盖泄露数据库、社交网络、DNS记录和开放网络搜索——返回统一的暴露评分和结构化调查结果，可供导出或输入到Maltego。

专为在授权下工作的安全研究员、OSINT分析师和渗透测试人员打造。使用前请阅读 [免责声明](DISCLAIMER.md)。

## 安装

### 仅CLI（无Docker）


```
pip install mailaccess



# am JSONL

mailaccess investigate you@example.com

# Filter critical findings

# 0.5.3



# 0.5.2

mailaccess serve  # in one terminal

mailaccess investigate you@example.com  # in another



# 0.5.1

git clone https://github.com/YOUR_USERNAME/mailaccess

docker compose up -d
```


## 快速开始


```
mailaccess investigate you@example.com

mailaccess investigate you@example.com -o report.pdf

mailaccess investigate you@example.com --format jsonl

mailaccess investigate -                        # read email from stdin

mailaccess serve                                # start backend server on :8000

mailaccess keys list

mailaccess keys set HIBP_API_KEY your-key-here

mailaccess modules

mailaccess doctor                               # coming soon



# 0.5.0

mailaccess investigate email -m breach_deep

mailaccess investigate email -m all
```


![调查演示](https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/public/investigation.gif)

## 功能概述

- **身份图谱** — 跨平台关联每次调查中的账户、用户名和信号
- **手机号码恢复** — 发现并验证与目标关联的号码的流程
- **Telegram / WhatsApp 线索** — 在其它模块之外进行轻量级的即时通讯应用足迹检查
- **YAML驱动的平台系统** — 在 `backend/platforms/` 中定义社交类检查；社区可扩展，无需为每个网站编写新的Python代码
- **深度泄露模式** — 检查前100个严重性最高的泄露站点是否存在账户
- **历史情报** — Wayback Machine 归档搜索 + GitHub 提交者搜索
- **递归邮箱发现** — 通过姓名关联恢复同一人拥有的其他邮箱地址
- **凭据风险评分** — 单独的0-100凭据风险信号，分为 低 / 中 / 高 / 严重 等级，显示主要驱动因素和建议的后续步骤
- 并发模块执行 — 所有模块并行运行，结果流式返回
- WebSocket 流式传输 — 部分结果实时到达，无需轮询
- REST API + Web UI + CLI — 使用适合您工作流程的任何接口
- 插件模块系统 — 将 `.py` 文件放入 `backend/modules/` 即可自动注册；无需配置
- 6种导出格式：JSON、CSV、PDF、Markdown、STIX 2.1、Maltego XML
- Maltego 本地转换服务器 — 可直接从 Maltego 桌面应用运行调查
- Webhook 通知 — 支持 Slack、Discord 或任何 HTTP 端点
- 暴露评分（0–100）及风险标签：低 / 中 / 高 / 严重
- 默认使用 SQLite；通过 Docker Compose profile 可选 PostgreSQL

## 模块

| 模块 | 覆盖范围 | 需要密钥 | 可选启用 |

|--------|----------|--------------|--------|

| gravatar | 个人资料哈希查找 | 否 | 否 |

| hibp | 泄露检查 | 是 | 否 |

| breach_deep | 探测前100个严重性最高的泄露站点是否存在账户 | 否（HIBP语料库自动获取） | 是 |

| emailrep | 声誉 + 黑名单 | 否 | 否 |

| hudson_rock | 信息窃取器日志（免费） | 否 | 否 |

| google_dork | 5个自动化dork搜索 | 是（SerpAPI） | 否 |

| email_discovery | 通过姓名dork恢复同一人拥有的其他邮箱地址 | 是（SERPAPI_KEY） | 否 |

| domain_intel | 域名 + Shodan | 否（Shodan可选） | 否 |

| dns_lookup | MX/SPF/DMARC/DKIM/A/NS 记录提取 | 否 | 否 |

| whois_lookup | 域名WHOIS，隐私检测 | 否 | 否 |

| wayback | 通过 Wayback Machine CDX 查找邮箱公开出现过的历史页面 | 否 | 否 |

| github_commits | 查找使用此邮箱提交过的仓库，从git配置中提取真实姓名。提交搜索需要 GITHUB_TOKEN；用户资料搜索无需令牌。 | 否（GITHUB_TOKEN 可选，提交搜索需要） | 否 |

| xposedornot | 默认启用的直接邮箱到泄露语料库查询，提供泄露名称、数据类别和风险指标 | 否 | 否 |

| leakcheck | 默认启用的公开泄露语料库查询，覆盖区域广泛且具有信息窃取器路由功能 | 否 | 否 |

| ransomware_intel | 默认启用的域名受害者与勒索软件列表关联；跳过免费提供商 | 否 | 否 |

| social | 通过 YAML 覆盖13个平台 | 否 | 否 |

| social_links | 用户名提取，供情报枢轴查询 | 否 | 否 |

| account_discovery | Holehe 覆盖120+平台 | 否 | 是 |

| user_scanner | 205+平台向量 | 否 | 是 |

| whatsmyname | 700+平台 | 否 | 是 |

| breachdirectory | 第二泄露源 | 是 | 否 |

| username_pivot | 通过已恢复的用户名进行WMN查询 | 否 | 是 |

| permutation_discovery | 60种邮箱变体 | 否 | 是 |

| phone_intel | 手机号码验证 + WA/TG 线索 | 否 | 否 |

| messaging_hints | Telegram/WhatsApp 用户名检查 | 否 | 否 |

| ghunt | Gmail 深度情报 | 否（需要配置） | 是 |

| identity_graph | 跨平台集群分析 | 否 | 否（自动） |



## 身份图谱

每次调查都会生成一个跨平台的身份图谱，通过共享的用户名、照片、显示名称和泄露数据将账户关联起来。在以下地址查看：

`/investigation/:id/graph`

通过 `GET /api/report/{id}/graph` 导出为 D3 兼容的 JSON，或通过 `GET /api/report/{id}/clusters` 获取带有置信度评分的集群。

调查结果会自动分组为身份集群并进行置信度评分。在 CLI 输出中使用 `--show-collisions` 可展开低置信度匹配项。

## 历史情报

MailAccess 搜索 Wayback Machine CDX API，查找邮箱公开出现过的归档页面——包括已删除的博客文章、旧的论坛签名和被移除的联系页面。

通过作者邮箱搜索 GitHub 提交历史，揭示贡献过的仓库、git 配置中的真实姓名以及开发活动时间线。

## 深度泄露模式

通过 `ENABLE_BREACH_DEEP=true` 启用。

启动时获取完整的 HIBP 泄露语料库，按严重性（记录数 × 数据类别乘数）对站点进行排名，然后通过 YAML 探测和通用的重置流程推断，探测前100个严重性最高的站点是否存在账户。调查结果显示泄露名称、记录数、数据类别和严重性——为分析师提供概率性的凭据暴露估计。

示例输出：


```
⚠ adobe.com    CRITICAL  153M records

  [Passwords, Email, Password hints]

✓ dropbox.com  HIGH       69M records

  [Email, Passwords]

~222M records across 2 breaches potentially include this email's credentials
```


## 管道集成

MailAccess 友好支持管道集成：从 stdin 读取目标邮箱，流式输出 JSONL，并可在 CI/CD 脚本中根据退出码进行分支。


```
# 0.4.3

cat emails.txt | mailaccess investigate -



# 0.4.2

mailaccess investigate you@example.com --format jsonl | jq .



# 0.4.1

mailaccess investigate you@example.com --format jsonl | jq 'select(.severity=="critical")'
```


**退出码：** `0` 干净 · `1` 发现结果 · `2` 泄露 · `3` 错误

更多 GitHub Actions 示例请参见 [文档/集成](docs/integrations.md#pipeline-integration)。

## 添加平台

无需Python。将YAML文件放入 `backend/platforms/`：


```
cp backend/platforms/TEMPLATE.yaml backend/platforms/mysite.yaml
```


编辑字段，提交PR。

## 导出格式

| 格式 | `?format=` 值 | 用例 |

|--------|-----------------|----------|

| JSON | `json` | 程序化使用，存档 |

| CSV | `csv` | 电子表格分析 |

| PDF | `pdf` | 人类可读的报告 |

| Markdown | `markdown` | 维基，问题跟踪器 |

| STIX 2.1 | `stix` | 威胁情报平台 |

| Maltego XML | `maltego` | Maltego 图谱导入 |

## 集成

| 集成 | 方式 |

|-------------|-----|

| Maltego | 本地转换服务器，端点为 `POST /maltego/email_investigate`（无需API密钥） |

| Slack | 在 `.env` 中设置 `SLACK_WEBHOOK_URL` |

| Discord | 在 `.env` 中设置 `DISCORD_WEBHOOK_URL` |

| 通用webhook | `INTEGRATION_WEBHOOK_URL` + 可选的 `INTEGRATION_WEBHOOK_SECRET`（HMAC） |

## 自托管


```
cp .env.example .env      # all API keys are optional

docker compose up         # backend :8000  ·  frontend :3000
```


在浏览器中打开 **http://localhost:3000**。完整设置指南：[文档/自托管](docs/self-hosting.md)。

## CLI 参考

| 命令 | 描述 |

|---------|-------------|

| `mailaccess investigate ` | 对邮箱地址运行完整调查 |

| `mailaccess investigate -` | 从 stdin 读取目标邮箱 |

| `mailaccess serve` | 在 :8000 端口启动后端服务器 |

| `mailaccess history` | 列出历史调查 |

| `mailaccess keys list` | 显示所有已配置的 API 密钥 |

| `mailaccess keys set  ` | 设置 API 密钥 |

| `mailaccess keys unset ` | 移除 API 密钥 |

| `mailaccess config set-url ` | 将 CLI 指向 MailAccess 实例 |

| `mailaccess modules` | 列出所有可用模块 |

| `mailaccess commands` | 列出所有 CLI 命令 |

| `mailaccess doctor` | 检查配置和模块健康状态 _（即将推出）_ |

| `mailaccess investigate  -m` / `--enable` | 仅为本次运行启用可选模块。逗号分隔或 `all`。示例：`-m breach_deep,ghunt` |

`investigate` 命令上的 `--output` / `-o` 标志会将报告保存到文件。扩展名决定格式：`.json`, `.csv`, `.pdf`, `.md`, `.stix.json`, `.maltego.csv`。

当只提供裸文件名（无目录组件）时，文件会自动写入 `results/` 目录（例如 `-o report.json` → `results/report.json`）。该目录已被git忽略，因此调查输出永远不会被意外提交。包含目录组件的绝对或相对路径（例如 `-o /tmp/report.json`）将按原样写入。

## API 密钥

| 密钥 | 模块 | 获取地址 | 必需？ |

|-----|--------|-----------------|-----------|

| `HIBP_API_KEY` | `hibp` | https://haveibeenpwned.com/API/Key | 是（模块会跳过） |

| `SERPAPI_KEY` | `google_dork` | https://serpapi.com | 是（模块会跳过） |

| `SHODAN_API_KEY` | `domain_intel` | https://account.shodan.io | 否 |

| `EMAILREP_API_KEY` | `emailrep` | https://emailrep.io | 否 |

| `HUNTER_IO_API_KEY` | `hunter_io` | https://hunter.io | 否 |

| `GITHUB_TOKEN` | `github_commits` | https://github.com/settings/tokens | 否（可选） |

| `SLACK_WEBHOOK_URL` | Webhooks | https://api.slack.com/messaging/webhooks | 否 |

| `DISCORD_WEBHOOK_URL` | Webhooks | Discord 服务器设置 | 否 |

## 更新日志

### 0.4.0"

- 集群身份分析在超时时不再显示原始回溯，改为显示暗淡的备用消息
- 为 pip 安装的用户设定了硬编码的最小超时底线：
  account_discovery 120秒，username_pivot 60秒，
  user_scanner 180秒，whatsmyname 200秒
- 如果在 `.env` 中设置更高的值，该设置仍然优先

### Counting lines:

- 配置健壮性：CORS_ORIGINS 和字典字段现在接受纯字符串、逗号分隔的值和空字符串而不会崩溃
- 首次使用默认 `.env` 运行时不再出现 SettingsError
- 启动确认行显示配置已正确解析

### 1. Option A: auto-start (simplest)

- LeakCheck 集成：免费语料库查询，覆盖 XposedOrNot 错过的独联体/区域泄露
- XposedOrNot paste 信号在 CLI 和摘要栏中与泄露信号分开显示
- 勒索软件域名受害者关联：检查邮箱域名是否在勒索软件受害者列表中（ransomware.live + ransomlook.io）
- 摘要栏现在显示三部分分解：泄露：X | 贴文：Y | 窃取器：Z
- LeakCheck 窃取器类别现在正确路由到窃取器信号计数，而非泄露计数
- 从 JSON 导出中移除了遗留的 `credential_risk: null`

### 2. Server starts automatically, runs investigation,

- XposedOrNot 集成：免费直接泄露语料库查询，无需API密钥，默认开启，覆盖约70-80%的HIBP覆盖缺口
- 泄露规范化器：将所有来源的泄露调查结果去重为单一的规范记录，并附带来源归属
- 凭据风险评分：独立的0-100评分，带有等级、前3个评分驱动因素和建议的分析师行动。信息窃取器命中强制为“严重”。显示在 CLI、UI、所有导出和 Webhook 中。

### 3. stops when done.

- `github_commits`：在没有 `GITHUB_TOKEN` 时返回 `PARTIAL`（而非 `FAILED`），并包含设置提示
- `whois_lookup`：IANA 管理的域名现在能正确解析，修复了时区感知的日期时间问题，提取的字段更丰富（`organisation`, `nserver`, `registered`, `expires`）

### 4. Option B: keep server running

- 默认模块现在无需任何标志即可运行：`whatsmyname`, `account_discovery`, `user_scanner`, `username_pivot`, `permutation_discovery`, `phone_intel`, `messaging_hints`
- `-m` / `--enable` 标志用于每次运行选择性启用模块（`breach_deep`, `ghunt`, `email_discovery`）
- `-m all` 启用所有三个可选模块
- 无效的 `-m` 模块名会显示有用的警告

### 5. Option C: full stack with Web UI

- 深度泄露模式和邮箱发现改进
- 修复了携带过来的电话号码提取器误报问题

### 6. Enable specific opt-in modules for one run

- 深度泄露模式：探测前100个严重性最高的泄露站点是否存在账户（可选，`ENABLE_BREACH_DEEP=true`）
- 姓名 → 邮箱发现：通过 SerpAPI dork 恢复同一人拥有的其他邮箱地址（需要 `SERPAPI_KEY`）
- Wayback Machine：CDX 搜索邮箱公开出现过的历史页面
- GitHub 提交搜索：在所有公开提交中按作者邮箱搜索，揭示仓库 + git 配置中的真实姓名（`GITHUB_TOKEN` 可选）
- 泄露语料库：从 HIBP 公开 API 自动获取，按记录数 × 数据类别乘数严重性排名，缓存24小时

## 故障排除

![故障排除演示](https://static.pigsec.cn/wp-content/uploads/repos/2026/05/376192b94a124612.gif)

## 链接

| | |

|-|-|

| [自托管指南](docs/self-hosting.md) | Docker Compose, `.env` 参考, PostgreSQL, 代理/Tor, Maltego 设置 |

| [模块参考](docs/modules.md) | 所有模块，调查结果模式，添加新模块 |

| [API 参考](docs/api.md) | REST 端点，WebSocket 事件，身份验证 |

| [导出格式](docs/exports.md) | 支持的格式，MIME 类型，文件名约定 |

| [集成](docs/integrations.md) | Maltego, Slack, Discord, 通用 webhooks |

| [贡献](CONTRIBUTING.md) | 添加模块，添加导出器，代码风格，PR 清单 |

| [PyPI](https://pypi.org/project/mailaccess/) | `pip install mailaccess` |

| [GitHub](https://github.com/YOUR_USERNAME/mailaccess) | 源代码，问题，发布 |

## 许可

MIT。MailAccess 查询的所有数据均来自公共来源。有关授权用例和法律责任，请参阅 [免责声明](DISCLAIMER.md)。