soyrageagency/mailaegis

## 📑 目录 - [为什么选择 MailAegis](#-why-mailaegis) - [快速开始](#-quick-start) - [查看截图](#-see-it) - [也支持手机端](#-on-a-phone-too) - [安装到手机](#-two-ways-to-get-it-on-your-phone) - [检测能力](#-what-it-detects) - [邮件客户端](#-the-mail-client) - [无需应用密码登录](#-sign-in-without-an-app-password-oauth-20) - [工作原理](#-how-it-works) - [桌面应用 (macOS & Windows)](#-desktop-app-macos--windows) - [集成方式](#-integrate-it) - [配置说明](#-configuration) - [隐私与安全](#-privacy--safety) - [项目结构](#-project-structure) - [开发指南](#-development) - [常见问题](#-faq) - [SoyRage 套件中的更多项目](#-more-from-the-soyrage-suite) - [支持项目](#-support-the-project) - [致谢与许可](#-credits--license) ## 💡 为什么选择 MailAegis **商业邮件妥协是损失最昂贵的网络犯罪** —— 年复一年地超过 勒索软件 —— 它以纯文本形式到达，没有 附件，没有链接，签名引擎没有任何可以匹配的内容。 企业邮件过滤器用一个比特位来回答这个问题：投递或隔离。因此 当财务人员问“*这封发票是真的吗？*”时，没人能在 一分钟内告诉他们**原因**。那一分钟就是整个攻击的全部。 MailAegis 就是为那一分钟而构建的。 | | | | --- | --- | | 🧾 **自我解释** | 每个结论都是一系列发现，包含严重性、通俗的解释和证据：*“文本写的是 `portal.corp.example`，但链接指向了 `secure-corp-login.example`”*。 | | 🧠 **理解意图，而非仅仅是签名** | 银行账户详情变更、紧急情况、保密施压、来自免费邮箱的高管冒充 —— 对 BEC 的惯用伎俩进行评分。 | | 🧭 **展示证据** | 完整的 `Received:` 链，逐跳显示原始 IP、其反向 DNS 及其信誉。这就是“*它到底是从哪来的？*”的答案。 | | 🔬 **六重意见，一个结论** | 您自己的 ClamAV、VirusTotal 信誉、Hybrid Analysis 沙箱行为、SPF/DKIM/DMARC、投递路径取证以及启发式引擎 —— 并且它会告诉您**实际运行了哪些引擎**。 | | 📬 **像邮件客户端一样阅读** | 多个邮箱、文件夹、已发送、搜索运算符、威胁类别、标签、键盘快捷键。以您实际工作的方式进行分类审查，而不是通过日志文件。 | | ✉️ **同时也扫描您发送的邮件** | 被盗账户向您的客户发送恶意软件是损失更惨重的事件。出站邮件在提交前会进行扫描。 | | 🔗 **融入 pipeline** | `cat message.eml \| mailaegis scan` 会为 干净/可疑/恶意 退出并返回 `0/1/2` —— Postfix、procmail 或 milter 所需的全部信息。 | | 📦 **零运行时依赖** | MIME 解析器、IMAP 客户端、SMTP 客户端、ClamAV 协议和 Web 服务器都是基于 Node 核心手写的。除了这个仓库，没有什么需要审计的。 | ### 适用人群 - **没有 SOC 的 IT 团队**，需要快速、有理有据地回答“这是真的吗？”。 - 对多个客户邮箱中的可疑邮件进行分类的 **MSP**。 - 想要投递路径、IOC 和 `.eml`，而不是看仪表盘的 **安全分析师**。 - **任何自托管邮件** 的人 —— Mailcow、Zimbra、Postfix、Proton —— 想要一个自己控制的扫描器。 ### 对比情况 | | MailAegis | 安全邮件网关 | Thunderbird / Outlook | | --- | :---: | :---: | :---: | | 解释一封邮件**为什么**不好 | ✅ 逐条说明 | ⚠️ 有时有评分 | ❌ | | BEC / 意图检测 | ✅ | ✅ | ❌ | | 投递路径取证 | ✅ | ⚠️ 原始头 | ⚠️ 原始头 | | 可以在其中办公的邮件客户端 | ✅ | ❌ | ✅ | | 自托管，数据不外传 | ✅ | ❌ | ✅ | | 成本 | **免费且开源** | 按席位按月收费 | 免费 | ## ⚡ 快速开始 **您需要 [Node.js ≥ 18](https://nodejs.org/)。** 想要桌面应用？→ [下载构建版](#-desktop-app-macos--windows)。 **macOS / Linux** ``` curl -fsSL https://raw.githubusercontent.com/soyrageagency/mailaegis/main/install.sh | bash ``` **Windows (PowerShell)** ``` irm https://raw.githubusercontent.com/soyrageagency/mailaegis/main/install.ps1 | iex ``` 或手动执行： ``` git clone https://github.com/soyrageagency/mailaegis.git && cd mailaegis npm install && npm run build node dist/index.js demo --demo # analyse the built-in corpus, no keys needed node dist/index.js serve --demo # open http://127.0.0.1:4850 ``` ``` $ mailaegis demo --demo ✓ CLEAN score 0/100 Legitimate supplier invoice ✓ CLEAN score 0/100 Marketing newsletter ✓ MALICIOUS score 100/100 CEO fraud / bank-detail change (BEC) ✓ MALICIOUS score 100/100 Credential phishing from a look-alike domain ✓ MALICIOUS score 100/100 Macro-enabled attachment carrying malware ``` ## 🖼️ 查看截图 ### 📲 在手机上使用的两种方式

