Simon
798 lines
36 KiB
Markdown
798 lines
36 KiB
Markdown
# 联软LV7000终端安全管理系统集成分析
|
||
|
||
> 基于联软LV7000系列LeagView5版本API接口说明文档（202210SP v1.1）
|
||
> 分析日期：2026-06-11
|
||
> 分析人：IT智能服务台项目组
|
||
|
||
---
|
||
|
||
## 一、联软API全景概览
|
||
|
||
### 1.1 认证机制
|
||
|
||
联软提供**三层认证**，灵活度高于火绒：
|
||
|
||
| 认证模式 | 说明 | 适用场景 |
|
||
|---------|------|---------|
|
||
| **白名单IP验证**（默认启用） | 配置`WhiteListServerIp`允许的调用方IP | 内网系统间调用 |
|
||
| **用户名密码验证** | 配置`ApiAccount`+`ApiPassword`，调用时传`apiAccount`+`apiPassword`+`validatekey` | 跨网段调用 |
|
||
| **一次性Token验证** | 先调`/token?act=getToken`获取token（默认30分钟有效），业务接口带`token`参数 | 安全要求高的场景 |
|
||
|
||
**端口**：`30098`（所有API统一端口）
|
||
|
||
**响应格式统一**：
|
||
```json
|
||
{
|
||
"status": "SUCCESS | ERROR | INVALID | Exceed",
|
||
"msg": "描述信息",
|
||
"rows": [...], // 数据列表（部分接口用"row"）
|
||
"total": 100 // 总记录数
|
||
}
|
||
```
|
||
|
||
- `SUCCESS`：成功
|
||
- `ERROR`：参数错误/业务失败
|
||
- `INVALID`：无权限（IP不在白名单）
|
||
- `Exceed`：数据量超限（仅仿冒设备接口）
|
||
|
||
### 1.2 API端点分类总览（68个）
|
||
|
||
| 大类 | 数量 | 核心端点 | 对IT服务台价值 |
|
||
|------|------|---------|--------------|
|
||
| **终端设备** | 8 | `queryDevByParams`, `getDevAllInfo`, `querysoftwarebydev` | ⭐⭐⭐⭐⭐ 极高 |
|
||
| **准入控制** | 7 | `existOnlineUser`, `onlineUserList`, `forcedOffline`, `queryAccessLog` | ⭐⭐⭐⭐ 高 |
|
||
| **组织架构/用户** | 8 | `getUserInfo`, `getUserInfoByAccount`, `getAllOrgInfo`, `getDeptInfo` | ⭐⭐⭐⭐⭐ 极高（映射） |
|
||
| **审计查询** | 4 | `queryCommonAuditInfo`, `queryClientPatchAuditInfo` | ⭐⭐⭐ 中 |
|
||
| **安全策略** | 5 | `getSecScopeByName`, `addSecpolicyScope` 等 | ⭐⭐ 低 |
|
||
| **审批流程** | 12 | `queryapprovallist`, `doapproval`, `endapproval` 等 | ⭐⭐ 低 |
|
||
| **免检设备** | 6 | `addByMac`, `delByMac`, `queryCheckDevList` | ⭐⭐ 低 |
|
||
| **访客/外协** | 8 | `getGuestAccount`, `create`, `find`, `applyOutsource` | ⭐⭐ 低 |
|
||
| **其他** | 10 | `noticeAgentMsg`, `remoteWakeUp`, `queryCounterfeitList` 等 | ⭐⭐⭐ 中 |
|
||
|
||
### 1.3 核心API详解（对IT服务台有价值的端点）
|
||
|
||
#### 1.3.1 🔴 P0级 — 终端设备查询
|
||
|
||
**查询指定终端设备** `queryDevByParams`
|
||
- URL: `http://{IP}:30098/terminal?act=queryDevByParams`
|
||
- **这是最核心的接口**！返回字段包含：
|
||
```
|
||
istatus // 终端状态（在线/离线）
|
||
strdevname // 计算机名
|
||
strdevip // IP地址
|
||
strmac // MAC地址
|
||
strdeptname // 所属部门名
|
||
strusername // ⭐ 使用该终端的用户账号
|
||
struserdes // ⭐ 用户姓名/描述
|
||
strswitchname // 接入交换机名
|
||
strifname // 交换机接口名
|
||
strmail // 用户邮箱
|
||
strphone // 用户电话
|
||
```
|
||
|
||
> **关键发现**：`strusername` + `struserdes` 字段**直接提供员工账号→终端的映射**！无需通过IP交叉匹配，这是联软相比火绒的最大优势。
|
||
|
||
**设备概要详细信息** `getDevAllInfo`
|
||
- URL: `http://{IP}:30098/devallinfoshowwithpaging?act=getDevAllInfo`
|
||
- 返回**极其详细**的设备信息：
|
||
```
|
||
equipment:
|
||
strdevname, strip1, strmac, strnatip, macverdor, strdevtype
|
||
strdeptname, strusername, struserdes
|
||
dtdevuptime, dtdevdowntime, dtdevfirstfoundtime
|
||
stros, strdomain, strserialnumber, strmainboardtype
|
||
|
||
equipmentdetail:
|
||
devdetail:
|
||
strverofuaagent // 安全助手版本
|
||
istatus // 在线状态
|
||
uniaccessagentstatus // UniAccess助手状态
|
||
devassetno // 设备资产号
|
||
devgroup // 设备所属设备组
|
||
mainboardInformation[] // 主板（厂商/型号/序列号）
|
||
CPUInformation[] // CPU（型号/核心/频率/缓存）
|
||
MemoryInformation[] // 内存（最大/当前/插槽数）
|
||
HardDiskInformation[] // 硬盘（类型/容量/型号/序列号）
|
||
LogicalDiskInformation[] // 逻辑盘（卷标/文件系统/总量/可用/使用率）
|
||
GraphicsCardInformation[] // 显卡
|
||
NetworkCardInformation[] // 网卡（名称/是否无线/厂商/MAC）
|
||
DisplayInformation[] // 显示器（厂商/型号/序列号/尺寸）
|
||
PCIInformation[] // PCI设备
|
||
MemoryModuleDetails[] // 内存条详情
|
||
SoundCardInformation[] // 声卡
|
||
OperatingSystemInformation[] // 操作系统详情（语言/补丁/安装时间）
|
||
```
|
||
|
||
> 比火绒的`_info2`更详细！尤其是**逻辑磁盘使用率**（可直接判断磁盘满导致卡慢）和**显示器信息**（多屏配置排查）。
|
||
|
||
**设备安装软件信息** `querysoftwarebydev`
|
||
- URL: `http://{IP}:30098/software?act=querysoftwarebydev`
|
||
- 返回：
|
||
```
|
||
strdevname, strdevip, strmac, strdomain, strusername
|
||
softwares: [
|
||
{ strsoftware, strversion, strvendor, installdate }
|
||
]
|
||
```
|
||
|
||
#### 1.3.2 🔴 P0级 — 组织架构/用户
|
||
|
||
**查询用户信息** `getUserInfo`
|
||
- URL: `http://{IP}:30098/querydeptuser?act=getUserInfo`
|
||
- 返回：`deptid, userid, useraccount, username`
|
||
|
||
**用户账号查询** `getUserInfoByAccount`
|
||
- URL: `http://{IP}:30098/querydeptuser?act=getUserInfoByAccount`
|
||
- **直接通过账号查用户**，映射核心接口！
|
||
|
||
**查询部门和用户信息** `getAllOrgInfo`
|
||
- URL: `http://{IP}:30098/querydeptuser?act=getAllOrgInfo`
|
||
- 一次性获取所有部门+用户，可做全量同步
|
||
|
||
**查询部门信息** `getDeptInfo`
|
||
- URL: `http://{IP}:30098/querydeptuser?act=getDeptInfo`
|
||
- 返回所有部门（含父子关系）
|
||
|
||
#### 1.3.3 🟡 P1级 — 准入控制
|
||
|
||
**查询终端用户是否在线** `existOnlineUser`
|
||
- URL: `http://{IP}:30098/access/onlineUser?act=existOnlineUser`
|
||
- 参数：`username` + `strdevip`
|
||
- 返回：`data: 0`（不在线）/ `1`（在线）
|
||
- **可精确判断某员工在某IP是否当前在线**
|
||
|
||
**查询用户在线列表** `onlineUserList`
|
||
- URL: `http://{IP}:30098/onlineUser?act=onlineUserList`
|
||
- 按时间范围查在线用户（间隔不超过3个月）
|
||
|
||
**强制下线** `forcedOffline`
|
||
- URL: `http://{IP}:30098/nac?act=forcedOffline`
|
||
- ⚠️ 高危操作！将终端从网络强制断开
|
||
- 与火绒的`netctrl`隔离功能类似但机制不同
|
||
|
||
**终端入网日志** `queryAccessLog`
|
||
- URL: `http://{IP}:30098/access/queryInfo?act=queryAccessLog`
|
||
- 可查看终端入网历史
|
||
|
||
#### 1.3.4 🟡 P1级 — 终端操作
|
||
|
||
**通知助手弹出消息** `noticeAgentMsg`
|
||
- URL: `http://{IP}:30098/terminal?act=noticeAgentMsg`
|
||
- 向终端安全助手推送弹窗消息
|
||
|
||
**设备远程唤醒** `remoteWakeUp`
|
||
- URL: `http://{IP}:30098/terminal?act=remoteWakeUp`
|
||
- 通过IP+MAC唤醒关机/休眠的终端
|
||
|
||
**补丁安装审计** `queryClientPatchAuditInfo`
|
||
- URL: `http://{IP}:30098/terminalaudit?act=queryClientPatchAuditInfo`
|
||
- 查看终端补丁安装状态（补丁名/KB号/安装时间/是否成功）
|
||
|
||
**查询助手安装率** `queryAgentInstallRate`
|
||
- URL: `http://{IP}:30098/terminal?act=queryAgentInstallRate`
|
||
- 返回Windows/macOS分别的安装率
|
||
|
||
**查询终端补丁安装率** `queryAllMspatchInstallRate`
|
||
- URL: `http://{IP}:30098/terminal?act=queryAllMspatchInstallRate`
|
||
- 返回全公司补丁安装率
|
||
|
||
#### 1.3.5 🟢 P2级 — 审计与安全
|
||
|
||
**通用审计信息查询** `queryCommonAuditInfo`
|
||
- URL: `http://{IP}:30098/auditinfo?act=queryCommonAuditInfo`
|
||
- 支持所有通用审计类型（文件操作/进程控制等）
|
||
|
||
**仿冒设备查询** `queryCounterfeitList`
|
||
- URL: `http://{IP}:30098/access/queryInfo?act=queryCounterfeitList`
|
||
- 查询准入仿冒信息（发现仿冒设备告警）
|
||
|
||
**屏幕录像审计** `listScreenAuditInfo`
|
||
- URL: `http://{IP}:30098/auditinfo?act=listScreenAuditInfo`
|
||
- 获取终端屏幕录像审计信息
|
||
|
||
**Syslog推送**
|
||
- 联软支持将审计日志通过Syslog推送到第三方平台（UDP 514）
|
||
- 吞吐量：约100条/秒
|
||
- 支持：文件读写审计、非授权外联审计、打印审计、漏洞审计、进程检测审计、安全U盘审计
|
||
|
||
---
|
||
|
||
## 二、与火绒的能力对比
|
||
|
||
### 2.1 功能矩阵对比
|
||
|
||
| 能力维度 | 火绒 | 联软 | 对IT服务台价值 |
|
||
|---------|------|------|--------------|
|
||
| **员工↔终端映射** | ❌ 只有computer_name | ✅ **strusername+struserdes** | 🔴 **最关键差异** |
|
||
| **终端基本信息** | ✅ `_list`（client_id/name/ip/mac/在线） | ✅ `queryDevByParams`（更丰富） | 相当 |
|
||
| **终端详细信息** | ✅ `_info2`（硬件+软件+资产+网络） | ✅ `getDevAllInfo`（**更详细**：含磁盘使用率/显示器/内存条详情） | 联软胜 |
|
||
| **病毒事件** | ✅ `_virus_events`（病毒统计+处理状态） | ❌ 无专门接口 | **火绒独有** |
|
||
| **高危漏洞** | ✅ `_leak`（漏洞等级+详情） | ✅ `queryClientPatchAuditInfo`（补丁审计） | 火绒更直观 |
|
||
| **终端隔离** | ✅ `netctrl`（网络隔离/解除） | ✅ `forcedOffline`（强制下线） | 火绒更精细（可隔离+解除） |
|
||
| **远程扫描** | ✅ `_create`（快速/全盘/自定义扫描） | ❌ 无 | **火绒独有** |
|
||
| **远程唤醒** | ❌ 无 | ✅ `remoteWakeUp` | **联软独有** |
|
||
| **消息推送** | ✅ `_create`(message) | ✅ `noticeAgentMsg` | 相当 |
|
||
| **准入控制** | ❌ 无 | ✅ `existOnlineUser`+`forcedOffline`+`queryAccessLog` | **联软独有** |
|
||
| **软件管理** | ✅ `_search`（软件安装率/版本分布） | ✅ `querysoftwarebydev`（按设备查软件） | 联软更实用 |
|
||
| **组织架构** | ❌ 无 | ✅ SCIM同步+部门/用户查询 | **联软独有** |
|
||
| **审计日志** | ❌ 无 | ✅ Syslog推送+通用审计查询 | **联软独有** |
|
||
| **仿冒设备** | ❌ 无 | ✅ `queryCounterfeitList` | **联软独有** |
|
||
| **审批流程** | ❌ 无 | ✅ 完整审批流程API | 低价值 |
|
||
| **屏幕录像** | ❌ 无 | ✅ 审计信息+图片导出 | 低价值 |
|
||
|
||
### 2.2 核心结论
|
||
|
||
> **火绒 = 安全防护**（杀毒+漏洞+隔离+扫描）
|
||
> **联软 = 终端管理**（准入+硬件+软件+映射+审计）
|
||
>
|
||
> **两者高度互补，不存在替代关系，应双系统集成！**
|
||
|
||
---
|
||
|
||
## 三、产品维度分析
|
||
|
||
### 3.1 联软独有高价值场景
|
||
|
||
| 场景 | 联软API | 用户体验 |
|
||
|------|---------|---------|
|
||
| **员工报修「电脑卡/慢」** | `getDevAllInfo` | 坐席直接看到磁盘使用率34%→11%、内存16GB/32GB、CPU负载，一秒定位瓶颈 |
|
||
| **员工报修「网络连不上」** | `existOnlineUser` + `queryAccessLog` | 坐席查看该员工终端当前是否准入在线、最近入网记录、是否被策略阻断 |
|
||
| **员工报修「电脑开不了机」** | `remoteWakeUp` | 坐席远程唤醒终端（WOL），员工无需等待IT到现场 |
|
||
| **员工问「我装了什么软件」** | `querysoftwarebydev` | 输入员工账号→自动列出已安装软件+版本+安装日期 |
|
||
| **IT查「谁用了这个IP」** | `queryDevByParams` | 按IP反查使用人、部门、MAC，网络冲突排查利器 |
|
||
| **安全巡检「补丁安装率」** | `queryAllMspatchInstallRate` + `queryClientPatchAuditInfo` | 管理后台展示补丁合规率 |
|
||
|
||
### 3.2 联软+火绒联合场景
|
||
|
||
| 场景 | 联软提供 | 火绒提供 | 联合效果 |
|
||
|------|---------|---------|---------|
|
||
| **坐席打开会话** | 员工→终端映射（strusername） | 终端安全画像（漏洞+病毒） | 一键获知「谁的电脑+什么安全状态」 |
|
||
| **安全事件响应** | `forcedOffline`快速断网 | `netctrl`精细隔离 | 双重保障：先联软断网→火绒隔离 |
|
||
| **磁盘满排查** | `getDevAllInfo`磁盘使用率 | `_info2`软件列表 | 联软看磁盘空间→火绒查大文件软件 |
|
||
| **补丁管理** | `queryClientPatchAuditInfo`安装审计 | `_leak`高危漏洞列表 | 联软看补丁安装结果→火绒看漏洞风险 |
|
||
| **终端画像** | 硬件详情+准入状态+资产号 | 安全评分+病毒事件 | 360°终端全景 |
|
||
|
||
### 3.3 集成功能规划（按优先级）
|
||
|
||
#### P0 — 核心查询+映射（阶段三 3A-3B）
|
||
|
||
| 功能 | 用户侧效果 | 涉及API |
|
||
|------|-----------|---------|
|
||
| **员工→终端映射服务** | 输入员工账号→返回终端列表（IP/MAC/计算机名/部门/在线状态） | `queryDevByParams` + `getUserInfoByAccount` |
|
||
| **终端详细信息卡片** | 坐席打开会话→自动展示该员工终端的完整硬件+软件信息 | `getDevAllInfo` + `querysoftwarebydev` |
|
||
| **终端在线状态查询** | AI Wingman自动检测→提示终端是否在线 | `existOnlineUser` |
|
||
|
||
#### P1 — 操作+控制（阶段三 3C + 阶段四）
|
||
|
||
| 功能 | 用户侧效果 | 涉及API |
|
||
|------|-----------|---------|
|
||
| **远程唤醒终端** | 坐席一键唤醒休眠/关机的终端 | `remoteWakeUp` |
|
||
| **推送助手消息** | 向员工终端弹窗通知（如「请重启电脑安装补丁」） | `noticeAgentMsg` |
|
||
| **强制下线** | 安全事件→坐席一键断网（与火绒隔离互为补充） | `forcedOffline` |
|
||
| **补丁审计查询** | 查看某终端补丁安装状态 | `queryClientPatchAuditInfo` |
|
||
| **入网日志查询** | 排查网络问题时查看终端入网历史 | `queryAccessLog` |
|
||
|
||
#### P2 — 管理与运营（阶段四 4B）
|
||
|
||
| 功能 | 用户侧效果 | 涉及API |
|
||
|------|-----------|---------|
|
||
| **助手安装率看板** | 管理后台展示公司安全助手安装率 | `queryAgentInstallRate` |
|
||
| **补丁合规率看板** | 管理后台展示补丁安装率 | `queryAllMspatchInstallRate` |
|
||
| **仿冒设备告警** | 发现仿冒设备自动推送告警 | `queryCounterfeitList` |
|
||
| **Syslog审计日志** | 联软审计事件实时推送到IT服务台 | Syslog接口 |
|
||
|
||
---
|
||
|
||
## 四、开发维度分析
|
||
|
||
### 4.1 后端模块设计
|
||
|
||
```
|
||
backend/app/
|
||
├── integrations/
|
||
│ ├── __init__.py
|
||
│ ├── base.py # 集成基类
|
||
│ ├── huorong/ # 火绒集成（已有设计）
|
||
│ │ ├── client.py
|
||
│ │ ├── config.py
|
||
│ │ ├── models.py
|
||
│ │ ├── cache.py
|
||
│ │ └── exceptions.py
|
||
│ ├── leagsoft/ # 联软集成模块
|
||
│ │ ├── __init__.py
|
||
│ │ ├── client.py # 联软API客户端（认证+请求）
|
||
│ │ ├── config.py # 配置（BaseUrl/账号密码/Token）
|
||
│ │ ├── models.py # 数据模型（Pydantic）
|
||
│ │ ├── cache.py # 缓存策略
|
||
│ │ └── exceptions.py # 自定义异常
|
||
│ └── mapping/ # 🆕 统一映射服务
|
||
│ ├── __init__.py
|
||
│ ├── service.py # 员工→终端映射核心逻辑
|
||
│ └── models.py # 映射数据模型
|
||
├── api/
|
||
│ └── integrations.py # 集成API路由
|
||
└── services/
|
||
└── integration_service.py # 集成业务逻辑
|
||
```
|
||
|
||
### 4.2 认证实现
|
||
|
||
联软推荐使用**一次性Token模式**（安全性最高）：
|
||
|
||
```python
|
||
import httpx
|
||
from datetime import datetime, timedelta
|
||
|
||
class LeagsoftClient:
|
||
"""联软API客户端"""
|
||
|
||
def __init__(self, base_url: str, api_account: str, api_password: str):
|
||
self.base_url = base_url # 如 http://leagsoft.oa.servyou-it.com:30098
|
||
self.api_account = api_account
|
||
self.api_password = api_password
|
||
self._token: str | None = None
|
||
self._token_expire: datetime | None = None
|
||
|
||
async def _ensure_token(self) -> str:
|
||
"""
|
||
确保token有效，过期则重新获取
|
||
- 联软token默认30分钟有效
|
||
- 提前5分钟刷新，避免临界过期
|
||
"""
|
||
if self._token and self._token_expire and datetime.now() < self._token_expire - timedelta(minutes=5):
|
||
return self._token
|
||
|
||
async with httpx.AsyncClient(timeout=10) as client:
|
||
resp = await client.get(f"{self.base_url}/token", params={"act": "getToken"})
|
||
data = resp.json()
|
||
# 解析token（具体字段需根据实际返回确认）
|
||
self._token = data.get("token", "")
|
||
self._token_expire = datetime.now() + timedelta(minutes=25) # 保守25分钟
|
||
|
||
return self._token
|
||
|
||
async def query_dev_by_params(self, username: str = None, devip: str = None,
|
||
mac: str = None, devname: str = None) -> list[dict]:
|
||
"""
|
||
查询终端设备
|
||
- username: 员工账号（映射核心参数）
|
||
- devip: 终端IP
|
||
- mac: MAC地址
|
||
- devname: 计算机名
|
||
- 支持多条件组合查询
|
||
"""
|
||
token = await self._ensure_token()
|
||
params = {"act": "queryDevByParams", "token": token}
|
||
form_data = {}
|
||
if username:
|
||
form_data["strusername"] = username
|
||
if devip:
|
||
form_data["strdevip"] = devip
|
||
if mac:
|
||
form_data["strmac"] = mac
|
||
if devname:
|
||
form_data["strdevname"] = devname
|
||
|
||
async with httpx.AsyncClient(timeout=10) as client:
|
||
resp = await client.post(
|
||
f"{self.base_url}/terminal",
|
||
params=params,
|
||
data=form_data
|
||
)
|
||
result = resp.json()
|
||
|
||
if result.get("status") != "SUCCESS":
|
||
raise LeagsoftAPIError(result.get("msg", "未知错误"))
|
||
|
||
return result.get("rows", [])
|
||
```
|
||
|
||
### 4.3 缓存策略
|
||
|
||
| 数据类型 | 缓存时间 | 理由 |
|
||
|---------|---------|------|
|
||
| 终端基本信息 (`queryDevByParams`) | 5分钟 | 终端上下线变化较频繁 |
|
||
| 终端详细信息 (`getDevAllInfo`) | 30分钟 | 硬件信息极少变化 |
|
||
| 软件安装信息 (`querysoftwarebydev`) | 1小时 | 软件安装变化慢 |
|
||
| 在线状态 (`existOnlineUser`) | 1分钟 | 需较实时 |
|
||
| 组织架构 (`getAllOrgInfo`) | 24小时 | 组织变更极少 |
|
||
| 用户信息 (`getUserInfoByAccount`) | 24小时 | 用户信息变更少 |
|
||
| 补丁审计 (`queryClientPatchAuditInfo`) | 1小时 | 补丁安装周期为天级 |
|
||
|
||
### 4.4 员工→终端映射方案（重大升级）
|
||
|
||
#### 原方案回顾
|
||
|
||
之前火绒集成分析中，因火绒API只有`computer_name`无员工账号，提出了三种映射方案：
|
||
|
||
| 方案 | 原理 | 缺点 |
|
||
|------|------|------|
|
||
| A. computer_name匹配 | 依赖命名规范 | 不稳定 |
|
||
| B. eHR+火绒IP交叉匹配 | eHR取IP→火绒查终端 | 需eHR接口，IP可能变化 |
|
||
| C. 手动绑定 | 坐席手动关联 | 运营成本高 |
|
||
|
||
#### 新方案：联软直接映射（方案D）⭐推荐
|
||
|
||
**核心发现**：联软 `queryDevByParams` 接口直接返回 `strusername`（员工账号）和 `struserdes`（员工姓名），且总部员工必须安装联软安全助手，因此**联软拥有最准确的员工↔终端映射数据**。
|
||
|
||
```
|
||
联软 queryDevByParams(strusername="songxian")
|
||
↓ 返回
|
||
[
|
||
{strdevname: "DESKTOP-SX001", strdevip: "10.8.11.21", strmac: "0C:C4:7A:0C:75:B5",
|
||
strusername: "songxian", struserdes: "宋献", strdeptname: "IT部", istatus: "在线"},
|
||
{strdevname: "DESKTOP-SX002", strdevip: "10.8.11.22", strmac: "0C:C4:7A:0C:75:B6",
|
||
strusername: "songxian", struserdes: "宋献", strdeptname: "IT部", istatus: "离线"}
|
||
]
|
||
```
|
||
|
||
#### 映射架构（多源融合）
|
||
|
||
```
|
||
┌──────────────────────────────────────────┐
|
||
│ IT服务台 统一映射服务 │
|
||
│ (mapping/service.py) │
|
||
└───────┬──────────┬──────────┬────────────┘
|
||
│ │ │
|
||
┌────────▼──┐ ┌────▼─────┐ ┌─▼──────────┐
|
||
│ 联软 │ │ aTrust │ │ eHR │
|
||
│ (主源) │ │ (VPN源) │ │ (辅助源) │
|
||
└───────────┘ └──────────┘ └────────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
总部终端映射 远程办公映射 人员基础信息
|
||
(最准确) (VPN连接时准确) (无终端信息)
|
||
```
|
||
|
||
**映射优先级策略**：
|
||
|
||
| 场景 | 数据源 | 匹配键 | 准确度 | 说明 |
|
||
|------|--------|--------|--------|------|
|
||
| 总部办公终端 | **联软** | `strusername` = 员工账号 | ⭐⭐⭐⭐⭐ | 最准确，安全助手必装 |
|
||
| 外网VPN终端 | **aTrust** | VPN登录账号 = 员工账号 | ⭐⭐⭐⭐⭐ | 远程办公时最准确 |
|
||
| eHR补充 | eHR | 员工工号 = 员工账号 | ⭐⭐⭐ | 无终端映射，仅人员信息 |
|
||
| 火绒安全数据 | 火绒 | 通过联软映射获得`client_id`→查安全 | ⭐⭐⭐⭐ | 依赖联软映射做桥梁 |
|
||
|
||
**映射实现**：
|
||
|
||
```python
|
||
class TerminalMappingService:
|
||
"""
|
||
统一员工→终端映射服务
|
||
优先级: 联软(主) > aTrust(VPN) > 手动绑定
|
||
"""
|
||
|
||
async def get_employee_terminals(self, employee_id: str) -> list[TerminalInfo]:
|
||
"""
|
||
根据员工ID获取关联的终端列表
|
||
|
||
策略:
|
||
1. 先查联软（最准确，覆盖总部终端）
|
||
2. 联软无结果 → 查aTrust（覆盖VPN终端）
|
||
3. 都无结果 → 返回空，标记为「未发现终端」
|
||
"""
|
||
# Step 1: 联软查询
|
||
leagsoft_terminals = await self.leagsoft_client.query_dev_by_params(
|
||
username=employee_id
|
||
)
|
||
if leagsoft_terminals:
|
||
return [self._parse_leagsoft_terminal(t) for t in leagsoft_terminals]
|
||
|
||
# Step 2: aTrust查询（后续实现）
|
||
# atrust_terminals = await self.atrust_client.query_user_devices(employee_id)
|
||
# if atrust_terminals:
|
||
# return atrust_terminals
|
||
|
||
# Step 3: 无结果
|
||
return []
|
||
|
||
async def get_terminal_security(self, employee_id: str) -> TerminalSecurityInfo:
|
||
"""
|
||
获取员工终端的安全信息（跨系统聚合）
|
||
|
||
流程:
|
||
1. 联软获取终端列表 → 得到strdevip/strmac
|
||
2. 用strdevip去火绒查安全状态
|
||
3. 聚合联软硬件+火绒安全 → 完整画像
|
||
"""
|
||
# Step 1: 联软获取终端
|
||
terminals = await self.get_employee_terminals(employee_id)
|
||
if not terminals:
|
||
return TerminalSecurityInfo(available=False, reason="未发现关联终端")
|
||
|
||
terminal = terminals[0] # 取主终端
|
||
|
||
# Step 2: 火绒查安全（用IP或computer_name匹配）
|
||
huorong_info = await self.huorong_client.query_by_ip(terminal.ip)
|
||
|
||
# Step 3: 聚合
|
||
return TerminalSecurityInfo(
|
||
terminal=terminal, # 联软硬件信息
|
||
security=huorong_info, # 火绒安全信息
|
||
available=True
|
||
)
|
||
```
|
||
|
||
### 4.5 前端集成设计
|
||
|
||
#### 坐席端新增
|
||
|
||
```
|
||
坐席工作台
|
||
└── 右侧面板
|
||
└── 「终端信息」标签页（替代原「终端安全」，合并联软+火绒）
|
||
├── 终端概要卡片（联软数据）
|
||
│ ├── 在线状态 🟢/🔴 + IP地址
|
||
│ ├── 计算机名 + 员工账号
|
||
│ ├── 操作系统版本
|
||
│ ├── 硬件概要（CPU/内存/磁盘使用率）
|
||
│ ├── 设备资产号
|
||
│ └── 安全助手版本
|
||
├── 安全状态卡片（火绒数据）
|
||
│ ├── 安全评分
|
||
│ ├── 🔴 高危漏洞 (N个)
|
||
│ ├── 🟡 未处理病毒事件 (N个)
|
||
│ └── 🟢 安全状态正常
|
||
├── 软件列表（联软数据）
|
||
│ └── 已安装软件 + 版本 + 安装日期
|
||
└── 快速操作
|
||
├── 📡 远程唤醒 (联软)
|
||
├── 📢 推送消息 (联软/火绒)
|
||
├── 🛡️ 快速扫描 (火绒)
|
||
├── 🔒 强制下线 (联软) / 隔离终端 (火绒)
|
||
└── 🔓 解除隔离 (火绒)
|
||
```
|
||
|
||
### 4.6 开发风险与应对
|
||
|
||
| 风险 | 影响 | 概率 | 应对措施 |
|
||
|------|------|------|---------|
|
||
| 联软API账户/密码未申请 | 无法调用任何接口 | 中 | 提前联系信息安全/终端安全团队 |
|
||
| 内网地址不通 | 开发环境无法调试 | 中 | 需VPN或开发机部署在内网 |
|
||
| Token过期处理 | 长时间运行后API调用失败 | 中 | 实现自动刷新token，提前5分钟续期 |
|
||
| IP白名单未配置 | 返回INVALID | 中 | 确认部署服务器IP加入白名单 |
|
||
| API字段名不一致 | 部分接口返回字段与文档不符 | 低 | 先用Postman验证，编写适配层 |
|
||
| 联软版本差异 | API端点可能不存在 | 低 | 确认当前版本是否为202210SP |
|
||
| 查询数据量过大 | 部分接口有数据量限制（仿冒设备默认1万条） | 低 | 分页查询+限制时间范围 |
|
||
|
||
---
|
||
|
||
## 五、安全维度分析
|
||
|
||
### 5.1 认证安全
|
||
|
||
| 风险项 | 等级 | 说明 | 建议 |
|
||
|--------|------|------|------|
|
||
| API账户密码泄露 | **严重** | 泄露后可调用所有联软API，包括强制下线 | 密码存环境变量，**禁止**写入代码 |
|
||
| Token泄露 | 高 | Token有效期内可被冒用 | 使用HTTPS（如有）；Token存储在内存不落盘 |
|
||
| IP白名单过宽 | 中 | 白名单IP范围过大增加攻击面 | 仅添加必要的服务器IP |
|
||
|
||
**认证方式建议**：
|
||
|
||
| 场景 | 推荐认证方式 | 理由 |
|
||
|------|------------|------|
|
||
| 内网服务器间调用 | IP白名单 + 一次性Token | 安全性最高 |
|
||
| 开发调试 | IP白名单 + 用户名密码 | 方便调试 |
|
||
| 生产环境 | **三种全部启用** | 纵深防御 |
|
||
|
||
### 5.2 操作安全
|
||
|
||
| 操作 | 风险等级 | 安全要求 |
|
||
|------|---------|---------|
|
||
| 查询终端设备 (`queryDevByParams`) | 🟢 低 | 无特殊要求 |
|
||
| 查询终端详情 (`getDevAllInfo`) | 🟢 低 | 无特殊要求 |
|
||
| 查询在线状态 (`existOnlineUser`) | 🟢 低 | 无特殊要求 |
|
||
| 推送助手消息 (`noticeAgentMsg`) | 🟡 中 | 记录审计日志；限制频率（同终端5分钟1条） |
|
||
| 远程唤醒 (`remoteWakeUp`) | 🟡 中 | 记录审计日志；仅坐席可操作 |
|
||
| **强制下线** (`forcedOffline`) | 🔴 **高** | **必须**二次确认 + 审计日志 + 仅admin角色 |
|
||
| Syslog推送 | 🟢 低 | 只读，无风险 |
|
||
|
||
**强制下线 vs 火绒隔离的区别**：
|
||
|
||
| 维度 | 联软强制下线 | 火绒网络隔离 |
|
||
|------|-----------|-----------|
|
||
| 机制 | 准入控制断网（802.1X） | 终端agent执行隔离 |
|
||
| 彻底性 | ⭐⭐⭐⭐⭐ 非常彻底（交换机层面断网） | ⭐⭐⭐⭐ 较彻底（终端层面断网） |
|
||
| 恢复 | 需重新认证入网 | 调用API即可解除 |
|
||
| 影响范围 | 该终端所有网络 | 可配置例外（如仅隔离外网） |
|
||
| 推荐场景 | 确认中毒/仿冒，紧急切断 | 可疑行为，需隔离观察 |
|
||
|
||
### 5.3 数据安全
|
||
|
||
| 风险项 | 说明 | 建议 |
|
||
|--------|------|------|
|
||
| 员工账号信息 | 联软返回员工账号/姓名/邮箱/电话 | H5用户端不展示；坐席端仅展示必要信息 |
|
||
| 终端敏感信息 | MAC/IP/序列号等 | 同火绒策略：坐席端可见，用户端不可见 |
|
||
| 硬件详情 | 包含主板序列号等资产信息 | 后端过滤后再传前端，不暴露内部序列号 |
|
||
| 组织架构 | 全量部门+用户数据 | 仅同步必要字段，不存储完整组织架构 |
|
||
|
||
---
|
||
|
||
## 六、aTrust集成方案
|
||
|
||
> ✅ aTrust OpenAPI V3文档已获取并完成分析（2026-06-11），详见 `docs/aTrust零信任系统集成分析.md`
|
||
|
||
### 6.1 系统信息
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 产品 | 深信服aTrust零信任访问控制系统 |
|
||
| API版本 | OpenAPI V3（适用于≥2.4.10版本） |
|
||
| 端点数 | **104个**（10大类） |
|
||
| 认证方式 | HMAC-SHA256签名（4个必填Header: x-ca-sign/key/timestamp/nonce） |
|
||
| 默认端口 | 4433（HTTPS） |
|
||
| IP白名单 | 支持 |
|
||
|
||
### 6.2 核心P0接口
|
||
|
||
| 接口 | 路径 | 方法 | 核心价值 |
|
||
|------|------|------|---------|
|
||
| **查询在线用户** | /api/v1/monitor/getUserStatus | GET | VPN在线状态+remoteIp+vips(虚拟IP)+os+browser |
|
||
| **查询全量终端** | /api/v1/device/queryAll | POST | 按绑定用户查询终端（bindUserList过滤） |
|
||
| **查询单个终端** | /api/v1/device/query | GET | 终端详情+bindUsers(绑定用户列表)+macList |
|
||
|
||
### 6.3 核心P1接口
|
||
|
||
| 接口 | 路径 | 方法 | 安全等级 |
|
||
|------|------|------|---------|
|
||
| **踢出在线用户** | /api/v1/monitor/kickoutUsers | POST | 🔴 高危（需二次确认+审计） |
|
||
| **终端绑定用户** | /api/v1/device/assignUser | POST | 🟡 中 |
|
||
| **查询用户详情** | /api/v3/user/queryByName | GET | 🟢 低 |
|
||
|
||
### 6.4 aTrust映射字段
|
||
|
||
| 映射路径 | 字段 | 说明 |
|
||
|---------|------|------|
|
||
| **在线用户→员工** | `name`（用户名） | 如果与公司域账号一致，直接映射employee_id |
|
||
| **在线用户→虚拟IP** | `vips[].ip` | VPN分配的内网IP，可用于火绒交叉匹配 |
|
||
| **终端→绑定用户** | `bindUsers[].bindUser` | 终端绑定的用户名 |
|
||
| **用户→外部ID** | `externalId` | **可设置为工号，实现直接映射** |
|
||
| **终端→MAC** | `macList` | MAC地址列表，与联软交叉匹配 |
|
||
|
||
### 6.5 与联软的互补关系
|
||
|
||
| 能力 | 联软（内网主源） | aTrust（VPN源） | 互补效果 |
|
||
|------|---------------|---------------|---------|
|
||
| 内网终端映射 | ⭐⭐⭐⭐⭐ strusername | ⭐⭐⭐ 部分覆盖 | 联软主导 |
|
||
| 远程/VPN终端 | ⚠️ 可能未覆盖 | ⭐⭐⭐⭐⭐ 核心覆盖 | aTrust补全 |
|
||
| VPN会话数据 | ❌ 无 | ✅ 唯一数据源 | 不可替代 |
|
||
| 踢出能力 | forcedOffline(准入下线) | kickoutUsers(VPN踢出) | 双通道 |
|
||
| 终端授信 | ❌ 无 | ✅ trusted字段 | aTrust独有 |
|
||
|
||
### 6.6 集成优先级
|
||
|
||
aTrust集成为**P1优先级**（联软P0之后），因为：
|
||
1. VPN连接问题是IT服务台高频场景
|
||
2. aTrust的`vips`虚拟IP可用于火绒交叉匹配，补全远程终端安全画像
|
||
3. aTrust API文档已获取，可直接开发
|
||
4. 104个端点中仅需3-5个P0接口，开发量可控
|
||
|
||
---
|
||
|
||
## 七、三系统集成总览
|
||
|
||
### 7.1 系统定位
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ IT智能服务台 │
|
||
│ （统一集成层） │
|
||
│ │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||
│ │ 联软 │ │ 火绒 │ │ aTrust │ │
|
||
│ │ 终端管理 │ │ 终端安全 │ │ 远程接入 │ │
|
||
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │
|
||
│ │ │ │ │
|
||
│ 员工↔终端映射 安全态势+隔离 VPN状态+远程IP │
|
||
│ 硬件+软件详情 病毒+漏洞+扫描 VPN连接审计 │
|
||
│ 准入+远程唤醒 网络隔离/解除 认证状态 │
|
||
│ 补丁+审计日志 软件合规统计 虚拟IP分配 │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 7.2 集成优先级与排程
|
||
|
||
| 阶段 | 系统 | 功能 | 预计周期 | 前置条件 |
|
||
|------|------|------|---------|---------|
|
||
| **P0** | 联软 | 员工→终端映射 + 终端详情查询 | ~2周 | 联软API账户+白名单 |
|
||
| **P0** | 火绒 | 终端安全画像 + 漏洞/病毒查询 | ~2周 | 火绒AccessKey |
|
||
| **P1** | 联软 | 远程唤醒 + 消息推送 + 准入查询 | ~1周 | P0已完成 |
|
||
| **P1** | 火绒 | 远程扫描 + 隔离/解除 | ~1周 | P0已完成 |
|
||
| **P1** | aTrust | VPN状态 + 远程终端映射 | ~2周 | aTrust API文档 |
|
||
| **P2** | 联软+火绒 | 管理后台安全态势看板 | ~1周 | P0+P1已完成 |
|
||
| **P2** | 联软 | Syslog审计日志对接 | ~1周 | 联软Syslog配置 |
|
||
|
||
### 7.3 统一数据模型
|
||
|
||
```python
|
||
class UnifiedTerminalInfo:
|
||
"""统一终端信息模型（聚合联软+火绒+aTrust）"""
|
||
|
||
# 基础标识（联软提供）
|
||
computer_name: str # 计算机名
|
||
ip: str # IP地址
|
||
mac: str # MAC地址
|
||
employee_id: str # 使用人账号
|
||
employee_name: str # 使用人姓名
|
||
department: str # 所属部门
|
||
|
||
# 在线状态（联软+aTrust）
|
||
is_online: bool # 是否在线
|
||
online_source: str # "leagsoft" | "atrust" | "offline"
|
||
last_online_time: str # 最后在线时间
|
||
|
||
# 硬件信息（联软 getDevAllInfo）
|
||
os_version: str # 操作系统版本
|
||
cpu: str # CPU型号
|
||
memory_gb: int # 内存(GB)
|
||
disk_total_gb: float # 磁盘总量(GB)
|
||
disk_usage_pct: float # 磁盘使用率(%)
|
||
|
||
# 安全信息（火绒提供）
|
||
security_score: int | None # 安全评分
|
||
high_risk_leaks: int | None # 高危漏洞数
|
||
uncleaned_virus: int | None # 未处理病毒数
|
||
last_scan_time: str | None # 最近扫描时间
|
||
|
||
# 准入信息（联软提供）
|
||
agent_version: str | None # 安全助手版本
|
||
patch_install_rate: float | None # 补丁安装率
|
||
|
||
# VPN信息（aTrust提供）
|
||
vpn_online: bool | None # VPN是否在线
|
||
vpn_virtual_ip: str | None # VPN虚拟IP
|
||
vpn_last_connect: str | None # 最近VPN连接时间
|
||
```
|
||
|
||
---
|
||
|
||
## 八、对接前准备清单
|
||
|
||
### 联软
|
||
|
||
#### 必须完成（阻塞性）
|
||
|
||
- [ ] **申请API账户**：联系终端安全团队，获取`ApiAccount` + `ApiPassword`
|
||
- [ ] **配置IP白名单**：将IT服务台服务器IP加入联软白名单
|
||
- [ ] **确认网络可达**：确认开发/部署服务器可访问联软系统（端口30098）
|
||
- [ ] **确认联软版本**：确认当前版本是否为202210SP，API文档是否匹配
|
||
|
||
#### 建议完成（非阻塞）
|
||
|
||
- [ ] **确认员工账号映射**：验证联软中`strusername`字段是否为公司企微/域账号
|
||
- [ ] **确认数据量级**：了解联软管理的终端数量，评估查询性能
|
||
- [ ] **确认安全助手安装率**：了解公司终端安全助手安装覆盖率
|
||
- [ ] **准备测试终端**：准备1-2台测试终端用于开发调试
|
||
|
||
### aTrust
|
||
|
||
- [ ] **获取API文档**：联系网络/信息安全团队获取aTrust API文档
|
||
- [ ] **确认认证方式**：了解aTrust API认证机制
|
||
- [ ] **确认映射数据格式**：了解aTrust中员工↔终端的映射字段
|
||
|
||
---
|
||
|
||
## 九、总结
|
||
|
||
### 9.1 核心结论
|
||
|
||
1. **联软是终端映射的金钥匙**：`strusername`字段直接打通员工→终端的映射，这是火绒和eHR都无法提供的关键能力
|
||
2. **联软+火绒高度互补**：联软管「终端画像+准入」，火绒管「安全态势+隔离」，无替代关系
|
||
3. **aTrust补全远程办公**：联软覆盖内网终端，aTrust覆盖VPN终端，两者结合实现100%覆盖
|
||
4. **三系统联合映射是最佳方案**：联软(主)+aTrust(VPN)+eHR(辅助)，取代之前推荐的IP交叉匹配方案
|
||
5. **实现成本低**：联软API为标准HTTP+JSON，认证简单，无需安装agent
|
||
|
||
### 9.2 映射策略升级总结
|
||
|
||
| 维度 | 旧方案（仅火绒） | 新方案（三系统） |
|
||
|------|----------------|----------------|
|
||
| 映射准确度 | ⭐⭐⭐（IP交叉匹配） | ⭐⭐⭐⭐⭐（联软直接映射） |
|
||
| 覆盖范围 | 仅内网在线终端 | 内网+VPN全覆盖 |
|
||
| 实现复杂度 | 需eHR+火绒双接口 | 仅联软单接口 |
|
||
| 维护成本 | 高（IP变化需定期校验） | 低（联软实时更新） |
|
||
| 前置依赖 | eHR接口+火绒接口 | 联软接口 |
|
||
|
||
### 9.3 一句话总结
|
||
|
||
> 联软是IT智能服务台打通「员工↔终端」映射的关键系统，与火绒形成「管理+安全」双引擎，加上aTrust补全远程办公，三系统集成将实现终端问题排查的360°全景视角。
|