MeshSate/README.md

# MeshSafe · 文件安全检测服务

![Version](https://img.shields.io/badge/version-v0.2.1-blue)
![Python](https://img.shields.io/badge/python-3.12%2B-green)
![License](https://img.shields.io/badge/license-proprietary-orange)

> **光闸摆渡场景下的独立文件安全守门员。** 外网文件进来之前，先过 MeshSafe。

---

## 一句话介绍

MeshSafe 是一套独立部署的文件安全检测服务，专为光闸内外网摆渡场景设计。它不修改、不清洗文件，只做一件事：**判断"这个文件能不能传进内网"**，把检测结论交还给摆渡系统决定。

一期只做 **外网 → 内网** 方向——保护内网不被外网文件伤到。

---

## 它能做什么

### 三层风险把关

| 维度 | 回答的问题 | 举个例子 |
|---|---|---|
| **恶意性检测** | 这个文件本身是不是病毒、木马、勒索？ | 已知病毒签名、家族特征 |
| **可执行性拦截** | 这个文件打开会不会自动跑代码？ | 带宏的 Word、带脚本的 PDF、快捷方式 |
| **合规性校验** | 这个文件在传输层面有没有问题？ | 路径穿越、压缩炸弹、伪装扩展名 |

### 两种判定结果

- **机器执行**：告诉摆渡系统"放行 / 拒绝 / 转人工复核"
- **人工提示**：告诉最终打开文件的内网用户"打开时要注意什么"（比如"此文件包含宏，请勿启用"）

两条结论独立返回——系统的事归系统，人的事归人。

---

## 它能拦住什么

以下是 MeshSafe 一期覆盖的全部核心风险场景：

### 文档类最常见风险

| 文件类型 | 风险场景 | MeshSafe 的处置 |
|---|---|---|
| Word / Excel / PPT (.docm / .xlsm / .pptm) | 打开即执行的宏，自动下载病毒、调用系统命令、关闭安全软件 | **零容忍直接拦截**，不走过场 |
| Word / Excel / PPT | 宏代码被故意混淆或加密，意图不可知 | **零容忍直接拦截** |
| Word / Excel (RTF) | DDE / DDEAUTO 字段——打开即启动程序 | **零容忍直接拦截** |
| PDF | 打开即执行的 JavaScript 脚本 | **零容忍直接拦截** |
| PDF | LaunchAction——打开即启动外部程序 | **零容忍直接拦截** |
| 所有 Office 文档 | 包含外部模板注入——借模板执行恶意代码 | **零容忍直接拦截** |
| 所有 Office 文档 | 嵌入了可执行文件的 OLE 对象 | **零容忍直接拦截** |

### 快捷方式与容器类风险

| 文件类型 | 风险场景 | MeshSafe 的处置 |
|---|---|---|
| 快捷方式 (.lnk) | 指向程序执行 / 远程路径 / 脚本 | **零容忍直接拦截** |
| 帮助文件 (.chm) | 包含可执行脚本 | **零容忍直接拦截** |
| 光盘镜像 (.iso) | 内部包含可执行文件——双击挂载后直接运行 | **零容忍直接拦截**，挂载后递归扫描内部 |
| 压缩包 (.zip / .rar / .7z 等) | 解压路径穿越——试图写出解压目录，覆盖系统文件 | **零容忍直接拦截** |
| 压缩包 | 压缩炸弹——几 KB 解压出几百 MB 甚至上 GB，耗尽服务器资源 | 拦截并报警 |
| 压缩包 | 解压深度超过 5 层，内部包含可执行文件 | 自动进入下一轮检测 |

### 伪装与迷惑类风险

| 风险场景 | MeshSafe 的处置 |
|---|---|
| 双扩展名伪装：`invoice.pdf.exe` 实际是程序 | 识破真实类型，拦截 |
| 图标伪装：可执行文件用 PDF 图标诱导用户双击 | 识破真实类型，拦截 |
| 声明扩展名与真实类型不一致 | 拦截并标记 |
| 文件名用 Unicode 欺骗（西里尔字母替换拉丁字母） | 识破并标记 |

### 链接与二维码分级处置

| 情形 | MeshSafe 的处置 |
|---|---|
| 文档/图片中的链接命中恶意地址库 | **零容忍直接拦截** |
| 链接指向非常规端口 / IP 直连 / 短链服务 | 标记为可疑，转人工复核 |
| 二维码解码后内容为上述情形 | 同上 |
| 普通 http / https 链接 | 放行但提示"请确认来源" |

### 加密文件处理

| 情形 | MeshSafe 的处置 |
|---|---|
| 加密的 Office 文档 | 默认拒绝——无法确认内部安全 |
| 加密的压缩包 | 默认拒绝——无法确认内部安全 |

### Linux 桌面环境特有威胁（一期重点覆盖）

内网终端是麒麟桌面/UOS（纯 Linux），因此 Linux 特有威胁载体必须覆盖：

| 威胁场景 | 风险说明 | MeshSafe 的处置 |
|---|---|---|
| Linux 原生可执行文件（ELF） | 传统杀毒不认识，可直接在终端运行 | **零容忍直接拦截** |
| Linux 快捷方式（.desktop 文件） | 看起来是桌面图标，实际 `Exec=` 字段可指向任意命令 | **零容忍直接拦截**，校验 Exec 字段是否含 shell 调用、下载器 |
| Shell / Python / Perl / Ruby 脚本 | 双击可执行，含恶意系统调用（下载、反弹 Shell） | **零容忍直接拦截**，识别危险函数 |
| AppImage / Flatpak / Snap 便携包 | 跨发行版可执行格式，双击即运行 | **零容忍直接拦截**，内部递归扫描 |
| 压缩包内混有 shell 脚本 / .run / .bin | 解压后用户容易误执行 | 自动进入下一轮检测 |

> **纵深防御**：虽然内网是 Linux，Windows 专属载体（快捷方式 .lnk、帮助文件 .chm）仍保持检测——文件可能通过其他路径流向运维人员的 Windows 工作站。

---

## 方案亮点（为什么 MeshSafe 和传统杀毒不一样）

### 亮点一：「打开即执行」载体零容忍——独立于评分体系

传统杀毒的逻辑是：**是不是已知恶意样本？** 匹配不到签名就放行。

但在光闸场景里，真正的高频风险不是"已知病毒"，而是**"打开就自动运行"的载体**——宏文档、DDE 字段、LNK 快捷方式。这类东西杀毒扫出来说"干净"，但用户双击后宏即刻执行。

MeshSafe 的逻辑反过来：**只要存在打开即执行的载体，就零容忍拦截**。这是一条独立于评分体系的硬性清单——不累计权重、不走过场，命中即拒。

### 亮点二：宏行为分级——不是"有没有宏"，而是"宏做了什么"

内网人员需要打开带宏的公文模板（自动编号、签章定位等），不能简单地把"含宏"等同于"拒绝"。

MeshSafe 会**分析宏的实际行为**：

| 宏的行为 | MeshSafe 判定 |
|---|---|
| 自动执行 + 调用系统命令 / 外联网络 | **零容忍拒绝** |
| 宏代码被混淆 / 加密（意图不可知） | **零容忍拒绝** |
| 自动执行 + 仅本地无害操作（编号、排版） | **放行或标记** |
| 无自动执行，仅手动触发 | 标记放行 / 转复核 |

### 亮点三：合法公文模板例外——五道保险受控放行

对于业务上确实需要打开的合法宏模板，MeshSafe 提供**受控的例外机制**，但有五道保险：

| 保险 | 怎么防绕过 |
|---|---|
| **指纹绑定** | 例外按文件内容精确匹配，换一个字节就失效 |
| **文件名匹配** | 指纹 + 文件名双重校验，防止不同文件复用 |
| **必须到期** | 所有例外必须有到期时间，最长不超过一年 |
| **审批留痕** | 谁批的、为什么批、批了什么，全部留痕可追溯 |
| **行为前提** | 就算在例外清单里，如果宏检测到危险行为（调用 Shell、下载文件），照样触发零容忍 |

### 亮点四：打开风险独立提示

检测结论分两层：
- **系统判定层**：摆渡系统看这个——放行 / 拒绝 / 转复核
- **人工提示层**：内网用户看这个——"此文件包含宏，请勿启用"、"请勿直接双击此 ISO 文件"

两层独立演进。即使摆渡系统选择忽略人工提示字段，内网侧安全审计面板也能单独展示。

### 亮点五：防篡改审计

所有检测记录、策略变更、例外增删都进入**链式审计日志**——每条记录的哈希值包含前一条记录的哈希。任何一条被篡改，后续链全部断裂可检出。

---

## 完整的检测能力清单（一期）

| 能力 | 覆盖范围 |
|---|---|
| 真实文件类型识别（不信任扩展名） | 全部文件 |
| 递归安全解包（最多 5 层） | 常见压缩格式 |
| 已知恶意样本特征匹配 | 全部文件 |
| 宏代码提取与行为分析 | Word / Excel / PPT 全系列 |
| DDE / DDEAUTO 自动执行检测 | 复合文档 |
| PDF 脚本与动作检测 | PDF |
| 文档内嵌文件检测 | 复合文档 |
| 文档深度解析 | 外部链接、模板注入、隐藏变量 |
| 快捷方式深度解析 | 目标路径、参数、远程链接 |
| 帮助文件类型校验 | 结构完整性检测 |
| 光盘镜像挂载后递归扫描 | 内部可执行文件检测 |
| 未知恶意样本家族匹配 | 可执行程序 / 脚本 / 内存马 |
| 可执行程序结构分析 | 异常特征、签名目录、导入表 |
| 外部链接与二维码提取 | 文档和图片 |
| 恶意链接库查询 | 分级处置 |
| 零容忍规则集（15 条） | 打开即执行载体全覆盖 |
| 宏行为例外机制 | 合法公文模板受控放行 |
| 引擎故障安全降级 | 任何检测引擎不可用时整体拒绝（安全优先） |
| 同步 + 异步双模式 | 小文件同步返回，大文件异步轮询 |
| 策略热重载 | 改配置不用重启 |
| 控制台权限分级 | 管理员 / 运维 / 只读三档 |
| 防篡改审计日志 | 链式哈希校验，任何一条被改后续全部断裂可检出 |
| 签名库版本追踪 | 检测有效性可举证 |

---

## 未来可支持的扩展方向

以下方向**架构已预留，但一期不实现**：

| 方向 | 价值 | 启动前提 |
|---|---|---|
| **内网 → 外网内容审计** | 判断内部内容是否允许外传（涉密 / 隐私 / 违规） | 需先明确业务密级规则和具体场景，与一期的"技术判据"属不同问题域 |
| **动态沙箱深检** | 在隔离环境中实际运行可疑文件，观察行为（释放文件、外联 C2 等） | 需要 Windows 虚拟化环境 + 国产化终端适配验证；场景收益有限（一期以文档为主） |
| **大模型语义分析** | 辅助识别诱导话术、仿冒公文模板、上下文关联钓鱼 | 需要内网推理算力；大模型输出仅作为辅助信号，不单独裁决 |
| **更多零容忍规则** | 随新威胁形态出现，可向规则清单中增量添加 | 规则必须满足"命中即有害 + 可稳定判定"的准入条件 |
| **内网特征词表引擎** | 识别内网特有的模板、关键词、命名规律，辅助例外判断和伪装识别 | 一期已有初步框架，可独立推进 |

> 所有扩展方向的接口和数据结构在一期架构中**已预留扩展位**，未来接入无需重构。

---

## 版本历史

### v0.2.1 (2026-10-28)

**并发与稳定性核心修复：**

- **诊断定时器分布式锁** — 多 worker 部署时，每个时间槽位只有一个 worker 执行，Redis 时间槽位设计（`key=<timer>:<int(time()//interval)> + SET NX + EX`），无主动释放，下一槽位自然放行
- **JSONL 存储跨进程文件锁** — `fcntl.flock` 排他锁 + `errors="replace"` 容错解码 + 临时文件 + `os.replace` 原子重写，彻底根除多 worker 并发写导致的 UnicodeDecodeError 和数据膨胀
- **移除 SQLite fallback** — 统一 PostgreSQL 作为唯一数据库后端
- **API_CLIENTS 脱敏** — `docker-compose.yml` 中硬编码的 MASTER_KEY 改为环境变量 `${MESHSAFE_API_CLIENTS:-test-client:test-secret}`，真实密钥移入 `.env`（已 `.gitignore`）
- **Docker 网络固定网段移除** — 删掉 `subnet: 172.28.0.0/16` + `ipam`，IP 由 Docker 自动分配

**产品与文档：**

- 新增 `/console/about` 产品介绍页（Hero + 痛点叙事 + 4 大卡片 + 6 层检测管线 + 架构 3 小卡）
- 新增 `deploy/OPERATIONS.md` 运维部署指南
- `.gitignore` 补 `/data/`、`benchmark_report*.json`、`out.json`、`/.screenshots/`

### v0.2.0 (2026-10-27)

- v1.0 初始架构落地：FastAPI + PostgreSQL + Redis + Docker Compose
- 6 层检测管线（L0-L5）、零容忍规则集、客户端 HMAC-SHA256 签名鉴权
- 控制台 UI：登录 / Dashboard / 诊断中心 / 策略管理 / 任务列表 / 测试中心

---

## 测试靶场（待办）

CSV 用例集共 126 条，引擎能力覆盖约 97%。以下 3 条因需要外部资源暂搁置，待办环境就绪后补全：

| CSV 用例 | 内容 | 缺失原因 | 后续 |
|----------|------|---------|------|
| **L1-009** | ClamAV 离线病毒库热加载 | 需要真实签名的 `.cvd` 文件（ClamAV 官方下载） | 从 https://www.clamav.net/downloads 下载 daily.cvd，放入 `data/clamav-db/` 测试 |
| **L1-010** | ClamAV 损坏库容错降级 | 需要损坏的真实 `.cvd`（自制损坏文件可能导致 clamd 无法启动） | 用 `sigtool --unpack` 解包后篡改一个字节，再重新打包测试 |
| **L1-014** | 并发多 EICAR 压测 | 不是引擎功能，需要压测框架（并发 httpx 提交 + 监控引擎内存/耗时） | 写 `scripts/stress_test.py`，用 asyncio.Semaphore 控制并发度 |

### 白名单机制（v0.2.1 新增）

- **关键词白名单** (`policy.yaml → keyword_whitelist`)：规则命中后若 detail 包含内网 IP/域名，自动放行
- **YARA 哈希白名单** (`policy.yaml → yara_hash_whitelist`)：YARA 命中后 MD5 在白名单 → 跳过告警
- 生产部署时按需补充内网地址段 / 已知安全工具哈希

### 靶场样本生成脚本

| 脚本 | 用途 |
|------|------|
| `scripts/generate_csv_samples.py` | 从 CSV 批量生成 CSV 对齐样本 + index.json |
| `scripts/generate_yara_rules.py` | 自动生成 CSV L4 段对应的 YARA `.yar` 规则 |
| `rules/test_rules.yar` | 生成的规则文件（引擎按 mtime 自动热加载） |

---

*更多技术细节请参阅 [总体方案](docs/00-总体方案.md) 和 [接口文档](docs/接口文档.md)*