simon/wecom_it_smart_desk

Fork 0

Files

T

Simon 63262292d7 chore: initial baseline with P0-safety .gitignore

2026-06-14 16:51:56 +08:00

34 KiB

Raw Blame History

aTrust零信任访问控制系统 — 集成分析

分析日期：2026-06-11 | 文档版本：V1.1 | 基于aTrust OpenAPI V3官方接口文档（docx版，适用于≥2.4.10版本）

1. 系统概述

1.1 产品定位

深信服aTrust是零信任访问控制系统（Zero Trust Network Access, ZTNA），替代传统VPN。员工远程办公时通过aTrust接入内网，系统基于身份认证+终端授信+最小权限原则进行访问控制。

关键事实：总部员工必须安装联软安全助手，远程办公通过aTrust连入内网。这两个系统分别覆盖了内网和VPN两种接入场景的终端。

1.2 与IT服务台的关系

场景	aTrust的角色
员工远程报修	坐席需要知道员工是否通过VPN在线、VPN IP地址
终端排查	查询VPN会话状态、接入方式、虚拟IP
安全应急	紧急踢出可疑VPN会话、断开远程连接
终端映射	获取远程办公员工的终端信息（联软可能未覆盖的VPN终端）

2. API概览

2.1 端点统计

API模块	端点数	与IT服务台相关度
在线监控	2	🔴 P0
用户管理	26	🟡 P1
组织架构管理	18	⚪ P2
角色管理	19	⚪ P2
应用管理	14	⚪ P2
应用分类管理	8	⚪ P2
认证服务器管理	2	⚪ P2
用户目录管理	5	⚪ P2
终端管理	9	🔴 P0
安全中心管理	1	⚪ P2
合计	104	—

2.2 认证机制

项目	说明
算法	HMAC-SHA256
4个必填Header	`x-ca-sign`（签名值）、`x-ca-key`（API ID）、`x-ca-timestamp`（10位秒级时间戳）、`x-ca-nonce`（UUID v4随机数）
签名密钥	`appId={API_ID}&appSecret={API_SECRET}&timestamp={ts}&nonce={nonce}`
签名串	`{pathname}?{sorted_query}&{compact_json_body}`
签名计算	`HMAC-SHA256(signing_key, signing_string)` → 64位十六进制
防重放	timestamp + nonce 组合
传输协议	必须HTTPS
IP白名单	支持配置接入IP限制
默认端口	4433
频率限制	8 QPS（所有接口共享8请求/秒）
实体并发	同一实体的操作必须串行调用，否则可能数据覆盖
时间校验	请求时间戳与服务器时间差>5分钟则拒绝
Python Demo	https://bbs.sangfor.com.cn/atrustdeveloper/openapiV3/openapi-demo_for_python.7z

签名计算示例

import hmac, hashlib, uuid, time, json

API_ID = "8165305"
API_SECRET = "aebd2e3c5ea2449aa2928c102f9db276"

# Step 1: 构建签名串
pathname = "/api/v1/monitor/getUserStatus"
query = "pageIndex=1&pageSize=20"  # key按ASCII排序
body = ""  # GET请求无body
sign_str = f"{pathname}?{query}" if query else pathname

# Step 2: 构建签名密钥
timestamp = str(int(time.time()))
nonce = str(uuid.uuid4())
sign_key = f"appId={API_ID}&appSecret={API_SECRET}&timestamp={timestamp}&nonce={nonce}"

# Step 3: HMAC-SHA256计算签名
signature = hmac.new(
    sign_key.encode('utf-8'),
    sign_str.encode('utf-8'),
    hashlib.sha256
).hexdigest()

# Step 4: 设置请求头
headers = {
    "x-ca-key": API_ID,
    "x-ca-sign": signature,
    "x-ca-timestamp": timestamp,
    "x-ca-nonce": nonce,
    "Content-Type": "application/json;charset=UTF-8"
}

2.3 响应格式

{
    "code": "OK",       // 成功="OK"（V3）/ 0（V1）；失败=错误码
    "msg": "请求成功",
    "traceId": "004c33070f4fa7b4",
    "data": { ... }
}

⚠️ 注意：V1接口（在线监控/终端管理）的 code 为数字（0=成功），V3接口（用户管理）的 code 为字符串（"OK"=成功）。

3. 核心接口详解

3.1 P0 — 查询在线用户

项目	说明
路径	`GET /api/v1/monitor/getUserStatus`
用途	查询当前通过aTrust在线的用户列表
价值	获取远程办公员工的VPN会话信息，包括接入IP和虚拟IP

