k3rt4s/email-evidence-tools

# email-evidence-tools 用于处理、精简、扫描和标记 mbox 或 IMAP 格式邮件归档的 Python 实用工具。适用于安全运营中对导出邮箱的分类筛查（网络钓鱼、数据泄露、策略违规）、内部调查、应急响应或法律证据审查。采用流式处理和失败恢复设计，可处理数 GB 的归档文件，且不会导致内存溢出或在网络断开时丢失进度。 **作者：** Jon Bowker **环境要求：** Python 3.10+。`pip install -r requirements.txt`。 ## 目录 - [docs/](docs/README.md)：email-evidence-tools 的相关支持文档，包括针对证据归档的工作站本地路径说明。 - [clean_evidence_csv.py](clean_evidence_csv.py)：清除 scan_mbox_for_evidence.py 生成的证据 CSV 文件中的 HTML 标签，并规范其中的空白字符。 - [extract_messages_by_address.py](extract_messages_by_address.py)：流式扫描一个或多个 mbox 归档，提取涉及指定地址的所有邮件，生成已过滤的 mbox 和索引 CSV，并支持失败恢复。 - [label_matching_emails_via_imap.py](label_matching_emails_via_imap.py)：连接到 IMAP 邮箱，对参与方地址匹配所配置域名的邮件应用标签或将其移至指定文件夹。 - [render_mbox_to_markdown.py](render_mbox_to_markdown.py)：将 mbox 归档渲染为单一的按时间排序的 Markdown 文档，包含取证邮件头、纯文本正文以及带有哈希值的附件清单。 - [requirements.txt](requirements.txt)：锁定的 Python 运行时依赖项。 - [scan_mbox_for_evidence.py](scan_mbox_for_evidence.py)：扫描 mbox 归档，查找可配置的证据关键字类别，并为每个匹配的句子生成一条 CSV 记录。 - [strip_attachments_from_mbox.py](strip_attachments_from_mbox.py)：创建去除附件的 mbox 归档副本，并生成记录每个提取附件的 SHA-256 清单 CSV。 ## 脚本 | 脚本 | 用途 | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `extract_messages_by_address.py` | 流式扫描一个或多个 mbox 文件，提取“发件人/收件人/抄送/密送/回复至/发件方/送达至”(From/To/Cc/Bcc/Reply-To/Sender/Delivered-To) 中包含指定地址（或域名子串）的所有邮件。输出已过滤的 mbox + 索引 CSV。按 Message-ID 去重。针对大型归档提供字节偏移检查点以支持恢复运行。 | | `render_mbox_to_markdown.py` | 将 mbox 渲染为按时间排序的 Markdown 证据文档，包含完整的取证邮件头、纯文本正文和附件清单（每个文件均提取至磁盘并计算哈希值）。 | | `scan_mbox_for_evidence.py` | 扫描 mbox 文件，提取与可配置证据关键字类别相匹配的邮件。 | | `label_matching_emails_via_imap.py` | 连接到 IMAP 邮箱，对地址域名匹配所配置域名的邮件应用标签/文件夹。 | | `strip_attachments_from_mbox.py` | 创建去除附件的 mbox 副本，并生成一份附件清单 CSV。 | | `clean_evidence_csv.py` | 通过移除 HTML 标签和规范空白字符，清理证据 CSV 输出中的文本字段。 | ## 用法 ``` python extract_messages_by_address.py --mbox-file "" --address "someone@example.com" python render_mbox_to_markdown.py --mbox-file "" --output-dir "" python scan_mbox_for_evidence.py --mbox-file "" --output-file "evidence_hits.csv" python strip_attachments_from_mbox.py --input-mbox "" python clean_evidence_csv.py --input-file "evidence_hits.csv" --output-file "evidence_hits_clean.csv" python label_matching_emails_via_imap.py --domains "example.com,example.org" --target-label "Labels/Evidence" ``` `extract_messages_by_address.py` 接受多个 `--mbox-file` 参数，并将 `--address` 视为不区分大小写的子串，因此传入 `@example.com` 即可匹配该域名下的所有地址。 所有脚本也支持通过环境变量接收输入以实现自动化；具体支持的变量请参阅各个脚本的 docstring。 ## 数据清理 这些工具会处理用户提供的邮件归档，其中可能包含 PII（个人身份信息）、凭证或敏感通信内容。请将本仓库仅视为代码库： - 请勿提交 mbox 文件、生成的 CSV、附件清单、检查点或 `.env` 文件。已包含的 `.gitignore` 会自动排除这些内容。 - 请通过命令行参数或环境变量传递输入和输出；切勿在脚本中硬编码地址、域名或标签。 - 对于针对大型归档的长时间运行任务，请将内容输出到仓库之外的目录中，以防止意外提交导致数据泄露。 ## 结构 ``` email-evidence-tools/ ├── clean_evidence_csv.py ├── extract_messages_by_address.py ├── label_matching_emails_via_imap.py ├── render_mbox_to_markdown.py ├── scan_mbox_for_evidence.py ├── strip_attachments_from_mbox.py ├── requirements.txt └── README.md ```

标签：Python, 代码示例, 安全取证, 安全运营, 库, 应急响应, 扫描框架, 数据分析, 无后门, 电子邮件处理, 逆向工具, 防御加固