Agent Sandbox 安全最佳实践

专属 VSwitch（子网隔离）

ACS Agent Sandbox 支持为沙箱 Pod 指定独立的 VSwitch，将沙箱流量与集群控制面和业务 Pod 在网段层面物理隔离。

annotations:
  network.alibabacloud.com/vswitch-ids: "vsw-****"

企业安全组（VPC 边界防护）

支持为沙箱 Pod 配置专属企业安全组，提供 VPC 级别的粗粒度边界防护。

annotations:
  network.alibabacloud.com/security-group-ids: "sg-****"

TrafficPolicy 和 GlobalTrafficPolicy（L4 Pod 级微隔离）

基于 Poseidon 组件提供 Pod 粒度的 L4 出入站流量控制，支持 IP 段、Service Label 和 FQDN 匹配。ACS 提供两种资源，共享相同 Spec，区别在作用范围：

策略执行规则：优先级 1-1000（数值越小越高）→ 同优先级内按定义顺序 → 命中即止 → Pod 被任一策略选中后，未显式允许的流量默认拒绝。具体规则在前、兜底规则在后。

FQDN 匹配限制：不支持泛域名、依赖动态 DNS 解析有延迟、多域名解析到同 IP 时无法区分 allow/deny。建议仅用于内部服务；公网/泛域名场景改用 SecurityProfile 的 L7 域名匹配。

SecurityProfile（L7 增强型出站控制）

SecurityProfile 是 ACS Agent Sandbox 独有的 L7 层出站流量管控能力，通过自动注入的 traffic-proxy Sidecar 透明拦截所有出站请求，在 egress-gateway 层进行安全策略评估。

架构流程：

核心组件（部署在 sandbox-traffic-system 命名空间）：

SecurityProfile 支持的匹配维度：

规则匹配逻辑：

• 同一 match 条目内多个字段为 AND 关系

• 多个 match 条目之间为 OR 关系

• 规则链按顺序执行，Block/Bypass 为终结动作，匹配后停止后续评估

支持 HTTPS 流量管控：启用 TLS termination 后，egress-gateway 对指定域名的 HTTPS 请求进行 TLS 终止，解密后应用 SecurityProfile 规则，对沙箱应用完全透明。

TrafficPolicy和SecurityProfile的典型能力如下：

实践1：使用 enhanced-traffic-policy 模式

注意：enhanced-traffic-policy 模式同时包含 L4（TrafficPolicy）和 L7（SecurityProfile）能力。选择该模式即可同时使用两种策略，无需单独启用 traffic-policy 模式。

Agent Sandbox 通过 network.alibabacloud.com/network-policy-mode 注解（Annotation）指定网络策略模式：

network.alibabacloud.com/network-policy-mode: enhanced-traffic-policy

一个完整的配置示例如下：

apiVersion: agents.kruise.io/v1alpha1
kind: Sandbox
metadata:
  name: sample
  namespace: default
spec:
  runtimes:
  - name: agent-runtime
  template:
    metadata:
      labels:
        agent: sample
        alibabacloud.com/compute-class: agent-sandbox
      annotations:
        network.alibabacloud.com/network-policy-mode: enhanced-traffic-policy
    spec:
      containers:
      - name: sandbox
        image: registry-cn-zhangjiakou.ack.aliyuncs.com/acs/code-interpreter:v1.6  # 替换成实际集群所在的地域
        command: ["/bin/sleep", "infinity"]

实践2：默认拒绝所有内网访问

沙箱中运行的是不可信的 AI 生成代码，必须假设沙箱内代码可能被提示注入攻击。配置 TrafficPolicy 默认拒绝所有内网段：

apiVersion: network.alibabacloud.com/v1alpha1
kind: TrafficPolicy
metadata:
  name: agent-internet-only-policy
  namespace: default
spec:
  priority: 100
  selector:
    matchLabels:
      app: agent
      
  egress:
    rules:
      # 允许 DNS
      - action: allow
        to:
          - service:
              namespace: kube-system
              name: kube-dns
  
      # 禁止访问私有网络
      - action: deny
        to:
          - cidr: 10.0.0.0/8
      - action: deny
        to:
          - cidr: 172.16.0.0/12
      - action: deny
        to:
          - cidr: 192.168.0.0/16