请求参数

参数	必须	说明	示例
pageSize	是	每页大小，默认20	20
pageIndex	是	页码，从1开始	1
filter	否	过滤字段	`name`/`remoteIp`/`os`/`browser`/`vip`
searchValue	否	过滤搜索值	`张三`
sortBy	否	排序字段	`lastLoginTime`/`remoteIp`/`vip`
asc	否	1=升序，0=降序	1

响应字段（关键字段加⭐）

字段	类型	说明
`id`	string	会话ID（非用户ID，用于踢出操作）
`name` ⭐	string	用户名（登录名）
`displayName`	string	显示名
`userId`	string	用户UUID
`remoteIp` ⭐	string	接入IP（公网IP或"内网IP"）
`remoteIpLocation` ⭐	string	IP归属地（如"内网IP"=从内网接入）
`os`	string	操作系统
`browser`	string	接入方式（浏览器/客户端版本）
`lastLoginTime` ⭐	string	最后登录时间
`domain`	string	登录域
`userDirectoryName`	string	所属用户目录
`groupPath`	string	组织架构路径
`isTrusted` ⭐	number	终端授信状态：0=未授信/1=已授信

⚠️ 关于vips（虚拟IP）字段：在线文档（web版）的getUserStatus返回包含vips[].ip（VPN虚拟内网IP），但官方docx文档的响应示例中未展示此字段。可能原因：1) docx为早期版本示例，新版API已新增；2) 需特定配置或隧道应用才返回。对接时必须实际验证此字段是否存在。若存在，则vips[].ip是远程终端接入内网的虚拟IP，可用于火绒交叉匹配。

响应示例（官方docx版）

{
    "code": 0,
    "data": {
        "data": [{
            "id": "33100014",
            "name": "张三",
            "groupPath": "/",
            "os": "Windows 10",
            "browser": "Chrome/104.0.5112.102",
            "remoteIp": "175.9.142.2",
            "remoteIpLocation": "内网IP",
            "lastLoginTime": "2022-09-29 16:04:33",
            "domain": "local",
            "userId": "9f8146c0-8aeb-11ec-b30f-e50f6db6d9d6",
            "userDirectoryName": "本地用户目录",
            "isTrusted": 0,
            "displayName": "显示名"
        }],
        "count": 1,
        "pageSize": 20,
        "pageIndex": 1,
        "amount": 1,
        "onlineUser": 1
    },
    "msg": "请求成功"
}

业务解读

id：会话ID，踢出用户时需使用此ID（非userId），支持精准踢出单个会话
remoteIp：员工当前IP，remoteIpLocation="内网IP"表示从内网直接接入（非VPN）
isTrusted：终端是否已授信，0=未授信可能影响访问权限
name：用户登录名，如果与公司域账号一致，则可直接映射到 employee_id
同一用户可能在多个终端登录，返回多条记录（每条有不同id）

3.2 P0 — 查询全量终端信息

项目	说明
路径	`POST /api/v1/device/queryAll`
用途	批量查询aTrust纳管的终端设备
价值	按绑定用户查询终端列表，建立用户→终端映射

请求参数

参数	必须	类型	说明
bindUserList	否	object[]	按绑定用户过滤（v2.6.6+）
├─ userName	是	string	用户名
├─ userDirectoryName	是	string	用户目录名
onlineStatus	否	number	0=离线，1=在线
loginStatus	否	number	0=未接入，1=已接入
assetType	否	string	CYOD/BYOD/COPE/NONE
trusted	否	number	0=未授信，1=已授信
tagList	否	string[]	标签过滤
osList	否	string[]	OS过滤（Windows/macOS/统信UOS/麒麟Kylin/Android/iOS/HarmonyOS/iPadOS）
pageSize	否	number	最大1000
pageIndex	否	number	默认1

响应字段（关键字段加⭐）

字段	类型	说明
`externalId` ⭐	string	终端外部ID（唯一标识）
`macList` ⭐	string[]	MAC地址列表
`deviceName` ⭐	string	终端名称/主机名
`os`	string	操作系统
`deviceType`	string	PC/Mobile
`deviceBrand`	string	品牌
`assetType`	string	CYOD(企业)/BYOD(个人)/COPE(纳管)
`trusted` ⭐	number	授信状态：0=未授信/1=已授信
`onlineStatus` ⭐	number	在线状态
`loginStatus` ⭐	number	接入状态
`tagList`	string[]	标签列表
`windowsDomain`	string	Windows域控
`bindUsers` ⭐	object[]	绑定用户列表
├─ bindUser	string	绑定的用户名
├─ bindType	string	绑定方式：userSelfBind/adminBind/adminAdmit
├─ bindTime	string	绑定时间
`historyUsers`	object[]	历史登录用户列表
`lastLoginUser`	string	最后登录用户名
`displayName`	string	最后登录用户显示名
`clientVersion`	string	客户端版本
`lastLoginTime`	string	最后接入时间
`lastActiveTime`	string	最后活跃时间

