AgentCore 运行时安全最佳实践

• 了解隔离边界 — 每个用户会话都运行在具有隔离的 CPU、内存和文件系统的专用 microVM 中。命令和代理代码无法访问其他客户的工作负载或逃离虚拟机边界。会话完成后，整个 microVM 将被终止并清理内存。

• 在后端强制执行会话到用户的映射 — AgentCore 不强制执行会话到用户的映射。您的客户端后端必须维护用户与其会话 ID 之间的关系，并实施生命周期管理，例如每个用户的最大会话数。

• 注意文件系统权限行为 — 使用永久文件系统时，权限是在会话中存储的，但不会强制执行。 chmod并且可以正常stat工作，但是访问检查总是成功的，因为代理以 microVM 中唯一的用户身份运行。

• 了解虚拟机内的凭据泄露 — 在 microVM 内运行的任何代码或操作者都可以通过调用元数据端点 (MMDS) 来访问执行角色凭证。谨慎确定执行角色权限的范围。有关更多信息，请参阅凭证管理。

• 请勿在生产环境中使用 CLI-generated 策略 — AgentCore CLI 创建的 IAM 策略专为开发和测试目的而设计。这些权限授予广泛访问权限，不适用于生产。创建自定义 IAM 策略，将权限限制为仅限于所需的特定资源和操作。有关完整参考，请参阅 IAM AgentCore 运行时权限。

• 将权限范围限定为特定的运行时 ARN-避免使用通配符资源语句。在 IAM 策略Resource字段中使用运行时资源的完整 ARN。

• 限制 InvokeAgentRuntimeForUser-只有受信任的委托人才应具有此权限。使用 IAM 资源条件将其范围限定为特定的运行时资源。

• 在不需要时拒绝用户 ID 委托 — 对于不需要用户 ID 委派的运行时，请明确拒绝该操作：

  {
     "Statement": [
        {
           "Sid": "DenyUserIdDelegation",
           "Effect": "Deny",
           "Action": "bedrock-agentcore:InvokeAgentRuntimeForUser",
           "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:runtime/*"
        }
     ]
  }

• 防止权限升级-确保与您的运行时关联的执行角色拥有的权限等于或少于可以调用它的委托人的权限。有关更多信息，请参阅凭证管理。

• 使用 IAM 条件密钥强制部署 VPC — 使用bedrock-agentcore:subnets和bedrock-agentcore:securityGroups条件密钥要求所有运行时都部署在经批准的 VPC 中。有关示例，请参阅将 VPC 条件键与 AgentCore 运行时一起使用。

• 使用 IAM Access Analyzer — 验证您的 IAM 策略以确保它们符合最佳实践和最低权限原则。

• 了解分层授权 — 对于运行时 API 操作，例如InvokeAgentRuntimeInvokeAgentRuntimeCommandInvokeAgentRuntimeCommandShell、和， AWS 评估代理运行时和代理端点上的策略。两者都必须允许该操作。

• 为跨账户访问配置这两个资源-要授予跨账户访问权限，请在代理运行时和代理端点上创建基于资源的策略。如果任一资源缺少明确允许，则请求将被拒绝。

• 请记住，显式拒绝永远是赢家 — 如果任何策略（基于身份或基于资源）明确拒绝某项操作，则无论其他策略如何，都将拒绝访问权限。

• 使用aws:SourceArn和 aws:SourceAccount — 将以下条件添加到您的执行角色信任策略中，以限制哪些 AgentCore 资源可以担任该角色：

  {
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "Service": "bedrock-agentcore.amazonaws.com"
        },
        "Action": "sts:AssumeRole",
        "Condition": {
          "StringEquals": {
            "aws:SourceAccount": "123456789012"
          },
          "ArnLike": {
            "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
          }
        }
      }
    ]
  }

• 尽可能使用完整的 ARN — 如果您知道特定的运行时资源，请使用其完整 ARN 代替通配符。aws:SourceArn

• Policy-based 授权-使用网关的策略引擎控制哪些呼叫者可以在什么条件下调用哪些目标。有关更多信息，请参阅使用策略控制对网关目标的访问权限。

• 护栏 — 通过策略引擎应用 Amazon Bedrock Guardrails 来筛选请求和响应。有关更多信息，请参阅在策略中使用护栏。