实践3：限制ECS元数据服务

阿里云 ECS metadata endpoint（100.100.100.200）可被沙箱内代码访问以获取实例角色临时凭证，导致凭据泄露。这是最关键的安全配置之一。

- action: deny
  to:
    - cidr: 100.100.100.200/32

建议用高优先级 GlobalTrafficPolicy（优先级 1）全集群禁止访问元数据服务，确保任何应用策略都无法绕过（见实践6）。

实践4：仅白名单开放必要外部访问

如果沙箱需要访问外部资源（如 OSS endpoint），使用 FQDN/CIDR 白名单精确放行：

egress:
  rules:
    # 允许 DNS
    - action: allow
      to:
        - service:
            namespace: kube-system
            name: kube-dns
    # 允许特定 OSS endpoint
    - action: allow
      to:
        - fqdn: your-bucket.oss-cn-hangzhou-internal.aliyuncs.com
    # 禁止沙箱访问沙箱网关从而跳转访问其他沙箱
    - action: deny
      to:
        - service:
            name: sandbox-gateway
            namespace: sandbox-system
        - service:
            name: sandbox-manager
            namespace: sandbox-system
    # 按需允许公网（仅当 Agent 需要互联网访问时）
    - action: allow
      to:
        - cidr: 0.0.0.0/0

FQDN 有解析延迟和多域名同 IP 的限制，公网/泛域名场景优先用 SecurityProfile L7 域名匹配（实践11）。

实践5：限制 Ingress 仅允许管控面访问

沙箱 Pod 不应接受任意来源的入站连接。优先按管控组件交换机网段放行（无 Pod IP 解析延迟），Service 匹配为辅，并补全 webhook 组件：

# Ingress 规则
- action: allow
  from:
    - service:
        namespace: sandbox-system
        name: sandbox-gateway
    - service:
        namespace: sandbox-system
        name: sandbox-manager
    - service:
        namespace: sandbox-system
        name: sandbox-controller-manager-webhook-service
- action: deny
  from:
    - cidr: 0.0.0.0/0

控制面/非托管组件交换机网段在集群信息>基本信息>网络>控制面交换机查看。

实践6：使用 GlobalTrafficPolicy 建立全集群安全基线

用 GlobalTrafficPolicy 对全集群 Pod 施加"任何沙箱都不能突破"的兜底规则，避免逐 namespace 重复配置、防漏配。

• 高优先级 gtp（优先级 1）：元数据服务硬禁，不可被任何应用策略覆盖。

• 低优先级 gtp（优先级 1000）：内网网段、跨沙箱访问兜底。

• 应用级 tp（优先级 50-200）：特定 Agent 的精细放行。

apiVersion: network.alibabacloud.com/v1alpha1
kind: GlobalTrafficPolicy
metadata:
  name: global-metadata-hard-deny
spec:
  priority: 1               # 最高优先级，不可被覆盖
  selector: {}              # 全集群所有 Pod
  egress:
    rules:
      - action: deny
        to:
          - cidr: 100.100.100.200/32
---
apiVersion: network.alibabacloud.com/v1alpha1
kind: GlobalTrafficPolicy
metadata:
  name: global-sandbox-baseline
spec:
  priority: 1000            # 低优先级兜底
  selector: {}
  egress:
    rules:
      - action: deny
        to:
          - cidr: 10.0.0.0/8
          - cidr: 172.16.0.0/12
          - cidr: 192.168.0.0/16
          - cidr: 100.64.0.0/10
      - action: allow
        to:
          - cidr: 0.0.0.0/0
  ingress:
    rules:
      # 禁止 Sandbox 网段互相访问（防横向移动）
      - action: deny
        from:
          - cidr: 10.8.0.0/16      # 替换为实际 Sandbox vSwitch 网段
      - action: allow
        from:
          - cidr: 0.0.0.0/0

实践7：配置网络策略时需要兼顾系统组件功能需求

配置任何 deny-all 策略前，必须先为下列系统组件放行，否则沙箱功能异常（DNS 不通、凭据注入失败、策略下发异常、无法连接沙箱）。

实践8：企业安全组配置（组内隔离 + 端口矩阵）