⚠️ 重要：aTrust终端接口不返回IP地址，只有 lastNetworkZone（网络区域标识，如"内网IP"）。需通过在线监控接口（4.1.1）获取VPN IP。

3.3 P0 — 查询单个终端信息

项目	说明
路径	`GET /api/v1/device/query`
用途	按externalId或MAC查询单个终端详情
约束	externalId和mac互斥，不可同时传入

请求参数

参数	必须	说明
externalId	二选一	终端外部ID
mac	二选一	MAC地址（匹配多条则报错）

额外响应字段（相比queryAll，来自官方docx）

字段	类型	说明
`idleTime` ⭐	number	终端闲置时长（天），可用于判断长期离线设备
`firstImportTime`	string	首次录入时间
`lastLoginMethod`	string	最后接入方式（如"Edge/98.0.1108.50"）
`lastLoginNetZone` ⭐	string	最后接入网络区域（"内网IP"/外网标识）
`userDescription`	string	最后登录用户描述
`path`	string	最后登录用户所属组织架构
`lastActiveTime`	string	最后活跃时间
`clientVersion`	string	aTrust客户端版本
`windowsDomain` ⭐	string	Windows域控名（可用于AD域映射）
`deviceBrand`	string	设备品牌
`historyUsers` ⭐	object[]	历史登录用户列表（含userName/userDirectoryName/displayName/userDescription）

💡 historyUsers字段非常有价值：即使终端当前未绑定用户，通过历史登录记录也能追溯设备使用者，辅助员工→终端映射。

3.4 P1 — 踢出在线用户

项目	说明
路径	`POST /api/v1/monitor/kickoutUsers`
用途	强制断开VPN会话
安全等级	🔴 高危操作，必须二次确认+审计日志

请求参数（二选一）

方式	参数	说明
按会话ID	`idList: string[]`	从查询在线用户接口获取的会话ID，精准踢出单个会话
按用户名	`userList: [{name, userDirectoryName}]`	⚠️ 该用户所有终端的会话都会被踢出

安全约束（与火绒隔离同级）

踢出操作必须人工二次确认 + 填写原因
仅 admin角色 可执行
操作记录写入审计日志
优先使用 idList（精准踢出），避免误伤其他终端

3.5 P1 — 查询用户详情

项目	说明
路径	`GET /api/v3/user/queryByName`
用途	按用户名查询用户详情

关键响应字段

字段	说明	与IT服务台映射
`name`	用户登录名	可能对应 `employee_id`
`externalId` ⭐	外部ID	可设置为工号，直接映射

⚠️ V3 API关键参数 directoryDomain：所有V3用户管理API必须传入directoryDomain参数（用户目录域名），例如"custom01339"或"local"。此值需从aTrust控制台的【系统管理/用户目录】页面获取，或在首次对接时通过4.8.1 查询用户目录列表接口获取。不同用户目录（本地/LDAP/外部同步）有不同的directoryDomain。 | displayName | 显示名 | 员工姓名 | | groupPath | 组织架构路径 | 部门信息 | | email | 邮箱 | 联系方式 | | phone | 手机号 | 联系方式 | | status | 启用/禁用 | 账号状态 | | roleIdList | 角色ID列表 | 权限信息 | | resourceIdList | 关联应用ID列表 | 有权限访问的应用 |

3.6 P1 — 终端绑定/解绑用户

项目	说明
绑定路径	`POST /api/v1/device/assignUser`
解绑路径	`POST /api/v1/device/unassignUser`

绑定参数

参数	说明
externalId 或 mac	终端标识（二选一）
userName	用户名
userDirectoryName	用户目录名

绑定方式

方式	说明
`userSelfBind`	用户自助绑定
`adminBind`	管理员手动绑定
`adminAdmit`	管理员审批后绑定

💡 可通过OpenAPI实现联软/eHR的终端绑定数据同步到aTrust。

3.7 P2 — 终端CRUD管理（官方docx新增）

