218 lines
9.5 KiB
Markdown
218 lines
9.5 KiB
Markdown
# 05 — 数据安全
|
||
|
||
> GB/T 22239-2019 第三级「应用和数据安全 — 数据部分」控制点映射。
|
||
|
||
## 1. 维度说明
|
||
|
||
AgentKit 处理的数据类型：
|
||
|
||
- **用户输入**：聊天消息、终端命令、工作流配置
|
||
- **LLM 调用**：prompt + completion（含潜在 PII）
|
||
- **持久化数据**：用户账户、会话、记忆（情景/语义/工作）
|
||
- **审计数据**：RBAC 变更、终端命令、SCIM 操作
|
||
|
||
AgentKit 自身实现：
|
||
|
||
- **已实现**：PII 脱敏（U2 fail-closed + hash 审计）、
|
||
session 撤销（剩余信息保护）、PG + pgvector 完整性、
|
||
审计数据 hash 化。
|
||
- **P0 补齐项**：PostgreSQL 备份恢复 runbook。
|
||
- **P1 参考**：国密加密（R11a，SM4/SM2 替代 AES/RSA）。
|
||
|
||
## 2. GB/T 22239-2019 三级要求（简要）
|
||
|
||
| 控制点 ID | 要求摘要 |
|
||
|-----------|----------|
|
||
| DAT-01 | 数据完整性：数据传输/存储完整性，校验机制 |
|
||
| DAT-02 | 数据保密性：敏感数据加密存储/传输，密钥管理 |
|
||
| DAT-03 | 数据备份与恢复：重要数据定期备份，恢复演练 |
|
||
| DAT-04 | 剩余信息保护：鉴别信息/文件/内存空间释放前清理 |
|
||
| DAT-05 | 个人信息保护：PII 采集/处理/传输最小化与脱敏 |
|
||
| DAT-06 | 数据采集与分类分级：按敏感度分级保护 |
|
||
| DAT-07 | 数据销毁：数据销毁审计，不可恢复 |
|
||
| DAT-08 | 国密算法合规（R11a，政企客户要求）：敏感数据加密使用国密算法 |
|
||
|
||
## 3. AgentKit 实现映射
|
||
|
||
### 3.1 数据完整性（DAT-01）— 已实现
|
||
|
||
- **PostgreSQL + pgvector**：主数据库使用 PostgreSQL（事务 ACID 保证），
|
||
pgvector 扩展存储向量记忆数据。
|
||
- 连接串：[values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml)
|
||
`postgres.url: postgresql+asyncpg://agentkit@postgres:5432/agentkit`
|
||
- SQLAlchemy 2 async ORM 提供应用层事务管理。
|
||
- **JWT 签名完整性**：HS256 签名防篡改（详见 `04-application.md` §3.4）。
|
||
- **Webhook 签名校验**：fail-closed 防篡改
|
||
（[channels.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py)）。
|
||
- **Pydantic 模型校验**：所有 API 入口 `extra="forbid"` 拒绝未知字段，
|
||
防止数据注入。
|
||
|
||
### 3.2 数据保密性 / PII 脱敏（DAT-02 / DAT-05）— 已实现（U2）
|
||
|
||
#### PII 脱敏 hook
|
||
|
||
[src/agentkit/llm/pii_filter.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/llm/pii_filter.py)
|
||
|
||
设计要点：
|
||
|
||
- **正则版（默认）**：识别手机号 / 邮箱 / 身份证 / 银行卡，
|
||
替换为 `[REDACTED_TYPE:hash8]`。
|
||
- **ner_hook（可选）**：客户内网 NER 模型（LAC/HanLP），
|
||
`module:func` 路径动态 import，优先于正则版。
|
||
- **fail-closed**：任何异常时拒绝发送至 LLM（`raise PIIFilterError`），
|
||
**不降级到原文发送**。
|
||
- **hash 审计**：脱敏前后记录 sha256 前 8 位（仅 hash，不含原文），
|
||
用于审计追溯。
|
||
|
||
#### PII 类型与正则
|
||
|
||
| PII 类型 | 正则模式 | 替换格式 |
|
||
|----------|----------|----------|
|
||
| 身份证 | 18 位（含校验位 X） | `[REDACTED_ID_CARD:hash8]` |
|
||
| 手机号 | `1[3-9]\d{9}` | `[REDACTED_PHONE:hash8]` |
|
||
| 邮箱 | 标准邮箱正则 | `[REDACTED_EMAIL:hash8]` |
|
||
| 银行卡 | 16-19 位数字 | `[REDACTED_BANK_CARD:hash8]` |
|
||
|
||
> 身份证正则优先于手机号正则匹配，避免身份证号内 11 位数字子串被
|
||
> 手机号正则误匹配。
|
||
|
||
#### OTel 脱敏指标
|
||
|
||
- `pii_filter.coverage` — 脱敏扫描覆盖率（status: success/failed_closed/fallback_regex）
|
||
- `pii_filter.redacted` — 脱敏实体计数
|
||
|
||
（[metrics.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/metrics.py)）
|
||
|
||
#### fail-closed 策略
|
||
|
||
```python
|
||
try:
|
||
result = _redact(text, ner_hook=ner_hook)
|
||
...
|
||
except Exception as e:
|
||
if fail_closed:
|
||
raise PIIFilterError(f"PII filter failed (fail-closed): {e}") from e
|
||
# fail-open（非默认）：降级到正则版重试
|
||
```
|
||
|
||
生产环境默认 `fail_closed=True`，宁可拒绝服务也不泄露 PII。
|
||
|
||
### 3.3 国密加密（R11a）— P1 参考
|
||
|
||
**当前状态：P1**。AgentKit 当前使用：
|
||
|
||
- **传输加密**：TLS（Ingress 终止），算法套件由 nginx ingress controller
|
||
默认配置（含 AES-GCM 等国际算法）。
|
||
- **密码哈希**：bcrypt（国际算法）。
|
||
- **JWT 签名**：HS256（HMAC-SHA256，国际算法）。
|
||
- **PII hash**：SHA-256（国际算法）。
|
||
|
||
**未使用国密算法**（SM2/SM3/SM4/SM9）。
|
||
|
||
**P1 补齐计划**（R11a）：
|
||
|
||
1. **JWT 签名**：替换 HS256 → SM2-HMAC 或国密 JWT 库（如 `gmssl`）。
|
||
2. **密码哈希**：评估 SM3 替代 bcrypt（需兼顾兼容性，可能双算法并行）。
|
||
3. **PII hash**：SHA-256 → SM3。
|
||
4. **TLS**：启用国密 TLS 套件（需 nginx ingress controller + 国密证书）。
|
||
5. **数据加密**：PG 字段级加密（透明数据加密 TDE 或应用层 SM4）。
|
||
|
||
**注**：国密算法**不阻碍等保三级认证**（三级要求「加密」而非「国密」），
|
||
但政企客户常要求国密合规，故列入 P1 整改计划。
|
||
|
||
### 3.4 数据备份与恢复（DAT-03）— P0 补齐项
|
||
|
||
**当前状态：P0**。AgentKit 自身未提供 PG 备份 runbook，
|
||
依赖客户侧数据库运维。
|
||
|
||
**AgentKit 侧已实现**：
|
||
|
||
- PostgreSQL 持久化（pgvector 扩展，事务日志 WAL 默认开启）。
|
||
- Redis 配置 AOF/RDB（由客户 Redis 运维决定）。
|
||
|
||
**P0 补齐计划**：
|
||
|
||
1. 新增 `docs/deployment/pg-backup-runbook.md`，包含：
|
||
- 全量备份策略（每日 `pg_dump`，保留 7 天）
|
||
- WAL 归档（连续归档，PITR 恢复）
|
||
- 恢复演练流程（每季度执行一次恢复测试）
|
||
- 备份加密（备份文件 SM4/AES-256 加密，密钥由 KMS 托管）
|
||
2. Helm Chart 增加 `backup` 段，可选部署 pg-backup sidecar / CronJob。
|
||
3. pgvector 向量数据备份纳入 `pg_dump`（已原生支持）。
|
||
|
||
### 3.5 剩余信息保护（DAT-04）— 已实现
|
||
|
||
#### Session 撤销
|
||
|
||
JWT V2 token 携带 `sid`（session id）+ `jti`（access token 唯一 id），
|
||
中间件校验 session 是否被服务端撤销
|
||
（[jwt_utils.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py)）：
|
||
|
||
- 销户时撤销该用户全部 session
|
||
（[auth.py deprovision](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/auth.py)）。
|
||
- Refresh token 轮换：旧 token 进入 denylist 30s 窗口
|
||
（[denylist.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/denylist.py)）。
|
||
- Token reuse 检测：reuse 触发撤销该用户全部 session（强制重新登录）。
|
||
|
||
#### Refresh token hash 化
|
||
|
||
denylist 不存储明文 refresh token，存储其 SHA-256 hash
|
||
（[denylist.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/denylist.py)
|
||
`hash_token`），减少敏感信息驻留内存。
|
||
|
||
#### JIT 用户随机密码
|
||
|
||
OIDC/SAML JIT 创建的本地用户使用随机密码
|
||
（`hash_password(secrets.token_urlsafe(32))`），不可用于本地登录，
|
||
避免 SSO 用户的本地密码驻留
|
||
（[oidc.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/providers/oidc.py)
|
||
`_find_or_create_user`）。
|
||
|
||
#### SCIM 用户随机密码
|
||
|
||
SCIM 创建的用户同样使用随机密码
|
||
（[scim/router.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py)
|
||
`create_user`）。
|
||
|
||
### 3.6 数据采集与分类分级（DAT-06）— 已实现
|
||
|
||
- **PII 分类**：pii_filter.py 按 PII 类型分级
|
||
（id_card / phone / email / bank_card），不同类型采用相同脱敏策略
|
||
但审计 hash 独立记录。
|
||
- **记忆分层**：4 层记忆架构（SOUL/USER/MEMORY/DAILY）按敏感度存储
|
||
（SOUL 最敏感，DAILY 最不敏感），详见 AGENTS.md。
|
||
- **数据最小化**：PII 脱敏后原文不落盘（仅 hash 用于审计），
|
||
LLM prompt 中不含原文 PII
|
||
（[pii_filter.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/llm/pii_filter.py)）。
|
||
|
||
### 3.7 数据销毁（DAT-07）— 已实现
|
||
|
||
- **账户销户**：deprovision 禁用账户（`is_active = 0`）+ 撤销全部 session。
|
||
- **审计保留**：销户操作本身记录审计日志，不可删除（admin 不可删除审计记录，
|
||
审计表无 delete 接口）。
|
||
- **PII 销毁**：脱敏后 PII 原文不落盘（内存中处理后即替换），
|
||
无需专门销毁流程。
|
||
- **PG 数据销毁**：客户侧 PG 运维负责（如需彻底删除用户数据，
|
||
由 admin 发起 SQL 操作，记录审计）。
|
||
|
||
## 4. 测评建议
|
||
|
||
1. **DAT-01 / DAT-04 / DAT-06 / DAT-07**：直接展示 PG 配置 + jwt_utils.py
|
||
+ denylist.py + pii_filter.py 即可。
|
||
2. **DAT-02 / DAT-05**：展示 pii_filter.py fail-closed 流程 + OTel 脱敏指标。
|
||
3. **DAT-03**：P0 补齐项，需在测评前完成 pg-backup-runbook.md。
|
||
4. **国密**：P1 参考，不阻碍三级认证，但写入整改计划。
|
||
|
||
## 5. PII 脱敏边界（重要说明）
|
||
|
||
AgentKit PII 脱敏的**边界**：
|
||
|
||
1. **覆盖范围**：仅脱敏发送至 LLM 的 prompt，**不脱敏**：
|
||
- 用户本地终端命令（终端命令有自己的审计）
|
||
- 用户上传的文档原文（文档处理模块不经过 pii_filter）
|
||
- bitable 数据（结构化数据，由客户自行控制）
|
||
2. **ner_hook 依赖客户**：正则版覆盖中国常见 PII（手机/邮箱/身份证/银行卡），
|
||
复杂 PII（地址/姓名/组织）需客户接入内网 NER 模型。
|
||
3. **不替代 DLP**：AgentKit PII 脱敏是应用层防护，不替代客户侧
|
||
DLP（数据防泄漏）系统。
|