安全组是 VPC/ENI 层的粗粒度边界防护，与 TrafficPolicy（Pod 级精细）是 AND 关系（互补，缺一不可）。

• 为沙箱配置独立企业级安全组，默认即为组内隔离（组内实例默认不互通，防横向移动），无需额外配置。

• 单安全组可关联 ENI 上限 65,536，建议 IP 占用率 ≤ 80%（约 52,000），临近上限扩容（见 实践10）。

安全组规则说明请参考复用或新建沙箱安全组。

实践9：VSwitch 隔离控制面

为沙箱创建独立 VSwitch（如 10.10.0.0/16），不要与集群控制面交换机混用。切勿将沙箱 VSwitch 添加到集群控制面交换机列表中，否则可能因网络隔离策略导致控制面服务异常。

实践10：网络扩容时同步更新安全组与 TrafficPolicy 网段

企业安全组 ENI 上限 65,536；接近上限或交换机 IP 耗尽时需新建一组 vSwitch + 安全组。扩容时必须同步：

1. 新 vSwitch 加 NAT SNAT 条目（否则新网段无公网）。

2. 目标侧安全组新增放行新 vSwitch 网段的入方向（例如CoreDNS TCP/UDP 53、Poseidon TCP/9082等规则）。

3. 检查现有 TrafficPolicy/GlobalTrafficPolicy 是否覆盖新网段。

4. 将新 vSwitch + 安全组配置到 Pod（已分配 Sandbox 需重建后生效）。

扩容后验证：hostname -i（IP 落在新 CIDR）、curl https://httpbin.org/ip（SNAT 正常）、getent hosts kubernetes.default.svc.cluster.local（DNS 正常）。

实践11：使用 SecurityProfile 实现 L7 出站精细控制

SecurityProfile 提供了比 L4 TrafficPolicy 更细粒度的出站控制，建议按以下场景配置：

场景 A：白名单模式（推荐生产环境）

只允许沙箱访问已知安全的域名，拒绝其他所有请求：

apiVersion: agents.kruise.io/v1alpha1
kind: SecurityProfile
metadata:
  name: allowlist-only
spec:
  selector:
    matchLabels:
      alibabacloud.com/compute-class: agent-sandbox
  rules:
  # 放行已知安全域名
  - name: allow-aliyuncs
    match:
    - domains: ["*.aliyuncs.com"]
    actions:
      bypass: true
  - name: allow-llm-provider
    match:
    - domains: ["dashscope.aliyuncs.com", "api.openai.com"]
    actions:
      bypass: true
  # 兜底拒绝所有
  - name: deny-all
    match:
    - domains: ["*"]
    actions:
      block:
        statusCode: 403
        body: '{"error":"access denied: domain not in allowlist"}'

场景 B：使用 SecurityProfile 封锁管理路径防止 SSRF

阻止 Agent 访问管理接口，即使域名被允许：

rules:
- name: deny-management-paths
  match:
  - domains: ["*"]
    paths:
    - type: Prefix
      value: /admin
    - type: Prefix
      value: /console
    - type: Prefix
      value: /dashboard
    - type: Prefix
      value: /manage
    - type: Regex
      value: "^/internal/v[0-9]+/.*"
  actions:
    block:
      statusCode: 403
      body: '{"error":"management paths are blocked"}'

场景 C：只读模式（限制 HTTP 写操作）

对于仅需读取数据的 Agent，封锁所有写方法：

rules:
- name: read-only-mode
  match:
  - domains: ["*"]
    paths:
    - type: Prefix
      value: /
    methods: ["POST", "PUT", "DELETE", "PATCH"]
  actions:
    block:
      statusCode: 405
      body: '{"error":"write operations are not allowed in read-only mode"}'

场景 D：封锁非标准端口防止安全审计绕过

rules:
- name: deny-non-standard-ports
  match:
  - domains: ["*"]
    ports: [8080, 8443, 9090, 3000, 6379, 27017]
  actions:
    block:
      statusCode: 403
      body: '{"error":"access to non-standard ports is blocked"}'

实践12：启用 HTTPS 流量管控

对于需要管控 HTTPS 出站的场景（如阿里云 API 调用、第三方 LLM 服务），启用 TLS termination：