**1 · 添加到主屏幕 —— 无需安装** MailAegis 是一个 **PWA**。在 Chrome 或 Safari 中打开您托管的实例并轻触 *添加到主屏幕*。您将获得应用图标、全屏显示、无浏览器地址栏，并且 即使网络状况不佳，界面也能瞬间加载。 **2 · 安装 APK** 1. 从 [最新发布版本](https://github.com/soyrageagency/mailaegis/releases/latest) 获取 `MailAegis-*-android.apk`。 2. 打开它，并在 Android 提示时允许**从未知来源安装**。 3. 输入您的 MailAegis 地址 —— `https://mail.yourcompany.com` 或像 `http://192.168.1.20:4850` 这样的局域网地址。它会记住这个地址。 **为什么应用需要输入地址。** MailAegis 在 Node 进程中分析邮件 —— MIME 解析、ClamAV、IMAP、SMTP —— 这些无法在 APK 内部运行。因此 Android 应用是您已经运行的服务器的**客户端**。它不与任何 其他东西通信；没有需要注册的 MailAegis 云端。

The APK's first screen

## 🔍 检测能力 | 层级 | 示例 | | --- | --- | | 🪪 **身份 & BEC** | 来自免费邮箱的高管冒充 · 嵌入不同地址或您品牌名称的显示名称 · **相似域名** (`c0rp-example.com`, 抢注等) · 回复被重定向到另一个域名 | | 🎣 **网络钓鱼** | 链接文本与其目标不符 · 凭证收集页面 · 纯 IP 和 punycode 主机 · URL 缩短服务 | | 📎 **附件** | 可执行文件和被阻止的扩展名 · **双重扩展名** (`statement.pdf.exe`) · 启用宏的 Office 文件 · **magic-byte/扩展名不匹配** · 压缩包中的可执行文件 · 受密码保护的压缩包 | | 🔐 **身份验证** | SPF 失败/软失败 · DKIM 无效 · DMARC 失败 · 信封/From 不一致 · 伪造的*内部*发件人 | | 🧠 **意图** | 银行账户详情变更请求 · 紧急电汇 · 礼品卡骗局 · 账户过期施压 · 保密施压 | | 🛰️ **投递路径** | 重建完整的 `Received:` 链 —— **邮件真正来自的 IP**、其反向 DNS、每一跳及停留时间 · 标记与 From 域名矛盾的反向 DNS、伪造的中继身份和单跳注入 · 检查**源 IP 的信誉** | | 🦠 **扫描器** | **ClamAV** 签名命中 · **VirusTotal** 文件、URL 和 IP 检测 · **Hybrid Analysis** 沙箱引爆判定 · 任何引擎都未见过的文件 | 每个发现都有相应的权重；总分（上限为 100）即为风险评分，您的阈值会将其转换为 **干净 · 可疑 · 恶意。发现结果还会被分组到**威胁类别**中 —— 恶意软件、网络钓鱼、欺诈/BEC、欺骗 —— 以便分析师一眼就能看出这是*哪种类型*的威胁。 ## 📬 邮件客户端 MailAegis 不是一个生硬地连接在扫描器上的仪表盘 —— 它是一个您可以 整天在其中办公的邮件客户端，在每一行的底部都有防病毒层支持。 **邮箱。** 一家公司拥有 `security@`、`finance@` 和 `info@`，因此 MailAegis 可以**同时管理多个邮箱**。每个邮箱保留各自的文件夹、凭证和判定 计数；*所有邮箱* 是一个统一的收件箱，每一行都会显示它属于哪个 账户。支持 **Microsoft 365、Google Workspace、Mailcow、 Zoho、Zimbra、Fastmail、iCloud、IONOS、OVHcloud、Amazon WorkMail** 和 Proton Bridge 的一键预设 —— 并附带应用密码警告，可避免最常见的连接 失败。 **编写邮件。** 撰写、回复、全部回复和转发，支持抄送/密送和附件。 普通客户端会默默执行，而本客户端拒绝执行的两件事： - 回复带有标记的邮件时，会**首先声明判定结果和评分**。 - 当原邮件的 `Reply-To` 指向与 `From` 不同的地址时，编辑器会 **向您展示这两个地址** —— 这种重定向正是商业邮件妥协得以 成功的原因。 并且您发送的所有内容都会在**出口处被**同一个引擎**扫描**。如果 判定为恶意，邮件会被扣留并列出原因；只有再次 刻意按下发送，才会强制发送。 **处理队列。** | | | | --- | --- | | 🔎 **搜索运算符** | `from:acme` · `subject:invoice` · `has:attachment` · `has:link` · `is:malicious` · `is:unread` · `is:pinned` · `label:soc` · `score>50` · `in:finance` — 其他任何内容均作为纯文本搜索 | | ⭐ **保存的搜索** | 为查询命名一次；它将变成列表上方的一个标签 | | 📌 **置顶、标记、已读/未读** | 置顶的行将悬浮于任何排序顺序之上 | | ☑️ **批量操作** | 选中多个，然后一次性标记、置顶、标旗、贴标签或导出 | | 🔃 **排序和快速筛选** | 风险 · 最新 · 发件人 · 主题，以及一键 未读 / 高风险 / 已标旗 / 带文件 | | ⌨️ **键盘快捷键** | `j k` 移动 · `Enter` 打开 · `c` 撰写 · `r a f` 回复/全部回复/转发 · `u p s x e` 标记 · `/` 搜索 · `?` 查看完整列表 | | 💾 **导出** | 下载原始字节为 `.eml` —— 包含源码、Headers 等所有内容 | | 🌙 **深色模式** | 一键切换。另外还有您可以关闭的细微声音提示 | | 🔔 **公告** | 有新版本发布时角落会出现一张卡片 —— 由[本仓库中的一个 JSON 文件](channel/)驱动 | | 🧾 **原始来源** | 在查看器中查看 Headers、正文或所有内容 —— 没人应该只能凭借工具的一面之词来确认 Header | | 📋 **复制 IOC** | 哈希、URL、主机和源 IP，均已**消除威胁** (`hxxps://`, `evil[.]example`) 并可直接粘贴到工单中 | | 🚫 **阻止 / 允许发件人** | 按地址或按域名，附带解释原因的备注 | | ↩️ **撤销发送** | 用六秒钟来追回发错的收件人 —— 这是犯错后代价最小的时刻 | | ✍️ **签名和草稿** | 每个邮箱一个签名；编辑器会自动保存并提供草稿恢复 | | 🔄 **自动刷新** | 每两分钟一次，并带有提示告知您刚收到的新邮件是否安全 | | 📜 **审计追踪** | 记录每一个决策，并可根据需要转发到您的 SIEM | ### 🔑 无需应用密码登录 (OAuth 2.0) Microsoft 正在逐个租户地关闭基本身份验证，而 Google 仅在账户启用了双重验证 (2-Step Verification) 时才接受应用密码。这些权宜之计。 MailAegis 支持官方认可的机制，**XOAUTH2**，适用于 IMAP *和* SMTP。 **只需一次**，注册一个应用程序 —— [Entra ID](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps) 或 [Google Cloud console](https://console.cloud.google.com/apis/credentials) —— 使用 `http://localhost` 作为 **桌面 / 移动** 重定向 URI。然后： ``` OAUTH_PROVIDER=microsoft OAUTH_CLIENT_ID= mailaegis oauth ``` 您的浏览器将会打开，登录并同意授权后，MailAegis 会打印出需要 粘贴到 `.env` 中的配置行： ``` OAUTH_PROVIDER=microsoft OAUTH_CLIENT_ID=… OAUTH_TENANT=contoso.onmicrosoft.com # microsoft only OAUTH_REFRESH_TOKEN=… IMAP_HOST=outlook.office365.com IMAP_USER=security@contoso.com # no password needed ``` 此流程使用环回（“已安装应用程序”）方式，并带有 **PKCE** —— 重定向会落在 `127.0.0.1`，任何其他本地进程也可能在不同的 端口上监听它，因此如果验证器丢失，被盗的授权代码将毫无价值。 **刷新 token 是凭证**：请像对待密码一样保管它。 除非是发往提供商自己的 token endpoint，否则它永远不会离开您的机器。访问 token 仅存在于内存中，并在过期前一分钟重新获取，因此 token 不会在获取过程中失效。如果提供程序轮换了刷新 token，MailAegis 将打印出新的 token，而不会在一个月后默默失败。 ### 审计追踪与 SIEM 每一个日后值得为之辩护的决定 —— 被隔离的邮件、被扣留的 出站邮件、**无视拒绝强制执行的发送**、被添加到 列表中的发件人 —— 都会被追加到 `audit.jsonl` 中，并且如果您设置了 `MAILAEGIS_WEBHOOK_URL`， 会实时 POST 到 Splunk、Sentinel、Wazuh 或 n8n 工作流中。 ``` {"at":"2026-07-22T14:02:11.318Z","action":"outbound.blocked","id":"MA-20260722-a1b2c3", "verdict":"malicious","score":100,"from":"ana@corp.example","to":["victim@partner.example"], "rules":["blocked-extension","double-extension"],"product":"MailAegis","version":"1.2.0"} ``` 三个刻意的限制： - **它永远不会阻塞。** 写入只是一小行；webhook 是 即发即忘的，带有短超时，并在反复失败后自动退避。宕机的 SIEM 绝不能阻止邮件被分析。 - **它从不携带邮件内容。** 主题、正文和附件都不会被 包含在内 —— 规则*名称*会发送，但它们匹配的证据不会。审计 追踪是决策的记录，而不是一堆带有不同权限、存在于 日志目录中的所有人邮件的第二个副本。 - **它是只追加的，并按大小轮转**，因此它不会悄悄塞满磁盘。 ### 关于允许列表 这两个部分的故意是不对称的，因为它们带有截然不同的 风险。 **阻止是无条件的。** 无论邮件看起来有多 干净，被阻止的发件人都会被标记为恶意。 **允许则不然。** 一个简单地将分数归零的允许列表是电子邮件 安全工具可能发布的最为危险的功能：一旦供应商被列在其中，伪装成 该供应商就变成了绕过所有其他引擎的最廉价方式 —— 而且伪造一个 `From` 地址没有任何成本。 因此，只有当邮件**同时证明它确实来自** 该发件人时，该条目才会生效：DMARC `pass`，或者 SPF *和* DKIM 都通过且对齐。显式的 DMARC 失败永远不会被覆盖。来自 允许列表地址的未经验证的邮件，其评分完全如同列表为空一样，**并且 报告会告诉您发生了什么**。 即便如此，允许也仅抑制*启发式*怀疑 —— 语气、紧迫性、 相似度评分。ClamAV 命中、VirusTotal 检测或沙箱判定结果 永远不会被免除：一个邮箱被盗用的受信任供应商是再寻常不过的日常事件。 已读和置顶状态存在于**您的浏览器中，而不是 IMAP 服务器上**。 这是刻意为之的：MailAegis 使用 `BODY.PEEK` 获取邮件，因此连接它 永远不会改变您的用户在 Outlook 中看到的内容。写回 `\Seen` 会在分析师第一次打开邮件时就破坏这个承诺。 ## 🛠️ 工作原理 ``` parse → authenticate → trace → heuristics → ClamAV → VirusTotal → Hybrid → score (MIME) (SPF/DKIM/DMARC) (Received (in-house) (your (file/URL/IP (sandbox chain, IP) daemon) reputation) verdict) ``` 每份报告都会记录**实际运行了哪些引擎**，因此降级的 pipeline 给出的“一切正常”永远不会被误认为是真正的安全。 **零运行时依赖** —— MIME 解析器、IMAP 客户端、clamd INSTREAM 协议、VirusTotal 客户端和 HTTP 服务器都是直接基于 Node 核心编写的。 ## 💻 桌面应用 (macOS & Windows) MailAegis 作为一个具有原生体验的桌面应用程序发布，因此分析师无需使用终端。 **[⬇️ 下载最新版本](https://github.com/soyrageagency/mailaegis/releases/latest)** —— 提供 macOS (Intel + Apple Silicon) 的 `.dmg` 和 Windows 的 `.exe`。 桌面构建版本会在本地启动分析器，并在其专属窗口中打开邮件客户端 —— 不会向网络暴露任何内容。构建版本由 GitHub Actions 在每次标记发布时生成；参见 [`.github/workflows/release.yml`](./.github/workflows/release.yml)。 ``` # 自己构建它 cd desktop && npm install && npm run dist ``` ## 🔌 集成方式 ### 1. 命令行 (Postfix / procmail / 任何 MTA) ``` cat message.eml | mailaegis scan # exit 0 clean · 1 suspicious · 2 malicious · 3 error mailaegis scan message.eml --json # full analysis as JSON mailaegis scan message.eml --report # also write HTML + JSON + Markdown ``` 一个最小化的 Postfix `content_filter` 包装器： ``` #!/bin/sh # /usr/local/bin/mailaegis-filter — 由 Postfix 调用并在 stdin 上传递消息 tee /tmp/in.$$ | mailaegis scan >/dev/null 2>&1 case $? in 2) exit 69 ;; # malicious → bounce (EX_UNAVAILABLE) 1) exec sendmail -i -X quarantine "$@"

MailAegis 会把我的邮件发送到其他地方吗？

不会。邮件正文和附件内容永远不会离开您的机器。VirusTotal 和 Hybrid Analysis **仅接收 SHA-256 哈希**、URL 标识符和 源 IP —— 绝不包含文件，绝不包含文本。ClamAV 在您自己的 daemon 上运行。 在未配置 API 密钥的情况下，MailAegis 完全不会发出任何外部请求。

它会将我的邮件标记为已读吗？

不会。所有内容都通过 IMAP `BODY.PEEK` 获取，它不会设置 `\Seen` 标志。连接 MailAegis 永远不会改变您的用户在 Outlook 中看到的内容 —— 这也是为什么已读/置顶状态保存在浏览器中而不写回服务器的另一个原因。

它可以连接到 Microsoft 365 / Gmail 吗？

可以，有两种方式。 **OAuth 2.0（推荐）。** 运行 `mailaegis oauth`，在浏览器中登录，且 完全不涉及密码。这是进入已关闭基本身份验证的租户的 唯一途径 —— Microsoft 正在逐步推进这一点。参见 [无需应用密码登录](#-sign-in-without-an-app-password-oauth-20)。 **应用密码。** 在启用了基本身份验证的地方仍然有效：Microsoft 需要账户启用 MFA，Google 需要双重验证。在 UI 中选择任一预设都会链接到供应商提供的官方说明。

这是一个反垃圾邮件过滤器吗？

不是 —— 而且是刻意为之。垃圾邮件过滤是一个已经解决的大容量问题，您的 MX 已经处理了。MailAegis 是为那些**穿透了过滤**的邮件准备的：看起来很真实的发票、 不是真正 CEO 的 CEO。请在您的网关之外使用它，而不是 替代它。

我需要 VirusTotal 或 ClamAV 的密钥才能试用吗？

不需要。`npx mailaegis serve --demo` 将以逼真的语料库和模拟扫描器判定结果运行整个程序。本 README 中的每一张截图都来自该 demo。

我可以为我的团队自托管吗？

可以。`mailaegis serve` 是一个没有数据库的纯 Node HTTP 服务器 —— 将它 放在您的反向代理后面，设置 `MAILAEGIS_API_TOKEN`，响应式 UI 就可以在 桌面和手机上工作。对于物理隔离的环境，请设置 `MAILAEGIS_UPDATE_CHECK=false`，它就绝对不会发出任何外部请求。

采用什么许可协议？

**SoyRage Attribution License** —— 使用它，fork 它，进行商业部署； 只需保留对 [SoyRage Agency](https://soyrage.es/) 的署名。参见 [LICENSE](./LICENSE)。

## 🧰 SoyRage 套件中的更多项目 相同的设计，同样的用心。**如果其中一个能为您节省时间，点个 ⭐ 就是对我们莫大的帮助。**

标签：DAST, DMARC, MITM代理, 反病毒, 恶意软件分析, 桌面应用, 自动化攻击, 自托管, 邮件安全, 钓鱼检测