Agent Governance Toolkit 多租户隔离部署安全清单：从 Kubernetes 命名空间隔离到租户级策略引擎的落地指南-平芜编程栈

Agent Governance Toolkit 多租户隔离部署安全清单：从 Kubernetes 命名空间隔离到租户级策略引擎的落地指南

【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit

面向多租户生产环境部署的 AI Agent Governance Toolkit，其安全模型的核心在于"隔离"：租户与租户之间的数据、信任状态、审计流与策略执行都必须物理或逻辑上彼此独立。本文基于仓库内 docs/security/tenant-isolation-checklist.md 给出的部署前安全清单，逐项展开 Kubernetes 命名空间隔离、信任存储分离、审计日志分离、数据驻留、多租户策略引擎与出口（Egress）控制等六大维度的配置方法与底层原理，并结合 agentmesh 策略引擎与 TypeScript SDK 信任存储的源码实现，说明每项清单在工具包内部的落地机制。读完本文，你可以照单配置出一套"租户不可见、不可达、不可共享"的治理部署。

一、部署前总览：多租户隔离的六大支柱

清单将多租户部署安全拆解为六个互不重叠的检查维度，每个维度都对应一个"如果做不好会怎样"的明确风险：

维度	要解决的风险	清单要点
Kubernetes 命名空间隔离	跨租户网络可达、越权操作	每租户独立 Namespace + NetworkPolicy + RBAC + Pod Security
信任存储分离	信任评分被跨租户污染、串扰	每租户独立信任持久化文件与评分作用域
审计日志分离	审计流混淆、跨租户查询	每租户独立日志流与 sink 路由
数据驻留	数据跨区域流动违反合规	Node 亲和性与存储拓扑约束
多租户策略引擎	策略互相覆盖、越权访问	租户级 scope 策略 + 默认拒绝跨租户访问
出口控制	数据外泄、C2 通信	Egress NetworkPolicy + DNS 限制 + 出口代理

这六大支柱共同构成"纵深防御"：即使某一层（例如命名空间）被绕过，信任存储、策略引擎或出口控制仍会兜底。下面按部署顺序逐一展开。

二、Pre-Deployment：Kubernetes 命名空间隔离

清单要求为每个租户创建专属命名空间，并收紧网络、权限与资源边界：

每租户独立命名空间（kubectl create ns tenant-<id>）
NetworkPolicy 限制跨命名空间流量
RBAC 角色仅绑定到租户命名空间（不创建集群级绑定）
Pod Security Standards 设为restricted配置档
每租户命名空间配置资源配额（CPU、内存、Pod 数）
启用静态加密（etcd encryption provider）

其中最关键的是第一条 NetworkPolicy。清单给出的默认拒绝示例把策略绑定到具体租户命名空间tenant-acme，podSelector: {}匹配该命名空间内所有 Pod，policyTypes: [Ingress]只管制入站流量，而ingress.from.podSelector: {}的含义是"仅允许来自同一命名空间的 Pod"——即同一租户内部互通不受影响，跨命名空间（跨租户）的入站访问被静默丢弃：

# NetworkPolicy: deny all cross-namespace ingress apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: deny-cross-namespace namespace: tenant-acme spec: podSelector: {} policyTypes: [Ingress] ingress: - from: - podSelector: {} # same namespace only

实操提示：该策略只防"入站"，不防"出站"。Agent 侧车（sidecar）对外发起连接属于 Egress 范畴，需配合本文第六节的出口策略一并下发。此外，RBAC 建议为每个租户单独创建 Role/ RoleBinding 并锚定到对应命名空间，避免任何ClusterRoleBinding跨租户授权；etcd 加密应在集群层面开启（--encryption-provider-config），确保即使 etcd 数据被窃取，租户密钥与 Secret 也不会明文泄露。

三、信任存储分离：每个租户一个独立的信任世界

清单要求信任状态"零共享"：

每租户独立信任存储（无共享状态）
信任评分按租户命名空间限定作用域
未经显式联合（federation），禁止跨租户信任传播

清单给出了通过 ConfigMap 注入的每租户信任配置：

# Per-tenant trust store config apiVersion: v1 kind: ConfigMap metadata: name: agt-trust-config namespace: tenant-acme data: AGT_TRUST_PERSIST_PATH: "/data/trust/tenant-acme.json" AGT_TRUST_THRESHOLD: "500"

这两个环境变量对应工具包信任子系统的两个核心配置维度：持久化路径与信任阈值。在 TypeScript SDK 的 src/trust.ts 中，信任状态由TrustStore类管理，底层是一个"类贝叶斯"评分模型：每次成功交互给评分加分（第 89 行state.score = Math.min(1, state.score + ...)），每次失败交互扣分（第 99 行），并通过可配置的衰减因子decayFactor让陈旧信任随时间自然回落（第 125 行）。

