9.5 KiB

Raw Blame History

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 postgres.url: postgresql+asyncpg://agentkit@postgres:5432/agentkit
- SQLAlchemy 2 async ORM 提供应用层事务管理。
JWT 签名完整性：HS256 签名防篡改（详见 04-application.md §3.4）。
Webhook 签名校验：fail-closed 防篡改（channels.py）。
Pydantic 模型校验：所有 API 入口 extra="forbid" 拒绝未知字段，防止数据注入。

3.2 数据保密性 / PII 脱敏（DAT-02 / DAT-05）— 已实现（U2）

PII 脱敏 hook

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）

fail-closed 策略

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）：

JWT 签名：替换 HS256 → SM2-HMAC 或国密 JWT 库（如 gmssl）。
密码哈希：评估 SM3 替代 bcrypt（需兼顾兼容性，可能双算法并行）。
PII hash：SHA-256 → SM3。
TLS：启用国密 TLS 套件（需 nginx ingress controller + 国密证书）。
数据加密：PG 字段级加密（透明数据加密 TDE 或应用层 SM4）。

注：国密算法不阻碍等保三级认证（三级要求「加密」而非「国密」），但政企客户常要求国密合规，故列入 P1 整改计划。

3.4 数据备份与恢复（DAT-03）— P0 补齐项

当前状态：P0。AgentKit 自身未提供 PG 备份 runbook，依赖客户侧数据库运维。

AgentKit 侧已实现：

PostgreSQL 持久化（pgvector 扩展，事务日志 WAL 默认开启）。
Redis 配置 AOF/RDB（由客户 Redis 运维决定）。

P0 补齐计划：

新增 docs/deployment/pg-backup-runbook.md，包含：
- 全量备份策略（每日 pg_dump，保留 7 天）
- WAL 归档（连续归档，PITR 恢复）
- 恢复演练流程（每季度执行一次恢复测试）
- 备份加密（备份文件 SM4/AES-256 加密，密钥由 KMS 托管）
Helm Chart 增加 backup 段，可选部署 pg-backup sidecar / CronJob。
pgvector 向量数据备份纳入 pg_dump（已原生支持）。

3.5 剩余信息保护（DAT-04）— 已实现

Session 撤销

JWT V2 token 携带 sid（session id）+ jti（access token 唯一 id），中间件校验 session 是否被服务端撤销（jwt_utils.py）：

销户时撤销该用户全部 session （auth.py deprovision）。
Refresh token 轮换：旧 token 进入 denylist 30s 窗口（denylist.py）。
Token reuse 检测：reuse 触发撤销该用户全部 session（强制重新登录）。

Refresh token hash 化

denylist 不存储明文 refresh token，存储其 SHA-256 hash （denylist.py hash_token），减少敏感信息驻留内存。

JIT 用户随机密码

OIDC/SAML JIT 创建的本地用户使用随机密码（hash_password(secrets.token_urlsafe(32))），不可用于本地登录，避免 SSO 用户的本地密码驻留（oidc.py _find_or_create_user）。

SCIM 用户随机密码

SCIM 创建的用户同样使用随机密码（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）。

3.7 数据销毁（DAT-07）— 已实现

账户销户：deprovision 禁用账户（is_active = 0）+ 撤销全部 session。
审计保留：销户操作本身记录审计日志，不可删除（admin 不可删除审计记录，审计表无 delete 接口）。
PII 销毁：脱敏后 PII 原文不落盘（内存中处理后即替换），无需专门销毁流程。
PG 数据销毁：客户侧 PG 运维负责（如需彻底删除用户数据，由 admin 发起 SQL 操作，记录审计）。

4. 测评建议

DAT-01 / DAT-04 / DAT-06 / DAT-07：直接展示 PG 配置 + jwt_utils.py
- denylist.py + pii_filter.py 即可。
DAT-02 / DAT-05：展示 pii_filter.py fail-closed 流程 + OTel 脱敏指标。
DAT-03：P0 补齐项，需在测评前完成 pg-backup-runbook.md。
国密：P1 参考，不阻碍三级认证，但写入整改计划。

5. PII 脱敏边界（重要说明）

AgentKit PII 脱敏的边界：

覆盖范围：仅脱敏发送至 LLM 的 prompt，不脱敏：
- 用户本地终端命令（终端命令有自己的审计）
- 用户上传的文档原文（文档处理模块不经过 pii_filter）
- bitable 数据（结构化数据，由客户自行控制）
ner_hook 依赖客户：正则版覆盖中国常见 PII（手机/邮箱/身份证/银行卡），复杂 PII（地址/姓名/组织）需客户接入内网 NER 模型。
不替代 DLP：AgentKit PII 脱敏是应用层防护，不替代客户侧 DLP（数据防泄漏）系统。

9.5 KiB Raw Blame History Unescape Escape