Mailuminati/Guardian

GitHub: Mailuminati/Guardian

高性能、可扩展的邮件垃圾/钓鱼检测服务，利用本地学习与共享情报提升检测精度与隐私保护。

Stars: 14 | Forks: 3

Docker Pulls Docker Image Size Docker Image Version

# Mailuminati Guardian **Guardian** 是一个 **高性能、可扩展的垃圾邮件/钓鱼检测与执行服务**，设计用于与您的 MTA 和过滤引擎并行运行。它以 **超高速** 分析传入邮件（结构指纹 + 邻近检测），应用 **即时本地学习** 来自操作员/用户的报告，仅在需要时联系 **Mailuminati Oracle** 以获取共享、协作的情报。 Guardian 适用于任何运营电子邮件基础设施的人员，无论是从大型提供商到小型社区运行服务器，都能在最低开销下实现快速决策。 ## 目录 - [快速开始](#quick-start) - [前提条件与要求](#prerequisites--requirements) - [安装选项](#installation-options) - [配置](#configuration) - [Guardian 工作原理](#how-guardian-works) - [架构与生态系统](#architecture--ecosystem) - [API 参考](#api-reference) - [许可证](#license) ## 快速开始使用一条命令安装 Guardian： ``` /bin/bash -c "$(curl -fsSL https://guardian.mailuminati.com/install.sh)" ``` 安装程序将： - 检测您的系统配置 - 安装 Guardian 及其依赖项 - 与现有的电子邮件过滤系统集成（Rspamd、SpamAssassin 等） - 自动启动服务 **自定义安装选项：** ``` /bin/bash -c "$(curl -fsSL https://guardian.mailuminati.com/install.sh)" -- --redis-host 192.168.1.50 --redis-port 6380 ``` （注意选项前带有双破折号 `--`） **使用我们的官方 Docker 镜像安装：** ``` docker pull mailuminati/guardian:latest ``` 有关先决条件配置选项和环境变量的详细说明，请参见下文。 ## 前提条件与要求 ### 必需项 - Linux 服务器 - 用于本地缓存和学习的 `redis` 服务器（可位于同一主机或远程） - 兼容 POSIX 的 Shell（`/bin/sh` 或 `/bin/bash`） - `curl` - `tar` - `sudo`（除非以 root 身份安装） ### 可选但推荐 - 用于服务管理的 `systemd` - 能够调用 HTTP API 的反垃圾邮件引擎示例：Rspamd、SpamAssassin、自定义过滤器 - 支持 Sieve 的 IMAP 服务器示例：Dovecot、Cyrus 或等效组件 ### Guardian 不需要 - IMAP 凭据 - 访问原始邮箱内容 - 沉重的运行时依赖 ## 安装选项您可以通过向安装程序传递参数来自定义安装。 **查看所有可用选项：** ``` /bin/bash -c "$(curl -fsSL https://guardian.mailuminati.com/install.sh)" -- --help ``` **常用选项：** - **Redis 配置：** 如果您的 Redis 实例不在 localhost（或 Docker 的 `redis`）： --redis-host 192.168.1.50 --redis-port 6380 - **过滤器集成：** 跳过所有过滤器集成提示： --no-filter-integration 即使已安装也禁用特定集成： --no-rspamd --no-spamassassin - **强制重新安装：** 即使版本匹配也强制重新安装 Guardian 引擎： --force-reinstall ## 配置 Guardian 可通过环境变量或配置文件进行配置，具体取决于您的安装方式。 **源码安装：** 配置文件位于 `/etc/mailuminati-guardian/guardian.conf`。您可以编辑此文件以更改设置。要在不重启服务的情况下应用更改（热重载），请运行： ``` sudo systemctl reload mailuminati-guardian ``` **Docker 安装：** 配置主要通过 `docker-compose.yaml` 中的环境变量进行管理。 ### 可用配置变量 | 变量 | 描述 | 默认值 | | :--- | :--- | :--- | | `REDIS_HOST` | Redis 服务器的主机名或 IP | `localhost`（源码）/ `redis`（Docker） | | `REDIS_PORT` | Redis 服务器的端口 | `6379` | | `GUARDIAN_BIND_ADDR` | 要绑定的网络接口 IP。
仅使用 `127.0.0.1` 表示本地主机，或 `0.0.0.0` 表示所有接口。 | `127.0.0.1` | | `MI_ENABLE_IMAGE_ANALYSIS` | 设置为 `1` 以启用对低文本电子邮件的外部图像分析。 | `0`（禁用） | | `FORCE_REINSTALL` | 设置为 `1` 以强制重新安装 Guardian 引擎。 | `0` | | `SPAM_WEIGHT` | 报告为垃圾邮件的哈希值的权重。 | `1` | | `HAM_WEIGHT` | 报告为正常邮件（误报）的哈希值的权重。 | `2` | | `SPAM_THRESHOLD` | 消息被本地判定为垃圾邮件所需的最低分数。
默认值（`1`）表示：只要有一条垃圾报告（权重为 1）就足以阻止相似消息。
提高此值（例如设为 `2`）可在阻止前要求多条报告。 | `1` | | `LOCAL_RETENTION_DAYS` | 本地学习条目的保留周期（天数）。 | `15` | | `LOG_LEVEL` | 日志详细程度（`DEBUG`、`INFO`、`WARN`、`ERROR`）。 | `INFO` | | `LOG_FORMAT` | 日志格式（`JSON` 用于工具/ELK，`TEXT` 用于人工阅读）。 | `JSON` | 权重与阈值变量协同工作，为您提供对本地学习机制的完全控制： - **检测逻辑：** 当计算得分大于或等于 `SPAM_THRESHOLD` 时，消息被视为垃圾邮件。 - **垃圾报告：** 报告一条消息为垃圾邮件会为其增加 `SPAM_WEIGHT`。 - **正常报告：** 报告一条消息为正常（误报）会减去 `HAM_WEIGHT`。 **示例场景：** - **默认（激进）：** `SPAM_WEIGHT=1`，`SPAM_THRESHOLD=1`。 - 1 条垃圾报告 = 得分 1。由于 `1 >= 1`，立即被阻止。 - **谨慎：** `SPAM_WEIGHT=1`，`SPAM_THRESHOLD=2`。 - 1 条垃圾报告 = 得分 1。未阻止（`1 < 2`）。 - 2 条垃圾报告 = 得分 2。被阻止（`2 >= 2`）。 - 1 条垃圾报告 + 1 条正常报告 = 得分 0。未阻止（`0 < 2`）。 ## Guardian 工作原理 Guardian 将本地情报与共享威胁检测相结合，以提供快速、准确的垃圾邮件过滤。 ### 核心概念 **本地情报：** - 基于操作员特定威胁的即时分析与学习 - 用户/操作员报告后立即生效 - 即使与 Oracle 断开连接也能工作 - 为大多数消息提供零延迟决策 **共享情报（通过 Oracle）：** - 跨操作员的垃圾邮件活动关联 - 来自独立报告的共享威胁集群 - 防止大规模、快速移动的威胁 - 早期检测以前未知的活动通过在检测到有意义的邻近性时才查询 Oracle，Guardian 能够在不牺牲性能或隐私的情况下利用集体情报。 ### 分析流水线 #### 1. 本地分析对于每封传入邮件，Guardian 将： - 规范化文本与 HTML 内容 - 提取有意义的附件 - 计算一个或多个 TLSH 结构指纹此过程快速、确定性，且不依赖外部调用。 **图像分析（可选）：** 当通过 `MI_ENABLE_IMAGE_ANALYSIS=1` 启用时，Guardian 可获取并分析外部图像，以检测包含极少文本的电子邮件。这对于检测“仅图像”垃圾邮件很有用——其内容隐藏在远程图片中以绕过基于文本的过滤器。 #### 2. 本地邻近检测每个指纹使用 LSH（局部敏感哈希）技术拆分为重叠的 band。 Guardian 检查： - 其本地学习数据库 - 本地缓存的 Oracle band 数据子集如果检测到足够邻近性，Guardian 可能： - 本地分类消息 - 标记为部分或可疑匹配 - 升级为 Oracle 确认 #### 3. Oracle 确认（必要时）仅在邻近性阈值满足时，Guardian 才会联系 Oracle 以： - 计算与已知威胁集群的精确距离 - 将指纹与基于已确认报告的簇质心进行比较 - 接收最终判决此设计确保 **只有极少数消息需要远程确认。 #### 4. 学习与反馈 Guardian 支持通过以下方式学习： - 用户投诉（通过 IMAP/Sieve 集成） - 操作员验证 - 滥用台信号已确认的报告会立即强化本地检测，并可共享至 Oracle，为全局 Mailuminati 情报做出贡献。 ### 架构图


