Files

561 lines
23 KiB
Markdown
Raw Permalink Normal View History

# 火绒终端安全管理系统集成分析
> 基于火绒终端安全管理系统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周内可上线见效。