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-*/
453 lines
18 KiB
Markdown
453 lines
18 KiB
Markdown
# 技术方案：安全策略检查平台
|
|
|
|
> **版本**: v1.0
|
|
> **日期**: 2026-07-20
|
|
> **状态**: [草稿]
|
|
> **关联PRD**: `01-产品文档/08-集成生态/PRD-REQ-集成-001-OpenClaw合规检查-v1.0.md`
|
|
|
|
---
|
|
|
|
## 1. 系统架构
|
|
|
|
### 1.1 整体架构
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 安全策略检查平台 │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────┐ │
|
|
│ │ 策略配置 │ │ 渠道配置 │ │ 任务调度 │ │
|
|
│ │ (策略管理) │ │ (渠道管理) │ │ (定时/手动) │ │
|
|
│ └──────┬───────┘ └──────┬───────┘ └────────┬──────────┘ │
|
|
│ │ │ │ │
|
|
│ └──────────────────┼─────────────────────┘ │
|
|
│ ▼ │
|
|
│ ┌─────────────────────────────────────────────────────────┐ │
|
|
│ │ 策略执行引擎 │ │
|
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
|
│ │ │ 数据采集层 │→ │ 数据融合层 │→ │ 规则匹配层 │ │ │
|
|
│ │ │ 火绒API │ │ IP/主机名 │ │ 关键词过滤 │ │ │
|
|
│ │ │ 联软Excel │ │ MAC匹配 │ │ 白名单过滤 │ │ │
|
|
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────┘ │
|
|
│ ▼ │
|
|
│ ┌─────────────────────────────────────────────────────────┐ │
|
|
│ │ 通知发送层 │ │
|
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
|
│ │ │ 企微应用 │ │ 企微群 │ │ (扩展)邮件 │ │ │
|
|
│ │ │ │ │ │ │ (扩展)短信 │ │ │
|
|
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────┘ │
|
|
│ ▼ │
|
|
│ ┌─────────────────────────────────────────────────────────┐ │
|
|
│ │ 数据存储层 │ │
|
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
|
│ │ │ 策略配置 │ │ 命中记录 │ │ 执行日志 │ │ │
|
|
│ │ │ (PostgreSQL)│ │ (PostgreSQL)│ │ (PostgreSQL)│ │ │
|
|
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 1.2 模块设计
|
|
|
|
| 模块 | 职责 | 技术选型 |
|
|
|------|------|----------|
|
|
| 策略配置管理 | 策略增删改查、启停 | FastAPI + SQLAlchemy |
|
|
| 渠道配置管理 | 渠道增删改查、适配器 | 策略模式 |
|
|
| 数据采集层 | 火绒API调用、联软Excel解析 | openpyxl + requests |
|
|
| 数据融合层 | IP/主机名/MAC三级匹配 | Python dict/hash |
|
|
| 规则匹配层 | 关键词过滤、白名单 | 正则表达式 |
|
|
| 通知发送层 | 企微消息发送 | 适配器模式 |
|
|
| 任务调度层 | APScheduler定时任务 | APScheduler |
|
|
| 数据存储层 | PostgreSQL | SQLAlchemy ORM |
|
|
|
|
---
|
|
|
|
## 2. 数据库设计
|
|
|
|
### 2.1 表结构
|
|
|
|
#### 2.1.1 安全策略配置表 (security_strategies)
|
|
|
|
```sql
|
|
CREATE TABLE security_strategies (
|
|
id SERIAL PRIMARY KEY,
|
|
strategy_id VARCHAR(50) UNIQUE NOT NULL, -- 如: openclaw_remote
|
|
name VARCHAR(100) NOT NULL, -- 策略名称
|
|
description TEXT, -- 描述
|
|
detection_type VARCHAR(20) NOT NULL, -- 检测类型: software/usb/network
|
|
keywords TEXT NOT NULL, -- 关键词,逗号分隔
|
|
data_source VARCHAR(50) NOT NULL, -- 数据源: huorong/lianruan/both
|
|
channels JSONB NOT NULL DEFAULT '[]', -- 推送渠道配置
|
|
whitelist TEXT, -- 白名单,逗号分隔
|
|
is_enabled BOOLEAN DEFAULT FALSE,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
```
|
|
|
|
#### 2.1.2 渠道配置表 (notification_channels)
|
|
|
|
```sql
|
|
CREATE TABLE notification_channels (
|
|
id SERIAL PRIMARY KEY,
|
|
channel_id VARCHAR(50) UNIQUE NOT NULL, -- 如: wecom_app
|
|
name VARCHAR(100) NOT NULL, -- 渠道名称
|
|
channel_type VARCHAR(20) NOT NULL, -- 渠道类型: wecom/email/sms/dingtalk
|
|
config JSONB NOT NULL DEFAULT '{}', -- 渠道配置参数
|
|
is_enabled BOOLEAN DEFAULT FALSE,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
```
|
|
|
|
#### 2.1.3 命中记录表 (security_hits)
|
|
|
|
```sql
|
|
CREATE TABLE security_hits (
|
|
id SERIAL PRIMARY KEY,
|
|
strategy_id VARCHAR(50) NOT NULL, -- 策略ID
|
|
username VARCHAR(100), -- 用户名
|
|
fullname VARCHAR(100), -- 用户全名
|
|
dept VARCHAR(100), -- 部门
|
|
device_name VARCHAR(100), -- 设备名称
|
|
ip_address VARCHAR(50), -- IP地址
|
|
mac_address VARCHAR(50), -- MAC地址
|
|
hit_content TEXT NOT NULL, -- 命中内容(软件名等)
|
|
status VARCHAR(20) DEFAULT 'pending', -- pending/notified/resolved/false_positive
|
|
first_detected_at TIMESTAMP NOT NULL, -- 首次检测时间
|
|
last_detected_at TIMESTAMP NOT NULL, -- 最近检测时间
|
|
notified_at TIMESTAMP, -- 通知时间
|
|
resolved_at TIMESTAMP, -- 解决时间
|
|
resolved_by VARCHAR(100), -- 解决人
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
FOREIGN KEY (strategy_id) REFERENCES security_strategies(strategy_id)
|
|
);
|
|
```
|
|
|
|
#### 2.1.4 状态变更历史表 (security_hit_history)
|
|
|
|
```sql
|
|
CREATE TABLE security_hit_history (
|
|
id SERIAL PRIMARY KEY,
|
|
hit_id INTEGER NOT NULL,
|
|
old_status VARCHAR(20),
|
|
new_status VARCHAR(20) NOT NULL,
|
|
changed_by VARCHAR(100),
|
|
change_reason TEXT,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
FOREIGN KEY (hit_id) REFERENCES security_hits(id)
|
|
);
|
|
```
|
|
|
|
#### 2.1.5 执行日志表 (security_executions)
|
|
|
|
```sql
|
|
CREATE TABLE security_executions (
|
|
id SERIAL PRIMARY KEY,
|
|
strategy_id VARCHAR(50) NOT NULL,
|
|
execution_type VARCHAR(20) NOT NULL, -- scheduled/manual
|
|
total_terminals INTEGER DEFAULT 0, -- 总终端数
|
|
hit_count INTEGER DEFAULT 0, -- 命中数
|
|
notified_count INTEGER DEFAULT 0, -- 通知成功数
|
|
status VARCHAR(20) NOT NULL, -- running/success/failed
|
|
error_message TEXT,
|
|
started_at TIMESTAMP NOT NULL,
|
|
finished_at TIMESTAMP,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
FOREIGN KEY (strategy_id) REFERENCES security_strategies(strategy_id)
|
|
);
|
|
```
|
|
|
|
#### 2.1.6 通知模板表 (notification_templates)
|
|
|
|
```sql
|
|
CREATE TABLE notification_templates (
|
|
id SERIAL PRIMARY KEY,
|
|
strategy_id VARCHAR(50) NOT NULL,
|
|
channel_id VARCHAR(50) NOT NULL,
|
|
title VARCHAR(200),
|
|
content TEXT NOT NULL,
|
|
is_default BOOLEAN DEFAULT FALSE,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
FOREIGN KEY (strategy_id) REFERENCES security_strategies(strategy_id),
|
|
FOREIGN KEY (channel_id) REFERENCES notification_channels(channel_id)
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 核心流程设计
|
|
|
|
### 3.1 定时检查流程
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ 定时任务触发 │
|
|
│ (APScheduler) │
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐ ┌─────────────────┐
|
|
│ 检查活动期间 │ │ 检查策略是否启用 │
|
|
│ (活动开关) │ │ (is_enabled) │
|
|
└────────┬────────┘ └────────┬────────┘
|
|
│ │
|
|
└───────────┬───────────┘
|
|
▼
|
|
┌─────────────┐
|
|
│ 加载策略 │
|
|
│ 获取关键词 │
|
|
│ 获取渠道 │
|
|
└──────┬──────┘
|
|
▼
|
|
┌─────────────────────┐
|
|
│ 从火绒API获取 │
|
|
│ 终端软件列表 │
|
|
└──────────┬──────────┘
|
|
▼
|
|
┌─────────────────────┐
|
|
│ 加载联软Excel │
|
|
│ 用户-终端关联 │
|
|
└──────────┬──────────┘
|
|
▼
|
|
┌─────────────────────┐
|
|
│ 三级匹配 │
|
|
│ IP → 主机名 → MAC │
|
|
└──────────┬──────────┘
|
|
▼
|
|
┌─────────────────────┐
|
|
│ 关键词过滤 │
|
|
│ 白名单过滤 │
|
|
└──────────┬──────────┘
|
|
▼
|
|
┌─────────────────────┐
|
|
│ 生成命中记录 │
|
|
│ 状态=pending │
|
|
└──────────┬──────────┘
|
|
▼
|
|
┌─────────────────────┐
|
|
│ 匹配历史记录 │
|
|
│ 状态变更判断 │
|
|
│ (自动解决逻辑) │
|
|
└──────────┬──────────┘
|
|
▼
|
|
┌─────────────────────┐
|
|
│ 发送企微通知 │
|
|
│ 更新状态 │
|
|
└──────────┬──────────┘
|
|
▼
|
|
┌─────────────────────┐
|
|
│ 记录执行日志 │
|
|
│ 更新统计 │
|
|
└─────────────────────┘
|
|
```
|
|
|
|
### 3.2 状态自动变更逻辑
|
|
|
|
```python
|
|
def auto_update_status(new_hits, old_hits_map):
|
|
"""
|
|
new_hits: 本次检测到的命中列表
|
|
old_hits_map: 历史命中字典 {user+device: hit_record}
|
|
"""
|
|
for hit in new_hits:
|
|
key = f"{hit.username}:{hit.device_name}"
|
|
if key in old_hits_map:
|
|
old_hit = old_hits_map[key]
|
|
# 历史存在，本次仍命中 -> 保持原状态或更新为已通知
|
|
if old_hit.status == 'pending':
|
|
old_hit.status = 'notified'
|
|
old_hit.notified_at = now()
|
|
else:
|
|
# 新命中 -> 创建记录，状态=pending
|
|
create_hit_record(hit)
|
|
|
|
# 检查历史命中本次是否未命中 -> 自动标记已解决
|
|
for key, old_hit in old_hits_map.items():
|
|
if key not in new_hits_map:
|
|
if old_hit.status in ['pending', 'notified']:
|
|
old_hit.status = 'resolved'
|
|
old_hit.resolved_at = now()
|
|
old_hit.resolved_by = 'system:auto'
|
|
```
|
|
|
|
---
|
|
|
|
## 4. API设计
|
|
|
|
### 4.1 策略管理
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| GET | /api/security/strategies | 获取策略列表 |
|
|
| POST | /api/security/strategies | 创建策略 |
|
|
| GET | /api/security/strategies/{id} | 获取策略详情 |
|
|
| PUT | /api/security/strategies/{id} | 更新策略 |
|
|
| DELETE | /api/security/strategies/{id} | 删除策略 |
|
|
| POST | /api/security/strategies/{id}/toggle | 启用/停用策略 |
|
|
|
|
### 4.2 渠道管理
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| GET | /api/security/channels | 获取渠道列表 |
|
|
| POST | /api/security/channels | 创建渠道 |
|
|
| PUT | /api/security/channels/{id} | 更新渠道 |
|
|
| DELETE | /api/security/channels/{id} | 删除渠道 |
|
|
| POST | /api/security/channels/{id}/test | 测试渠道连接 |
|
|
|
|
### 4.3 命中记录
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| GET | /api/security/hits | 获取命中记录列表 |
|
|
| PUT | /api/security/hits/{id}/status | 更新命中状态 |
|
|
| GET | /api/security/hits/{id}/history | 获取状态变更历史 |
|
|
|
|
### 4.4 执行控制
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| POST | /api/security/execute | 手动触发检查 |
|
|
| GET | /api/security/executions | 获取执行历史 |
|
|
| GET | /api/security/executions/{id} | 获取执行详情 |
|
|
|
|
### 4.5 导出
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| GET | /api/security/export | 导出Excel报告 |
|
|
|
|
---
|
|
|
|
## 5. 扩展性设计
|
|
|
|
### 5.1 策略类型扩展
|
|
|
|
```python
|
|
# 策略检测器基类
|
|
class BaseDetector(ABC):
|
|
@abstractmethod
|
|
def detect(self, terminals: List[Terminal]) -> List[Hit]:
|
|
pass
|
|
|
|
# 软件检测器
|
|
class SoftwareDetector(BaseDetector):
|
|
def detect(self, terminals):
|
|
# 关键词匹配
|
|
pass
|
|
|
|
# USB检测器
|
|
class USBDetector(BaseDetector):
|
|
def detect(self, terminals):
|
|
# USB设备检测
|
|
pass
|
|
|
|
# 注册策略检测器
|
|
DETECTOR_REGISTRY = {
|
|
'software': SoftwareDetector,
|
|
'usb': USBDetector,
|
|
}
|
|
```
|
|
|
|
### 5.2 渠道适配器扩展
|
|
|
|
```python
|
|
# 渠道发送器基类
|
|
class BaseSender(ABC):
|
|
@abstractmethod
|
|
def send(self, template: Template, targets: List[Target]) -> SendResult:
|
|
pass
|
|
|
|
# 企微发送器
|
|
class WeComSender(BaseSender):
|
|
def send(self, template, targets):
|
|
# 企微API调用
|
|
pass
|
|
|
|
# 邮件发送器
|
|
class EmailSender(BaseSender):
|
|
def send(self, template, targets):
|
|
# SMTP发送
|
|
pass
|
|
|
|
# 注册渠道发送器
|
|
SENDER_REGISTRY = {
|
|
'wecom': WeComSender,
|
|
'email': EmailSender,
|
|
'sms': SMSSender,
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 安全与合规
|
|
|
|
### 6.1 数据安全
|
|
|
|
- 白名单、敏感配置数据加密存储
|
|
- 操作日志记录所有管理操作
|
|
- 定期备份数据库
|
|
|
|
### 6.2 隐私合规
|
|
|
|
- 用户-终端关联数据仅用于通知定位
|
|
- 不存储额外个人信息
|
|
- 符合公司数据安全规范
|
|
|
|
---
|
|
|
|
## 7. 部署方案
|
|
|
|
### 7.1 依赖服务
|
|
|
|
| 服务 | 版本要求 |
|
|
|------|----------|
|
|
| PostgreSQL | 14+ |
|
|
| Redis | 6+ (可选，用于缓存) |
|
|
| APScheduler | 3.10+ |
|
|
|
|
### 7.2 环境变量
|
|
|
|
```bash
|
|
# 数据库
|
|
DATABASE_URL=postgresql://user:pass@localhost:5432/security_db
|
|
|
|
# 火绒API (复用现有配置)
|
|
HUORONG_BASE_URL=
|
|
HUORONG_KEY=
|
|
HUORONG_SECRET=
|
|
|
|
# 企微应用 (复用现有配置)
|
|
WECOM_AGENT_ID=
|
|
WECOM_SECRET=
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 验收标准
|
|
|
|
| 验收项 | 标准 |
|
|
|--------|------|
|
|
| 定时执行 | 每天8:00自动执行，99%可用率 |
|
|
| 手动触发 | 点击后5分钟内完成检查 |
|
|
| 匹配准确率 | IP/主机名/MAC三级匹配成功率≥85% |
|
|
| 通知成功率 | 企微通知送达率≥95% |
|
|
| 状态自动更新 | 历史命中用户再次未命中，自动标记已解决 |
|
|
| Excel导出 | 正确导出所有命中字段 |
|
|
|
|
---
|
|
|
|
## 9. 后续扩展
|
|
|
|
| 扩展项 | 工作量 | 说明 |
|
|
|--------|--------|------|
|
|
| 新增检测策略 | 0.5天 | 配置关键词和数据源 |
|
|
| 新增邮件渠道 | 1天 | 开发EmailSender |
|
|
| 新增短信渠道 | 1天 | 开发SMSSender |
|
|
| 新增钉钉渠道 | 1天 | 开发DingTalkSender |
|