AgentCore 运行时安全最佳实践

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

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

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

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

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

• 将权限范围限定为特定的运行时 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:subnetsbedrock-agentcore:securityGroups条件密钥要求所有运行时都部署在经批准的 VPC 中。有关示例，请参阅在 AgentCore 运行时使用 VPC 条件密钥。

• 使用 IAM 访问分析器 — 验证您的 IAM 策略，确保它们符合最佳实践和最低权限原则。

• 了解分层授权 — 对于InvokeAgentRuntimeInvokeAgentRuntimeCommand、和等运行时 API 操作InvokeAgentRuntimeCommandShell， 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 而不是通配符。

• 在提示字段上强制使用字符串类型 — payload 您的入口点接收到的内容是从任意 JSON 中解析出来的。调用者可以在prompt字段中发送非字符串值（例如列表或对象）。如果您的代理框架接受非字符串内容块（尤其是区块），则toolUse该框架可能会直接调度工具。这绕过了模型推理、护栏和系统即时执法。在将提示符传递给代理之前，请务必验证提示符是否为字符串：

  @app.entrypoint
  def invoke(payload, context):
      user_message = payload.get("prompt", "")
      if not isinstance(user_message, str) or not user_message.strip():
          return {"error": "Invalid input: 'prompt' must be a non-empty string"}
      result = agent(user_message)
      return {"response": result.message}

• 拒绝或删除toolUse内容屏蔽 -如果您的代理接受结构化消息阵列（用于多回合会话），请从用户提供的消息中过滤掉所有toolUse内容块。消息历史记录中的toolUse区块可能导致代理框架的事件循环在没有模型评估的情况下立即执行命名工具。

• 使用架构验证负载结构 —使用 Pydantic、Zod 或等效架构库来强制请求正文符合您的预期结构。在架构中定义prompt为str（不是Any）：

  from pydantic import BaseModel
  
  class InvocationRequest(BaseModel):
      prompt: str  # Enforces string type at the schema level

• 不要依赖默认值作为验证，类似的模式payload.get("prompt", "Hello")提供默认值，但不拒绝非字符串输入。返回的值是调用者发送的任何值，可能是一个包含内容块的字典或列表。

• 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、允许的受众、允许的客户端、允许的范围和所需的自定义声明。

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

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

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

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

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

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

• 启用 MMDSv2 — 从 2026 年 6 月 30 日起，您的代理运行时必须启用 MMDSv2。未启用 MMDSv2 的运行时无法调用并返回。ValidationException要启用，请requireMMDSV2将设置UpdateAgentRuntime为 true in 进行调用metadataConfiguration。有关解决此错误的更多信息，请参阅 MMDSv2 ValidationException 故障排除。

• 以非 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.api) com.amazonaws.region.ecr.dkr、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 代码工件存储桶是在账户区域命名空间通用存储桶中创建的。 AWS 只能拥有该服务使用的实际存储桶名称。该aws:PrincipalServiceName条件确保只有 AgentCore 服务主体才能通过此端点策略访问存储桶。如果您还使用永久文件系统，请将会话存储桶添加到此策略中。有关更多信息，请参阅配置 VPC AgentCore 运行时间。

• 将私有子网与 NAT 网关一起使用 — 公共子网不为 Runtime 提供互联网接入。 AgentCore 务必将运行时 ENI 放置在私有子网中，并附有一条指向 NAT 网关的路由，用于出站互联网访问。

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

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

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

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

• 尽可能使用 TLS 1.3 — 尽管 TLS 1.2 是最低配置，但 AWS 建议使用 TLS 1.3 以提高安全性和性能。

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

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

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

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

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

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

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

AWS 职责：

• 硬件级别的安全基础设施和微虚拟机隔离

• 所有部署模式的操作系统内核补丁

• 为直接代码部署提供语言运行时补丁

• 网络基础设施安全

• 服务可用性和弹性

你的责任：

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

• IAM 访问控制和资源策略

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

• Session-to-user 测绘执法

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

• 输入验证和即时注入保护，包括在使用托管工具时验证InvokeHarness输入（请参阅 Harn ess 共享 AgentCore 运行时信任边界）

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

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

• InvokeAgentRuntimeCommandShell— 具有持久 PTY 访问权限的交互式 WebSocket shell 会话。IAM 操作:bedrock-agentcore:InvokeAgentRuntimeCommandShell.

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

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

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

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

• 将流量保持在网络内 — 配置 VPC 终端节点，以避免命令执行 API 调用时遍历互联网。

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

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

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

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