# ack-sandbox-manager 组件配置
enhancedTrafficManagement:
  egressGateway:
    tlsTermination:
      includeHosts:
        - "*.aliyuncs.com"       # 阿里云 API
        - "*.openai.com"         # OpenAI
        - "api.anthropic.com"    # Anthropic
      excludeHosts:
        - "*.cluster.local"      # 排除集群内部通信

启用后，系统自动向沙箱 Pod 注入 Gateway CA 证书并配置 SSL_CERT_FILE、NODE_EXTRA_CA_CERTS、REQUESTS_CA_BUNDLE、CURL_CA_BUNDLE 等环境变量，对应用完全透明。

注意：如果对某域名启用了 TLS termination，但沙箱 Pod 未配置 enhanced-traffic-policy annotation（因而未注入 CA 证书），则该沙箱的 HTTPS 请求会因 TLS 握手失败而报错。

实践13：启用审计 Webhook 实现安全事件追踪

SecurityProfile 支持审计 Webhook——当规则匹配时向外部服务发送 HTTP 通知，用于安全审计、异常监控和事件告警。审计为非终结动作，不影响请求处理。

apiVersion: agents.kruise.io/v1alpha1
kind: SecurityProfile
metadata:
  name: audited-policy
spec:
  selector:
    matchLabels:
      security.agents.kruise.io/agent-name: my-agent
  audit:
  - name: central-audit
    when: 'result == "blocked"'    # 仅在请求被拦截时审计
    webhook:
      url: "https://audit.internal.company.com/events"
      timeout: 5s
      request:
        method: POST
        headers:
        - name: Authorization
          value: "Bearer <audit-service-token>"
        body:
          json:
            event: "request_blocked"
            result: "{{ .Result }}"
            pod: "{{ .Pod.Namespace }}/{{ .Pod.Name }}"
            rule: "{{ .Rule.Name }}"
            host: "{{ .Request.Host }}"
            path: "{{ .Request.Path }}"
            method: "{{ .Request.Method }}"
  rules:
  - name: deny-admin
    match:
    - domains: ["*"]
      paths:
      - type: Prefix
        value: /admin
    actions:
      block:
        statusCode: 403
        body: '{"error":"admin path is blocked"}'

CEL 条件表达式变量（用于 when 字段）：

实践14：启用控制面/数据面流量分离（SandboxGateway）

默认配置下控制面（api.{domain}）与数据面（*.{domain}）流量都汇聚到 sandbox-manager，控制面故障会波及业务数据通信。切换后数据面改由 sandbox-gateway 转发，实现故障隔离。

• 前置：ack-sandbox-manager ≥ v0.5.2，sandbox-gateway 副本 ≥ 1；控制面安全组放行 TCP/7788；TrafficPolicy 放行来自 sandbox-gateway 的入方向。

• 切换：组件管理 → ack-sandbox-manager → 配置，将 dataplaneService 切换为 sandbox-gateway（业务低峰期执行，可回滚）。

实践15：启用 SandboxGateway 入站流量认证（推荐 JWT 动态令牌）

仅靠 TrafficPolicy 限制来源 IP 不够，应在 sandbox-gateway 层叠加令牌认证。sandbox-gateway 提供两种认证方式，优先选用基于 JWT 的动态令牌认证：

为什么推荐 JWT 动态令牌：静态 Token 是数据面/envd 凭据，一旦泄露可重放至 Sandbox 销毁，且明文持久化在 CR 注解中；JWT 是数据面代理专用凭据、非对称签名、绑定 Sandbox ID/UID、失效可重签，泄露窗口受有效期约束，且不落盘到 CR，适合限时失效、防重放、多租户隔离场景。

开启方式请参考 基于 JWT 的动态令牌认证。

实践16：默认 readOnly 挂载共享存储

除非明确需要写入，共享存储卷一律只读挂载。

# SandboxClaim 方式
dynamicVolumesMount:
  - pvName: oss-pv-sandbox-system
    mountPath: "/data/readonly"
    subPath: "tenant-a/datasets"
    readOnly: true
    attributes:
      credentialProviderName: "oss-ro"

实践17：使用 subPath 实现租户级数据隔离

不同租户挂载同一 PV 时，通过 subPath + 独立 CredentialProvider 确保每个租户只能访问自己的数据子目录，互不可见。

