# 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（数据防泄漏）系统。