Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
346 lines
16 KiB
Markdown
346 lines
16 KiB
Markdown
# PRD: OpenClaw 安全合规检查与通知系统
|
||
|
||
> **版本**: v1.0
|
||
> **日期**: 2026-07-20
|
||
> **状态**: [草稿]
|
||
> **作者**: Simon
|
||
> **需求编号**: REQ-集成-001
|
||
> **关联文档**:
|
||
> - 原型: `01-产品文档/08-集成生态/原型-REQ-集成-001-OpenClaw合规检查-v1.0.html`
|
||
> - 技术: `02-技术文档/实现配置/技术方案-REQ-集成-001-OpenClaw合规检查-v1.0.md`
|
||
> - 测试: `03-测试文档/03-功能测试用例/TC-REQ-集成-001-OpenClaw合规检查.md`
|
||
|
||
---
|
||
|
||
## 1. 问题陈述 (Problem Statement)
|
||
|
||
### 背景
|
||
在重大安全活动期间（如国家网络安全周、重大会议保障期），公司需要对终端进行合规审计。
|
||
|
||
> 💡 **本期目标**：以 OpenClaw 检测为 **一期试点**，验证安全策略检查与通知框架的可行性。
|
||
>
|
||
> **扩展性设计**：本系统设计为 **通用安全策略检查平台**，未来可低成本扩展其他策略和推送渠道。
|
||
|
||
### 问题描述
|
||
- **现状**：目前依赖手工导出联软数据或通过火绒终端管理查看，缺乏自动化的定期检查和通知机制
|
||
- **痛点**：
|
||
- 无法及时发现违规软件安装
|
||
- 依赖人工通知，效率低、易遗漏
|
||
- 无法形成定期的合规审计报告
|
||
|
||
### 影响
|
||
- **安全风险**：未经授权的远程软件可能成为攻击入口
|
||
- **合规风险**：无法满足重大活动期间的安全审计要求
|
||
- **业务影响**：IT 运维人员需要投入大量人工排查
|
||
|
||
---
|
||
|
||
## 2. 目标 (Goals)
|
||
|
||
| # | 目标 | 成功衡量标准 |
|
||
|---|------|-------------|
|
||
| G1 | **一期试点**：自动检测 OpenClaw 安装 | 系统可自动发现所有已安装 OpenClaw 的终端，覆盖率 ≥ 95% |
|
||
| G2 | 及时通知当事人 | 检测到违规软件后，24 小时内通过企微发送通知给终端用户 |
|
||
| G3 | 支持定时+手动执行 | 支持每日定时执行 + 管理员手动触发两种方式 |
|
||
| G4 | 合规审计留痕 | 支持导出 Excel 审计报告，保留检测记录至少 6 个月 |
|
||
| G5 | 活动期间管控 | 支持设置活动期间，自动开启检查 |
|
||
| G6 | **框架可扩展** | 新增其他安全策略和推送渠道的成本 ≤ 1人天 |
|
||
|
||
---
|
||
|
||
## 3. 非目标 (Non-Goals)
|
||
|
||
| # | 非目标 | 原因 |
|
||
|---|--------|------|
|
||
| N1 | **自动封禁/断网** | 仅做通知提醒，不做自动阻断，避免影响业务连续性 |
|
||
| N2 | ~~**支持其他软件检查**~~ | ⚠️ 已调整为扩展性设计，详见下方框架说明 |
|
||
| N3 | **实时监控** | 采用定时检查（非实时推送），5 分钟级延迟可接受 |
|
||
| N4 | **移动端管理** | 本期仅支持 PC Web 端管理 |
|
||
| N5 | **火绒+联软自动同步** | 联软数据本期采用手动导入 Excel，不做自动 API 对接 |
|
||
|
||
---
|
||
|
||
## 3.1 扩展性框架设计（重要）
|
||
|
||
> 📐 **架构理念**：将"检测策略"与"推送渠道"解耦，实现可扩展的安全合规平台
|
||
|
||
### 3.1.1 策略类型（Strategy）
|
||
|
||
| 策略ID | 策略名称 | 检测规则 | 数据源 | 状态 |
|
||
|--------|----------|----------|--------|------|
|
||
| openclaw_remote | OpenClaw/向日葵远程软件 | 软件名包含 OpenClaw/向日葵/sunflower | 火绒API | 🔵 一期 |
|
||
| unknown_usb | 未知USB设备 | 未登记的USB设备接入 | 联软/火绒 | ⚪ 二期 |
|
||
| illegal_proxy | 非法代理软件 | 软件名包含 proxy/vpn | 火绒API | ⚪ 二期 |
|
||
| unverified_software | 未授权软件 | 不在白名单内的软件 | 火绒API | ⚪ 二期 |
|
||
|
||
### 3.1.2 推送渠道（Channel）
|
||
|
||
| 渠道ID | 渠道名称 | 适用场景 | 状态 |
|
||
|--------|----------|----------|------|
|
||
| wecom_app | 企微应用消息 | 终端用户通知 | 🔵 一期 |
|
||
| wecom_group | 企微群通知 | 部门汇总、管理员 | 🔵 一期 |
|
||
| email | 邮件通知 | 正式留痕、邮件通知 | ⚪ 二期 |
|
||
| sms | 短信通知 | 紧急告警、无企微用户 | ⚪ 二期 |
|
||
| dingtalk | 钉钉通知 | 跨平台通知 | ⚪ 二期 |
|
||
|
||
### 3.1.3 策略-渠道映射
|
||
|
||
```
|
||
策略配置:
|
||
{
|
||
"strategy_id": "openclaw_remote",
|
||
"name": "OpenClaw远程软件检测",
|
||
"channels": [
|
||
{"id": "wecom_app", "template": "终端用户通知"},
|
||
{"id": "wecom_group", "template": "部门汇总"}
|
||
],
|
||
"schedule": "0 8 * * *", # 每天8点
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
### 3.1.4 扩展成本
|
||
|
||
| 扩展项 | 工作量预估 | 说明 |
|
||
|--------|------------|------|
|
||
| 新增检测策略 | 0.5人天 | 仅需配置检测规则和数据源 |
|
||
| 新增推送渠道 | 1人天 | 需开发渠道适配器 |
|
||
| 新策略+新渠道 | 1人天 | 配置映射关系即可 |
|
||
|
||
---
|
||
|
||
## 4. 用户故事 (User Stories)
|
||
|
||
### 角色定义
|
||
- **IT 管理员**：负责配置检查策略、查看检测结果、触发手动检查
|
||
- **终端用户**：收到通知的被检查对象
|
||
- **部门负责人**：（可选）收到本部门汇总通知
|
||
|
||
### 用户故事列表
|
||
|
||
| # | 角色 | 用户故事 | 优先级 |
|
||
|---|------|----------|--------|
|
||
| US1 | IT 管理员 | 我希望系统能自动从火绒 API 获取终端软件列表，以便及时发现 OpenClaw 安装 | P0 |
|
||
| US2 | IT 管理员 | 我希望能够导入联软导出的用户-终端关联 Excel，以便知道哪台设备属于哪个用户 | P0 |
|
||
| US3 | IT 管理员 | 我希望系统能自动匹配"终端→用户"，输出"谁在哪台设备安装了 OpenClaw"，以便精准确认责任人 | P0 |
|
||
| US4 | IT 管理员 | 我希望能够设置定时任务（如每天 8:00 自动检查），以便在活动期间自动执行 | P0 |
|
||
| US5 | IT 管理员 | 我希望能够手动点击"立即检查"按钮，以便随时执行检查 | P0 |
|
||
| US6 | IT 管理员 | 我希望能够编辑通知模板（包含变量），以便自定义通知内容 | P1 |
|
||
| US7 | IT 管理员 | 我希望能够设置"是否通知部门负责人"开关，以便灵活配置通知范围 | P1 |
|
||
| US8 | IT 管理员 | 我希望能够导出 Excel 报告，以便留存审计记录 | P0 |
|
||
| US9 | 终端用户 | 我希望收到企微应用消息通知，告诉我哪台设备安装了违规软件，以便及时卸载 | P0 |
|
||
| US10 | 部门负责人 | 我希望收到本部门的汇总通知（可选），以便了解本部门合规情况 | P1 |
|
||
| US11 | IT 管理员 | 我希望能够新增其他安全策略（如未知USB、非法代理），以便扩展检测范围 | P0 |
|
||
| US12 | IT 管理员 | 我希望能够配置不同策略使用不同推送渠道（如邮件、短信），以便灵活通知 | P1 |
|
||
|
||
---
|
||
|
||
## 5. 需求规格 (Requirements)
|
||
|
||
### 5.1 功能需求
|
||
|
||
> 📌 **需求说明**：一期以 OpenClaw 为试点，但架构设计需支持策略和渠道的扩展。
|
||
|
||
#### T0: 策略与渠道管理（框架层）
|
||
|
||
| 需求ID | 描述 | 优先级 | 验收标准 |
|
||
|--------|------|--------|----------|
|
||
| REQ-001-00 | 策略配置：支持创建/编辑/启停安全策略 | P0 | 可配置策略名称、检测规则、数据源、推送渠道 |
|
||
| REQ-001-00a | 预置策略：一期预置"OpenClaw远程软件"检测策略 | P0 | 内置关键词规则（OpenClaw/向日葵/sunflower） |
|
||
| REQ-001-00b | 渠道配置：支持配置推送渠道参数 | P0 | 企微渠道：应用ID/Secret；邮件渠道：SMTP配置 |
|
||
| REQ-001-00c | 渠道适配器：企微应用消息发送 | P0 | 复用现有企微消息能力 |
|
||
| REQ-001-00d | 渠道适配器：（扩展）邮件发送 | P2 | 可延后至二期 |
|
||
| REQ-001-00e | 渠道适配器：（扩展）短信发送 | P2 | 可延后至二期 |
|
||
|
||
#### T1: 数据采集层
|
||
|
||
> ⚠️ **注意**：火绒 API 集成功能已存在于系统中（`app/integrations/huorong`），无需重复开发。
|
||
> - 现有 API：`GET /api/admin/integrations/huorong/terminals` - 获取终端列表
|
||
> - 现有 API：`GET /api/admin/integrations/huorong/terminals/{client_id}` - 获取终端详情（含软件列表）
|
||
> - 本期仅需确认现有 API 满足 OpenClaw 检测需求（获取终端软件列表）。
|
||
|
||
| 需求ID | 描述 | 优先级 | 验收标准 |
|
||
|--------|------|--------|----------|
|
||
| REQ-001-01 | ✅ 已存在：火绒 API 集成（`/api/clnts/_list` 获取终端列表） | - | 复用现有功能 |
|
||
| REQ-001-02 | ✅ 已存在：火绒 API 集成（`/api/clnts/_info2` 获取软件列表） | - | 复用现有功能，确认支持 OpenClaw 检测 |
|
||
| REQ-001-03 | 联软 Excel 导入：支持上传 .xlsx/.xls 文件 | P0 | 能解析联软导出的 Excel，提取用户-终端关联字段 |
|
||
| REQ-001-04 | 联软字段映射：自动识别 `用户名`、`设备名称`、`MAC地址`、`设备IP`、`部门名称` | P0 | 上传文件后自动匹配字段，无需手动配置 |
|
||
| REQ-001-05 | 联软数据存储：将导入的关联数据存入数据库 | P0 | 导入后数据持久化，支持后续匹配查询 |
|
||
|
||
#### T2: 数据融合引擎
|
||
|
||
| 需求ID | 描述 | 优先级 | 验收标准 |
|
||
|--------|------|--------|----------|
|
||
| REQ-001-06 | IP 地址匹配：优先通过 IP 完全匹配关联终端和用户 | P0 | 火绒终端 IP 与联软数据完全一致时，成功匹配 |
|
||
| REQ-001-07 | 主机名匹配：IP 未匹配时，通过主机名包含匹配 | P0 | 火绒主机名包含联软设备名称时，成功匹配 |
|
||
| REQ-001-08 | MAC 地址匹配：前两者未匹配时，通过 MAC 地址匹配 | P0 | 火绒 MAC 与联软 MAC 一致时，成功匹配 |
|
||
| REQ-001-09 | 未匹配记录标记：无法关联到用户的终端需标记为"未匹配" | P0 | 输出结果中明确标注哪些终端无法确定责任人 |
|
||
| REQ-001-10 | OpenClaw 命中过滤：仅输出安装了 OpenClaw 的终端 | P0 | 匹配关键词：`OpenClaw`, `向日葵`, `sunflower`（不区分大小写） |
|
||
|
||
#### T3: 策略规则与命中管理
|
||
|
||
| 需求ID | 描述 | 优先级 | 验收标准 |
|
||
|--------|------|--------|----------|
|
||
| REQ-001-11 | 白名单规则：支持配置排除的用户/终端 | P1 | 配置白名单后，命中用户不在通知范围内 |
|
||
| REQ-001-12 | 部门汇总：支持按部门聚合命中结果 | P1 | 统计每个部门的违规终端数量 |
|
||
| REQ-001-12a | 命中状态管理：支持手动修改命中记录状态 | P0 | 状态：待处理→已通知→已解决/误报 |
|
||
| REQ-001-12b | 自动状态更新：再次检测时自动判断状态变化 | P0 | 历史命中用户再次检测未命中，自动标记"已解决" |
|
||
| REQ-001-12c | 状态变更记录：记录状态变更时间和操作人 | P1 | 可查看每条记录的状态变更历史 |
|
||
|
||
#### T4: 通知模板管理
|
||
|
||
| 需求ID | 描述 | 优先级 | 验收标准 |
|
||
|--------|------|--------|----------|
|
||
| REQ-001-13 | 模板变量：支持变量替换（{username}, {device}, {dept}, {software}, {detect_time}） | P0 | 通知内容中变量被正确替换 |
|
||
| REQ-001-14 | 默认模板：内置默认通知模板 | P0 | 未配置模板时使用默认模板发送 |
|
||
| REQ-001-15 | 模板编辑：支持富文本编辑通知模板 | P1 | 可编辑标题和正文内容 |
|
||
| REQ-001-16 | 企微消息发送：通过企微应用消息接口发送通知 | P0 | 成功发送至终端用户企微 |
|
||
|
||
#### T5: 调度与执行
|
||
|
||
| 需求ID | 描述 | 优先级 | 验收标准 |
|
||
|--------|------|--------|----------|
|
||
| REQ-001-17 | 定时任务：支持配置 cron 表达式执行检查 | P0 | 每天 8:00 自动执行检查任务 |
|
||
| REQ-001-18 | 手动触发：提供"立即检查"按钮 | P0 | 点击后立即执行检查流程 |
|
||
| REQ-001-19 | 活动期间开关：支持设置活动起止时间 | P0 | 活动期间自动开启检查，非活动期间可手动开启 |
|
||
| REQ-001-20 | 执行日志：记录每次执行的起止时间、命中数量、发送结果 | P0 | 可查看历史执行记录 |
|
||
| REQ-001-21 | Excel 导出：支持导出检测结果为 Excel | P0 | 导出字段：用户名、用户全名、部门、设备名称、IP、MAC、软件名称、安装日期 |
|
||
|
||
### 5.2 边缘情况处理
|
||
|
||
| 场景 | 处理方式 |
|
||
|------|----------|
|
||
| 火绒 API 调用失败 | 记录错误日志，发送告警给 IT 管理员，继续使用上次导入的联软数据 |
|
||
| 联软 Excel 未导入 | 仅使用火绒数据，未匹配用户的终端标记为"用户未知" |
|
||
| 用户无企微账户 | 跳过发送，标记为"发送失败"，记录日志 |
|
||
| 重复检测 | 同一用户同一天多次检测，仅发送首次通知（去重） |
|
||
| 空结果（无违规） | 发送"本次检查无违规"的汇总通知给管理员 |
|
||
|
||
---
|
||
|
||
## 6. 成功指标 (Success Metrics)
|
||
|
||
### 6.1 领先指标（Leading Indicators）
|
||
|
||
| 指标 | 定义 | 目标 | 测量方式 |
|
||
|------|------|------|----------|
|
||
| 检测覆盖率 | 成功关联到用户的终端数 / 火绒总终端数 | ≥ 85% | 数据库统计 |
|
||
| 通知成功率 | 成功发送通知数 / 需通知总数 | ≥ 95% | 企微 API 返回 |
|
||
| 执行完成率 | 定时任务成功执行次数 / 计划执行次数 | ≥ 99% | 调度日志 |
|
||
|
||
### 6.2 滞后指标（Lagging Indicators）
|
||
|
||
| 指标 | 定义 | 目标 | 测量方式 |
|
||
|------|------|------|----------|
|
||
| 闭环率 | 当事人确认处理（卸载）的比例 | ≥ 80% | 用户反馈或二次检测 |
|
||
| 投诉率 | 通知后用户投诉误报的比例 | < 5% | 反馈记录 |
|
||
| 合规达标率 | 活动期间最后一天违规终端清理比例 | 100% | 最终检测报告 |
|
||
|
||
---
|
||
|
||
## 7. 开放问题 (Open Questions)
|
||
|
||
| # | 问题 | 负责人 | 状态 |
|
||
|---|------|--------|------|
|
||
| Q1 | 联软 Excel 导入频率？建议每日导入一次还是每次检查前导入？ | 产品 | 待确认 |
|
||
| Q2 | 部门负责人通知是否需要汇总（多条合并为1条）？ | 产品 | 待确认 |
|
||
| Q3 | 活动期间结束后，是否需要自动关闭定时任务？ | 产品 | 待确认 |
|
||
|
||
---
|
||
|
||
## 7.1 任务拆分说明（重要）
|
||
|
||
> ⚠️ **系统现有火绒 API 集成，无需重复开发**
|
||
|
||
| 任务 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| **T0: 策略与渠道管理** | 需开发：策略配置、渠道适配器框架 | 🔲 待开发 |
|
||
| **T1a: 火绒API集成** | 现有功能已支持（`/api/admin/integrations/huorong/terminals`） | ✅ 已存在 |
|
||
| **T1b: 联软Excel导入** | 需开发：从联软导出Excel导入用户-终端关联 | 🔲 待开发 |
|
||
| T2: 数据融合引擎 | 需开发：IP/主机名/MAC三级匹配 | 🔲 待开发 |
|
||
| T3: 策略规则引擎 | 需开发：白名单、命中过滤 | 🔲 待开发 |
|
||
| T4: 通知模板管理 | 需开发：模板编辑、企微消息发送 | 🔲 待开发 |
|
||
| T5: 调度与执行 | 需开发：定时任务、手动触发、活动开关 | 🔲 待开发 |
|
||
|
||
**实际开发任务**：T0 + T1b + T2 + T3 + T4 + T5（共6个任务）
|
||
|
||
---
|
||
|
||
## 8. 时间计划 (Timeline)
|
||
|
||
### 阶段划分
|
||
|
||
> ⚠️ **注**：T1a（火绒API）已存在，无需开发。
|
||
|
||
| 阶段 | 内容 | 预估工期 |
|
||
|------|------|----------|
|
||
| Phase 0 | T0（策略与渠道框架）+ T1b（联软导入） | 2 天 |
|
||
| Phase 1 | T2（融合引擎）+ T3（策略规则） | 2 天 |
|
||
| Phase 2 | T4（通知模板）+ T5（调度执行+导出） | 2 天 |
|
||
| Phase 3 | 联调测试 + 验收 | 2 天 |
|
||
| **合计** | 实际开发 | **8 天** |
|
||
|
||
### 里程碑
|
||
|
||
| 日期 | 里程碑 |
|
||
|------|--------|
|
||
| 2026-07-25 | Phase 1-2 完成，进入联调 |
|
||
| 2026-07-28 | Phase 3-4 完成，进入测试 |
|
||
| 2026-07-30 | UAT 通过，具备上线条件 |
|
||
|
||
---
|
||
|
||
## 9. 风险与依赖 (Risks & Dependencies)
|
||
|
||
| 风险/依赖 | 影响 | 缓解措施 |
|
||
|-----------|------|----------|
|
||
| 火绒 API 性能 | 终端数量多时可能超时 | 分页获取，增加重试机制 |
|
||
| 联软数据更新 | 用户-终端关联可能变更 | 建议每次检查前重新导入最新 Excel |
|
||
| 企微消息频率限制 | 大批量发送可能触发限制 | 增加发送间隔，批量改单发 |
|
||
|
||
---
|
||
|
||
## 10. 附录
|
||
|
||
### 数据字段映射
|
||
|
||
#### 火绒终端字段（API 返回）
|
||
- `client_id`: 终端唯一标识
|
||
- `hostname`: 主机名
|
||
- `ip`: IP 地址
|
||
- `mac`: MAC 地址
|
||
- `software`: 已安装软件列表
|
||
|
||
#### 联软 Excel 字段
|
||
- `用户名`: 企微/AD 用户名
|
||
- `用户全名`: 真实姓名
|
||
- `部门名称`: 组织架构
|
||
- `设备名称`: 终端名称
|
||
- `设备IP`: IP 地址
|
||
- `MAC地址`: MAC 地址
|
||
- `软件名称`: 已安装软件
|
||
- `安装日期`: 软件安装时间
|
||
|
||
### 匹配优先级
|
||
1. IP 地址完全匹配
|
||
2. 主机名包含匹配（联软设备名称 in 火绒主机名）
|
||
3. MAC 地址匹配
|
||
|
||
---
|
||
|
||
## 变更记录
|
||
|
||
| 日期 | 版本 | 变更内容 | 变更人 | 变更原因 |
|
||
|------|------|----------|--------|----------|
|
||
| 2026-07-20 | v1.0 | 初始版本 | Simon | 新建需求 |
|
||
|
||
---
|
||
|
||
**审批记录**
|
||
|
||
| 角色 | 姓名 | 日期 | 签字 |
|
||
|------|------|------|------|
|
||
| 产品负责人 | | | |
|
||
| 技术负责人 | | | |
|
||
| 业务负责人 | | | |
|