# HotPlex Worker Gateway — 安全治理资产 (Security Governance Asset)

> **设计目标**：HotPlex 将安全视为核心竞争力，通过分层防御体系保护 Agent 运行环境、用户会话及后端基础设施。

---

## 1. 威胁模型 (Threat Model)

项目识别出以下四大核心安全威胁，并针对性地建立了防御机制：

| 威胁类别 | 描述 | 防御手段 |
| :--- | :--- | :--- |
| **会话劫持** | 攻击者尝试接入或 resume 他人的 AI 会话 | ES256 JWT 认证 + 确定性 Ownership 验证 |
| **命令注入** | 通过恶意输入在宿主机执行未授权代码 | PGID 进程隔离 + Shell 元字符过滤 |
| **资源枯竭** | 大量僵尸进程或恶意请求导致 OOM/CPU 打满 | Pool Manager 配额治理 + Zombie IO Polling |
| **SSRF 攻击** | Agent 被诱导访问内部私有网络资源 | SSRF 过滤器 (私有 IP 阻断) + URL 白名单 |

---

## 2. 分层防御体系

### 2.1 认证与授权 (Authentication)
- **非对称加密**：强制使用 **ES256 (ECDSA P-256)** 签名算法，禁止安全性较低的 HS256。
- **双保险握手**：
    1.  **WebSocket 握手**：通过 Cookie 或 Authorization Header 进行初步鉴权。
    2.  **AEP Init 阶段**：在 `init` 事件中嵌入 JWT，完成用户 ID 与 Session ID 的最终所有权绑定。
- **JTI 防重放**：基于 Redis/内存黑名单校验 JWT 的唯一 ID (JTI)，有效防御重放攻击。

### 2.2 运行隔离 (Isolation)
- **进程隔离 (PGID)**：每个 Worker 运行在独立的进程组中，通过 `syscall.SysProcAttr` 确保网关层与 Worker 层的物理隔离。
- **环境脱敏**：网关在启动 Worker 前，会自动剔除 `HOTPLEX_` 前缀的敏感环境变量，仅透传白名单中的变量。
- **路径安全**：通过 `path/filepath` 严格校验 `work_dir`，防止路径遍历攻击。

### 2.3 工具执行策略 (Tool Policy)
- **显式授权**：所有涉及写操作或高危行为的工具，必须触发 `permission_request` 获取用户显式授权。
- **自动拒绝**：交互请求设置 5 分钟硬超时，过期自动标记为 `denied`，防止 Agent 陷入无限挂起状态。

---

## 3. 内容与网络安全

### 3.1 输入输出审计
- **Shell 字符过滤**：严控 `;`, `&`, `|`, `` ` ``, `$` 等元字符，防止在 stdio 通道中触发非预期的 Shell 执行。
- **敏感词脱敏**：对 Agent 输出的密钥、密码等模式进行正则识别并自动遮盖。

### 3.2 基础设施防护
- **SSRF 阻断**：所有 Worker 尝试发起的外部 HTTP 请求（针对支持网络访问的 Agent）需经过网关层代理或 DNS 检查，阻断对 `127.0.0.1`、`169.254.169.254` 等私有及元数据地址的访问。

---

## 4. 治理与合规

- **安全审计日志**：记录所有敏感操作（如 Session 创建、工具授权、配置变更）的详细日志。
- **零信任原则**：假定底层 Agent 处于不可信状态，所有跨进程通信均需经过 AEP 协议栈的严格校验。