# 租户 A（只读）
metadata = {
  "e2b.agents.kruise.io/csi-volume-config": json.dumps([
    {"pvName": "oss-pv-sandbox-system", "mountPath": "/data",
     "subPath": "tenants/tenant-a", "attributes": {"credentialProviderName": "oss-ro"}}
  ]),
  "security.agents.kruise.io/agent-name": "my-storage-agent"
}

实践18：OSS 凭据使用 Agent Identity + 模板函数（替换静态 AccessKey）

CredentialProvider的policy字段支持使用专用模板函数，由sandbox-controller根据每个Sandbox实例的挂载配置自动填充，无需为每个子路径单独创建CredentialProvider。

只读 CredentialProvider：

apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: CredentialProvider
metadata:
  name: oss-ro
  namespace: <YOUR-NAMESPACE>
spec:
  type: RAM
  ram:
    source:
      provider: RRSA
      rrsa:
        roleName: <YOUR-RAM-ROLE-NAME>
        tokenValidity: 1h
        policy: |
          {
            "Statement": [
              {
                "Action": ["oss:GetObject"],
                "Effect": "Allow",
                "Resource": {{ build_policy_oss_resource() }}
              },
              {
                "Action": ["oss:ListObjects"],
                "Effect": "Allow",
                "Resource": {{ build_policy_oss_resource(limit_sub_path=false) }},
                "Condition": {
                  "StringLike": { "oss:Prefix": {{ build_policy_oss_prefix_condition() }} }
                }
              }
            ],
            "Version": "1"
          }

ListObjects 是 Bucket 级操作，必须用 oss:Prefix Condition 限制子路径，否则 Sandbox 可列举整个 Bucket。读写场景改用 oss-rw（含 PutObject/DeleteObject 等）。

授权（AgentRole + AgentRoleBinding）：

apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: AgentRole
metadata:
  name: oss-storage-role
  namespace: <YOUR-NAMESPACE>
spec:
  rules:
    - effect: Allow
      action: "GetResourceCredential"
      resource: "CredentialProvider/oss-ro"
    - effect: Allow
      action: "GetResourceCredential"
      resource: "CredentialProvider/oss-rw"
---
apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: AgentRoleBinding
metadata:
  name: my-agent-oss-binding
  namespace: <YOUR-NAMESPACE>
spec:
  agentRoleRef:
    apiGroup: agentidentity.alibabacloud.com
    kind: AgentRole
    name: oss-storage-role
  subjects:
    - authorizationType: "Agent"
      agentAuthorizationConfiguration:
        agentName: my-storage-agent

更多的模板配置方式请参考为Agent Sandbox挂载OSS存储

实践19：PV 使用 Agent Identity（无需 Secret + 必须 sigv4）

Agent Identity 方式下 PV 无需 nodePublishSecretRef、无需创建 Secret。

apiVersion: v1
kind: PersistentVolume
metadata:
  name: oss-pv-sandbox-system
  labels:
    alicloud-pvname: oss-pv-sandbox-system
spec:
  accessModes: [ReadWriteMany]
  capacity:
    storage: 50Gi
  csi:
    driver: ossplugin.csi.alibabacloud.com
    volumeAttributes:
      authType: agent-identity                              # 固定值
      bucket: <YOUR-BUCKET-NAME>
      url: https://oss-cn-hangzhou-internal.aliyuncs.com    # HTTPS 内网 Endpoint
      path: /
      otherOpts: "-o sigv4 -o region=cn-hangzhou -o umask=022 -o allow_other"  # 必须带 sigv4 + region
    volumeHandle: oss-pv-sandbox-system                     # 必须与 PV 名称一致
  persistentVolumeReclaimPolicy: Retain
  storageClassName: test
  volumeMode: Filesystem

• otherOpts 必须包含 -o sigv4 和 -o region=<实际region>。

• PV 的 volumeAttributes 创建后不可修改，变更鉴权方式需删除重建。

实践20：SandboxSet 与挂载配置

• SandboxSet 启用 csi + agent-runtime 两个 runtime；dnsPolicy 必须为 ClusterFirst；建议加注解 network.alibabacloud.com/wait-clusterip-ready: "*"。