持久化路径（persistPath）决定了信任状态落在哪里：构造函数在第 43～46 行对路径做校验，拒绝任何包含..的路径穿越组件，防止恶意租户配置把信任文件写到其他租户目录；persist()在第 178～184 行把信任快照写入 JSON 文件，load()在第 191～198 行读取时还会把反序列化出的评分钳制到合法区间[0, 1]，避免脏数据把信任分数"撑爆"。

评分的作用域隔离则体现在阈值上。默认阈值定义在 src/trust.ts：

const DEFAULT_THRESHOLDS = { untrusted: 0.0, provisional: 0.3, trusted: 0.6, verified: 0.85, };

computeTier()（第 130～135 行）按评分把 Agent 划分为 Untrusted / Provisional / Trusted / Verified 四个信任层级。清单里的AGT_TRUST_THRESHOLD: "500"是一个部署侧阈值——例如要求"信任评分达到 500 才允许该租户的 Agent 访问敏感操作"，它与代码内的四档层级配合使用：存储按租户隔离后，一个租户内 Agent 的信任累积绝不会抬高另一个租户 Agent 的信任等级，这正是"无跨租户信任传播"的实现基础。

四、审计日志分离：租户流互不混淆

清单要求：

每租户独立审计日志流
审计 sink 按命名空间标签路由
RBAC 阻止跨租户审计查询

清单给出了 Fluent Bit 的租户级路由示例，用grep过滤器只匹配tenant-acme命名空间的日志，再输出到独立的 Azure Blob 容器audit-tenant-acme：

# Fluent Bit filter for tenant-scoped log routing [FILTER] Name grep Match kube.* Regex kubernetes.namespace_name ^tenant-acme$ [OUTPUT] Name azure_blob Match kube.* Account_name ${STORAGE_ACCOUNT} Container_name audit-tenant-acme Shared_key ${STORAGE_KEY} Path audit/

实操提示：Regex中的^tenant-acme$必须锚定首尾，否则tenant-acme-evil之类的命名空间也会被误路由进同一容器。落地时建议把"容器名/路径含租户 ID"作为命名约定固化为组织规范，并在查询侧用 RBAC 把审计检索权限限制到对应租户命名空间，阻断跨租户审计查询（清单第三项）。

工具包侧，审计事件由 agent-governance-typescript/src/audit.ts 等模块产生，并在 docs/adr/0021-cloudevents-envelope-for-mesh-audit.md 中确立了以 CloudEvents 信封承载审计事件的格式——事件携带的元数据字段（如来源命名空间）正是上方 Fluent Bitgrep过滤器做租户路由所依赖的输入。若需审计链防篡改证据，可进一步参考 docs/adr/0017-merkle-chain-for-audit-tamper-evidence.md 的 Merkle 链方案。

五、数据驻留：把租户数据和存储钉在合规区域

数据驻留的通用做法是"让计算和存储都显式声明区域约束"，清单给出了两层：

5.1 Node 亲和性：区域钉扎

# Pin tenant workloads to specific region apiVersion: v1 kind: Pod metadata: name: agt-sidecar namespace: tenant-acme spec: nodeSelector: topology.kubernetes.io/region: eastus >apiVersion: v1 kind: PersistentVolumeClaim metadata: name: agt-audit-pvc namespace: tenant-acme spec: accessModes: [ReadWriteOnce] storageClassName: managed-premium-zrs resources: requests: storage: 10Gi # Ensure storage stays in tenant's region volumeMode: Filesystem

storageClassName: managed-premium-zrs选用区域冗余存储（ZRS），在租户区域内提供多可用区冗余；ReadWriteOnce保证同一时刻只有一个 Pod 挂载，避免跨 Pod 并发写审计数据导致串扰。搭配topology.kubernetes.io/zone的存储拓扑约束，可确保 PVC 动态供给的卷落在租户所在区域，实现"计算与存储同区"的驻留闭环。

六、多租户策略引擎：scope=tenant 与默认拒绝

清单给出了两份租户级策略资产，这是整份清单中与代码贴合最深的部分。

6.1 租户作用域策略 YAML

# Policy scoped to tenant namespace apiVersion: "1.0" version: "1.0" name: tenant-acme-policy scope: tenant agent: "*" rules: - name: restrict-data-access condition: "tenant_id == 'acme'" ruleAction: deny description: "Block cross-tenant data access" priority: 100 - name: rate-limit-per-tenant condition: "tenant_id == 'acme'" ruleAction: rate_limit limit: "100/minute"

两个condition都以tenant_id为判断依据，第一条对非本租户的数据访问直接deny，第二条对acme租户的请求施加每分钟 100 次的限流。

在 agentmesh 策略引擎源码 agentmesh/governance/policy.py 中，这些字段都有对应实现：

