# 火绒终端安全管理系统集成分析 > 基于火绒终端安全管理系统API说明文档(内网地址: `huorong.oa.servyou-it.com:8080`) > 分析日期:2026-06-11 > 分析人:IT智能服务台项目组 --- ## 一、火绒API全景概览 ### 1.1 认证机制 | 项目 | 说明 | |------|------| | 认证方式 | AccessKey ID + AccessKey Secret(HMAC-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` 标识员工。需要映射: #### 早期方案(仅考虑火绒) | 方案 | 原理 | 优点 | 缺点 | 推荐 | |------|------|------|------|------| | **方案A:computer_name匹配** | 火绒`computer_name` = 公司电脑命名规则(如`DESKTOP-工号`或`姓名-部门`)| 无需额外数据源 | 依赖命名规范一致性 | ⭐⭐⭐ | | **方案B:eHR+火绒交叉匹配** | 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 → 获取安全状态 ↓ 远程办公员工 aTrust(VPN源)→ 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周内可上线见效。