Files
wecom_it_smart_desk/docs/火绒终端安全系统集成分析.md

561 lines
23 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 火绒终端安全管理系统集成分析
> 基于火绒终端安全管理系统API说明文档(内网地址: `huorong.oa.servyou-it.com:8080`
> 分析日期:2026-06-11
> 分析人:IT智能服务台项目组
---
## 一、火绒API全景概览
### 1.1 认证机制
| 项目 | 说明 |
|------|------|
| 认证方式 | AccessKey ID + AccessKey SecretHMAC-SHA1签名) |
| 签名方式 | Header签名(推荐) / URL签名(备选) |
| 签名算法 | HMAC-SHA1 → Base64编码 |
| 公共参数 | `access_key_id``signature``timestamp``nonce` |
| 内网地址 | `http://huorong.oa.servyou-it.com:8080` |
### 1.2 API端点清单
| 分类 | 端点 | 方法 | 说明 | 优先级建议 |
|------|------|------|------|-----------|
| **分组管理** | `/api/group/_list` | POST | 获取全部分组 | P1 |
| | `/api/group/_add` | POST | 新增分组 | P2 |
| | `/api/group/_delete` | POST | 删除分组 | P2 |
| | `/api/group/_move` | POST | 移动终端到指定分组 | P2 |
| | `/api/group/_modify` | POST | 修改分组名称 | P2 |
| **终端信息** | `/api/clnts/_list` | POST | 查询终端基本信息 | **P0** |
| | `/api/clnts/_info` | POST | 获取终端详细信息 | **P0** |
| | `/api/clnts/_info2` | POST | 终端详细信息v2(可选字段) | **P0** |
| | `/api/clnts/_online` | POST | 查询上线终端 | P1 |
| | `/api/clnts/_leak` | POST | 查询高危漏洞终端 | **P0** |
| | `/api/clnts/_virus_events` | POST | 统计病毒事件 | **P0** |
| **终端任务** | `/api/task/_create` | POST | 创建任务(type区分) | P1 |
| | ↳ type=quick_scan | | 快速扫描 | P1 |
| | ↳ type=full_scan | | 全盘扫描 | P2 |
| | ↳ type=custom_scan | | 自定义扫描 | P2 |
| | ↳ type=netctrl | | 终端隔离/解除 | **P0**(安全场景) |
| | ↳ type=message | | 发送通知 | P1 |
| **软件管理** | `/api/swinfo/_search` | POST | 查询软件信息 | P1 |
### 1.3 关键数据结构
**终端基本信息** (`/api/clnts/_list` 返回)
```
client_id // 终端唯一ID(40位十六进制字符串,用于所有任务下发)
computer_name // 计算机名
mac // MAC地址
ip // 本地IP
os_version // 操作系统版本
is_online // 在线状态 (bool)
group_id // 分组ID
group_name // 分组名称
```
**终端详细信息v2** (`/api/clnts/_info2`,可选信息块)
```
hardware: { cpu, memory, disk, motherboard, network_card } // 硬件信息
software: { installed_apps[] } // 已安装软件
assets: { asset_tag, serial_number } // 资产信息
netconf: { ip, gateway, dns, adapter_info } // 网络配置
```
**高危漏洞信息** (`/api/clnts/_leak` 返回)
```
client_id, computer_name, mac, ip
leaks: [{ leak_id, name, level, description, publish_time }]
```
**病毒事件统计** (`/api/clnts/_virus_events` 返回)
```
client_id, computer_name, mac
total_events // 事件总数
auto_cleaned // 自动处理数
manual_cleaned // 手动处理数
uncleaned // 未处理数
```
**终端隔离任务** (`type=netctrl`)
```
net_isolation: true // 隔离终端(断网)
net_isolation: false // 解除隔离(恢复网络)
clients: ["client_id_1", "client_id_2"] // 目标终端
```
**软件信息查询** (`/api/swinfo/_search`)
- 按软件统计 (groupby=software.list):软件名+发布者+安装数+安装率
- 按版本统计 (groupby=softwareVer.list):软件名+发布者+版本+安装数
- 按终端统计 (groupby=client.list):终端名+分组+IP+MAC+软件安装总数
---
## 二、产品维度分析
### 2.1 场景匹配度评估
| IT服务台场景 | 对应火绒API | 匹配度 | 说明 |
|-------------|-----------|--------|------|
| 员工报修「电脑卡/慢」 | `_info2`(hardware) | ⭐⭐⭐⭐⭐ | 直接获取CPU/内存/磁盘,判断是否硬件瓶颈 |
| 员工报修「中病毒了」 | `_virus_events` + `_list` | ⭐⭐⭐⭐⭐ | 精确查看该终端病毒事件及处理状态 |
| 员工报修「软件安装问题」 | `_info2`(software) | ⭐⭐⭐⭐ | 查看已安装软件列表及版本 |
| 坐席排查「网络问题」 | `_info2`(netconf) | ⭐⭐⭐⭐ | 查看IP/网关/DNS配置 |
| 坐席排查「安全漏洞」 | `_leak` | ⭐⭐⭐⭐⭐ | 直接获取高危漏洞列表及修复状态 |
| 安全应急「隔离中毒终端」 | `_create`(netctrl) | ⭐⭐⭐⭐⭐ | 一键隔离/解除,黄金场景 |
| 安全巡检「批量扫描」 | `_create`(quick_scan) | ⭐⭐⭐ | 坐席可远程触发扫描 |
| 软件合规审计 | `_search`(software.list) | ⭐⭐⭐ | 查询软件安装率和版本分布 |
### 2.2 集成功能规划(按优先级)
#### P0 — 核心查询能力(阶段三 3A-3B)
| 功能 | 用户侧效果 | 涉及API |
|------|-----------|---------|
| **终端安全画像** | 坐席打开会话→自动展示该员工终端的在线状态/系统版本/硬件概要/安全评分 | `_list` + `_info2` |
| **漏洞预警卡片** | AI Wingman自动检测→推送高危漏洞提醒→坐席一键查看详情 | `_leak` |
| **病毒事件看板** | 展示该终端病毒事件统计(已处理/未处理)| `_virus_events` |
| **一键隔离/解除** | 安全事件→坐席在排查流程中点击按钮→火绒执行隔离 | `_create`(netctrl) |
#### P1 — 增强排查能力(阶段三 3C + 阶段四)
| 功能 | 用户侧效果 | 涉及API |
|------|-----------|---------|
| **远程触发扫描** | 坐席一键下发快速扫描→等待结果→自动回传 | `_create`(quick_scan) |
| **发送安全通知** | 坐席向终端推送安全提醒(如「请尽快更新系统」)| `_create`(message) |
| **软件清单查询** | 输入员工工号→自动列出已安装软件+版本 | `_search`(client.list) |
| **终端上线检查** | 排查网络问题时检查终端是否在线 | `_online` |
#### P2 — 管理与运营(阶段四 4B)
| 功能 | 用户侧效果 | 涉及API |
|------|-----------|---------|
| **安全数据看板** | 管理后台展示公司终端安全态势(漏洞分布/病毒事件趋势/隔离终端数) | `_leak` + `_virus_events` + `_list` |
| **软件合规报告** | 统计软件安装率、版本分布,发现违规软件 | `_search` |
| **终端分组视图** | 按部门/分组展示终端安全状况 | `_group/_list` + `_list` |
### 2.3 产品建议
#### ✅ 推荐:分三步走集成策略
**第一步(P0,约2周)**:只做「查」——终端安全画像+漏洞/病毒查询
- 坐席端集成:会话面板右侧新增「终端安全」标签页
- 数据获取方式:**被动查询**(坐席点击查看 / AI Wingman自动推送),不主动定时同步
- 理由:纯查询零风险,不影响火绒系统运行,且立刻为坐席提供关键信息
**第二步(P1,约2周)**:增加「控」——远程扫描+通知+隔离
- 坐席端集成:排查流程图中新增「安全操作」节点
- 操作需**二次确认**(尤其是隔离操作,需弹窗确认+记录审计日志)
- 理由:控制类操作有安全风险,需坐席主动触发,不适合AI自动执行
**第三步(P2,约1周)**:做「看」——管理后台数据看板
- 管理后台集成:新增「终端安全态势」页面
- 数据获取方式:定时同步(每天凌晨增量拉取)
- 理由:管理视角的聚合数据,时效性要求低,可用批处理
#### ⚠️ 关键产品约束
1. **隔离操作必须人工确认**`net_isolation=true` 是高危操作,禁止AI自动执行,必须坐席点击确认
2. **扫描任务需控制频率**:同一终端5分钟内不得重复下发扫描任务
3. **数据展示需脱敏**:终端MAC/IP等敏感信息,在H5用户端不展示(仅坐席端可见)
4. **API调用需降级容错**:火绒系统不可用时,终端安全标签页显示「暂不可用」,不影响主流程
---
## 三、开发维度分析
### 3.1 架构设计
#### 整体架构
```
┌─────────────┐ ┌──────────────┐ ┌──────────────────┐
│ 坐席工作台 │────▶│ 后端 API │────▶│ 火绒 API │
│ / 管理后台 │ │ (FastAPI) │ │ (内网:8080) │
└─────────────┘ └──────────────┘ └──────────────────┘
┌─────┴──────┐
│ Redis │
│ 缓存层 │
└────────────┘
```
#### 后端模块设计
```
backend/app/
├── integrations/
│ ├── __init__.py
│ ├── huorong/ # 火绒集成模块
│ │ ├── __init__.py
│ │ ├── client.py # 火绒API客户端(签名+请求)
│ │ ├── config.py # 配置(AccessKey/Secret/BaseUrl
│ │ ├── models.py # 数据模型(Pydantic
│ │ ├── cache.py # 缓存策略
│ │ └── exceptions.py # 自定义异常
│ └── base.py # 集成基类(供未来联软等复用)
├── api/
│ └── integrations.py # 新增:集成API路由
└── services/
└── integration_service.py # 新增:集成业务逻辑
```
### 3.2 签名实现
火绒使用 HMAC-SHA1 签名,Python 实现要点:
```python
import hmac
import hashlib
import base64
import time
import uuid
def sign_request(access_key_id: str, access_key_secret: str,
method: str, path: str, body: str = "") -> dict:
"""
火绒API签名实现
- method: HTTP方法(POST
- path: 请求路径(如 /api/clnts/_list
- body: 请求体JSON字符串
返回: 需附加到请求的Header字典
"""
timestamp = str(int(time.time()))
nonce = str(uuid.uuid4())
# 签名字符串 = Method + Path + Timestamp + Nonce + Body
string_to_sign = f"{method}\n{path}\n{timestamp}\n{nonce}\n{body}"
# HMAC-SHA1签名
signature = base64.b64encode(
hmac.new(
access_key_secret.encode("utf-8"),
string_to_sign.encode("utf-8"),
hashlib.sha1
).digest()
).decode("utf-8")
return {
"X-Access-Key-Id": access_key_id,
"X-Signature": signature,
"X-Timestamp": timestamp,
"X-Nonce": nonce,
}
```
### 3.3 缓存策略
火绒API属于**内部系统调用**,数据时效性与调用频率需平衡:
| 数据类型 | 缓存时间 | 理由 |
|---------|---------|------|
| 终端基本信息 (`_list`) | 5分钟 | 终端上下线状态变化较频繁 |
| 终端详细信息 (`_info2`) | 10分钟 | 硬件/软件变化慢,但坐席可能实时查询 |
| 漏洞信息 (`_leak`) | 30分钟 | 漏洞修复周期通常为天级 |
| 病毒事件 (`_virus_events`) | 5分钟 | 安全事件需较实时展示 |
| 分组信息 (`_group/_list`) | 1小时 | 分组变更极少 |
| 软件信息 (`_swinfo/_search`) | 1小时 | 软件安装变化慢 |
**缓存Key设计**
```
huorong:clnts:list:{group_id}:{page} # 终端列表
huorong:clnts:info2:{client_id}:{fields} # 终端详情
huorong:leak:{group_id}:{page} # 漏洞信息
huorong:virus:{client_id} # 病毒事件
```
### 3.4 员工→终端映射方案
火绒API以 `client_id`(40位十六进制)标识终端,而IT服务台以 `employee_id` 标识员工。需要映射:
#### 早期方案(仅考虑火绒)
| 方案 | 原理 | 优点 | 缺点 | 推荐 |
|------|------|------|------|------|
| **方案Acomputer_name匹配** | 火绒`computer_name` = 公司电脑命名规则(如`DESKTOP-工号``姓名-部门`)| 无需额外数据源 | 依赖命名规范一致性 | ⭐⭐⭐ |
| **方案BeHR+火绒交叉匹配** | eHR取员工IP/MAC → 火绒按IP/MAC查终端 | 精确匹配 | 需eHR接口支持,IP可能变化 | ⭐⭐⭐⭐ |
| **方案C:手动绑定** | 员工首次报修时坐席手动关联 | 最灵活 | 运营成本高,容易遗漏 | ⭐⭐ |
#### ⭐ 升级方案D:联软直接映射(推荐)
> **重大发现**2026-06-11补充):联软LV7000的 `queryDevByParams` 接口直接返回 `strusername`(员工账号)+ `struserdes`(员工姓名),且总部员工必须安装联软安全助手,**天然具备最准确的员工↔终端映射**。
**新映射架构(多源融合)**
```
联软(主源)→ strusername 精确匹配员工账号 → 获取终端IP/MAC/计算机名
↓ 用联软获取的IP/MAC去火绒查
火绒(安全源)→ 按IP/MAC匹配client_id → 获取安全状态
↓ 远程办公员工
aTrustVPN源)→ VPN登录账号匹配 → 获取VPN终端
```
**实现流程**
1. 输入 `employee_id` → 联软 `queryDevByParams(strusername=employee_id)` → 获取终端列表
2. 取终端IP/MAC → 火绒 `_list` 按IP查 `client_id` → 获取安全状态
3. 建立映射 `employee_id → [{leagsoft终端信息, huorong安全信息}]`
4. aTrust补全VPN终端(远程办公员工)
> 详见 `docs/联软终端安全系统集成分析.md` §4.4
### 3.5 前端集成设计
#### 坐席端新增
```
坐席工作台
└── 右侧面板
└── 「终端安全」标签页(与AI推送区并列)
├── 终端概要卡片
│ ├── 在线状态 🟢/🔴
│ ├── OS版本
│ ├── 硬件概要(CPU/内存/磁盘)
│ └── 安全评分(综合漏洞+病毒事件)
├── 安全事件列表
│ ├── 🔴 高危漏洞 (N个)
│ ├── 🟡 未处理病毒事件 (N个)
│ └── 🟢 安全状态正常
└── 快速操作
├── 📡 快速扫描
├── 🔒 隔离终端 (需二次确认)
├── 🔓 解除隔离
└── 📢 发送通知
```
#### 管理后台新增
```
管理后台
└── 终端安全态势页面(阶段四 P2)
├── 全局指标卡片
│ ├── 终端总数 / 在线数 / 离线数
│ ├── 高危漏洞终端数
│ └── 未处理病毒事件数
├── 漏洞分布图(按等级/部门)
├── 病毒事件趋势图(7天/30天)
└── 隔离终端列表
```
### 3.6 开发风险与应对
| 风险 | 影响 | 概率 | 应对措施 |
|------|------|------|---------|
| 火绒API签名实现有误 | 无法调用任何接口 | 中 | 先用Postman/curl验证签名逻辑,再编码 |
| 内网地址不通 | 开发环境无法调试 | 高 | 需VPN或开发机部署在内网 |
| AccessKey权限不足 | 部分API返回权限错误 | 中 | 提前与信息安全团队确认API账户权限范围 |
| API响应超时 | 坐席端体验卡顿 | 低 | 所有火绒调用设3秒超时+异步加载+降级展示 |
| 火绒版本升级API变更 | 集成失效 | 低 | 记录当前API版本号,抽象接口层便于适配 |
| 并发查询量过大 | 触发火绒限流 | 低 | 缓存+合并查询+限制QPS≤10 |
---
## 四、安全维度分析
### 4.1 认证安全
| 风险项 | 等级 | 说明 | 建议 |
|--------|------|------|------|
| AccessKey Secret泄露 | **严重** | 泄露后可调用所有火绒API,包括隔离终端 | Secret必须存环境变量,**禁止**写入代码/配置文件 |
| API签名重放攻击 | 中 | 同一请求可被截获重放 | 火绒已内置timestamp+nonce防重放,但需确认服务端校验 |
| 传输层安全 | 中 | 内网HTTP明文传输 | 内网可接受;若跨网段需走HTTPS代理 |
**AccessKey管理建议**
```python
# .env 配置(不提交Git
HUORONG_ACCESS_KEY_ID=你的AccessKeyID
HUORONG_ACCESS_KEY_SECRET=你的AccessKeySecret
HUORONG_BASE_URL=http://huorong.oa.servyou-it.com:8080
```
### 4.2 操作安全
| 操作 | 风险等级 | 安全要求 |
|------|---------|---------|
| 查询终端信息 (`_list`/`_info2`) | 🟢 低 | 无特殊要求 |
| 查询漏洞/病毒事件 (`_leak`/`_virus_events`) | 🟢 低 | 无特殊要求 |
| 发送通知 (`_create` message) | 🟡 中 | 记录审计日志(谁发的、发给谁、内容) |
| 远程扫描 (`_create` scan) | 🟡 中 | 记录审计日志;限制同一终端5分钟内不重复扫描 |
| **隔离终端** (`_create` netctrl) | 🔴 **高** | **必须**二次确认弹窗 + 审计日志 + 管理员审批(阶段四后) |
**隔离操作安全流程**
```
坐席点击「隔离终端」
弹窗确认:⚠️ 确认隔离该终端?该操作将断开终端网络连接
输入隔离原因(必填,≥10字)
[执行隔离] → 调用API → 记录审计日志
通知被隔离终端用户(通过企微消息)
```
### 4.3 数据安全
| 风险项 | 说明 | 建议 |
|--------|------|------|
| 终端敏感信息泄露 | MAC/IP/资产编号等敏感数据 | H5用户端不展示,仅坐席端可见 |
| 火绒数据本地存储 | 缓存数据包含终端信息 | Redis缓存设TTL自动过期,不落盘到数据库 |
| API响应数据清洗 | 火绒返回全量字段 | 后端只透传必要字段,过滤内部敏感字段 |
### 4.4 权限设计
| 角色 | 查询终端 | 远程扫描 | 隔离终端 | 发送通知 |
|------|---------|---------|---------|---------|
| 普通坐席 (agent) | ✅ | ✅ | ❌ | ✅ |
| 管理员 (admin) | ✅ | ✅ | ✅ | ✅ |
| H5用户 | ❌ | ❌ | ❌ | ❌ |
> 隔离操作初期仅限admin角色,待流程成熟后可下放至agent(需配置审批流)
### 4.5 审计日志
所有火绒API调用(尤其是写入/控制操作)必须记录审计日志:
```python
class HuorongAuditLog(Base):
__tablename__ = "huorong_audit_logs"
id: Mapped[int] # 主键
agent_id: Mapped[int] # 操作坐席ID
action: Mapped[str] # 操作类型: query/scan/isolate/notify
target_client_id: Mapped[str] # 目标终端client_id
request_params: Mapped[dict] # 请求参数(JSON
response_code: Mapped[int] # 火绒返回码
reason: Mapped[str] # 操作原因(隔离时必填)
created_at: Mapped[datetime] # 操作时间
```
---
## 五、实施路线图
### 阶段一(P0,约2周)— 查询能力集成
```
Week 1: 后端集成
├── Day 1-2: 火绒API客户端开发(签名+请求+异常处理)
├── Day 3-4: 缓存层+员工-终端映射逻辑
└── Day 5: API端点开发+单元测试
Week 2: 前端集成
├── Day 1-3: 坐席端「终端安全」标签页UI+数据对接
├── Day 4: AI Wingman接入漏洞/病毒推送
└── Day 5: 集成测试+Bug修复
```
**前置条件**
- [ ] 联系信息安全团队获取AccessKey ID/Secret
- [ ] 确认开发环境可访问火绒内网地址
- [ ] 确认API账户权限范围(是否包含所有端点)
### 阶段二(P1,约2周)— 控制能力集成
```
Week 3: 后端开发
├── Day 1-2: 任务下发API(扫描/通知/隔离)
├── Day 3: 审计日志模块
└── Day 4-5: 权限控制+二次确认流程
Week 4: 前端+联调
├── Day 1-3: 安全操作按钮+确认流程UI
├── Day 4: 排查流程图新增安全节点
└── Day 5: 端到端测试
```
### 阶段三(P2,约1周)— 管理看板
```
Week 5: 数据看板
├── Day 1-2: 定时同步任务+数据聚合
├── Day 3-4: 管理后台安全态势页面
└── Day 5: 验收测试
```
---
## 六、与现有系统的协同
### 6.1 与eHR集成协同
| 维度 | eHR提供 | 火绒提供 | 协同效果 |
|------|---------|---------|---------|
| 员工身份 | 姓名/工号/部门 | 计算机名/MAC/IP | 建立员工↔终端映射 |
| 资产信息 | 资产编号/领用日期 | 硬件配置/序列号 | 交叉验证资产归属 |
| 任职信息 | 岗位/入职日期 | 无直接关联 | 判断安全基线适用范围 |
**关键映射逻辑**
```
eHR: employee_id → 办公IP/资产编号
火绒: IP/MAC → client_id → 安全状态
IT服务台: employee_id → conversation → 坐席 → 查看安全状态
```
### 6.2 与AI Wingman协同
| AI推送场景 | 触发条件 | 推送内容 |
|-----------|---------|---------|
| 漏洞预警 | 员工终端有高危漏洞未修复 | 「⚠️ 该员工终端存在N个高危漏洞,建议优先处理」 |
| 病毒预警 | 员工终端有未处理病毒事件 | 「🔴 该终端检测到N个未处理病毒事件,建议立即排查」 |
| 离线提醒 | 员工终端不在线 | 「💡 该终端当前离线,部分远程操作不可用」 |
| 安全评分 | 综合漏洞+病毒+在线状态 | 「终端安全评分:72/100,主要扣分项:3个高危漏洞」 |
### 6.3 与排查流程图协同
在阶段三的排查流程图中新增安全相关节点:
```
[开始] → [确认员工身份] → [检查终端在线状态]
↓ (在线)
[安全基线检查] → 有高危漏洞?→ [推送漏洞详情] → [建议隔离/扫描]
↓ (无漏洞)
[病毒事件检查] → 有未处理事件?→ [推送病毒详情] → [触发扫描]
↓ (安全)
[继续常规排查...]
```
---
## 七、对接前准备清单
### 必须完成(阻塞性)
- [ ] **获取AccessKey**:联系信息安全团队(潘工/信息安全组),申请API调用权限的AccessKey ID + Secret
- [ ] **网络可达**:确认部署服务器/开发机可访问 `huorong.oa.servyou-it.com:8080`
- [ ] **权限范围确认**:确认API账户可调用哪些端点(尤其是隔离操作的权限)
- [ ] **电脑命名规范确认**:了解公司电脑命名规则(是否包含工号/姓名),影响员工↔终端映射方案
### 建议完成(非阻塞)
- [ ] **火绒版本确认**:确认当前火绒版本是否与API文档一致
- [ ] **限流策略确认**:确认API调用频率限制(QPS/每日调用上限)
- [ ] **联软集成调研**:同步了解联软安全系统的API开放性,为未来双系统接入做准备
- [ ] **测试终端准备**:准备1-2台测试用终端,用于开发调试
---
## 八、总结
### 8.1 核心结论
1. **火绒API成熟可用**:17个端点覆盖终端查询/控制/软件管理,签名机制标准,响应格式统一
2. **与IT服务台场景高度匹配**:员工报修场景中80%涉及终端问题,火绒数据可直接赋能坐席
3. **安全隔离是杀手级功能**:坐席一键隔离中毒终端,将安全事件响应从「小时级」缩短到「秒级」
4. **实现成本低**:纯REST API集成,无需安装agent或修改现有系统架构
5. **安全风险可控**:查询类零风险,控制类通过权限+审计+二次确认三层防护
### 8.2 投入产出比
| 维度 | 评估 |
|------|------|
| 开发投入 | 约5周(含P0+P1+P2 |
| 坐席效率提升 | 安全类工单处理时间预计降低40%+ |
| 安全响应提速 | 终端隔离从小时级→秒级 |
| 数据价值 | 首次将终端安全数据引入IT服务流程 |
| 风险 | 低(纯API集成,不修改火绒系统本身) |
### 8.3 一句话总结
> 火绒集成是IT智能服务台从「被动响应」走向「主动安全」的关键一步,建议优先推进P0查询能力,2周内可上线见效。