操作	路径	方法	版本要求	说明
新增终端	`/api/v1/device/create`	POST	v2.2.7+	MAC/计算机名+externalId
修改终端	`/api/v1/device/update`	POST	v2.2.9+	基于externalId修改，支持newExternalId
删除终端	`/api/v1/device/delete`	POST	v2.2.7+	基于externalId或MAC删除

终端匹配规则

aTrust判断终端是否已存在的规则：

externalId匹配已有终端
根据控制台【终端匹配规则】，MAC或计算机名与已有终端一致

新增终端请求示例

{
    "mac": ["FE-FC-FE-21-F5-D1", "FE-FC-FE-21-F5-D2"],
    "deviceType": "PC",
    "name": "DESKTOP-I3ABQBS",
    "externalId": "0c4e9039-f81d-11ec-a760-fefcfe545bb7",
    "assetType": "BYOD",
    "tagList": ["开发测试终端", "办公网终端"]
}

💡 assetType选项：CYOD（企业选型）/ BYOD（自带）/ COPE（纳管）/ NONE。可通过externalId与联软终端ID对齐。

3.8 P2 — 终端标签管理

项目	说明
设置标签	`POST /api/v1/device/setTag`（支持追加`isAppend=1`或覆盖模式）
取消标签	`POST /api/v1/device/unsetTag`

标签不存在时自动新增。可用于标注终端类型（如"开发测试终端"、"办公网终端"），与IT服务台的设备分类对齐。

3.9 P2 — SPA安全码管理

项目	说明
路径	`POST /api/v1/spa/sendSpaCode`
版本	v2.2.10+
用途	为指定用户申请SPA安全码（单包授权），通过短信发送

💡 SPA（Single Packet Authorization）安全码是零信任中"先认证后连接"机制的关键。当员工报修"无法访问内网应用"时，坐席可通过此接口为其重新发送安全码，恢复VPN接入能力。

请求参数

参数	说明
name/displayName/phone/email	至少传一个（联合查询用户）
userDirectoryName	必传（用户目录名）
expiredTime	过期时间戳（秒），0=永不过期
sendMode	发送方式：`["sms"]`（暂仅支持短信）

3.10 API版本兼容性说明

⚠️ aTrust不同API端点的版本要求不同，对接前必须确认公司aTrust版本。

API模块	最低版本	说明
在线监控（4.1）	未标注	可能v2.2.x+即可
终端管理-基础（create/delete/queryAll）	v2.2.7
终端管理-高级（update/query/assignUser/unassignUser/setTag）	v2.2.9
SPA安全码	v2.2.10
V3用户管理（4.2~4.8）	v2.4.10	用户/组织架构/角色/应用管理

关键判断：如果公司aTrust版本 < v2.2.9，则终端绑定用户功能不可用，映射策略需调整。

4. 集成架构设计

4.1 四系统联合映射架构（最终版）

                        ┌─────────────────┐
                        │  IT智能服务台    │
                        │  employee_id    │
                        └────────┬────────┘
                                 │
                ┌────────────────┼────────────────┐
                ↓                ↓                ↓
   ┌─────────────────┐ ┌────────────────┐ ┌────────────────┐
   │ 联软LV7000(主源)│ │ aTrust(VPN源) │ │ eHR(辅助源)    │
   │                 │ │                │ │                │
   │ queryDevByParams│ │ 4.1.1 在线用户 │ │ 员工基础信息    │
   │ strusername=    │ │ name=          │ │ 任职信息        │
   │ employee_id     │ │ employee_id    │ │ 部门/职位       │
   │                 │ │                │ │                 │
   │ → 终端MAC/IP   │ │ → remoteIp    │ │ → 员工姓名      │
   │ → 硬件详情      │ │ → vips[].ip   │ │ → 联系方式      │
   │ → 准入状态      │ │ → os/browser  │ │ → 上级主管      │
   │ → 在线状态      │ │ → loginTime   │ │                 │
   └────────┬────────┘ └────────┬───────┘ └─────────────────┘
            │                     │
            │   用IP/MAC交叉匹配    │
            ↓                     ↓
   ┌─────────────────────────────────────┐
   │ 火绒企业版(安全源)                   │
   │                                     │
   │ _list(ip=终端IP) → client_id       │
   │ _info2 → 病毒事件/高危漏洞/安全评分  │
   │ _virus_events → 病毒统计            │
   │ _leak → 高危漏洞未修复               │
   │ _create(netctrl) → 一键隔离          │
   └─────────────────────────────────────┘

4.2 映射优先级与数据源选择