• 请求和响应拦截器-使用网关上配置的拦截器 Lambda 函数检查或转换流量。

• IAM (Sigv4) 运行时 — 附加一个基于资源的策略，该策略限制对网关执行角色的调用。请参阅将 IAM (Sigv4) 入站调用限制到您的网关。

• OAuth (JWT) 运行时-在运行时的授权方allowedWorkloadConfiguration上进行配置。请参阅限制对您的网关的调用。

• 选择正确的身份验证方法 — 使用 IAM Sigv4 进行内部服务到服务的调用。 AWS当最终用户直接通过身份提供商进行身份验证时，请使用 JWT 不记名令牌身份验证。运行时一次只能支持一种方法；为不同的身份验证类型创建不同的版本。

• 首选用于生产的 JWT-based 用户标识 — 当您的代理代表最终用户检索 OAuth 令牌时，首选 JWT 持有者令牌路径 (GetWorkloadAccessTokenForJWT)，该路径可以验证令牌的颁发者、签名和到期时间。 UserId 路径（GetWorkloadAccessTokenForUserId/X-Amzn-Bedrock-AgentCore-Runtime-User-Id标头）将用户标识符视为不透明的字符串，不经过 IdP 验证，仅将其用于开发、快速入门场景或在上游解析用户身份的企业架构。有关更多信息，请参阅获取工作负载访问令牌。

• 完全配置 JWT 授权方 — 使用 JWT 身份验证时，请配置所有可用的验证字段：发现 URL、允许的受众、允许的客户端、允许的范围和所需的自定义声明。

• 切勿在生产代码中对令牌进行硬编码 — 使用安全的令牌检索机制。硬编码令牌在源代码控制和已部署的工件中存在安全风险。

• 从经过身份验证的委托人中派生 user-i d — 如果您使用X-Amzn-Bedrock-AgentCore-Runtime-User-Id标头，则该值应来自经过身份验证的委托人的上下文（IAM 调用者身份或用户令牌声明），而不是来自客户端提供的任意值。这样可以防止经过身份验证的用户冒充其他用户。

• ForUserId 在不需要的地方拒绝 — 对于始终有 JWT 可用的工作负载，请bedrock-agentcore:InvokeAgentRuntimeForUser在 IAM 策略中明确拒绝bedrock-agentcore:GetWorkloadAccessTokenForUserId。这样可以确保所有用户身份都通过经过加密验证的 JWT 路径。

• 为您的身份验证方法配置 VPC 终端节点策略 — VPC 终端节点策略只能基于 IAM 委托人限制来电者，不能基于 OAuth 用户。对于 OAuth-based 请求，请在终端节点策略*中设置为Principal。要进行 SigV4-based 身份验证，请指定允许的 IAM 身份。

• 使用 AgentCore 身份进行出站身份验证 — Id AgentCore entity 可以安全地管理 OAuth 凭据和 API 密钥，防止代理代码或日志中的凭据泄露。使用它来访问所有第三方服务（Slack、 GitHub、Zoom）。

• 了解 MMDS 凭据泄露 — microVM 元数据服务 (MMDS) 为虚拟机中运行的任何代码提供执行角色证书，类似于 EC2 的 IMDS。将执行角色权限范围仅限于您的代理所需的权限。

• 启用 mmdsv2 — 从 2026 年 6 月 30 日起，您的代理运行时必须启用 mmdSv2。未启用 mmdSv2 的运行时无法调用并返回。ValidationException要启用，请在requireMMDSV2设置为 in 的情况下UpdateAgentRuntime进行true呼叫metadataConfiguration。有关解决此错误的更多信息，请参阅 mmdsv ValidationException 2 疑难解答。

• 以@@ 非 root 用户身份运行容器 — 构建自定义容器镜像时，请将其配置为以非 root 用户身份运行。这限制了潜在的代码执行漏洞的影响。

• 将用户委派的凭证和自主凭证分开 — 当您的代理代表特定用户行事时，使用用户委托的身份验证（授权码授予）。当代理独立运行时，使用自主身份验证（授予客户机凭证）。

• 在 VPC 中部署运行时以访问私有资源 — 配置 VPC 连接以访问私有数据库、内部 API 和服务，而无需将其暴露在互联网上。有关配置的详细信息，请参阅为 VPC 配置 AgentCore 运行时。

