# mail_guard

**Repository Path**: tianlangcz/mail_guard

## Basic Information

- **Project Name**: mail_guard
- **Description**: MailGuard是中南大学计算机学院开发的一套面向短信骚扰与诈骗的短信安全网关系统，采用混合检测架构融合规则引擎、文本分类模型（含提示学习）和行为画像技术，实现对短信的风险评估与分级处置，同时创新性地提出非本人意图短信防护机制，识别非预期验证码和错投敏感短信并默认隔离打码展示以保护双方隐私，系统每条短信提供详细的判决证据链增强可解释性，为运营商和企业提供可落地的短信安全解决方案。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-01-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 短信过滤筛查系统

## 1. 项目简介

### 1.1 系统定位
本项目是一个**专注于短信过滤与筛查**的系统，目标是在用户接收短信时进行实时判断，并对“高风险/不属于本人/广告骚扰/诈骗”短信进行**自动屏蔽或隔离**，同时以**手机端弹窗**方式通知用户发生了安全处置。

### 1.2 核心价值
系统的核心价值在“过滤决策链”与“用户可感知但不泄露隐私”的交互，而不是任何“管理平台”。

### 1.3 明确不做（Non-Goals）
- 不做通用管理后台、运营平台、策略配置中心
- 不展示用户隐私字段（手机号、姓名、短信全文、验证码、账号、地址等）
- 不提供复杂的规则编辑、模型参数调节、用户画像可视化面板
- 不做“监控他人手机”的能力（仅面向用户本人设备、明确授权）

## 2. 系统架构

### 2.1 组件划分
1. **Android Agent（手机端）**
   - 作为默认短信应用（关键）
   - 接收短信 → 发送到过滤引擎 → 执行“投递/隔离/拦截”
   - 触发弹窗提示
   - 提供“隔离箱”查看模块（脱敏展示）

2. **Java Filter Gateway（核心，项目主体）**
   - 过滤决策引擎：规则 + 模型 + 行为画像融合
   - 输出：风险分、等级、处置动作、解释标签（非敏感）
   - 提供本地 API（HTTP）供 Android Agent 调用

3. **Web Security Viewer（前端）**
   - 展示拦截统计与AI解释证据链
   - 3页：Dashboard/Events/Explain
   - 只展示脱敏事件数据与 reason_tags

## 3. 快速开始

### 3.1 环境准备
- 安装 JDK 17+
- 安装 Maven 3.6+
- 安装 Android Studio（用于编译和运行 Android Agent）
- 连接 Android 设备并开启 USB 调试模式

### 3.2 一键启动
1. 运行 ADB 端口转发脚本：
   ```bash
   scripts\adb_reverse.bat
   ```

2. 运行一键启动脚本：
   ```bash
   scripts\start_all.bat
   ```

3. 安装并运行 Android Agent，设置为默认短信应用

### 3.3 访问 Web Security Viewer
在浏览器中访问：http://localhost:8081

## 4. 演示流程

### 4.1 广告短信
- 发送广告短信 → 网关隔离 → 手机弹窗 → Web UI 更新
- 预期结果：手机弹出“短信已被隔离”提示，Web UI 显示“群发广告模式”标签

### 4.2 诈骗短信
- 发送诈骗短信 → 网关拦截 → 手机弹窗 → Web UI 更新
- 预期结果：手机弹出“短信已被拦截”提示，Web UI 显示“疑似钓鱼链接”标签

### 4.3 非预期验证码
- 发送非预期验证码 → 网关隔离 → 手机弹窗 → Web UI 更新
- 预期结果：手机弹出“短信已被隔离”提示，Web UI 显示“非预期验证码”标签

### 4.4 错投敏感短信
- 发送错投敏感短信 → 网关隔离 → 手机弹窗 → Web UI 更新
- 预期结果：手机弹出“短信已被隔离”提示，Web UI 显示“疑似错投敏感信息”标签

## 5. 隐私保证

### 5.1 数据处理
- 不传输短信全文，只传输特征向量
- 所有存储的短信相关数据均脱敏
- 禁止在任何界面展示敏感信息

### 5.2 界面限制
- 弹窗只显示固定 reason_tags
- 隔离箱只显示脱敏摘要
- Web UI 只显示脱敏事件数据

### 5.3 安全措施
- 采用 ADB 本地端口转发，不依赖公网
- 所有数据传输均在本地完成，不涉及云服务

## 6. 功能边界

### 6.1 支持的短信类型
- 广告短信
- 诈骗短信
- 非预期验证码
- 错投敏感短信
- 正常短信

### 6.2 处置动作
- ALLOW：正常进入系统收件箱
- QUARANTINE：进入隔离箱，触发弹窗
- BLOCK：直接拦截，触发弹窗

### 6.3 风险等级
- L0：放行，不打扰用户
- L1：轻提示，短信顶部加风险提示标签
- L2：强提示，弹窗/二次确认
- L3：隔离，进入“安全收件箱/隔离区”
- L4：拦截，不下发/直接丢弃

## 7. 项目结构

```
mail_guard/
├── gateway-core/          # 核心决策引擎
├── gateway-api/           # HTTP API接口
├── rule-engine/           # 规则引擎
├── model-service/         # 模型服务（stub）
├── profile-store/         # 轻量画像存储
├── demo-console/          # USB演示控制台
├── android-agent/         # Android Agent
├── web-ui/                # Web Security Viewer
├── scripts/               # 一键启动和adb脚本
├── config/                # 配置文件
│   ├── rules/             # 规则YAML
│   └── profiles/          # 画像配置
├── data/                  # 样例回放数据
├── README.md              # 项目说明
└── CHANGELOG.md           # 变更记录
```

## 8. 技术栈

- **后端**：Spring Boot 3.2.0+
- **前端**：Spring Boot + Thymeleaf + ECharts
- **Android**：Kotlin + Android SDK
- **规则引擎**：自研YAML解析
- **画像存储**：SQLite
- **构建工具**：Maven

## 9. 注意事项

### 9.1 Android 权限
- 需要短信相关权限：RECEIVE_SMS、READ_SMS、SEND_SMS、WRITE_SMS
- 需要设置为默认短信应用才能实现真正的拦截功能

### 9.2 ADB 连接
- 确保 Android 设备已开启 USB 调试模式
- 确保 ADB 命令可在系统路径中执行

### 9.3 网络配置
- 系统使用本地端口转发，不需要网络连接
- Android Agent 通过 http://127.0.0.1:8081 访问 Java Gateway

## 10. 联系方式

如有问题或建议，请联系项目维护人员。