diff --git a/docs/compliance/dengbao-level3/00-overview.md b/docs/compliance/dengbao-level3/00-overview.md new file mode 100644 index 0000000..484430a --- /dev/null +++ b/docs/compliance/dengbao-level3/00-overview.md @@ -0,0 +1,143 @@ +# 等保三级认证文档 — 总览 + +## 1. 认证目标与范围 + +### 1.1 认证目标 + +本套文档用于 Fischer AgentKit(以下简称 "AgentKit")通过 GB/T 22239-2019 +《信息安全技术 网络安全等级保护基本要求》**第三级**(等保三级)测评准备。 + +目标:在政企 POC 采购关闭前完成认证 readiness,使 AgentKit 作为应用系统 +具备部署到等保三级信息系统的合规条件。 + +### 1.2 认证范围 + +AgentKit 作为一个**应用系统**纳入等保三级测评,覆盖: + +- 应用软件本身(FastAPI 后端 + Vue 前端 + Tauri 桌面客户端) +- 部署形态:Kubernetes(客户内网)+ Redis + PostgreSQL(含 pgvector) +- 数据处理:用户输入、LLM 调用、记忆存储、终端命令执行 + +**不在范围内**(由客户/平台侧负责): + +- 物理机房环境(客户机房) +- K8s 宿主机操作系统内核加固 +- 网络骨干设施(防火墙、入侵检测系统、堡垒机) +- PKI 证书签发机构(CA) +- HSM/KMS 硬件设备 + +AgentKit 文档中明确标注「依赖客户侧」与「AgentKit 实现」的边界,避免越界承诺。 + +### 1.3 文档结构 + +本套文档按 GB/T 22239-2019 三级要求 6 个维度组织: + +| 文件 | 维度 | 主要内容 | +|------|------|----------| +| `00-overview.md` | — | 总览(本文档) | +| `01-physical.md` | 物理安全 | 部署假设(客户机房)、物理访问、环境监控、电力 | +| `02-network.md` | 网络安全 | 网络架构、边界防护(Ingress TLS)、访问控制(NetworkPolicy)、入侵防范、安全审计(OTel) | +| `03-host.md` | 主机安全 | 容器镜像安全、K8s node 基线、身份鉴别(SA token)、访问控制(RBAC)、安全审计、入侵防范 | +| `04-application.md` | 应用安全 | 身份鉴别(SSO 多 IDP)、访问控制(RBAC 3 级 + 权限位)、安全审计(OTel + audit.py)、通信完整性(TLS + JWT)、软件容错、资源控制 | +| `05-data.md` | 数据安全 | 数据完整性(PG + pgvector)、数据保密性(PII 脱敏 + 国密 P1)、备份恢复、剩余信息保护(session revoke) | +| `06-management.md` | 管理安全 | 密钥轮换 runbook、break-glass 告警、变更管理、应急响应、安全评估 | +| `control-points.yaml` | — | 控制点清单 + AgentKit 实现映射(已实现 / P0 / P1 / 待评估) | + +## 2. AgentKit 架构摘要 + +### 2.1 技术栈 + +- **后端**:Python 3.11+、FastAPI、Uvicorn、Pydantic v2、SQLAlchemy 2(async) +- **前端**:Vue 3、TypeScript、Vite 5、Ant Design Vue 4、Pinia +- **桌面端**:Tauri 2.x(Rust 外壳 + Python sidecar) +- **基础设施**:Redis(总线/缓存/状态)、PostgreSQL + pgvector(情景记忆) +- **可观测性**:OpenTelemetry(OTLP gRPC 导出,U1 已强制依赖) +- **部署**:Helm Chart(K8s 内网部署,U5) + +### 2.2 部署形态 + +``` +客户内网 K8s 集群 + ├── Ingress (nginx, TLS 终止) ← 唯一对外入口 + │ └── TLS 证书(cert-manager 或手动) + ├── AgentKit Pod (非 root, UID 1001) + │ ├── FastAPI serve (:8001) — API + │ └── FastAPI gui (:8002) — Web GUI + ├── Redis (内部, requirepass) + ├── PostgreSQL + pgvector (内部, 密码) + └── OTel Collector (内部, bearer token) + ↑ OTLP gRPC (mTLS: 待评估) +``` + +密钥通过 Sealed Secrets 或 External Secrets Operator 注入(禁止明文 +Kubernetes Secret + Git 提交,KTD-4 / R2a)。共 10 个 secret slot, +每个含轮换周期(90~365 天)。 + +### 2.3 关键安全子系统映射 + +| 子系统 | 模块 | 等保维度 | +|--------|------|----------| +| OTel 可观测性 | `src/agentkit/telemetry/` | 网络/主机/应用审计 | +| PII 脱敏 | `src/agentkit/llm/pii_filter.py` | 数据保密性 | +| SSO 多 IDP | `src/agentkit/server/auth/providers/`、`idp_registry.py` | 应用身份鉴别 | +| SCIM 2.0 | `src/agentkit/server/auth/scim/router.py` | 应用账户生命周期 | +| RBAC 审计 | `src/agentkit/server/auth/audit.py` | 应用安全审计 | +| 终端安全 6 层 | `src/agentkit/server/auth/terminal_security.py` | 应用访问控制 | +| RBAC 权限 | `src/agentkit/server/auth/permissions.py` | 应用访问控制 | +| JWT 会话 | `src/agentkit/server/auth/jwt_utils.py`、`denylist.py` | 应用身份鉴别 + 剩余信息保护 | +| 密码哈希 | `src/agentkit/server/auth/password.py` | 应用身份鉴别 | +| Helm 部署 | `deploy/helm/agentkit/` | 网络/主机/管理 | +| 密钥轮换 | `docs/deployment/key-rotation-runbook.md` | 管理安全 | + +## 3. 各维度实现状态概览 + +下表汇总各维度控制点的实现状态。状态定义: + +- **已实现**:代码/配置已落地,有对应文件可查 +- **P0**:认证 readiness 必需,本次 POC 采购关闭前需补齐 +- **P1**:下一阶段补齐,文档中标注为参考 +- **待评估**:依赖客户侧或需进一步评估方案 + +| 维度 | 控制点数 | 已实现 | P0 | P1 | 待评估 | +|------|----------|--------|----|----|--------| +| 物理安全 | 6 | 0 | 0 | 0 | 6 | +| 网络安全 | 8 | 4 | 2 | 1 | 1 | +| 主机安全 | 7 | 4 | 2 | 0 | 1 | +| 应用安全 | 8 | 8 | 0 | 0 | 0 | +| 数据安全 | 8 | 6 | 1 | 1 | 0 | +| 管理安全 | 7 | 4 | 1 | 1 | 1 | +| **合计** | **44** | **26** | **6** | **3** | **9** | + +> 应用安全是 AgentKit 自身责任范围,已全部实现。物理安全完全依赖客户机房, +> 故全部为「待评估」。网络/主机/数据/管理维度的 P0 项(共 6 个)是认证 +> readiness 的关键补齐项,详见 `control-points.yaml`。 +> +> **P0 关键补齐项清单**: +> - NET-03 NetworkPolicy 模板 +> - NET-07 审计日志保留 180 天(KTD-9) +> - HST-03 容器日志标准化采集 +> - HST-07 镜像漏洞扫描(Trivy/CI 集成) +> - DAT-03 PostgreSQL 备份恢复 runbook +> - MGT-02 CI/CD 规范文档化 + +## 4. 与既有交付的引用关系 + +本套文档不重复实现细节,只映射到既有交付物: + +| 既有交付 | 等保映射 | 引用文档 | +|----------|----------|----------| +| U1 OTel(telemetry/) | 应用/网络审计 | `02-network.md` §5、`04-application.md` §4 | +| U2 PII 脱敏(pii_filter.py) | 数据保密性 | `05-data.md` §2 | +| U3 DR-fixes(bitable) | 应用容错 | `04-application.md` §5 | +| U4 SSO/SCIM/Audit | 应用身份鉴别/审计 | `04-application.md` §1/§4、`06-management.md` §2 | +| U5 K8s Helm Chart | 网络/主机/管理 | `02-network.md`、`03-host.md`、`06-management.md` | +| R7a 终端安全 6 层 | 应用访问控制 | `04-application.md` §2 | + +## 5. 文档使用说明 + +1. 测评机构按 `control-points.yaml` 逐条核对,每条含 `id` / `dimension` / + `title` / `requirement` / `implementation` / `status` / `references`。 +2. `references` 字段给出 AgentKit 代码文件绝对路径,使用 `file:///` 链接格式。 +3. 状态为 P0 的控制点需在认证前补齐,对应文件中标有「P0 补齐项」段落。 +4. 状态为 P1 的控制点在文档中标注为「P1 参考」,不阻碍三级认证但需写入整改计划。 +5. 状态为「待评估」的控制点依赖客户侧环境,需在客户机房测评时单独核对。 diff --git a/docs/compliance/dengbao-level3/01-physical.md b/docs/compliance/dengbao-level3/01-physical.md new file mode 100644 index 0000000..0611843 --- /dev/null +++ b/docs/compliance/dengbao-level3/01-physical.md @@ -0,0 +1,99 @@ +# 01 — 物理安全 + +> GB/T 22239-2019 第三级「物理和环境安全」控制点映射。 + +## 1. 维度说明 + +AgentKit 作为应用系统以容器形态部署在客户内网 Kubernetes 集群中, +**不拥有也不运维物理机房**。物理安全责任由客户机房运营方承担。 + +本维度文档的目的是: + +1. 明确 AgentKit 部署对物理环境的**假设**(前置条件)。 +2. 列出 AgentKit 自身在物理安全维度的**实现空缺**(全部为「待评估」)。 +3. 在客户机房测评时,由客户方提供物理安全控制点证据, + AgentKit 侧仅提供「部署形态证明」(Helm Chart / Pod 清单)。 + +## 2. GB/T 22239-2019 三级要求(简要) + +| 控制点 ID | 要求摘要 | +|-----------|----------| +| PHY-01 | 物理访问控制:机房出入口配置电子门禁,记录进入人员和时间 | +| PHY-02 | 防盗窃和防破坏:主要设备设置防盗标识,机房设置监控系统 | +| PHY-03 | 防雷击:机房设置防雷保安器,接地电阻符合要求 | +| PHY-04 | 防火:机房设置火灾自动消防系统,检测报警器 | +| PHY-05 | 防水和防潮:机房安装水敏检测装置,防止水管安装 | +| PHY-06 | 防静电:机房采用防静电地板,设置静电消除器 | + +## 3. AgentKit 实现映射 + +### 3.1 部署假设(前置条件) + +AgentKit 容器化部署对物理环境的假设: + +1. 客户机房满足 GB/T 22239-2019 三级物理安全全部要求。 +2. K8s 宿主机位于受控机房内,物理访问由客户运营方管理。 +3. 电力供应由机房提供(含 UPS / 后备发电机)。 +4. 网络骨干(防火墙、IDS、堡垒机)由客户网络团队运维。 + +### 3.2 控制点状态 + +全部 6 个物理安全控制点状态均为 **待评估** —— 依赖客户机房测评时由客户方 +提供证据。AgentKit 侧仅提供以下证明材料: + +- 部署形态证明:[deploy/helm/agentkit/values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) + (`podSecurityContext.runAsNonRoot: true`,`runAsUser: 1000`) +- Pod 资源清单:[deploy/helm/agentkit/templates/deployment.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/deployment.yaml) +- 容器镜像基线:[Dockerfile](file:///Users/chiguyong/Code/Fischer-agentkit/Dockerfile) + (多阶段构建 + `USER appuser` 非 root 运行) + +### 3.3 控制点详情 + +#### PHY-01 物理访问控制 — 待评估 + +- **要求**:机房出入口配置电子门禁,记录进入人员和时间。 +- **AgentKit 实现**:无物理访问控制责任。AgentKit 软件资产以镜像形式 + 存储在客户镜像仓库,物理访问由客户机房运营方控制。 +- **客户侧需提供**:机房门禁系统记录、人员进出日志、访问审批流程。 + +#### PHY-02 防盗窃和防破坏 — 待评估 + +- **要求**:主要设备设置防盗标识,机房设置监控系统。 +- **AgentKit 实现**:无物理设备责任。K8s worker node 由客户运维。 +- **客户侧需提供**:机房监控系统、设备资产清单。 + +#### PHY-03 防雷击 — 待评估 + +- **要求**:机房设置防雷保安器,接地电阻符合要求。 +- **AgentKit 实现**:无防雷责任。 +- **客户侧需提供**:防雷检测报告、接地电阻测试记录。 + +#### PHY-04 防火 — 待评估 + +- **要求**:机房设置火灾自动消防系统,检测报警器。 +- **AgentKit 实现**:无消防责任。 +- **客户侧需提供**:消防系统验收报告、定期检测记录。 + +#### PHY-05 防水和防潮 — 待评估 + +- **要求**:机房安装水敏检测装置,防止水管安装。 +- **AgentKit 实现**:无防水责任。 +- **客户侧需提供**:水敏检测装置部署记录、机房湿度监控。 + +#### PHY-06 防静电 — 待评估 + +- **要求**:机房采用防静电地板,设置静电消除器。 +- **AgentKit 实现**:无防静电责任。 +- **客户侧需提供**:防静电地板验收报告、静电消除器检测记录。 + +## 4. 测评建议 + +物理安全维度在 AgentKit 侧**无代码/配置可核对**,全部依赖客户机房测评。 +建议在测评前与客户安全团队确认: + +1. 客户机房是否已通过等保三级(或更高)测评。 +2. 客户机房测评报告是否覆盖 AgentKit 部署区域。 +3. 若客户机房未单独测评,需将 AgentKit 部署区域纳入本次测评范围。 + +AgentKit 侧提供的证明材料仅证明「软件部署形态合规」(非 root 容器、 +资源受限、Helm Chart 标准化部署),不替代物理环境测评。 diff --git a/docs/compliance/dengbao-level3/02-network.md b/docs/compliance/dengbao-level3/02-network.md new file mode 100644 index 0000000..18cdc6d --- /dev/null +++ b/docs/compliance/dengbao-level3/02-network.md @@ -0,0 +1,197 @@ +# 02 — 网络安全 + +> GB/T 22239-2019 第三级「网络和通信安全」控制点映射。 + +## 1. 维度说明 + +AgentKit 部署在客户内网 K8s 集群,网络安全的边界由 Ingress 控制, +内部东西向流量由 K8s 网络模型与(待补齐的)NetworkPolicy 控制。 +AgentKit 自身实现: + +- **已实现**:Ingress TLS 终止、OTel 安全审计(日志/trace)、 + Redis/PG 密码鉴权(基础设施层)、API 限流。 +- **P0 补齐项**:NetworkPolicy 模板(东西向流量隔离)、 + 审计日志保留策略(180 天,KTD-9)。 +- **P1 参考**:OTel exporter mTLS、网络入侵检测接入。 + +## 2. GB/T 22239-2019 三级要求(简要) + +| 控制点 ID | 要求摘要 | +|-----------|----------| +| NET-01 | 网络架构:划分网络区域,避免单点故障 | +| NET-02 | 边界防护:边界实施访问控制和安全过滤 | +| NET-03 | 访问控制:网络层访问控制策略,最小权限 | +| NET-04 | 入侵防范:网络入侵检测,恶意流量检测 | +| NET-05 | 安全审计:网络审计日志,覆盖关键网络活动 | +| NET-06 | 恶意代码防范:网络边界恶意代码检测 | +| NET-07 | 安全审计日志保留:日志保留期满足合规要求 | +| NET-08 | 资源控制:会话与带宽限制,防止资源耗尽 | + +## 3. AgentKit 实现映射 + +### 3.1 网络架构(NET-01)— 已实现 + +AgentKit K8s 部署采用单 Ingress 入口 + 内部 Service 架构: + +``` +外网/办公网 ── HTTPS ──> Ingress (nginx, TLS 终止) + │ + ▼ + AgentKit Service (ClusterIP) + │ + ▼ + AgentKit Pod (:8001 API, :8002 GUI) + │ + ┌─────────────┼─────────────┐ + ▼ ▼ ▼ + Redis PostgreSQL OTel Collector + (ClusterIP) (ClusterIP) (ClusterIP) +``` + +- **Ingress 是唯一对外入口**:[deploy/helm/agentkit/templates/ingress.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/ingress.yaml) +- **Service 类型为 ClusterIP**(不直接对外暴露): + [deploy/helm/agentkit/values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) + (`service.type: ClusterIP`) +- **API 与 GUI 走分离路径**:`/api` → API Service,`/` → GUI Service + +### 3.2 边界防护(NET-02)— 已实现 + +Ingress 启用 TLS 终止,所有外网流量强制 HTTPS: + +```yaml +ingress: + enabled: true + className: nginx + tls: + enabled: true + secretName: agentkit-tls # 引用 secrets.tlsServerCert +``` + +- TLS 证书通过 cert-manager 自动续期或手动签发(365 天轮换)。 +- HTTP→HTTPS 跳转由 nginx ingress controller 默认配置提供 + (客户侧 ingress controller 责任)。 +- 证书私钥通过 Sealed Secret / External Secret 注入(KTD-4 / R2a)。 + +**参考文件**: +[deploy/helm/agentkit/templates/ingress.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/ingress.yaml) +[deploy/helm/agentkit/values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml)(`ingress` 段、`secrets.tlsServerCert` slot) + +### 3.3 访问控制 / NetworkPolicy(NET-03)— P0 补齐项 + +**当前状态:P0**。Helm Chart 暂无 NetworkPolicy 模板, +Pod 间东西向流量默认全通(K8s 默认网络模型)。 + +**P0 补齐计划**: + +1. 新增 `deploy/helm/agentkit/templates/networkpolicy.yaml`。 +2. 默认 deny-all,按白名单放行: + - Ingress → AgentKit Pod(8001/8002) + - AgentKit Pod → Redis(6379) + - AgentKit Pod → PostgreSQL(5432) + - AgentKit Pod → OTel Collector(4317) +3. 命名空间隔离:AgentKit 独立 namespace,跨 namespace 流量显式声明。 + +**当前缓解**:Service 全部 ClusterIP(不对外),Redis/PG 由客户 K8s 集群 +内部网络策略保护(客户侧责任)。 + +### 3.4 入侵防范(NET-04)— P1 参考 + +**当前状态:P1**。AgentKit 自身不部署网络 IDS, +依赖客户侧网络骨干的 IDS / IPS。 + +- API 层面:[RateLimitMiddleware](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/middleware.py) + 实现单进程滑动窗口限流,Webhook 入站端点单独限流 + ([src/agentkit/server/routes/channels.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py))。 +- 异常登录:JWT 验证失败、SCIM token 校验失败返回 401 + ([scim/router.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py) + 使用 `hmac.compare_digest` 恒定时间比较)。 + +**P1 补齐计划**:接入客户 SIEM,将 AgentKit OTel 日志投递到客户 +入侵检测平台,由 SIEM 做 abnormal pattern 检测。 + +### 3.5 安全审计(NET-05)— 已实现 + +AgentKit 通过 OpenTelemetry(U1,强制依赖)实现网络活动审计: + +- **HTTP 请求 trace**:FastAPI Instrumentor 自动埋点,每个请求生成 span, + 含 HTTP method/path/status/duration。 + [src/agentkit/telemetry/setup.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/setup.py) + (`FastAPIInstrumentor`) +- **审计事件 span**:RBAC 角色变更、deprovisioning 写入 OTel span event + ([src/agentkit/server/auth/audit.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py))。 +- **SCIM 推送失败告警**:span event `scim.push.failure` + ([scim/router.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py))。 +- **终端命令审计**:每条终端命令写入 `terminal_audit_logs` 表 + ([terminal_security.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py))。 + +OTLP gRPC 导出到内部 collector +([values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) +`otel.endpoint: http://otel-collector:4317`)。 + +### 3.6 恶意代码防范(NET-06)— 待评估 + +**当前状态:待评估**。网络边界恶意代码检测由客户网络骨干的 +防病毒网关 / 沙箱负责。AgentKit 不在网络边界位置。 + +AgentKit 侧的缓解: + +- 容器镜像来自可信构建(CI/CD),不在运行时下载可执行文件。 +- 终端命令执行受 6 层白名单 + 危险检测约束(R7a), + 限制任意命令执行能力(详见 `04-application.md` §2)。 + +### 3.7 安全审计日志保留(NET-07)— P0 补齐项 + +**当前状态:P0**。审计日志保留策略未在代码中强制实施: + +- `auth_audit_log` 表(SQLite)和 `terminal_audit_logs` 表无自动清理 / + 归档策略,依赖运维手动管理。 +- OTel collector 侧的日志保留由客户可观测性平台配置,AgentKit 不控制。 + +**P0 补齐计划**: + +1. 在 Helm values 增加 `audit.retentionDays: 180` 配置(KTD-9)。 +2. 实现审计日志归档 CronJob:超过 180 天的记录导出到对象存储(客户侧) + 并从主表清理。 +3. OTel collector 配置 180 天保留策略(与客户可观测性团队协同)。 + +### 3.8 资源控制(NET-08)— 已实现 + +AgentKit 在应用层与容器层均实现资源控制: + +- **容器层**:Pod resources requests/limits + ([values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) + `resources` 段,CPU 250m~1000m / Memory 512Mi~2Gi)。 +- **应用层**:[RateLimiter](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/middleware.py) + 实现 IP 维度滑动窗口限流,Webhook 入站端点独立限流 + ([channels.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py))。 +- **会话超时**:终端 session 闲置 1800s 自动断开 + ([terminal_server.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/terminal_server.py) + `SESSION_IDLE_TIMEOUT = 1800`)。 +- **JWT 短时效**:access token 15min + ([jwt_utils.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py) + `ACCESS_TOKEN_TTL`)。 + +## 4. OTel exporter mTLS(P1 参考) + +**当前状态:P1**。OTel exporter 通过 bearer token 鉴权 +([values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) +`secrets.otelExporterToken` slot),未启用 mTLS。 + +Helm Chart 已预留 `secrets.mtlsClientCert` slot(用于下游服务 mTLS), +但 OTel exporter 侧的 mTLS 配置待补齐。 + +**P1 补齐计划**: + +1. 在 OTel SDK 初始化时配置 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE` / + `OTEL_EXPORTER_OTLP_CLIENT_KEY` / `OTEL_EXPORTER_OTLP_CA_CERT` 环境变量。 +2. OTel collector 侧启用 mTLS 服务端证书验证。 +3. 复用 `secrets.mtlsClientCert` slot 注入客户端证书。 + +## 5. 测评建议 + +1. **NET-01 / NET-02 / NET-05 / NET-08**:直接展示 Helm Ingress + OTel + + 限流配置即可。 +2. **NET-03 / NET-07**:P0 补齐项,需在测评前完成 NetworkPolicy 模板和 + 审计日志保留 CronJob。 +3. **NET-04 / NET-06**:依赖客户侧网络骨干,由客户网络团队提供 IDS / + 恶意代码检测证据。 diff --git a/docs/compliance/dengbao-level3/03-host.md b/docs/compliance/dengbao-level3/03-host.md new file mode 100644 index 0000000..9fec7ea --- /dev/null +++ b/docs/compliance/dengbao-level3/03-host.md @@ -0,0 +1,197 @@ +# 03 — 主机安全 + +> GB/T 22239-2019 第三级「设备和计算安全」控制点映射。 +> 本维度以**容器与 Pod**为「主机」单元(AgentKit 不直接运维 K8s node)。 + +## 1. 维度说明 + +AgentKit 以容器形态运行在客户 K8s 集群。「主机安全」分为两层: + +- **容器/Pod 层**(AgentKit 责任):镜像安全、运行时安全上下文、 + ServiceAccount、Pod 级 RBAC。 +- **K8s node 层**(客户责任):宿主机操作系统内核加固、node 基线、 + 主机入侵检测(HIDS)。 + +AgentKit 自身实现: + +- **已实现**:非 root 容器、最小权限安全上下文(capabilities drop ALL)、 + ServiceAccount 隔离、容器级资源限制。 +- **P0 补齐项**:容器镜像漏洞扫描(CI 集成 Trivy/Grype)、 + Pod 安全审计日志采集标准化。 +- **P1 参考**:distroless 基础镜像。 + +## 2. GB/T 22239-2019 三级要求(简要) + +| 控制点 ID | 要求摘要 | +|-----------|----------| +| HST-01 | 身份鉴别:设备/系统身份标识与鉴别 | +| HST-02 | 访问控制:操作系统/账户权限最小化,远程管理受控 | +| HST-03 | 安全审计:设备审计日志,覆盖系统管理活动 | +| HST-04 | 入侵防范:主机入侵检测,系统加固 | +| HST-05 | 恶意代码防范:主机防病毒,恶意代码检测 | +| HST-06 | 资源控制:CPU/内存/磁盘限制,会话超时 | +| HST-07 | 镜像与补丁管理:系统补丁及时更新,镜像来源可信 | + +## 3. AgentKit 实现映射 + +### 3.1 容器镜像安全(HST-07)— 部分已实现 / P0 补齐 + +#### 已实现 + +- **多阶段构建**:builder + runner 两阶段,最终镜像不含构建工具链。 + [Dockerfile](file:///Users/chiguyong/Code/Fischer-agentkit/Dockerfile) +- **非 root 用户**:runner 阶段创建 `appuser`(UID 1001 / GID 1001), + `USER appuser` 强制非 root 运行。 +- **基础镜像**:`python:3.11-slim`(精简版,比 full 镜像减少攻击面)。 +- **HEALTHCHECK**:内置健康检查 + (`/api/v1/health`,30s 间隔)。 +- **不写字节码**:`PYTHONDONTWRITEBYTECODE=1`,减少磁盘 .pyc 残留。 + +#### P0 补齐项:镜像漏洞扫描 + +**当前状态:P0**。CI 流水线未集成容器镜像漏洞扫描。 + +**P0 补齐计划**: + +1. CI 流水线增加 Trivy 扫描步骤: + ```yaml + - name: Trivy scan + run: trivy image --severity HIGH,CRITICAL --exit-code 1 fischer-agentkit:${{ github.sha }} + ``` +2. Helm Chart 增加 `image.digest` 字段,部署时使用不可变 digest 而非 tag。 +3. 镜像签名(cosign)— P1,可选。 + +### 3.2 K8s node 安全基线(HST-04 / HST-05)— 待评估 + +**当前状态:待评估**。K8s 宿主机由客户运维,AgentKit 不控制 node 操作系统。 + +客户侧需提供: + +- node 操作系统加固基线(CIS Benchmark for Kubernetes / 操作系统)。 +- 主机入侵检测(HIDS,如 Falco / OSSEC)。 +- 主机防病毒(如客户机房要求)。 + +AgentKit 侧的缓解: + +- Pod `securityContext` 强制非 root + drop ALL capabilities + ([values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) + `podSecurityContext` / `securityContext` 段),即使 node 被攻破, + 容器逃逸到 root 的难度提升。 + +### 3.3 身份鉴别 / ServiceAccount(HST-01)— 已实现 + +AgentKit Pod 使用专用 ServiceAccount,不共享 default SA: + +- **ServiceAccount 创建**: + [deploy/helm/agentkit/templates/serviceaccount.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/serviceaccount.yaml) +- **values 配置**: + ```yaml + serviceAccount: + create: true + name: "" # 留空则用 fullname(专用 SA) + annotations: {} # 云厂商 workload identity 注解 + ``` +- **Workload Identity**(可选):`workloadIdentity.enabled: true` 时 + 注入 projected SA token,用于访问云 KMS / STS + ([values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) + `workloadIdentity` 段)。 + +Pod 内应用层身份鉴别见 `04-application.md` §1(SSO + JWT)。 + +### 3.4 访问控制 / Pod 级 RBAC(HST-02)— 已实现 + +- **capabilities drop ALL**: + ```yaml + securityContext: + allowPrivilegeEscalation: false + capabilities: + drop: [ALL] + ``` + ([values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) `securityContext` 段) +- **runAsNonRoot 强制**:`podSecurityContext.runAsNonRoot: true`, + K8s admission 拒绝非 root Pod。 +- **readOnlyRootFilesystem**:当前为 `false`(agentkit 需写临时文件用于缓存/日志), + 通过 `emptyDir` 挂载 `/tmp` 实现写入隔离 + ([deployment.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/deployment.yaml) + `volumes.tmp`)。 +- **privileged: false**(默认,未启用特权模式)。 + +应用层 RBAC(member/operator/admin + 9 权限位)见 +`04-application.md` §2。 + +### 3.5 安全审计 / 容器日志(HST-03)— 已实现 + P0 补齐 + +#### 已实现 + +- **stdout/stderr 标准输出**:AgentKit 日志全部输出到 stdout, + 由 K8s 日志采集(如 Loki / Fluent Bit)收集。 +- **OTel trace**:每个 Pod 的请求 trace 通过 OTLP 导出到 collector + (U1,强制依赖)。 +- **审计事件**:RBAC 变更、deprovisioning、SCIM 操作写入 `auth_audit_log` 表 + + OTel span event([audit.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py))。 +- **终端命令审计**:每条终端命令 + 决策(executed/confirmed/blocked/denied) + 写入 `terminal_audit_logs` 表 + ([terminal_security.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py))。 + +#### P0 补齐项:审计日志标准化采集 + +**当前状态:P0**。容器日志采集到客户日志平台的链路未标准化。 + +**P0 补齐计划**: + +1. Helm Chart 增加 `logging.fluentBitSidecar` 选项(可选 sidecar 采集)。 +2. 审计日志 JSON 化(structured logging),便于 SIEM 解析。 +3. 与 `02-network.md` §3.7 的 180 天保留策略协同落地。 + +### 3.6 入侵防范(HST-04)— 已实现(容器层) + +容器层入侵防范已实现: + +- **非 root + drop ALL capabilities**:限制容器内可执行的系统调用。 +- **allowPrivilegeEscalation: false**:阻止子进程提权。 +- **资源 limits**:CPU 1000m / Memory 2Gi 上限,防止容器失控耗尽 node 资源 + ([values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) + `resources.limits`)。 +- **Liveness/Readiness 探针**:故障 Pod 自动重启 + ([deployment.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/deployment.yaml) + `livenessProbe` / `readinessProbe`)。 + +node 层入侵检测(HIDS)见 §3.2,依赖客户侧。 + +### 3.7 资源控制(HST-06)— 已实现 + +- **Pod resources**: + ```yaml + resources: + requests: { cpu: 250m, memory: 512Mi } + limits: { cpu: 1000m, memory: 2Gi } + ``` +- **应用层限流**:[RateLimiter](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/middleware.py) + IP 维度滑动窗口。 +- **会话超时**:终端 session 1800s 闲置断开 + ([terminal_server.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/terminal_server.py))。 +- **JWT 短时效**:access 15min / refresh 7d + ([jwt_utils.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py))。 + +## 4. distroless 基础镜像(P1 参考) + +**当前状态:P1**。当前基础镜像为 `python:3.11-slim`,含 shell + 包管理器, +攻击面大于 distroless。 + +**P1 升级路径**: + +1. 切换到 `gcr.io/distroless/python3-debian12` 作为 runner 基础镜像。 +2. 需调整:distroless 无 shell,HEALTHCHECK 的 `python -c` 命令需改为 + HTTP 探针(K8s livenessProbe httpGet,已支持)。 +3. 多阶段构建的 builder 阶段保持 `python:3.11-slim`(构建工具链需要)。 + +distroless 不阻碍等保三级认证,但作为安全增强项写入整改计划。 + +## 5. 测评建议 + +1. **HST-01 / HST-02 / HST-06**:直接展示 ServiceAccount + securityContext + + resources 配置即可。 +2. **HST-03**:已实现部分展示 audit.py + terminal_security.py, + P0 补齐日志标准化采集。 +3. **HST-07**:P0 补齐镜像漏洞扫描后展示 Trivy 扫描报告。 +4. **HST-04 / HST-05**:容器层已实现,node 层由客户提供 HIDS 证据。 diff --git a/docs/compliance/dengbao-level3/04-application.md b/docs/compliance/dengbao-level3/04-application.md new file mode 100644 index 0000000..2b05041 --- /dev/null +++ b/docs/compliance/dengbao-level3/04-application.md @@ -0,0 +1,257 @@ +# 04 — 应用安全 + +> GB/T 22239-2019 第三级「应用和数据安全 — 应用部分」控制点映射。 + +## 1. 维度说明 + +应用安全是 AgentKit **自身核心责任范围**,全部 8 个控制点已实现。 +本维度文档引用 U4 SSO 多 IDP / SCIM、U1 OTel 审计、R7a 终端安全 6 层、 +RBAC 3 级权限、JWT 会话等既有实现,不重复代码细节。 + +## 2. GB/T 22239-2019 三级要求(简要) + +| 控制点 ID | 要求摘要 | +|-----------|----------| +| APP-01 | 身份鉴别:用户身份标识与鉴别,口令复杂度,登录失败处理 | +| APP-02 | 访问控制:基于角色的访问控制,最小权限,默认拒绝 | +| APP-03 | 安全审计:应用审计日志,覆盖用户操作关键事件 | +| APP-04 | 通信完整性:传输完整性保护,防篡改 | +| APP-05 | 软件容错:错误处理,故障隔离,降级机制 | +| APP-06 | 资源控制:会话并发控制,超时自动断开 | +| APP-07 | 应用账户生命周期:开户/变更/销户审计,SCIM 自动化 | +| APP-08 | 代码安全:输入验证,输出编码,依赖漏洞管理 | + +## 3. AgentKit 实现映射 + +### 3.1 身份鉴别(APP-01)— 已实现 + +#### 多 IDP 单点登录(U4 SSO) + +AgentKit 支持 OIDC + SAML 双协议并存的多 IDP 信任边界: + +- **OIDC 适配器**(authlib redirect flow + JIT 用户创建): + [src/agentkit/server/auth/providers/oidc.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/providers/oidc.py) +- **SAML 2.0 适配器**(python3-saml / OneLogin ACS): + [src/agentkit/server/auth/providers/saml.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/providers/saml.py) +- **多 IDP 注册表**(热证书轮换 + 单 IDP 故障隔离,R1a 按 sub 关联 + 禁止邮箱合并): + [src/agentkit/server/auth/idp_registry.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/idp_registry.py) + +支持的 IDP 类型:飞书 / Azure AD / 阿里云 IDaaS 等任意 OIDC/SAML 合规 IDP。 + +#### 本地密码认证 + +- **bcrypt 哈希**:rounds=12(OWASP 推荐值) + [src/agentkit/server/auth/password.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/password.py) +- **JWT 会话**:HS256 签名,access 15min + refresh 7d(30d 记住我) + [src/agentkit/server/auth/jwt_utils.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py) + - V2 claims 含 `sid`(session id)+ `jti`(per-token unique id), + 支持服务端 session 撤销。 +- **Refresh token 轮换 + reuse 检测**:旧 token 进入 denylist 30s 窗口, + reuse 触发撤销该用户全部 session + [src/agentkit/server/auth/denylist.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/denylist.py) +- **登录失败处理**:JWT 验证失败返回 401,refresh token reuse 触发 + 全 session 撤销(强制重新登录)。 +- **OAuth state CSRF 防护**:OIDC state 缓存 TTL 5min,一次性消费 + ([oidc.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/providers/oidc.py) `_StateCache`)。 + +### 3.2 访问控制 / RBAC 3 级(APP-02)— 已实现 + +#### 3 级 RBAC + 9 权限位 + +[src/agentkit/server/auth/permissions.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/permissions.py) + +| 角色 | 权限 | +|------|------| +| `member` | CHAT / KB_QUERY / WORKFLOW_EXECUTE | +| `operator` | member 全部 + KB_WRITE + TERMINAL_LOCAL_USE + TERMINAL_WHITELIST_MANAGE | +| `admin` | operator 全部 + TERMINAL_SERVER_USE + USER_MANAGE + SYSTEM_CONFIG | + +权限位作为稳定字符串标识符用于 JWT payload + 前端 store + 审计日志, +不重命名既有值(向前兼容)。 + +#### 终端安全 6 层白名单(R7a) + +[src/agentkit/server/auth/terminal_security.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py) + +评估优先级(最高→最低): + +1. **Blocklist**(admin 管理,永远拒绝) +2. **Built-in safe whitelist**(`_SAFE_COMMAND_PREFIXES`) +3. **Global whitelist**(admin 管理,DB 持久化) +4. **User whitelist**(per-user,DB 持久化 + 内存缓存) +5. **Session whitelist**(per-session,仅内存) +6. **Danger detection**(`_is_dangerous`,需确认) + +**关键安全特性**:shell 操作符(`&&`、`;`、`|`、`$()`、backticks、`>`、`<`、 +换行)**永远绕过所有 whitelist 层**,强制走 danger detection — +即使 `git push` 在白名单中,`git push && rm -rf /` 仍需确认。 + +#### 终端双层授权 + +终端端点要求 RBAC 角色 + 个人授权标志双重校验: + +- `is_terminal_authorized` — 本地终端(client sidecar) +- `is_server_terminal_authorized` — 服务端终端(server PTY) + +允许 admin 按用户授权终端而不改变其角色。 + +#### SCIM token 恒定时间比较 + +SCIM bearer token 使用 `hmac.compare_digest` 恒定时间比较防时序攻击: +[src/agentkit/server/auth/scim/router.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py) +(`_verify_scim_token`)。 + +### 3.3 安全审计(APP-03)— 已实现 + +#### OTel 审计通道(U1 强制依赖) + +[src/agentkit/server/auth/audit.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py) + +审计事件类型: + +- `role_change` — RBAC 角色变更(actor/target/role_before/role_after) +- `deprovision` — 手动 deprovisioning(含 `break_glass` 标记) + +每条记录含 actor/target/reason/source/timestamp,写入 `auth_audit_log` 表 ++ 发 OTel span event(OTel 不可用时降级为 SQLite + 日志)。 + +审计来源(`source` 字段): + +- `manual` — 手动操作 +- `scim` — SCIM 自动化 +- `cron_reconciliation` — 定时对账 +- `break_glass` — 应急通道(高权限账户) + +#### SCIM 推送失败告警 + +SCIM push 失败实时告警:日志 error + OTel span event `scim.push.failure` +([scim/router.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py) +`_alert_scim_failure`)。 + +#### 终端命令审计 + +每条终端命令 + 决策结果(executed/confirmed/rejected/blocked/denied) ++ cwd + exit_code 写入 `terminal_audit_logs` 表 +([terminal_security.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py) +`write_audit_log`)。 + +#### OTel 指标 + +U1 OTel 暴露以下审计相关指标 +([src/agentkit/telemetry/metrics.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/metrics.py)): + +- `agent.request.total` / `agent.execution.duration` +- `gen_ai.usage.tokens` / `tool.call.duration` +- `prompt_cache.hit` / `prompt_cache.miss` +- `pii_filter.coverage` / `pii_filter.redacted`(U2 PII 脱敏覆盖率) + +### 3.4 通信完整性(APP-04)— 已实现 + +- **传输层 TLS**:Ingress TLS 终止(详见 `02-network.md` §3.2), + 客户端→Ingress 全程 HTTPS。 +- **JWT 签名完整性**:HS256 签名,任何 payload 字段篡改导致签名校验失败 + ([jwt_utils.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py) + `verify_token`)。 +- **mTLS 客户端证书**(下游服务):Helm Chart 预留 `secrets.mtlsClientCert` + slot,用于与 KMS/HSM、内部 API 双向 TLS(详见 `06-management.md`)。 +- **Webhook 签名校验**:入站 Webhook fail-closed,签名校验失败返回 401 + ([channels.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py))。 + +### 3.5 软件容错(APP-05)— 已实现 + +- **LLM 网关 fallback**:多 provider fallback 链 + ([src/agentkit/llm/gateway.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/llm/gateway.py))。 +- **OTel 运行时容错**:OTel exporter 连接失败时降级为 NoOpTracer, + 应用启动不崩溃([tracer.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/tracer.py) + `init_telemetry`)。 +- **PII 脱敏 fail-closed**:脱敏异常时拒绝发送至 LLM,不降级到原文 + ([pii_filter.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/llm/pii_filter.py) + `fail_closed=True` 默认)。 +- **专家团队失败回退**:所有阶段失败时回退到单 agent 模式 + (详见 AGENTS.md「专家团队模式」)。 +- **DR-fixes(U3)**:bitable 字段校验(DR-1)、LastViewDeletionError(DR-4)、 + 工具调用容错(DR-5)。 + - [src/agentkit/bitable/repository.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/bitable/repository.py) + - [src/agentkit/bitable/service.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/bitable/service.py) + - [src/agentkit/tools/bitable_tool.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/tools/bitable_tool.py) + +### 3.6 资源控制(APP-06)— 已实现 + +- **IP 限流**:[RateLimiter](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/middleware.py) + 滑动窗口(`max_requests` / `window_seconds` 可配置)。 +- **Webhook 独立限流**:[channels.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py) + 入站端点单独限流 + nonce dedup。 +- **会话超时**: + - 终端 session 闲置 1800s 自动断开 + ([terminal_server.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/terminal_server.py))。 + - JWT access token 15min 过期强制重新认证。 +- **专家名称正则校验**:`_EXPERT_NAME_RE = re.compile(r"^[a-zA-Z0-9_-]{1,64}$")` + 防止注入(项目规则)。 +- **HandoffTransport 有界队列**:`maxsize=1024`,关闭使用 sentinel 模式 + 防止无界内存增长(项目规则)。 + +### 3.7 应用账户生命周期 / SCIM(APP-07)— 已实现 + +#### SCIM 2.0 自动化 + +[src/agentkit/server/auth/scim/router.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py) + +端点: + +- `POST /scim/v2/Users` — 创建用户(随机密码,不可本地登录) +- `PATCH /scim/v2/Users/{id}` — 禁用(active=false)/ 更新字段 +- `GET /scim/v2/Users` — 列表 / 过滤(`userName eq` / `active eq`) + +Bearer token 认证(独立于 JWT,恒定时间比较)。 + +#### Deprovisioning(账户销户) + +管理员通过 `/admin/users/{id}/deprovision` 强制销户: + +1. 禁用本地用户账户(`is_active = 0`) +2. 撤销该用户所有活跃 session +3. 记录审计(actor/target/reason/source/timestamp)+ OTel +4. `break_glass=True` 时记录 `source=break_glass`(应急通道标记) + +详见 `06-management.md` §2 break-glass 告警流程。 + +#### JIT 用户创建(R1a) + +OIDC/SAML 首次登录 JIT 创建本地用户 + `user_idp_links` 行, +按 `(idp_name, sub)` 严格关联,**禁止邮箱合并**已存在账户 +([oidc.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/providers/oidc.py) +`_find_or_create_user`)。 + +### 3.8 代码安全(APP-08)— 已实现 + +- **输入验证**:所有 API 入口使用 Pydantic v2 模型校验 + (`model_config = ConfigDict(extra="forbid")` 拒绝额外字段)。 + - SCIM 模型:[src/agentkit/server/auth/scim/models.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/models.py) + - IDP 配置:[src/agentkit/server/auth/idp_registry.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/idp_registry.py) + (`OIDCConfig` / `SAMLConfig` 均 `extra="forbid"`) +- **禁止 `any` 类型**:项目规则强制使用 Pydantic 模型或 `Unknown` + (AGENTS.md)。 +- **专家名称正则校验**:`_EXPERT_NAME_RE` 防 SQL/命令注入。 +- **API Key 恒定时间比较**:`hmac.compare_digest`(项目规则)。 +- **Ruff lint + format**:`ruff check src/ && ruff format src/`(目标 py311) + 作为代码质量基线。 +- **依赖管理**:`pyproject.toml` 锁定精确版本,`pip install -e ".[dev]"` + 可复现环境。 +- **终端命令安全**:6 层白名单 + shell 操作符检测 + (详见 §3.2),防止命令注入链。 + +## 4. 测评建议 + +应用安全维度全部控制点已实现,测评时直接展示对应代码文件即可: + +1. **APP-01**:展示 oidc.py / saml.py / jwt_utils.py / password.py。 +2. **APP-02**:展示 permissions.py / terminal_security.py + RBAC 矩阵表。 +3. **APP-03**:展示 audit.py + 终端审计日志 + OTel 指标清单。 +4. **APP-04**:展示 ingress.yaml TLS + jwt_utils.py 签名校验 + channels.py + Webhook 签名。 +5. **APP-05**:展示 gateway.py fallback + pii_filter.py fail-closed + + DR-fixes 引用。 +6. **APP-06**:展示 middleware.py 限流 + terminal_server.py 超时。 +7. **APP-07**:展示 scim/router.py + deprovision 端点 + JIT 创建逻辑。 +8. **APP-08**:展示 Pydantic 模型校验 + Ruff 配置 + 终端命令安全。 diff --git a/docs/compliance/dengbao-level3/05-data.md b/docs/compliance/dengbao-level3/05-data.md new file mode 100644 index 0000000..ab2c3c5 --- /dev/null +++ b/docs/compliance/dengbao-level3/05-data.md @@ -0,0 +1,217 @@ +# 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(数据防泄漏)系统。 diff --git a/docs/compliance/dengbao-level3/06-management.md b/docs/compliance/dengbao-level3/06-management.md new file mode 100644 index 0000000..b52da74 --- /dev/null +++ b/docs/compliance/dengbao-level3/06-management.md @@ -0,0 +1,215 @@ +# 06 — 管理安全 + +> GB/T 22239-2019 第三级「安全管理」控制点映射。 + +## 1. 维度说明 + +管理安全覆盖「安全管理制度的运行」,AgentKit 自身已实现: + +- **已实现**:密钥轮换 runbook(U5,10 个 secret slot)、 + break-glass 告警流程(U4 R1b)、审计日志记录、应急隔离(销户 + session 撤销)。 +- **P0 补齐项**:变更管理流程文档化(CI/CD 流水线规范)。 +- **P1 参考**:定期安全评估流程。 +- **待评估**:应急响应预案演练(依赖客户安全团队协同)。 + +## 2. GB/T 22239-2019 三级要求(简要) + +| 控制点 ID | 要求摘要 | +|-----------|----------| +| MGT-01 | 密钥管理:密钥生成/存储/分发/轮换/销毁 | +| MGT-02 | 变更管理:变更审批/测试/回滚/审计 | +| MGT-03 | 应急响应:应急事件处置流程,隔离/恢复 | +| MGT-04 | 安全审计与评估:定期安全评估,漏洞管理 | +| MGT-05 | 配置管理:基线配置,配置变更审计 | +| MGT-06 | 应急通道(break-glass):高权限应急通道,审计追溯 | +| MGT-07 | 密钥泄露响应:泄露检测/隔离/轮换/通报 | + +## 3. AgentKit 实现映射 + +### 3.1 密钥管理(MGT-01)— 已实现 + +#### 10 个 secret slot + 轮换 runbook + +[docs/deployment/key-rotation-runbook.md](file:///Users/chiguyong/Code/Fischer-agentkit/docs/deployment/key-rotation-runbook.md) ++ [docs/deployment/secret-inventory.md](file:///Users/chiguyong/Code/Fischer-agentkit/docs/deployment/secret-inventory.md) + +| # | Slot 名称 | 用途 | 轮换周期 | 归属 | +|---|-----------|------|----------|------| +| 1 | JWT 签名密钥 | access(15m)/refresh(7d) token HS256 签名 | 90 天 | 安全团队 | +| 2 | API Key | 服务间 / SCIM / `agentkit pair` 鉴权 | 180 天 | 平台运维 | +| 3 | DB 凭据 | 应用层 PG 连接 DSN | 90 天 | DBA | +| 4 | IDP 签名证书 | OIDC/SAML IdP 签名证书 PEM(多 IDP 热轮换) | 365 天 | 身份团队 | +| 5 | 第三方 API Key | LLM provider API Key(JSON map) | 90 天 | LLM 运维 | +| 6 | TLS 服务器证书 | Ingress TLS 终止证书 + 私钥 | 365 天 | 平台运维 | +| 7 | mTLS 客户端证书 | 下游服务(KMS/HSM)mTLS | 180 天 | 安全团队 | +| 8 | KMS/HSM PKCS#11 PIN | 硬件安全模块访问 PIN | 365 天 | HSM 运维 | +| 9 | OTel exporter token | OTLP collector 鉴权 bearer | 90 天 | 可观测性团队 | +| 10 | Redis-PG 密码 | Redis requirepass + PG 服务密码 | 90 天 | DBA | + +#### 通用轮换原则 + +1. **零停机**:新密钥生效后再淘汰旧密钥,避免单点切换失败。 +2. **审计先行**:轮换前记录当前密钥指纹(hash8),轮换后校验变更。 +3. **回滚预案**:保留旧密钥值至少一个轮换周期,便于快速回滚。 +4. **权限最小化**:轮换操作仅限归属角色,操作全程审计日志。 +5. **后端无关**:适用于 Sealed Secrets 与 External Secrets 两种后端。 + +#### 密钥存储 + +- **禁止明文 Kubernetes Secret + Git 提交**(KTD-4 / R2a)。 +- 后端二选一:Sealed Secrets(Bitnami)或 External Secrets Operator + (指向 Vault / AWS SM / GCP SM / Azure KV)。 +- 渲染到统一 `-secrets` Secret,通过 `env.valueFrom.secretKeyRef` + 注入 Pod。 + +详见 [values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) +`secrets` 段。 + +#### 热证书轮换(SAML) + +SAML IDP 签名证书支持**热轮换**(不重启即时生效): +[src/agentkit/server/auth/idp_registry.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/idp_registry.py) +`update_certificate` 方法。OIDC 通过 `server_metadata_url` 自动发现 +(authlib 缓存 TTL),无需显式热轮换。 + +### 3.2 break-glass 应急通道(MGT-06 / MGT-07)— 已实现 + +#### break-glass deprovisioning + +[src/agentkit/server/routes/auth.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/auth.py) +`deprovision_user` 端点支持 `break_glass: true` 标记: + +```python +class DeprovisionRequest: + reason: str | None = None + break_glass: bool = False # 高权限账户 break-glass 标记 +``` + +`break_glass=True` 时审计记录 `source=break_glass` +([audit.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py) +`SOURCE_BREAKGLASS`),用于事后追溯应急操作。 + +#### 应急流程 + +1. **隔离**:admin 通过 deprovision 端点强制销户 + (`break_glass=True` + `reason` 说明) +2. **撤销**:自动撤销该用户全部活跃 session +3. **审计**:记录 actor/target/reason/source=break_glass/timestamp +4. **告警**:OTel span event `audit.deprovision` 接入审计通道 +5. **通报**:由安全团队人工通报(AgentKit 不自动通报,避免误报) + +#### 密钥泄露响应 + +[key-rotation-runbook.md §紧急轮换](file:///Users/chiguyong/Code/Fischer-agentkit/docs/deployment/key-rotation-runbook.md) +「紧急轮换(泄露响应)」段落: + +1. **隔离**:撤销泄露密钥(provider 控制台 / HSM / CA) +2. **轮换**:按对应 slot 步骤紧急轮换(不遵循「双密钥并行」原则, + 直接切换到新密钥并废弃旧密钥) +3. **审计**:检索泄露密钥的使用日志,确认无异常调用 +4. **通报**:通知安全团队 + 受影响用户 +5. **复盘**:记录泄露原因,加固访问控制 + +### 3.3 变更管理(MGT-02 / MGT-05)— P0 补齐项 + +#### 已实现 + +- **Git 版本控制**:所有代码 / 配置 / Helm Chart 纳入 Git, + 变更可追溯。 +- **Helm Chart checksum**:ConfigMap 变更触发 Pod rollout + ([deployment.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/deployment.yaml) + `checksum/config` annotation),配置变更自动生效。 +- **配置同步**:[config_sync.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/config_sync.py) + 支持配置版本管理 + 轮询同步。 +- **审计记录**:所有 RBAC 变更、deprovision 操作记录审计 + ([audit.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py))。 + +#### P0 补齐项:CI/CD 流水线规范 + +**当前状态:P0**。CI/CD 流水线(GitHub Actions / Gitea Actions)规范 +未文档化。 + +**P0 补齐计划**: + +1. 新增 `docs/CI-CD-STANDARDS.md`,包含: + - 分支策略(feature 分支 → PR → main) + - 必须的 CI 检查(ruff + pytest + 镜像漏洞扫描 P0) + - 部署审批流程(Staging → Production) + - 回滚流程(Helm rollback) +2. CI 集成镜像漏洞扫描(详见 `03-host.md` §3.1 P0 补齐项)。 +3. 部署变更审计:`kubectl rollout` 历史记录接入审计通道。 + +### 3.4 应急响应(MGT-03)— 待评估 + +**当前状态:待评估**。AgentKit 自身应急隔离能力已实现(销户 + session 撤销 ++ 密钥紧急轮换),但**完整应急响应预案**需与客户安全团队协同: + +- 事件分级标准(P0/P1/P2) +- 响应时限(P0 事件 15min 内响应) +- 通报链路(AgentKit admin → 客户安全团队 → 测评机构) +- 恢复流程(密钥轮换 → 服务恢复 → 数据完整性校验) + +**建议**:客户安全团队基于本套等保文档 + AgentKit 应急能力 +(销户/密钥轮换/审计日志)构建完整预案,并在认证前完成至少一次 +桌面演练。 + +### 3.5 安全审计与评估(MGT-04)— P1 参考 + +**当前状态:P1**。AgentKit 审计日志已记录,但定期评估流程未建立。 + +#### 已实现 + +- **审计日志覆盖**:RBAC 变更 / deprovision / 终端命令 / SCIM 操作 + 全部记录审计 + ([audit.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py) + + [terminal_security.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py))。 +- **OTel 指标监控**:U1 OTel 暴露应用指标,可观测性平台监控异常 + ([metrics.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/metrics.py))。 + +#### P1 补齐计划 + +1. **定期漏洞扫描**:每月对依赖执行 `pip-audit` / `safety` 扫描。 +2. **代码安全评估**:每次重大版本发布前进行 SAST 扫描 + (如 Bandit / Semgrep)。 +3. **渗透测试**:认证后每年至少一次渗透测试(客户侧组织)。 +4. **审计日志定期审查**:admin 每季度审查审计日志异常模式 + (非自动告警,依赖人工 review — P1 可引入 SIEM 自动告警)。 + +### 3.6 配置管理(MGT-05)— 已实现 + +- **Helm values 标准化**:所有可配置项集中在 + [values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml), + 含注释说明。 +- **配置优先级**:CLI 参数 > `agentkit.yaml` > 环境变量(`${VAR:-default}`) + > `.env` > 硬编码默认值(AGENTS.md)。 +- **配置版本管理**:[config_sync.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/config_sync.py) + 支持配置版本 + 轮询同步。 +- **密钥与配置分离**:含密钥的段(llm/auth/telemetry)由 env 注入, + 不进 ConfigMap;非密配置进 ConfigMap + ([values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml) + `config` 段注释)。 + +## 4. 测评建议 + +1. **MGT-01 / MGT-06 / MGT-07**:直接展示 key-rotation-runbook.md + + secret-inventory.md + audit.py break_glass 流程即可。 +2. **MGT-02 / MGT-05**:已实现部分展示 Helm Chart + config_sync, + P0 补齐 CI/CD 规范文档。 +3. **MGT-03**:待评估,由客户安全团队基于本套文档构建完整预案。 +4. **MGT-04**:P1 参考,写入整改计划(依赖扫描 + 季度审计 review)。 + +## 5. 密钥管理边界(重要说明) + +AgentKit 密钥管理的**边界**: + +1. **不持有 HSM/KMS 硬件**:HSM/KMS 由客户运维,AgentKit 通过 + PKCS#11 PIN 访问(slot 8)。 +2. **不签发证书**:TLS / mTLS 证书由客户 CA / cert-manager 签发, + AgentKit 仅消费。 +3. **不托管 LLM provider 密钥**:DashScope/DeepSeek/OpenAI/Anthropic + 的密钥在 provider 控制台生成,AgentKit 仅存储引用(slot 5)。 +4. **多实例密钥同步**:进程内 IDP 注册表不持久化,多实例部署时 + 各进程独立加载 `agentkit.yaml`;证书热轮换需配合配置同步 + (config_sync.py 轮询)或重启 + ([idp_registry.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/idp_registry.py) + ponytail 注释)。 diff --git a/docs/compliance/dengbao-level3/control-points.yaml b/docs/compliance/dengbao-level3/control-points.yaml new file mode 100644 index 0000000..02edd36 --- /dev/null +++ b/docs/compliance/dengbao-level3/control-points.yaml @@ -0,0 +1,491 @@ +# Fischer AgentKit — 等保三级控制点清单 +# +# 按 GB/T 22239-2019 第三级 6 维度组织。每个控制点含: +# id — 控制点唯一标识(DIM-NN) +# dimension — 维度(physical / network / host / application / data / management) +# title — 控制点名称 +# requirement — GB/T 22239-2019 三级要求摘要 +# implementation — AgentKit 实现映射(含状态说明) +# status — implemented / p0 / p1 / 待评估 +# implemented = 已实现,代码/配置已落地 +# p0 = 认证 readiness 必需,POC 采购关闭前补齐 +# p1 = 下一阶段补齐,写入整改计划 +# 待评估 = 依赖客户侧或需进一步评估 +# references — AgentKit 代码/配置文件绝对路径(file:/// 链接) +# +# 总计 44 个控制点:implemented=26, p0=6, p1=3, 待评估=9 + +# ============================================================================= +# 1. 物理安全(6 个,全部待评估 — 依赖客户机房) +# ============================================================================= + +- id: "PHY-01" + dimension: physical + title: "物理访问控制" + requirement: "机房出入口配置电子门禁,记录进入人员和时间" + implementation: "AgentKit 不运维物理机房。K8s 部署在客户内网,物理访问由客户机房运营方控制。AgentKit 仅提供部署形态证明(非 root 容器 + Helm Chart)。" + status: "待评估" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/deployment.yaml" + +- id: "PHY-02" + dimension: physical + title: "防盗窃和防破坏" + requirement: "主要设备设置防盗标识,机房设置监控系统" + implementation: "无物理设备责任。K8s worker node 由客户运维,机房监控由客户方提供。" + status: "待评估" + references: [] + +- id: "PHY-03" + dimension: physical + title: "防雷击" + requirement: "机房设置防雷保安器,接地电阻符合要求" + implementation: "无防雷责任。依赖客户机房防雷设施。" + status: "待评估" + references: [] + +- id: "PHY-04" + dimension: physical + title: "防火" + requirement: "机房设置火灾自动消防系统,检测报警器" + implementation: "无消防责任。依赖客户机房消防系统。" + status: "待评估" + references: [] + +- id: "PHY-05" + dimension: physical + title: "防水和防潮" + requirement: "机房安装水敏检测装置,防止水管安装" + implementation: "无防水责任。依赖客户机房防水设施。" + status: "待评估" + references: [] + +- id: "PHY-06" + dimension: physical + title: "防静电" + requirement: "机房采用防静电地板,设置静电消除器" + implementation: "无防静电责任。依赖客户机房防静电设施。" + status: "待评估" + references: [] + +# ============================================================================= +# 2. 网络安全(8 个) +# ============================================================================= + +- id: "NET-01" + dimension: network + title: "网络架构" + requirement: "划分网络区域,避免单点故障" + implementation: "单 Ingress 入口 + ClusterIP Service 架构。Ingress 是唯一对外入口,Redis/PG/OTel 全部 ClusterIP 内部访问。API 与 GUI 走分离路径(/api 与 /)。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/ingress.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + +- id: "NET-02" + dimension: network + title: "边界防护(Ingress TLS)" + requirement: "边界实施访问控制和安全过滤" + implementation: "Ingress 启用 TLS 终止,所有外网流量强制 HTTPS。TLS 证书通过 cert-manager 自动续期或手动签发(365 天轮换),私钥通过 Sealed Secret / External Secret 注入(KTD-4 / R2a)。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/ingress.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + +- id: "NET-03" + dimension: network + title: "访问控制(NetworkPolicy)" + requirement: "网络层访问控制策略,最小权限" + implementation: "P0 补齐项。Helm Chart 暂无 NetworkPolicy 模板,Pod 间东西向流量默认全通。计划新增 networkpolicy.yaml,默认 deny-all + 白名单放行(Ingress→Pod, Pod→Redis/PG/OTel)。当前缓解:Service 全部 ClusterIP,Redis/PG 由客户 K8s 网络策略保护。" + status: "p0" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/ingress.yaml" + +- id: "NET-04" + dimension: network + title: "入侵防范" + requirement: "网络入侵检测,恶意流量检测" + implementation: "应用层已实现 RateLimiter 滑动窗口限流 + Webhook 独立限流 + JWT/SCIM token 恒定时间比较。网络层 IDS/IPS 依赖客户骨干网络。P1:接入客户 SIEM,将 OTel 日志投递到客户入侵检测平台。" + status: "p1" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/middleware.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py" + +- id: "NET-05" + dimension: network + title: "安全审计(OTel)" + requirement: "网络审计日志,覆盖关键网络活动" + implementation: "OpenTelemetry(U1 强制依赖)实现网络活动审计:FastAPI Instrumentor 自动埋点每个 HTTP 请求 span;RBAC 变更/SCIM 失败/终端命令写入审计 + OTel span event;OTLP gRPC 导出到内部 collector。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/setup.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/metrics.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py" + +- id: "NET-06" + dimension: network + title: "恶意代码防范" + requirement: "网络边界恶意代码检测" + implementation: "AgentKit 不在网络边界位置,恶意代码检测由客户网络骨干(防病毒网关/沙箱)负责。AgentKit 侧缓解:容器镜像来自可信 CI 构建,不在运行时下载可执行文件;终端命令受 6 层白名单 + 危险检测约束。" + status: "待评估" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py" + +- id: "NET-07" + dimension: network + title: "安全审计日志保留(180 天)" + requirement: "日志保留期满足合规要求(≥180 天)" + implementation: "P0 补齐项。auth_audit_log 与 terminal_audit_logs 表无自动清理/归档策略。计划:Helm values 增加 audit.retentionDays=180(KTD-9),实现归档 CronJob 导出超过 180 天记录到对象存储并清理主表,OTel collector 配置 180 天保留策略。" + status: "p0" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py" + +- id: "NET-08" + dimension: network + title: "资源控制(会话/带宽)" + requirement: "会话与带宽限制,防止资源耗尽" + implementation: "容器层 Pod resources requests/limits(CPU 250m~1000m / Mem 512Mi~2Gi);应用层 RateLimiter IP 滑动窗口 + Webhook 独立限流;终端 session 1800s 闲置断开;JWT access 15min 强制重新认证。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/middleware.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/terminal_server.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py" + +# ============================================================================= +# 3. 主机安全(7 个,以容器/Pod 为单元) +# ============================================================================= + +- id: "HST-01" + dimension: host + title: "身份鉴别(ServiceAccount)" + requirement: "设备/系统身份标识与鉴别" + implementation: "AgentKit Pod 使用专用 ServiceAccount(不共享 default SA),Helm Chart 自动创建。可选 workload identity 注入 projected SA token 用于访问云 KMS/STS。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/serviceaccount.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + +- id: "HST-02" + dimension: host + title: "访问控制(Pod 安全上下文)" + requirement: "操作系统/账户权限最小化,远程管理受控" + implementation: "podSecurityContext.runAsNonRoot=true(UID/GID 1000);securityContext.allowPrivilegeEscalation=false + capabilities.drop=[ALL];readOnlyRootFilesystem=false(需写临时文件,通过 emptyDir 挂载 /tmp 隔离);未启用特权模式。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/deployment.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/Dockerfile" + +- id: "HST-03" + dimension: host + title: "安全审计(容器日志标准化采集)" + requirement: "设备审计日志,覆盖系统管理活动" + implementation: "已实现基础审计:stdout/stderr 由 K8s 采集 + OTel trace 导出 + auth_audit_log 表 + terminal_audit_logs 表 + OTel span event。P0 补齐:容器日志到客户日志平台的标准化采集链路 + 审计日志 JSON 化便于 SIEM 解析 + 180 天保留(与 NET-07 协同)。" + status: "p0" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/setup.py" + +- id: "HST-04" + dimension: host + title: "入侵防范(容器层)" + requirement: "主机入侵检测,系统加固" + implementation: "容器层已实现:非 root + drop ALL capabilities 限制系统调用;allowPrivilegeEscalation=false 阻止提权;资源 limits 防失控;Liveness/Readiness 探针故障自动重启。node 层 HIDS(Falco/OSSEC)依赖客户侧。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/deployment.yaml" + +- id: "HST-05" + dimension: host + title: "恶意代码防范(主机防病毒)" + requirement: "主机防病毒,恶意代码检测" + implementation: "AgentKit 容器内不部署防病毒(无文件系统持久化,镜像来自可信 CI)。K8s node 层主机防病毒/HIDS 由客户运维。依赖客户机房 node 安全基线。" + status: "待评估" + references: [] + +- id: "HST-06" + dimension: host + title: "资源控制(CPU/内存/磁盘)" + requirement: "CPU/内存/磁盘限制,会话超时" + implementation: "Pod resources requests/limits(CPU 250m~1000m / Mem 512Mi~2Gi);应用层 RateLimiter;终端 session 1800s 闲置断开;JWT access 15min / refresh 7d。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/middleware.py" + +- id: "HST-07" + dimension: host + title: "镜像与补丁管理" + requirement: "系统补丁及时更新,镜像来源可信" + implementation: "P0 补齐项。已实现:多阶段构建 + 非 root appuser(UID 1001)+ python:3.11-slim 基础镜像 + HEALTHCHECK。P0 待补:CI 集成 Trivy 镜像漏洞扫描(HIGH/CRITICAL 阻断)+ image.digest 不可变引用。P1 增强:distroless 基础镜像 + cosign 签名。" + status: "p0" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/Dockerfile" + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + +# ============================================================================= +# 4. 应用安全(8 个,全部已实现 — AgentKit 核心责任) +# ============================================================================= + +- id: "APP-01" + dimension: application + title: "身份鉴别(SSO 多 IDP + JWT)" + requirement: "用户身份标识与鉴别,口令复杂度,登录失败处理" + implementation: "U4 SSO 多 IDP(OIDC authlib + SAML python3-saml,热证书轮换,R1a 按 sub 关联禁止邮箱合并);本地密码 bcrypt rounds=12;JWT HS256 access 15min + refresh 7d(30d 记住我)含 sid+jti claims;refresh token 轮换 + reuse 检测撤销全 session;OAuth state CSRF 防护 TTL 5min 一次性消费。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/providers/oidc.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/providers/saml.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/idp_registry.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/password.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/denylist.py" + +- id: "APP-02" + dimension: application + title: "访问控制(RBAC 3 级 + 终端 6 层)" + requirement: "基于角色的访问控制,最小权限,默认拒绝" + implementation: "3 级 RBAC(member/operator/admin)+ 9 权限位(CHAT/KB_QUERY/KB_WRITE/WORKFLOW_EXECUTE/TERMINAL_LOCAL_USE/TERMINAL_SERVER_USE/TERMINAL_WHITELIST_MANAGE/USER_MANAGE/SYSTEM_CONFIG)。R7a 终端安全 6 层白名单(blocklist→builtin→global→user→session→danger),shell 操作符永远绕过白名单强制走 danger detection。终端双层授权(RBAC 角色 + 个人授权标志)。SCIM token 恒定时间比较。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/permissions.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py" + +- id: "APP-03" + dimension: application + title: "安全审计(OTel + audit.py)" + requirement: "应用审计日志,覆盖用户操作关键事件" + implementation: "U1 OTel 强制依赖。审计事件:role_change / deprovision(含 break_glass 标记),写入 auth_audit_log 表 + OTel span event(OTel 不可用降级 SQLite+日志)。SCIM 推送失败 span event scim.push.failure。终端命令审计 terminal_audit_logs(决策 + cwd + exit_code)。OTel 指标:agent.request.total / pii_filter.coverage 等。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/metrics.py" + +- id: "APP-04" + dimension: application + title: "通信完整性(TLS + JWT + Webhook 签名)" + requirement: "传输完整性保护,防篡改" + implementation: "传输层 Ingress TLS 终止(HTTPS);JWT HS256 签名校验(篡改即失败);Webhook 入站 fail-closed 签名校验失败返回 401;mTLS 客户端证书(Helm 预留 secrets.mtlsClientCert slot 用于下游 KMS/HSM)。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/ingress.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py" + +- id: "APP-05" + dimension: application + title: "软件容错(fallback + fail-closed)" + requirement: "错误处理,故障隔离,降级机制" + implementation: "LLM 网关多 provider fallback;OTel 运行时错误降级 NoOpTracer 不崩溃;PII 脱敏 fail-closed(异常拒绝发送不降级原文,默认 fail_closed=True);专家团队全失败回退单 agent;U3 DR-fixes(bitable 字段校验 DR-1 / LastViewDeletionError DR-4 / 工具调用容错 DR-5)。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/llm/gateway.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/tracer.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/llm/pii_filter.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/bitable/repository.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/bitable/service.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/tools/bitable_tool.py" + +- id: "APP-06" + dimension: application + title: "资源控制(限流 + 会话超时)" + requirement: "会话并发控制,超时自动断开" + implementation: "RateLimiter IP 滑动窗口 + Webhook 独立限流 + nonce dedup;终端 session 1800s 闲置断开;JWT access 15min 过期;专家名称正则校验防注入;HandoffTransport 有界队列 maxsize=1024 + sentinel 关闭模式。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/middleware.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/terminal_server.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py" + +- id: "APP-07" + dimension: application + title: "应用账户生命周期(SCIM 2.0 + JIT + deprovision)" + requirement: "开户/变更/销户审计,SCIM 自动化" + implementation: "SCIM 2.0 端点(POST/PATCH/GET Users,bearer token 恒定时间比较);OIDC/SAML JIT 创建本地用户 + user_idp_links(R1a 按 sub 关联禁止邮箱合并,随机密码不可本地登录);deprovision 端点禁用账户 + 撤销全 session + 审计(含 break_glass 标记)。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/providers/oidc.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/auth.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py" + +- id: "APP-08" + dimension: application + title: "代码安全(输入验证 + 依赖管理)" + requirement: "输入验证,输出编码,依赖漏洞管理" + implementation: "Pydantic v2 模型校验(extra=forbid 拒绝未知字段,SCIM/IDP 配置均启用);禁止 any 类型(项目规则,用 Pydantic 模型或 Unknown);专家名称正则 _EXPERT_NAME_RE 防 SQL/命令注入;API Key 恒定时间比较 hmac.compare_digest;Ruff lint+format(py311);pyproject.toml 锁定精确版本;终端 6 层白名单防命令注入链。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/models.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/idp_registry.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py" + +# ============================================================================= +# 5. 数据安全(8 个) +# ============================================================================= + +- id: "DAT-01" + dimension: data + title: "数据完整性(PG + pgvector)" + requirement: "数据传输/存储完整性,校验机制" + implementation: "PostgreSQL 事务 ACID 保证 + pgvector 扩展存储向量记忆;SQLAlchemy 2 async ORM 应用层事务;JWT HS256 签名防篡改;Webhook fail-closed 签名校验;Pydantic extra=forbid 防数据注入。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py" + +- id: "DAT-02" + dimension: data + title: "数据保密性(PII 脱敏 U2)" + requirement: "敏感数据加密存储/传输,密钥管理" + implementation: "U2 PII 脱敏 hook:正则版(手机/邮箱/身份证/银行卡)+ ner_hook(客户内网 NER 模型优先)+ fail-closed(异常拒绝发送不降级原文,默认 fail_closed=True)+ hash 审计(sha256 前 8 位,仅 hash 不含原文)。身份证正则优先于手机避免误匹配。OTel 指标 pii_filter.coverage / pii_filter.redacted。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/llm/pii_filter.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/metrics.py" + +- id: "DAT-03" + dimension: data + title: "数据备份与恢复(PG backup runbook)" + requirement: "重要数据定期备份,恢复演练" + implementation: "P0 补齐项。已实现:PostgreSQL 持久化 + WAL 默认开启 + Redis AOF/RDB(客户运维)。P0 待补:新增 docs/deployment/pg-backup-runbook.md(每日 pg_dump 保留 7 天 + WAL 归档 PITR + 季度恢复演练 + 备份加密 SM4/AES-256);Helm Chart 增加 backup 段(可选 pg-backup sidecar/CronJob)。" + status: "p0" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + +- id: "DAT-04" + dimension: data + title: "剩余信息保护(session revoke)" + requirement: "鉴别信息/文件/内存空间释放前清理" + implementation: "JWT V2 含 sid+jti claims,中间件校验 session 是否服务端撤销;销户撤销全 session;refresh token 轮换旧 token 进 denylist 30s 窗口;token reuse 检测撤销全 session;denylist 存 SHA-256 hash 不存明文;JIT/SCIM 用户随机密码不可本地登录。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/denylist.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/auth.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py" + +- id: "DAT-05" + dimension: data + title: "个人信息保护(PII 最小化)" + requirement: "PII 采集/处理/传输最小化与脱敏" + implementation: "PII 脱敏后原文不落盘(仅 hash 用于审计),LLM prompt 不含原文 PII;PII 按类型分级(id_card/phone/email/bank_card),不同类型 hash 独立记录;记忆 4 层架构(SOUL/USER/MEMORY/DAILY)按敏感度存储;数据最小化原则。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/llm/pii_filter.py" + +- id: "DAT-06" + dimension: data + title: "数据采集与分类分级" + requirement: "按敏感度分级保护" + implementation: "PII 按 4 类分级(id_card/phone/email/bank_card)独立 hash 审计;记忆 4 层架构(SOUL 最敏感→DAILY 最不敏感);PII 脱敏覆盖发送至 LLM 的 prompt(边界:不覆盖终端命令/上传文档/bitable 结构化数据,由客户自行控制)。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/llm/pii_filter.py" + +- id: "DAT-07" + dimension: data + title: "数据销毁" + requirement: "数据销毁审计,不可恢复" + implementation: "账户销户 deprovision 禁用账户+撤销全 session;审计记录不可删除(审计表无 delete 接口,admin 不可删除审计);PII 原文脱敏后不落盘无需专门销毁;PG 数据销毁由客户 DBA 发起 SQL 记录审计。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/auth.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py" + +- id: "DAT-08" + dimension: data + title: "国密算法合规(R11a)" + requirement: "敏感数据加密使用国密算法(政企客户要求)" + implementation: "P1 参考。当前使用国际算法:TLS(AES-GCM)/ bcrypt 密码哈希 / HS256 JWT / SHA-256 PII hash。未使用国密(SM2/SM3/SM4/SM9)。P1 升级路径:JWT 签名→SM2-HMAC、密码哈希→SM3(双算法并行兼容)、PII hash→SM3、TLS→国密套件、PG 字段级加密→SM4 TDE。注:国密不阻碍等保三级认证(三级要求加密而非国密),但政企客户常要求国密合规。" + status: "p1" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/password.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/llm/pii_filter.py" + +# ============================================================================= +# 6. 管理安全(7 个) +# ============================================================================= + +- id: "MGT-01" + dimension: management + title: "密钥管理(10 secret slot + 轮换 runbook)" + requirement: "密钥生成/存储/分发/轮换/销毁" + implementation: "U5 10 个 secret slot(JWT/API Key/DB/IDP/第三方API/TLS/mTLS/KMS-HSM/OTel/Redis-PG)含轮换周期(90~365 天)。禁止明文 K8s Secret+Git 提交(KTD-4/R2a),后端二选一:Sealed Secrets 或 External Secrets Operator。SAML IDP 证书热轮换(不重启即时生效,idp_registry.update_certificate)。通用原则:零停机双密钥并行+审计先行+回滚预案+权限最小化。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/docs/deployment/key-rotation-runbook.md" + - "file:///Users/chiguyong/Code/Fischer-agentkit/docs/deployment/secret-inventory.md" + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/idp_registry.py" + +- id: "MGT-02" + dimension: management + title: "变更管理(CI/CD 规范)" + requirement: "变更审批/测试/回滚/审计" + implementation: "P0 补齐项。已实现:Git 版本控制所有代码/配置/Helm Chart;Helm Chart checksum/config annotation ConfigMap 变更触发 rollout;config_sync.py 配置版本管理+轮询同步;审计记录 RBAC 变更。P0 待补:新增 docs/CI-CD-STANDARDS.md(分支策略+CI 检查 ruff/pytest/镜像扫描+部署审批+回滚流程);CI 集成镜像漏洞扫描(与 HST-07 协同);部署变更审计接入。" + status: "p0" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/deployment.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/config_sync.py" + +- id: "MGT-03" + dimension: management + title: "应急响应" + requirement: "应急事件处置流程,隔离/恢复" + implementation: "待评估。AgentKit 自身应急隔离能力已实现(销户+session 撤销+密钥紧急轮换,见 MGT-06/MGT-07),但完整应急响应预案需与客户安全团队协同:事件分级标准+响应时限+通报链路+恢复流程。建议客户基于本套等保文档+AgentKit 应急能力构建完整预案,认证前完成至少一次桌面演练。" + status: "待评估" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/docs/deployment/key-rotation-runbook.md" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/auth.py" + +- id: "MGT-04" + dimension: management + title: "安全审计与评估" + requirement: "定期安全评估,漏洞管理" + implementation: "P1 参考。已实现:审计日志覆盖 RBAC 变更/deprovision/终端命令/SCIM 操作;OTel 指标监控异常。P1 补齐:每月依赖漏洞扫描(pip-audit/safety);每次重大版本发布前 SAST 扫描(Bandit/Semgrep);认证后每年至少一次渗透测试(客户侧组织);admin 每季度审查审计日志异常模式(P1 可引入 SIEM 自动告警)。" + status: "p1" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/metrics.py" + +- id: "MGT-05" + dimension: management + title: "配置管理(Helm values + 配置同步)" + requirement: "基线配置,配置变更审计" + implementation: "Helm values 标准化所有可配置项含注释;配置优先级 CLI>agentkit.yaml>环境变量>.env>硬编码默认;config_sync.py 配置版本管理+轮询同步;密钥与配置分离(含密钥段由 env 注入不进 ConfigMap,非密配置进 ConfigMap)。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/config_sync.py" + +- id: "MGT-06" + dimension: management + title: "应急通道(break-glass)" + requirement: "高权限应急通道,审计追溯" + implementation: "U4 R1b break-glass deprovisioning:/admin/users/{id}/deprovision 端点支持 break_glass=true 标记,审计记录 source=break_glass(SOURCE_BREAKGLASS)。流程:隔离(销户)→撤销全 session→审计(actor/target/reason/source/timestamp)→OTel span event audit.deprovision 接入审计通道→人工通报。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/auth.py" + - "file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py" + +- id: "MGT-07" + dimension: management + title: "密钥泄露响应" + requirement: "泄露检测/隔离/轮换/通报" + implementation: "key-rotation-runbook.md §紧急轮换(泄露响应)段落:1.隔离(撤销泄露密钥 provider控制台/HSM/CA)→2.轮换(按对应 slot 步骤紧急轮换,不遵循双密钥并行直接切换废弃旧密钥)→3.审计(检索泄露密钥使用日志确认无异常)→4.通报(安全团队+受影响用户)→5.复盘(记录原因加固访问控制)。" + status: "implemented" + references: + - "file:///Users/chiguyong/Code/Fischer-agentkit/docs/deployment/key-rotation-runbook.md"