76 lines
4.2 KiB
Markdown
76 lines
4.2 KiB
Markdown
# 安全模型
|
||
|
||
## 1. 信任边界
|
||
|
||
- Gateway、Distribution、Admin 和 Metrics 为四个独立监听边界。
|
||
- Provider API 和上游 Proxy 属于外部不可信网络。
|
||
- Worker 与 Controller 通道必须进行双向身份校验并绑定 cluster/worker。
|
||
- PostgreSQL 保存管理面持久状态；Redis 保存可重建的短效 Proxy 活动池与协调
|
||
信息，Proxy 地址和凭据不写入 PostgreSQL。
|
||
|
||
## 2. 入口控制
|
||
|
||
- 严格模式下，非回环监听必须配置认证或 CIDR allowlist。
|
||
- 认证关闭不代表匿名状态消失：仍按可信代理链解析来源并形成 Client ID。
|
||
- Access、Auth、Rate Limit 和 Client Identification 相互独立。
|
||
- Admin 使用独立凭据，不能复用普通 Gateway 或 Distribution 凭据。
|
||
- `httpsecurity.Protection` 统一实现 Basic、API Key、Bearer、CIDR、可信代理链、
|
||
Client ID 与入口准入；API 使用 401/`WWW-Authenticate`，Gateway 使用
|
||
407/`Proxy-Authenticate`。
|
||
- Listener 可将固定权限绑定到单个认证方式，或在 `mode: any` 中绑定到每个凭据；
|
||
`admin:read`、`admin:write` 与 `distribution:extract` 在 Handler 入口完成匹配，
|
||
不把无权请求传入管理 mutation 或 Proxy 提取流程。
|
||
- Token Client ID 使用 SHA-256 的 128 位摘要前缀，不把 Token 本身写入领域、
|
||
日志或审计键。
|
||
- 启用 Gateway 粘性会话时，绑定键由认证 Client、Routing 和会话头共同派生；
|
||
原始会话标识不写入 PostgreSQL、Redis、日志或指标，也不会转发给目标站点。
|
||
绑定仅保留在当前 Worker 的有界内存中，并在代理不再符合当前 Snapshot、到达
|
||
代理可用期或转发失败时失效。
|
||
- Gateway 凭据的 requestsPerMinute 限制按认证 Client 在本 Worker 内执行，不把
|
||
认证身份、会话或请求计数写入 PostgreSQL、Redis 或 Prometheus 标签。
|
||
- Gateway 凭据的 maxConcurrentConnections 在请求或 CONNECT 隧道的完整生命周期
|
||
内保留一个本地租约；无论转发成功、失败还是服务排空，租约都会释放。
|
||
|
||
## 3. 目标地址策略
|
||
|
||
在解析和每次连接前同时检查：
|
||
|
||
- 私网、回环、链路本地、组播、保留地址和云元数据地址。
|
||
- 域名解析出的全部 A/AAAA 地址，而不是只检查原始 Host。
|
||
- 重定向或重试后的新目标，防止 DNS Rebinding 和策略绕过。
|
||
- CONNECT 的端口 allowlist 与规范化 host:port。
|
||
|
||
CONNECT 与绝对 URL 共用端口白名单；省略配置时仅允许 80/443。保留地址、
|
||
CGNAT、协议转换保留段和已知云元数据端点属于硬拒绝项。私网、回环或链路
|
||
本地的拒绝字段采用三态语义：省略等于拒绝，只有显式 `false` 才放行对应
|
||
类别，且不覆盖这些硬拒绝项。
|
||
|
||
## 4. Secret 处理
|
||
|
||
- 配置只保存环境变量或文件引用，不在日志中输出解析后的值。
|
||
- Proxy 唯一键包含 username 与 credentialVersion，不包含密码或 SecretRef 内容。
|
||
- Provider Parser 将静态/响应密码写入 `credentials.Store`，Proxy Snapshot 只携带
|
||
SecretRef 与 credentialVersion；Gateway 通过统一 Resolver 按版本读取。
|
||
- 指标标签不得使用 token、Proxy URL、Client ID、session 或完整目标 URL。
|
||
- Provider 响应和模板错误只记录分类、Upstream 和 requestId。
|
||
|
||
## 5. Provider 模板
|
||
|
||
- 限制响应体大小、模板执行时间和输出候选数量。
|
||
- 模板函数采用白名单，禁止文件、网络、进程和环境变量访问。
|
||
- URL、Header、Query 和 Body 分别结构化编码，不拼接未转义字符串。
|
||
- 认证失败与限流响应分类处理，429 尊重有上限的 Retry-After。
|
||
|
||
## 6. 审计
|
||
|
||
PostgreSQL 审计只记录 Admin 管理 mutation 的 actor、来源、资源、变更结果和
|
||
时间；它不保存 Proxy ID、代理地址、凭据、逐次 Extraction 或 Gateway 请求。
|
||
Extraction 的短期幂等结果仅位于 Redis TTL 活动池；审计查询接口必须受 Admin
|
||
权限保护并具备保留期限。
|
||
|
||
## 7. 优雅停机
|
||
|
||
- 先原子停止接收新请求，并关闭 HTTP 空闲连接。
|
||
- 已接收的 HTTP 请求和 CONNECT 隧道在 shutdown deadline 内继续排空。
|
||
- deadline 到期后强制关闭仍活跃的 Hijacked 隧道并返回超时结果。
|