simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
wecom_it_smart_desk/docs/联软终端安全系统集成分析.md
T

798 lines
36 KiB
Markdown
Raw Permalink Normal View History

chore: initial baseline with P0-safety .gitignore
2026-06-14 16:49:18 +08:00
# 联软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°全景视角。
Reference in New Issue Copy Permalink