wecom_it_smart_desk/docs/aTrust零信任系统集成分析.md

# 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 |

#### 签名计算示例

```python
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 响应格式

```json
{
    "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版）

```json
{
    "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判断终端是否已存在的规则：
1. `externalId`匹配已有终端
2. 根据控制台【终端匹配规则】，MAC或计算机名与已有终端一致

#### 新增终端请求示例

```json
{
    "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（更安全）。

```python
# 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 与其他系统的交叉匹配

```python
# 终端安全画像聚合伪代码
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 |