obslove/mailmap

# mailmap [](https://www.python.org/) [](#本地验证) [](./pyproject.toml) 通过 IMAP 邮箱分析，生成与特定电子邮件绑定的服务清单。 该项目会扫描整个 mailbox，复用 SQLite 本地缓存，交叉比对 headers、发件人、链接、HTML、文本和出现频率，从而生成一份关于可能与所分析地址相关联的保守服务清单。 除了服务清单之外，`mailmap` 还可以： - 生成 inbox 清理计划； - 在存在标准机制时，生成并执行 unsubscribe 操作； - 按服务归档低优先级的邮件流量。 ## 快速安装 进入项目目录，创建 venv 并安装： ``` cd /home/ven/Projects/mailmap python3 -m venv .venv source .venv/bin/activate pip install -e . ``` 用于开发和测试： ``` pip install -e .[dev] ``` 在 `fish` 中： ``` source .venv/bin/activate.fish ``` ## 标准流程 预期用法： 1. 将 `.env.example` 复制为 `.env`； 2. 填入 IMAP 主机、电子邮件和密码； 3. 运行 `mailmap`。 最小化流程： ``` cp .env.example .env mailmap ``` 默认命令会执行以下操作： 1. 读取 `.env` 和环境变量； 2. 通过 IMAP SSL 建立安全连接； 3. 发现有用的文件夹； 4. 分批按 UID 进行全面扫描； 5. 增量复用 SQLite 缓存； 6. 为服务分配具有可解释性的评分； 7. 自动生成报告。 在标准流程中生成的文件： - `services.json` - `services.csv` - `report.md` - `mailmap_cache.sqlite3` 在请求额外操作时生成的文件： - `hygiene.json` - `hygiene.md` - `unsubscribe_actions.json` - `unsubscribe_actions.md` - `clean_results.json` - `clean_results.csv` ## 项目功能 在一次正常运行期间，`mailmap` 会： 1. 加载来自 CLI、环境和 `.env` 的配置； 2. 验证配置，并在提供商存在问题时及早发出警告； 3. 以安全模式开启 IMAP 会话； 4. 自动选择有用的文件夹，如 `INBOX`、`All Mail`、`Archive` 和 `Sent`； 5. 默认忽略明显无用的文件夹，如垃圾邮件和回收站； 6. 分批按 UID 获取邮件，并将解析后的 payload 保存到 SQLite； 7. 从 headers、主题、纯文本正文、HTML 和链接中提取信号； 8. 规范化域名，减少基础设施和跟踪带来的噪音； 9. 按服务整合证据，并给出保守的评分； 10. 导出易读的结果，以便手动使用和后处理。 当使用操作标志时，该项目还可以： 11. 生成针对各服务的清理建议； 12. 通过 `List-Unsubscribe` 构建或执行 unsubscribe； 13. 通过 IMAP 归档低优先级流量。 ## 项目目标 该项目是为以下场景设计的： - 个人邮箱分析； - 传统 IMAP 提供商； - 使用本地缓存的增量重复运行； - 在搭载 Python 3.12+ 的 Linux 本地环境运行。 简单的提供商： - Gmail - Fastmail - Proton Bridge - 其他使用应用密码或经典 IMAP 的传统提供商 问题较多的提供商： - Outlook / Hotmail ## 配置说明 创建本地文件： ``` cp .env.example .env ``` 主要变量： - `MAILMAP_IMAP_HOST` - `MAILMAP_IMAP_PORT` - `MAILMAP_EMAIL` - `MAILMAP_PASSWORD` - `MAILMAP_OUTPUT_DIR` 可选变量： - `MAILMAP_DEFAULT_FOLDERS` - `MAILMAP_AUTH_MODE` - `MAILMAP_MICROSOFT_CLIENT_ID` - `MAILMAP_MICROSOFT_TENANT` - `MAILMAP_SMTP_HOST` - `MAILMAP_SMTP_PORT` 适用于 Gmail 的简单示例： ``` MAILMAP_IMAP_HOST=imap.gmail.com MAILMAP_IMAP_PORT=993 MAILMAP_EMAIL=voce@gmail.com MAILMAP_PASSWORD=sua_senha_de_app MAILMAP_AUTH_MODE=basic MAILMAP_OUTPUT_DIR=results ``` 适用于 Outlook/Hotmail 并使用 OAuth 的示例： ``` MAILMAP_IMAP_HOST=imap-mail.outlook.com MAILMAP_IMAP_PORT=993 MAILMAP_EMAIL=voce@hotmail.com MAILMAP_AUTH_MODE=microsoft-oauth MAILMAP_MICROSOFT_CLIENT_ID=seu-client-id-real MAILMAP_MICROSOFT_TENANT=consumers MAILMAP_OUTPUT_DIR=results ``` ## 预期交互 在绝大多数情况下，该项目运行时不会出现额外的提示。 尽管如此，某些情况可能需要交互： - Microsoft OAuth 的初始身份验证； - 在设备代码流程中的浏览器登录； - 当不存在 `mailto:` 时，通过 HTTP 链接进行手动 unsubscribe； - 在特定服务上使用 `-c` 之前的人工审查。 ## 可用选项 基础命令： ``` mailmap ``` 标志： - `--since YYYY-MM-DD` 仅扫描指定日期之后的邮件。 - `--quick` 使用更轻量、更快速的分析，适用于首次验证 pipeline。 - `--output DIR` 将产物保存到其他目录。 - `-c`, `--clean` 按服务归档低优先级的邮件流量。 - `-u`, `--unsub` 生成 unsubscribe 操作，并在可能的情况下通过 `mailto:` 执行 unsubscribe。 - `-y`, `--hygiene` 生成 inbox 清理计划。 - `-s`, `--services "A,B,C"` 将 `clean` 和 `unsub` 限制为指定的服务。 - `-h`, `--help` 显示帮助信息。 示例： ``` mailmap mailmap --since 2024-01-01 mailmap --quick mailmap --output results/ mailmap -y mailmap -u mailmap -c mailmap -c -u -s "Pinterest,Spotify,Twitch" ``` ## `-y`、`-u` 和 `-c` 的作用 ### `-y`, `--hygiene` 不会对 inbox 进行任何更改。 它只会按服务生成建议，例如： - `keep` - `keep-but-mute` - `unsubscribe-and-archive` - `archive-or-delete` 文件： - `hygiene.json` - `hygiene.md` ### `-u`, `--unsub` 尝试在 `List-Unsubscribe` 中查找 unsubscribe 机制。 行为： - 如果存在 `mailto:`，可以在配置后通过 SMTP 发送 unsubscribe； - 如果存在 HTTP 链接，则生成供手动操作的计划； - 避免承诺为任何服务提供通用的 unsubscribe。 文件： - `unsubscribe_actions.json` - `unsubscribe_actions.md` ### `-c`, `--clean` 会修改 mailbox。 行为： 1. 选择目标服务； 2. 定位映射到这些服务的邮件； 3. 寻找归档文件夹（`All Mail` 或 `Archive`）； 4. 复制到目标位置； 5. 从原文件夹中删除。 文件： - `clean_results.json` - `clean_results.csv` ## 主要输出 ### services.json 结构化格式的完整清单，包含： - 规范名称； - 关联域名； - 置信度； - 状态； - 类别； - 邮件计数； - 日期； - 证据摘要； - 代表性发件人； - 代表性主题； - 建议的操作。 ### services.csv 用于电子表格的平面导出。 ### report.md 人类可读的报告，包含： - 服务； - 评分； - 状态； - 类别； - 日期； - 摘要； - 评分依据； - 建议的操作。 ### mailmap_cache.sqlite3 本地缓存和增量检查点。 ## 项目结构 ``` src/mailmap/ actions.py aggregation.py app.py cli.py config.py content.py database.py domains.py evidence.py exporters.py fingerprints.py imap_client.py message_parser.py models.py oauth.py scoring.py ui.py tests/ examples/ ``` ## 准确性与局限性 项目目前已实现： - 按域名减少误报； - 区分基础设施、跟踪和真实品牌； - 降低以 newsletter 为主的数据流的权重； - 对强有力的证据占总邮件量比例过低的情况进行惩罚； - 当归属关系不明确时，降级为 `ambiguous`。 实际局限性： - unsubscribe 并非普遍适用； - 解除账户绑定不属于自动流程的一部分； - 某些提供商出于其自身决策破坏了设置的简便性，这不是项目的问题； - 为世界上的每一个 inbox 实现完美的归属关系并不是一个现实的目标。 ## 本地验证 运行测试： ``` PYTHONPATH=src .venv/bin/pytest -q ``` 查看 CLI 帮助： ``` PYTHONPATH=src .venv/bin/mailmap --help ``` ## 示例文件 参见： - [examples/services.json](examples/services.json) - [examples/services.csv](examples/services.csv) - [examples/report.md](examples/report.md)

标签：ESC4, IMAP, meg, OSINT, Python, SQLite, Unix, 代码示例, 信息安全, 威胁情报, 开发者工具, 数字足迹, 数据分析, 数据泄露, 无后门, 电子邮件安全, 网络安全, 账号映射, 资产清点, 退订管理, 邮箱卫生, 邮箱情报, 隐私保护