• 用 AWS PrivateLink 于 API 访问 — 为 AgentCore 数据平面 (com.amazonaws.region.bedrock-agentcore) 和控制平面 () 创建接口 VPC 终端节点，以避免互联网穿越。com.amazonaws.region.bedrock-agentcore-control有关更多信息，请参阅使用 AWS PrivateLink。

• 对安全组应用最低权限-定义仅允许所需最低流量的出站规则。除非必要，否则不要开放广泛的出站访问权限。

• 为容器代理配置所需的 VPC 终端节点-对于 VPC-mode 容器代理，请为 ECR (com.amazonaws.region.ecr.dkr、com.amazonaws.region.ecr.api)、S3（com.amazonaws.region.s3网关终端节点）和 CloudWatch 日志 (com.amazonaws.region.logs) 配置 VPC 终端节点。S3 网关终端节点消除了 ECR 图像层拉取的 NAT 网关数据处理费用。

• 限制容器代理的 S3 网关终端节点策略 — 将 S3 网关终端节点策略限制为 Amazon ECR 用于图像层存储的存储桶：

  {
    "Statement": [
      {
        "Sid": "AllowECRLayerAccess",
        "Principal": "*",
        "Action": [
          "s3:GetObject"
        ],
        "Effect": "Allow",
        "Resource": ["arn:aws:s3:::prod-region-starport-layer-bucket/*"]
      }
    ]
  }

  region替换为您的 AWS 地区标识符（例如，us-east-2）。

• 将 S3 网关终端节点策略的范围限定为直接代码部署代理 — 对于基于 zip 的部署，请将策略限制为内部服务拥有的代码工件存储桶。添加一个aws:PrincipalServiceName条件以确保只有 AgentCore 服务委托人才能通过此端点策略访问存储桶：

  {
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": "*",
        "Action": "s3:GetObject",
        "Resource": [
          "arn:aws:s3:::acr-code-*-region-an",
          "arn:aws:s3:::acr-code-*-region-an/*"
        ],
        "Condition": {
          "StringEquals": {
            "aws:PrincipalServiceName": "bedrock-agentcore.amazonaws.com"
          }
        }
      }
    ]
  }

  region替换为您的 AWS 地区标识符（例如，us-west-2）。 AgentCore 代码工件存储桶是在 Acco unt 区域命名空间通用存储桶中创建的。 AWS 只能拥有服务使用的实际存储桶名称。该aws:PrincipalServiceName条件可确保只有 AgentCore 服务委托人才能通过此终端节点策略访问存储桶。如果您还使用永久性文件系统，请将会话存储桶添加到此策略中。有关更多信息，请参阅为 VPC 配置 AgentCore 运行时。

• 将私有子网与 NAT 网关配合使用 — 公有子网不为 Runtime 提供互联网接入。 AgentCore 请务必将运行时 ENI 放置在私有子网中，并提供通往 NAT 网关的路由，用于出站 Internet 访问。

• 传输安全-所有连接都使用 TLS 1.2 或更高版本。 WebSocket 连接InvokeAgentRuntimeCommandShell，包括仅通过 HTTPS 使用 WSS（WebSocket 安全）。不支持纯文本ws://连接。

• 强制执行标头限制-自定义标头限制为每个值 4KB，每个运行时限制为 20 个标头。该Authorization标头是为拥有 OAuth 入站访问权限的代理保留的。

• 传输中的加密-客户端与运行时之间以及 AgentCore 运行时与其依赖关系之间 AgentCore 的所有通信均使用 TLS 1.2 或更高版本进行保护。这是默认配置的，不需要额外的设置。

• 静态加密-默认情况下，静态数据使用密 AWS 钥管理服务 (AWS KMS) AWS 自有的加密密钥进行加密。

• 尽可能使用 TLS 1.3 — 虽然 TLS 1.2 是最低要求，但为了提高安全性和性能， AWS 建议使用 TLS 1.3。

• 启用 CloudTrail 日志 AWS CloudTrail 记录-记录 API 调用InvokeAgentRuntime，包括InvokeAgentRuntimeCommandInvokeAgentRuntimeCommandShell、、和控制平面操作。每条记录都包括来电者身份、时间戳、源 IP 地址和响应状态。