Incoming Email

      |

      v

+---------------------+

|  Mailuminati        |

|  Guardian (Local)   |

+---------------------+

   |           |

   |           +--------------------+

   |                                |

   v                                v

Local Analysis                  Local Learning

(TLSH + LSH)                (Immediate Effect)

   |

   |  No proximity

   |----------------------------->  ALLOW / LOCAL DECISION

   |

   |  Proximity detected

   v

+---------------------+

|   Mailuminati       |

|   Oracle (Remote)   |

+---------------------+

        |

        v

Shared Intelligence

(Clusters, Medoids,

Community Reports)

        |

        v

   Verdict Returned

        |

        v

Local Enforcement

(Spam / Allow / Flag)

### 设计目标

- **极低延迟**——大多数决策无需网络调用即可完成
- **即时学习**——报告立即生效
- **资源占用最小**——低 CPU 与内存占用
- **隐私保护**——不共享原始邮件内容
- **弹性可靠**——即使 Oracle 不可用也能工作
- **可扩展**——适用于高吞吐量与小规模操作

## 架构与生态系统

### 在 Mailuminati 生态系统中的角色

Guardian 负责：

- 对传入邮件进行本地垃圾邮件/钓鱼分析
- 使用 TLSH 进行结构指纹识别
- 通过局部敏感哈希（LSH）实现快速邻近检测
- 即时应用本地学习
- 通过 Mailuminati Oracle 进行远程确认
- 执行最终决策（允许、标记为垃圾/邻近匹配）