接入场景	首选数据源	查询路径	覆盖率
总部内网办公	联软(主源)	`queryDevByParams(strusername=id)` → IP/MAC → 火绒安全状态	~95%
远程/出差	aTrust(VPN源)	`getUserStatus(name=id)` → vips[].ip → 火绒安全状态	~90%
历史/离线	联软+aTrust	联软历史记录 + aTrust historyUsers	~80%
新入职	eHR(辅助)	eHR员工信息 → 手动关联终端	~0%

4.3 完整查询流程

1. 坐席/员工输入 employee_id
2. 并行查询：
   ├── 联软 queryDevByParams(strusername=employee_id) → 内网终端列表
   ├── aTrust getUserStatus(name=employee_id) → VPN在线会话
   └── aTrust queryAll(bindUserList=[{userName=id}]) → VPN绑定终端
3. 合并终端列表（去重，以MAC为主键）
4. 用合并后的IP/MAC列表查火绒安全状态
5. 组装「终端安全画像」返回给坐席/员工

4.4 aTrust与联软映射对比

维度	联软LV7000	aTrust
映射字段	`strusername`（直接是员工账号）	`name`（用户名）+ `bindUsers[].bindUser`
映射准确度	⭐⭐⭐⭐⭐ 总部必装，100%覆盖	⭐⭐⭐⭐ 依赖绑定策略
IP地址	✅ 有内网IP	✅ 有公网IP + VPN虚拟IP
MAC地址	✅ strmac	✅ macList（数组）
硬件详情	✅ 极详细（磁盘/内存/显示器）	❌ 仅基础信息
远程终端	⚠️ 可能未覆盖	✅ 核心覆盖VPN终端
实时在线	✅ existOnlineUser	✅ onlineStatus + getUserStatus
组织架构	✅ 组织架构查询	✅ groupPath + 组织架构API

5. 产品维度分析

5.1 场景匹配度

IT服务台场景	aTrust能做什么	匹配度
员工报修"远程无法访问内网"	查询VPN在线状态+虚拟IP+接入方式	⭐⭐⭐⭐⭐
坐席排查"VPN连接异常"	查询在线状态、最后登录时间、接入IP	⭐⭐⭐⭐⭐
安全应急"发现可疑VPN连接"	踢出在线用户（断开VPN会话）	⭐⭐⭐⭐⭐
终端排查"设备是否授信"	查询终端trusted状态+绑定用户	⭐⭐⭐⭐
AI推送"VPN连接诊断"	获取VPN会话信息供AI分析	⭐⭐⭐⭐
员工自助"查看VPN状态"	查询自己是否在线+虚拟IP	⭐⭐⭐

5.2 功能规划

P0 — 查询能力（零风险，~1.5周）

功能	使用接口	说明
VPN在线状态查询	4.1.1 getUserStatus	坐席查看员工VPN连接状态
远程终端查询	4.9.5 queryAll(bindUserList)	按员工查询VPN绑定终端
终端安全画像集成	4.9.4 query + 火绒/联软	aTrust终端信息加入画像

P1 — 控制能力（中风险，~1周）

功能	使用接口	安全约束
踢出VPN会话	4.1.2 kickoutUsers	admin角色+二次确认+审计
终端授信标签同步	4.9.8/4.9.9 setTag/unsetTag	与联软准入状态同步

P2 — 管理能力（低风险，~1周）

功能	使用接口	说明
用户同步	4.2.x 用户管理API	eHR→aTrust用户同步
终端绑定同步	4.9.6 assignUser	联软映射→aTrust绑定
安全态势看板	4.1.1+4.9.5	管理后台VPN在线统计

6. 开发维度分析

6.1 技术架构

backend/app/
├── integrations/
│   ├── atrust/
│   │   ├── __init__.py
│   │   ├── client.py          # aTrust API客户端（签名+请求）
│   │   ├── models.py          # 数据模型（ATrustUser/ATrustTerminal/ATrustSession）
│   │   ├── cache.py           # 缓存策略
│   │   └── service.py         # 业务服务层
│   ├── huorong/
│   │   └── ... (已有)
│   ├── leagsoft/
│   │   └── ... (已有)
│   └── device_profile.py      # 四系统聚合 → 终端安全画像
├── api/
│   └── integrations.py        # 统一对外API

6.2 签名实现

aTrust签名比火绒复杂（4步），但逻辑清晰：

与火绒签名的关键区别：火绒使用HMAC-SHA1，aTrust使用HMAC-SHA256；火绒签名放在Header和URL两种方式，aTrust仅Header方式；aTrust签名密钥包含timestamp和nonce（更安全）。