• 挂载时通过 attributes.credentialProviderName 指定 CredentialProvider，security.agents.kruise.io/agent-name 关联 AgentIdentity（名称必须完全一致，区分大小写）。

• 同一 Sandbox 可挂多个 subPath，分别引用 oss-ro/oss-rw 实现混合权限。

实践21：使用 HTTPS endpoint 访问 OSS

PV 的 url 使用 HTTPS internal endpoint，防止存储流量被窃听：

url: "https://oss-cn-hangzhou-internal.aliyuncs.com"

实践22：理解 CSI Sidecar 的安全权衡

CSI 动态挂载需要特权容器和 hostPath（/var/run/csi），打破标准容器安全边界。

• 仅在确需动态存储挂载时启用 CSI runtime；

• 仅需静态数据时，考虑镜像内置或 init container 预加载；

• 启用 CSI 时确保 TrafficPolicy 和安全组配置到位作为补偿控制；

• 基于安全共担责任模型——阿里云提供平台安全，用户需承担特权容器带来的额外风险。

OSS 挂载网络放行：使用 Agent Identity 挂载 OSS 时，网络策略必须放行 CredentialProvider（ack-agent-identity/credential-provider，安全组出方向 TCP/8443）、CoreDNS（53）、OSS Endpoint（HTTPS）。验证：telnet credential-provider.ack-agent-identity.svc 8443。

API Key 多租户认证

sandbox-manager 内置 API Key 认证体系，支持 Team 级别隔离：

• 每个 Team 映射到一个 Kubernetes Namespace

• API Key 仅能操作所属 Team 的沙箱

• admin Key 不可删除

ServiceAccount Token 禁用

SandboxSet 模板默认设置 automountServiceAccountToken: false，阻止沙箱获取 Kubernetes API 凭证。

环境变量清洗

支持显式清空 Kubernetes 注入的 Service 环境变量（如 KUBERNETES_SERVICE_HOST），防止泄露集群信息。

出站凭据注入（Agent Identity 体系）

ACS Agent Sandbox 提供了一套完整的出站凭据注入体系，核心设计原则是：沙箱内仅持有假凭证（占位符），真实凭证在 egress-gateway 层动态替换，沙箱永远不接触真实密钥。

五个 CRD 协作实现凭据注入：

两种注入模式：

spec:
  automountServiceAccountToken: false
  enableServiceLinks: false

spec:
  containers:
  - name: sandbox
    env:
    - name: KUBERNETES_SERVICE_HOST
      value: ""
    - name: KUBERNETES_SERVICE_PORT
      value: ""
    - name: KUBERNETES_SERVICE_PORT_HTTPS
      value: ""

# 1. 创建 Agent 身份
apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: AgentIdentity
metadata:
  name: my-agent
  namespace: tenant-a
spec:
  description: "生产环境 AI Agent 身份"

---
# 2. 将真实 API Key 存入 K8s Secret（集群侧管理，沙箱不可见）
apiVersion: v1
kind: Secret
metadata:
  name: llm-api-key
  namespace: tenant-a
type: Opaque
stringData:
  apiKey: "sk-xxxxxxxxxxxxxxxx"   # 真实 API Key

---
# 3. 创建 CredentialProvider 引用 Secret
apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: CredentialProvider
metadata:
  name: llm-api-key
  namespace: tenant-a
spec:
  type: APIKey
  apiKey:
    source:
      provider: Kubernetes
      kubernetes:
        secretRef:
          name: llm-api-key
        keyName: apiKey

---
# 4. 授权：AgentRole + AgentRoleBinding
apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: AgentRole
metadata:
  name: get-llm-key
  namespace: tenant-a
spec:
  rules:
  - effect: Allow
    action: "GetResourceCredential"
    resource: "CredentialProvider/llm-api-key"
---
apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: AgentRoleBinding
metadata:
  name: my-agent-get-llm-key
  namespace: tenant-a
spec:
  agentRoleRef:
    apiGroup: agentidentity.alibabacloud.com
    kind: AgentRole
    name: get-llm-key
  subjects:
  - authorizationType: "Agent"
    agentAuthorizationConfiguration:
      agentName: my-agent