它是**第一道防线**，在保持低延迟和资源占用的同时，连接更广泛的社区驱动检测网络。

### 部署模型

Guardian 通常以以下方式运行：

- 作为端口 `12421` 上的本地 HTTP 服务
- 作为 MTA 与 Mailuminati 生态系统之间的桥梁
- 与 Redis 一起容器化部署

您的电子邮件过滤引擎（Rspamd、SpamAssassin 等）会为每封传入邮件调用 Guardian 的 `/analyze` 端点，然后根据判决执行相应操作。

### 与其他组件的关系

- **Guardian** 执行本地检测、学习与执行
- **Oracle** 提供共享情报与协作确认

Guardian 可独立运行。与 Oracle 连接时，其有效性会提升，因为本地信号会成为集体防御的一部分。

## API 参考

Guardian 在端口 `12421` 上公开一个简单的 HTTP API。

### 基础 URL


```
http://:12421
```


### 端点

#### 获取 /status

健康与版本信息端点。

**示例：**


```
curl -sS http://localhost:12421/status | jq
```


**响应：**


```
{

  "node_id": "6c0a5e16-2b32-4f86-9b3d-2b2e3df5c7d8",

  "current_seq": 0,

  "version": "0.3.2"

}
```


#### 发布 /analyze

分析以原始 RFC822/MIME 字节提供的电子邮件。最大请求大小：**15 MB**。

**请求：**


```
curl -sS -X POST \

  -H 'Content-Type: message/rfc822' \

  --data-binary @message.eml \

  http://localhost:12421/analyze | jq
```


**响应：**


```
{

  "action": "allow",

  "proximity_match": false,

  "hashes": [

    "T1A9B0E0F2D3C4B5A6..."

  ]

}
```


**响应字段：**

- `action`: `allow` | `spam`
- `label`（可选）：例如 `local_spam`、`oracle_spam`
- `proximity_match`: 布尔值，指示是否检测到相似垃圾邮件
- `distance`（可选）：到最近威胁的 TLSH 距离（越小越相似）
- `hashes`（可选）：计算出的 TLSH 签名数组

**注意：**

- 如果邮件缺少 `Message-ID` 头，Guardian 仍会分析它，但 `/report` 后续无法引用它。
- `hashes` 字段包含消息的已计算 TLSH 指纹。

#### 发布 /report

将先前扫描的电子邮件报告给 Guardian 以改进其学习。

Guardian 将：

1. 立即应用 **本地学习**（垃圾邮件或正常纠正）
2. 将报告转发至 Oracle 以获取共享情报

**请求：**


```
curl -sS -X POST \

  -H 'Content-Type: application/json' \

  -d '{"message-id":"","report_type":"spam"}' \

  http://localhost:12421/report
```


**请求体：**


```
{

  "message-id": "",

  "report_type": "spam"

}
```


**报告类型：**

- `spam`：报告漏掉的垃圾邮件（假阴性）
- `ham`：报告误报（正常邮件被错误标记）

**注意：**

- Guardian 必须先前扫描过该邮件（通过 `Message-ID` 标识）
- 如果未找到该 Message-ID 的扫描数据，返回 `404 Not Found`
- 当 Oracle 可达时，响应由 Oracle 代理返回

#### 获取 /metrics

以 **Prometheus** 格式公开内部指标，用于监控。

**示例：**


```
curl -sS http://localhost:12421/metrics
```


**可用指标：**

- `mailuminati_guardian_scanned_total`：已扫描邮件总数
- `mailuminati_guardian_local_match_total`：使用本地情报检测到的邮件数
- `mailuminati_guardian_oracle_match_total`：通过 Oracle 匹配的邮件数
- `mailuminati_guardian_cache_hits_total`：缓存命中率

## 许可证

本客户端是遵循 GNU GPLv3 的开源软件。

版权所有 © 2025 Simon Bressier。

请注意：本许可证严格适用于本仓库中包含的客户端侧代码。

请参阅 [LICENSE](LICENSE) 文件以获取详细信息。

标签：AMSI绕过, Docker, EVTX分析, Go语言, GPLv3, MTA, Python 3.9+, SEO: 垃圾邮件过滤, SEO: 网络钓鱼防护, SEO: 邮件威胁检测, SEO: 隐私保护, 共享情报, 垃圾邮件检测, 威胁检测, 安全防御评估, 实时检测, 开源, 快速决策, 搜索引擎查询, 日志审计, 最小开销, 本地学习, 用户报告, 社区运维, 程序破解, 结构指纹, 网络安全, 网络钓鱼检测, 联邦学习, 请求拦截, 邮件基础设施, 邮件安全, 邻近检测, 隐私保护