# backend/app/integrations/atrust/client.py

import hmac, hashlib, uuid, time, httpx
from urllib.parse import urlparse, parse_qs

class ATrustClient:
    def __init__(self, base_url: str, api_id: str, api_secret: str):
        self.base_url = base_url       # https://atrust.xxx.com:4433
        self.api_id = api_id
        self.api_secret = api_secret
        self.client = httpx.AsyncClient(verify=False, timeout=30)

    def _build_sign_str(self, method: str, path: str, query: str, body: str) -> str:
        """
        构建签名串：pathname?sorted_query&compact_body
        - query的key必须按ASCII排序
        - body必须是紧凑JSON（无空格/换行）
        """
        parts = [path]
        if query or body:
            parts.append("?")
        if query:
            # 对query参数按key排序
            parsed = parse_qs(query)
            sorted_query = "&".join(
                f"{k}={v[0]}" for k, v in sorted(parsed.items())
            )
            parts.append(sorted_query)
        if query and body:
            parts.append("&")
        if body:
            parts.append(body)
        return "".join(parts)

    def _sign(self, sign_str: str) -> tuple[str, str, str]:
        """4步签名：生成签名密钥 → HMAC-SHA256 → 返回签名+时间戳+nonce"""
        timestamp = str(int(time.time()))
        nonce = str(uuid.uuid4())

        # 签名密钥
        sign_key = (
            f"appId={self.api_id}&appSecret={self.api_secret}"
            f"&timestamp={timestamp}&nonce={nonce}"
        )

        # HMAC-SHA256
        signature = hmac.new(
            sign_key.encode("utf-8"),
            sign_str.encode("utf-8"),
            hashlib.sha256,
        ).hexdigest()

        return signature, timestamp, nonce

    async def request(self, method: str, path: str, **kwargs) -> dict:
        """通用请求方法：自动签名"""
        url = f"{self.base_url}{path}"
        parsed = urlparse(url)

        query = parsed.query
        body = ""
        if kwargs.get("json"):
            body = json.dumps(kwargs["json"], separators=(",", ":"))

        sign_str = self._build_sign_str(method, parsed.path, query, body)
        signature, timestamp, nonce = self._sign(sign_str)

        headers = {
            "x-ca-key": self.api_id,
            "x-ca-sign": signature,
            "x-ca-timestamp": timestamp,
            "x-ca-nonce": nonce,
            "Content-Type": "application/json;charset=UTF-8",
        }

        response = await self.client.request(
            method, url, headers=headers, **kwargs
        )
        return response.json()

6.3 缓存策略

数据类型	缓存时间	理由
VPN在线状态	不缓存（实时查询）	实时性要求高
终端绑定信息	30分钟	绑定变更不频繁
用户信息	1小时	用户信息变更极少
组织架构	4小时	几乎不变

6.4 与其他系统的交叉匹配

# 终端安全画像聚合伪代码
async def get_device_profile(employee_id: str) -> DeviceProfile:
    # 1. 并行查三系统
    leagsoft_task = leagsoft.query_dev_by_params(strusername=employee_id)
    atrust_task = atrust.get_online_users(name=employee_id)
    atrust_terminals_task = atrust.query_all_terminals(
        bindUserList=[{"userName": employee_id, "userDirectoryName": "local"}]
    )

    leagsoft_devs, atrust_sessions, atrust_terminals = await asyncio.gather(
        leagsoft_task, atrust_task, atrust_terminals_task
    )

    # 2. 收集所有IP/MAC
    all_ips = set()
    all_macs = set()

    for dev in leagsoft_devs:
        all_ips.add(dev.strip)
        all_macs.add(dev.strmac.upper().replace(":", "-"))

    for session in atrust_sessions:
        all_ips.add(session.remoteIp)
        for vip in session.vips:
            all_ips.add(vip.ip)

    for terminal in atrust_terminals:
        for mac in terminal.macList:
            all_macs.add(mac.upper())

    # 3. 查火绒安全状态
    huorong_tasks = []
    for ip in all_ips:
        huorong_tasks.append(huorong.list_clients(ip=ip))

    huorong_results = await asyncio.gather(*huorong_tasks)

    # 4. 组装画像
    return DeviceProfile(
        employee_id=employee_id,
        leagsoft_devices=leagsoft_devs,
        atrust_sessions=atrust_sessions,
        atrust_terminals=atrust_terminals,
        huorong_security=huorong_results,
    )