---
# 5. SecurityProfile 定义替换规则
apiVersion: agents.kruise.io/v1alpha1
kind: SecurityProfile
metadata:
  name: inject-llm-key
  namespace: tenant-a
spec:
  selector:
    matchLabels:
      security.agents.kruise.io/agent-name: my-agent
  rules:
  - name: inject-openai-key
    match:
    - domains: ["api.openai.com", "dashscope.aliyuncs.com"]
    actions:
      tokenTransformation:
        type: ApiKey
        credentialRef:
          kind: CredentialProvider
          name: llm-api-key
        apiKey:
          when:
            header: Authorization
            pattern: "^Bearer .+"     # 仅当请求头包含 Bearer token 时替换
          targetHeader: Authorization
          valueTemplate: "Bearer {{ .Token }}"

import openai
client = openai.OpenAI(api_key="fake-token")  # 假凭证，网关会替换为真实 Key

# CredentialProvider 使用 RRSA 获取 STS 临时凭证
apiVersion: agentidentity.alibabacloud.com/v1alpha1
kind: CredentialProvider
metadata:
  name: aliyun-cs-readonly
  namespace: tenant-a
spec:
  type: RAM
  ram:
    source:
      provider: RRSA
      rrsa:
        roleName: ack-agent-identity-sample-role
        # policy 限制最终颁发的 STS Token 权限范围（必须是角色权限的子集）
        policy: |
          {
            "Statement": [{
              "Action": ["cs:Describe*", "cs:Get*", "cs:List*"],
              "Effect": "Allow",
              "Resource": ["*"]
            }],
            "Version": "1"
          }

env:
- name: ALIBABA_CLOUD_ACCESS_KEY_ID
  value: "FAKE_AK"     # 占位符
- name: ALIBABA_CLOUD_ACCESS_KEY_SECRET
  value: "FAKE_SK"     # 占位符

# SandboxClaim 通过 Label 传递业务参数
apiVersion: agents.kruise.io/v1alpha1
kind: SandboxClaim
metadata:
  name: user-sandbox
spec:
  templateName: my-sandbox-set
  replicas: 1
  labels:
    security.agents.kruise.io/agent-name: my-agent
    security.agents.kruise.io/oss-bucket-name: user-bucket-123
    security.agents.kruise.io/oss-subpath: user-data/alice

// CredentialProvider 的 policy 中引用模板变量
{
  "Action": ["oss:Get*", "oss:List*"],
  "Effect": "Allow",
  "Resource": [
    "acs:oss:*:*:${ack:agent-identity/metadata/oss-bucket-name}/${ack:agent-identity/metadata/oss-subpath}/*"
  ]
}

actions:
  tokenTransformation:
    failStrategy: Block    # 默认值，凭据获取失败则阻止请求
    # failStrategy: Allow  # 危险！失败时放行原始请求（含假凭证），仅用于调试

# 检查 Key 最后使用时间
curl -H "X-API-KEY: $ADMIN_KEY" https://your.domain.com/kruise/api/api-keys

# 创建租户 Namespace
kubectl create ns tenant-security-team

# 通过 Admin Key 为租户创建 API Key
curl -X POST -H "X-API-KEY: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "security-team-key", "teamName": "tenant-security-team"}' \
  https://your.domain.com/kruise/api/api-keys

spec:
  hostNetwork: false  # 必须确保为 false

spec:
  securityContext:
    runAsNonRoot: true          # 拒绝以 root（uid 0）启动，启动即校验
    runAsUser: 1000             # 指定非 root uid
    runAsGroup: 1000
    fsGroup: 1000               # 卷属组归属该 gid，保证非 root 可读写挂载卷
  containers:
    - name: app
      securityContext:
        allowPrivilegeEscalation: false   # 禁止通过 setuid 提权
        readOnlyRootFilesystem: true      # 根文件系统只读（按需放开可写目录）
        capabilities:
          drop: ["ALL"]                   # 丢弃所有 Linux capability

运行时安全能力与最佳实践

ACS Agent Sandbox 的网络/存储/凭据管控属于预防性基线安全控制（Preventive Controls），但完整的安全体系还需要检测性控制（Detective Controls）和响应性控制（Responsive Controls）。阿里云安全中心提供两个核心产品与 ACS Agent Sandbox 形成互补闭环：

最小权限原则实施清单