simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feature/p1-message-fixes
wecom_it_smart_desk/docs/火绒终端安全系统集成分析.md
T

23 KiB
Raw Permalink Blame History

火绒终端安全管理系统集成分析

基于火绒终端安全管理系统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 实现要点：

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管理建议：

# .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调用（尤其是写入/控制操作）必须记录审计日志：

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周内可上线见效。

Reference in New Issue View Git Blame Copy Permalink