scope字段（第 442～444 行）：定义为PolicyScope.GLOBAL/TENANT/AGENT三档，注释明确"Policy scope: global, tenant, or agent"；
作用域解析（第 1052～1053 行）：注释写明合并语义为most_specific_wins——"Agent-scoped > tenant > global"，同作用域内以priority决胜。这意味着清单中的scope: tenant策略优先级高于任何 global 策略，租户管理员无法用全局策略覆盖本租户的拒绝规则；
限流解析：limit: "100/minute"由parse_rate_limit()（第 44～83 行）解析为(100, 60)元组，格式必须是"<count>/<period>"，period 仅接受second/minute/hour/day四种；格式非法时在策略加载期直接抛ValueError（fail fast），而不会在评估期才崩溃。速率计数在 src/agentmesh/governance/policy.py 处按 agent、policy、rule 三级分别计数，天然支持"每租户每 Agent"的独立限流桶。
apiVersion兼容（第 29～33 行）：当前版本为governance.toolkit/v1，清单中的"1.0"仍被识别但标记为 deprecated 并提示迁移，未知版本会抛ValueError。

6.2 跨租户通信默认拒绝

from agentmesh import PolicyEngine engine = PolicyEngine() # Load tenant-specific policy engine.load_from_yaml(f"policies/tenant-{tenant_id}.yaml") # Evaluate with tenant context decision = engine.evaluate( action="data.read", context={"tenant_id": "acme", "source_tenant": "acme", "target_tenant": "acme"} ) # Cross-tenant requests denied by default cross_tenant = engine.evaluate( action="data.read", context={"tenant_id": "acme", "source_tenant": "acme", "target_tenant": "contoso"} ) assert cross_tenant.label() == "deny"

这段代码展示了多租户策略引擎的调用契约：evaluate()接受action与携带tenant_id、source_tenant、target_tenant的上下文。同租户请求（target_tenant == acme）放行；一旦target_tenant指向contoso，策略引擎基于tenant_id == 'acme'条件的拒绝规则返回deny——跨租户访问默认被拒，无需为每个租户对显式编写拒绝规则。

策略引擎的确定性保证也是多租户安全的重要一环：policy.py 头注释声明"Policy evaluation latency <5ms with 100% deterministic results"，而 docs/adr/0004-keep-policy-evaluation-deterministic.md 是这一约束的架构决策依据——确定性意味着同一租户上下文永远得到同一判定，不会因运行时状态不同而产生可被探测的判定漂移。若需在策略评估出错时保持安全姿态，可参考 docs/adr/0013-fail-closed-on-policy-evaluation-errors.md 的 fail-closed 设计。

七、出口控制：堵住数据外泄通道

清单要求三条：

Egress NetworkPolicy 限制出站流量
DNS 策略只允许解析白名单域名
通过出口代理防止数据外泄

清单的 Egress 策略只放行两件事：到治理系统命名空间agt-system的 443 端口（治理 API），以及 DNS（UDP 53）：

# Egress NetworkPolicy: allow only governance API + DNS apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: restrict-egress namespace: tenant-acme spec: podSelector: {} policyTypes: [Egress] egress: - to: - namespaceSelector: matchLabels: name: agt-system ports: - port: 443 - to: # DNS - namespaceSelector: {} ports: - port: 53 protocol: UDP

实操提示：这是"最小可用"基线。生产环境建议再追加：① 用 CoreDNS 级策略或dnsPolicy限制解析域名为批准列表；② 把对外出站流量（如模型 API 调用）收敛到受管出口代理，在代理层做内容过滤与 DLP 检测；③ 注意 Egress 与 Ingress 策略是独立的，本节的restrict-egress与第二节的deny-cross-namespace需要同时存在，才能形成"进出双向收紧"的闭环。

八、把清单落地为发布门槛

综合以上各节，一套完整的多租户隔离落地流程可以归纳为：

预检阶段：每租户创建命名空间，同步下发 Ingress（第二节）与 Egress（第七节）NetworkPolicy、租户级 RBAC、restrictedPod Security 与资源配额；
信任阶段：通过 ConfigMap 注入每租户的AGT_TRUST_PERSIST_PATH（隔离持久化文件）与信任阈值，确认无共享信任状态；
审计阶段：配置 Fluent Bit 按kubernetes.namespace_name精确路由到租户独立 sink，并用 RBAC 锁定查询权限；
驻留阶段：为工作负载声明 region/zone 亲和性与 ZRS 存储类，校验 PVC 拓扑约束；
策略阶段：为每租户加载scope: tenant的 YAML 策略（含默认拒绝跨租户规则与租户级限流），并用evaluate()回归验证source_tenant != target_tenant时返回deny；
验收阶段：以上每项均可在对应源码中找到实现依据——信任隔离见 src/trust.ts，策略作用域与限流解析见 policy.py，审计事件格式见 docs/adr/0021-cloudevents-envelope-for-mesh-audit.md。

仓库内还提供了与本文配套的姊妹文档 docs/security/tenant-isolation.md（同一清单的完整版）以及威胁视角文档 docs/security/threat-model.md，可作为多租户部署安全评审的补充材料。遵循本清单的每一核对项，即可将 Agent Governance Toolkit 部署为"网络不可达、信任不可共享、策略不可覆盖、审计不可混淆"的隔离多租户环境。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考