• 使用 CloudWatch 日志进行命令审计- AgentCore Runtime 会将请求 ID 和输入命令发送到代理的 CloudWatch 日志日志组。使用这些日志来维护会话中执行的命令的审计跟踪。

• 使用请求 ID 关联日志-使用请求 ID 将 CloudTrail 记录（谁调用了 API）与 CloudWatch 日志（执行了什么命令）关联起来。

• 设置指标筛选器和警报-配置 CloudWatch 日志指标筛选器以检测意外的命令模式或未经授权的访问尝试。创建警报，将异常情况通知您的团队。

• 记录用户 ID 委托关系 — 使用X-Amzn-Bedrock-AgentCore-Runtime-User-Id标头时，记录经过身份验证的 IAM 委托人与用户 ID 值之间的关系以供审计。

• 启用 VPC 流日志-对于 VPC-connected 运行时，启用 VPC 流日志以审计网络级流量并识别意外通信模式。

• 定期@@ 查看 CloudTrail 日志-定期查看日志中是否存在未经授权的访问尝试，尤其是敏感工作负载。

AWS 职责：

• 硬件级别的安全基础设施和 microVM 隔离

• 适用于所有部署模式的操作系统内核修补

• 用于直接部署代码的语言运行时补丁

• 网络基础设施安全

• 服务可用性和弹性

你的责任：

• 代理代码安全和依赖关系管理

• IAM 访问控制和资源策略

• 运行时会话中执行的命令的安全性

• Session-to-user 测绘执法

• 容器镜像更新（用于容器部署）— 定期使用最新的安全基础镜像进行重建

• 输入验证和提示注入防护 — 包括在使用托管线束时验证InvokeHarness输入（参见 Harness 共享 AgentCore 运行时信任边界）

• 网络配置（安全组、VPC 终端节点、路由表）

• InvokeAgentRuntimeCommand— One-shot，非交互式命令执行结束。 HTTP/2IAM 操作：bedrock-agentcore:InvokeAgentRuntimeCommand。

• InvokeAgentRuntimeCommandShell— 具有持续 PTY 访问权限的交互式 WebSocket 外壳会话。IAM 操作：bedrock-agentcore:InvokeAgentRuntimeCommandShell。

• 了解安全边界 — 命令可以完全访问容器文件系统以及 microVM 中任何已配置的凭据或机密。隔离边界是 microVM 本身。在分担责任模式下，您应对运行时容器中执行的任何代码的安全性负责。

• 对确定性任务使用确定性操作 — 使用InvokeAgentRuntimeCommand或InvokeAgentRuntimeCommandShell进行测试、git 和构建等操作。不要通过 LLM 路由确定性操作。InvokeAgentRuntime

• 限制谁可以执行命令 — 使用 IAM 策略限制哪些委托人可以调用InvokeAgentRuntimeCommand或InvokeAgentRuntimeCommandShell。并非所有可以调用代理的用户都应该能够执行任意命令。资源示例 ARN:. arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent

• WebSocket shell 仅使用 wss://— InvokeAgentRuntimeCommandShell 连接仅通过 WSS（WebSocket 安全）建立。不支持纯文本ws://连接。呼叫者在升级时通过 SigV4 进行身份验证。 WebSocket

• 将流量保持在您的网络内-配置 VPC 终端节点，以避免命令执行 API 调用的互联网穿越。

• 设置适当的超时-根据预期的执行持续时间配置命令超时，以防止失控的进程浪费资源。

• 在代理代码中限制 localhost 访问权限-配置您的代理和任何网络工具，以防止不受限制地访问 localhost。除非特定集成需要，否则代理代码不应对 localhost 进行任意 HTTP 调用。

• 仅允许列入边车设置所需的端口 — 如果您的架构在 localhost 上使用容器中的容器模式或边车模式，请明确将您的边车服务使用的特定端口列入许可名单。不要开放广泛的本地主机访问权限。

• 审核网络工具以覆盖本地主机-查看您提供给代理的所有工具（例如 HTTP 请求工具或常规网络实用程序），以确保他们不会向本地主机端点发出意外请求。在工具级别应用 URL 过滤或许可名单。