7. 安全维度分析

7.1 认证安全

风险	等级	缓解措施
API密钥泄露	🔴 高	环境变量存储，禁止写入代码；定期轮换
签名重放攻击	🟢 低	timestamp+nonce防重放（已内置）
中间人攻击	🟢 低	强制HTTPS
IP白名单绕过	🟡 中	白名单仅包含IT服务台服务器IP

7.2 操作安全

操作	风险	安全约束
踢出在线用户	🔴 高危	admin角色 + 二次确认 + 填写原因 + 审计日志
终端绑定/解绑	🟡 中	admin角色 + 操作日志
查询在线用户	🟢 低	只读操作，无风险
查询终端信息	🟢 低	只读操作，注意不向H5用户端暴露MAC等敏感信息

7.3 数据安全

数据类型	H5用户端是否可见	说明
VPN在线状态	✅ 可见（自己的）	"您当前VPN连接正常"
虚拟IP	❌ 不显示	内网敏感信息
接入IP	❌ 不显示	公网IP属于隐私
终端MAC	❌ 不显示	设备指纹，敏感
终端授信状态	✅ 可见（简化版）	"您的设备已通过安全认证"
绑定用户列表	❌ 不显示	其他用户的绑定信息

7.4 与火绒隔离的统一安全框架

安全规则	火绒网络隔离	aTrust踢出用户
执行角色	仅admin	仅admin
操作确认	二次确认弹窗	二次确认弹窗
原因记录	必填+审计日志	必填+审计日志
通知机制	通知被隔离用户	通知被踢出用户
可逆性	可解除隔离	用户可重新登录

8. 对接前检查清单

8.1 必须确认

aTrust版本确认（必须≥2.4.10才支持V3 API；终端管理高级功能需≥v2.2.9）
获取API ID和API密钥
IT服务台服务器IP加入aTrust白名单
确认aTrust用户目录类型（本地/LDAP/外部）及 directoryDomain 值
确认aTrust中用户名(name)是否与公司域账号/企微账号一致
确认externalId字段用途（是否可设置为工号）
验证getUserStatus接口是否返回vips字段（docx版未展示，web版有，需实测确认）
确认8 QPS限频是否满足业务需求（估计足够）

8.2 建议确认

aTrust终端绑定策略（是否开启一对一绑定）
在线用户数据保留时长（历史VPN会话是否可查）
API调用频率限制
是否有API调用审计日志

8.3 需找团队

对接方	需获取	预估时间
信息安全团队	API ID/密钥、白名单配置、版本确认	1-2天
网络运维团队	aTrust部署架构、用户目录配置	1天
终端安全团队	联软+aTrust+火绒统一映射策略对齐	2-3天

9. 四系统协同方案总结

9.1 系统定位矩阵

系统	定位	核心价值	不可替代性
联软LV7000	终端管理（主源）	员工→终端映射 + 硬件详情 + 准入控制	⭐⭐⭐⭐⭐ strusername精确映射
aTrust	远程接入（VPN源）	VPN会话数据 + 远程终端映射 + 踢出能力	⭐⭐⭐⭐⭐ 唯一VPN数据源
火绒企业版	终端安全（安全源）	病毒/漏洞/隔离 + 安全评分	⭐⭐⭐⭐⭐ 唯一安全数据源
北森eHR	人事数据（辅助源）	员工基础信息 + 任职 + 组织架构	⭐⭐⭐ 员工主数据

9.2 数据流向

员工报修 → employee_id
    ↓
联软 → 内网终端列表 (IP/MAC/硬件)
aTrust → VPN终端列表 (remoteIp/vips/macList)
    ↓ 合并去重
火绒 → 安全状态 (病毒/漏洞/隔离)
    ↓
eHR → 员工信息 (姓名/部门/主管)
    ↓
组装「终端安全画像」→ 展示给坐席/员工

9.3 接口调用频次估算

场景	调用次数	触发频率
员工发起报修	联软1 + aTrust2 + 火绒1~~3 = 4~~6次	按需（每天几十次）
坐席查看终端画像	同上	按需
安全态势看板	aTrust1 + 火绒1	定时刷新（5分钟）
终端映射全量同步	联软1 + aTrust1	每天凌晨1次

9.4 实施优先级

优先级	内容	周期	依赖
P0	aTrust查询能力上线	~1.5周	API ID/密钥 + 白名单
P1	踢出用户+标签同步	~1周	P0完成
P2	四系统联合画像	~1.5周	联软+火绒+eHR已集成
P3	用户同步自动化	~1周	eHR→aTrust对接流程确认

附录

A. aTrust vs 火绒 vs 联软 — 技术对比

维度	联软LV7000	火绒企业版	aTrust
API端点数	68	17	104
认证方式	IP白名单+账号密码+Token	AccessKey+HMAC-SHA1	API_ID+HMAC-SHA256
签名复杂度	简单（Base64编码）	中等（HMAC-SHA1）	较高（4步签名）
协议	HTTP	HTTPS	HTTPS(4433)
响应格式	{code, data, msg}	{errno, errmsg, data}	{code, msg, data, traceId}
成功标识	code=0	errno=0	code=0(V1)/"OK"(V3)
分页	pageSize+pageIndex	page+pageSize	pageSize+pageIndex
最大分页	500	500	1000
IP地址	✅ 有	✅ 有	✅ 有(remoteIp+vips*)
MAC地址	✅ strmac	❌ 无	✅ macList
员工→终端映射	⭐⭐⭐⭐⭐ strusername	⭐⭐ 需IP交叉匹配	⭐⭐⭐⭐ name+bindUsers+historyUsers
频率限制	未标注	未标注	8 QPS
历史用户	❌ 无	❌ 无	✅ historyUsers（追溯设备使用者）

*vips字段在web版文档中有，docx版未展示，需实测确认

B. aTrust关键API速查表

接口	路径	方法	P级
查询在线用户	/api/v1/monitor/getUserStatus	GET	P0
踢出在线用户	/api/v1/monitor/kickoutUsers	POST	P1
新增终端	/api/v1/device/create	POST	P2
修改终端	/api/v1/device/update	POST	P2
删除终端	/api/v1/device/delete	POST	P2
查询全量终端	/api/v1/device/queryAll	POST	P0
查询单个终端	/api/v1/device/query	GET	P0
终端绑定用户	/api/v1/device/assignUser	POST	P1
终端解绑用户	/api/v1/device/unassignUser	POST	P1
设置终端标签	/api/v1/device/setTag	POST	P2
取消终端标签	/api/v1/device/unsetTag	POST	P2
查询用户详情	/api/v3/user/queryByName	GET	P1
查询用户列表	/api/v3/user/queryAll	POST	P1
申请SPA安全码	/api/v1/spa/sendSpaCode	POST	P2

34 KiB Raw Blame History Unescape Escape

aTrust零信任访问控制系统 — 集成分析

1. 系统概述

1.1 产品定位

1.2 与IT服务台的关系

2. API概览

2.1 端点统计

2.2 认证机制

签名计算示例

2.3 响应格式

3. 核心接口详解

3.1 P0 — 查询在线用户

请求参数

响应字段（关键字段加⭐）

响应示例（官方docx版）

业务解读

3.2 P0 — 查询全量终端信息

请求参数

响应字段（关键字段加⭐）

3.3 P0 — 查询单个终端信息

请求参数

额外响应字段（相比queryAll，来自官方docx）

3.4 P1 — 踢出在线用户

请求参数（二选一）

安全约束（与火绒隔离同级）

3.5 P1 — 查询用户详情

关键响应字段

3.6 P1 — 终端绑定/解绑用户

绑定参数

绑定方式

3.7 P2 — 终端CRUD管理（官方docx新增）

终端匹配规则

新增终端请求示例

3.8 P2 — 终端标签管理

3.9 P2 — SPA安全码管理

请求参数

3.10 API版本兼容性说明

4. 集成架构设计

4.1 四系统联合映射架构（最终版）

4.2 映射优先级与数据源选择

4.3 完整查询流程

4.4 aTrust与联软映射对比

5. 产品维度分析

5.1 场景匹配度

5.2 功能规划

P0 — 查询能力（零风险，~1.5周）

P1 — 控制能力（中风险，~1周）

P2 — 管理能力（低风险，~1周）

6. 开发维度分析

6.1 技术架构

6.2 签名实现

6.3 缓存策略

6.4 与其他系统的交叉匹配

7. 安全维度分析

7.1 认证安全

7.2 操作安全

7.3 数据安全

7.4 与火绒隔离的统一安全框架

8. 对接前检查清单

8.1 必须确认

8.2 建议确认

8.3 需找团队

9. 四系统协同方案总结

9.1 系统定位矩阵

9.2 数据流向

9.3 接口调用频次估算

9.4 实施优先级

附录

A. aTrust vs 火绒 vs 联软 — 技术对比

B. aTrust关键API速查表

34 KiB

Raw Blame History