AWS bedrock-agentcore documentation change
Summary
Updated security documentation to cover new InvokeAgentRuntimeCommandShell API, clarified transport security requirements, expanded CloudTrail logging, added harness trust boundary details, and refined command execution security practices.
Security assessment
The changes enhance security documentation by explicitly prohibiting plaintext WebSocket connections (mandating WSS), clarifying trust boundaries for harness operations, and emphasizing input validation requirements. While these improve security guidance, there's no evidence of addressing a specific existing vulnerability or incident.
Diff
diff --git a/bedrock-agentcore/latest/devguide/runtime-security-best-practices.md b/bedrock-agentcore/latest/devguide/runtime-security-best-practices.md index cf582abb5..afa0cb80d 100644 --- a//bedrock-agentcore/latest/devguide/runtime-security-best-practices.md +++ b//bedrock-agentcore/latest/devguide/runtime-security-best-practices.md @@ -93 +93 @@ Resource-based policies provide fine-grained access control directly on your run - * **Understand hierarchical authorization** — For runtime API operations such as `InvokeAgentRuntime` and `InvokeAgentRuntimeCommand`, AWS evaluates policies on both the agent runtime and the agent endpoint. Both must allow the action. + * **Understand hierarchical authorization** — For runtime API operations such as `InvokeAgentRuntime`, `InvokeAgentRuntimeCommand`, and `InvokeAgentRuntimeCommandShell`, AWS evaluates policies on both the agent runtime and the agent endpoint. Both must allow the action. @@ -227 +227 @@ Replace `region` with your AWS Region identifier (for example, `us-west-2`). If - * **Transport security** — All connections use TLS 1.2 or higher. WebSocket connections use WSS (WebSocket Secure) over HTTPS. + * **Transport security** — All connections use TLS 1.2 or higher. WebSocket connections, including `InvokeAgentRuntimeCommandShell`, use WSS (WebSocket Secure) over HTTPS exclusively. Plaintext `ws://` connections are not supported. @@ -253 +253 @@ Implement comprehensive auditing to detect and investigate security events: - * **Enable CloudTrail logging** — AWS CloudTrail records API calls including `InvokeAgentRuntime`, `InvokeAgentRuntimeCommand`, and control plane operations. Each record includes caller identity, timestamp, source IP address, and response status. + * **Enable CloudTrail logging** — AWS CloudTrail records API calls including `InvokeAgentRuntime`, `InvokeAgentRuntimeCommand`, `InvokeAgentRuntimeCommandShell`, and control plane operations. Each record includes caller identity, timestamp, source IP address, and response status. @@ -301 +301 @@ Understand the division of security responsibilities between AWS and you: - * Input validation and prompt injection prevention + * Input validation and prompt injection prevention — including validating `InvokeHarness` input when using the managed harness (see Harness shares the AgentCore Runtime trust boundary) @@ -315,0 +316,11 @@ Security patches can expose issues with existing code that relies on previous in +### Harness shares the AgentCore Runtime trust boundary + +The managed harness is built on AgentCore Runtime. It does not add a security layer between the caller and the microVM. The security boundary is the same as AgentCore Runtime: IAM or JWT authentication combined with microVM isolation. + + * All `InvokeHarness` input considered trusted input — Any principal that passes the IAM or JWT authentication gate has full access to the capabilities configured on the harness. The harness does not perform any custom input sanitization, content-block filtering, or behavioral enforcement on your behalf. Design your architecture with the assumption that every authenticated caller is fully trusted to use the configured capabilities. + + * Validate untrusted input in your own application layer — If you expose the harness to end users you do not fully trust (employees, external consumers, or third-party integrations) between your frontend and `InvokeHarness`, it is your responsibility to sanitize, validate, or otherwise review messages before passing them to the harness. This includes stripping content block types that you do not want dispatched directly. This is the same pattern as any service that accepts payloads from authorized callers, such as Lambda, Amazon API Gateway, and Amazon SQS. + + + + @@ -318 +329,12 @@ Security patches can expose issues with existing code that relies on previous in -When using `InvokeAgentRuntimeCommand`, apply these security practices: +AgentCore Runtime provides two command execution APIs: + + * `InvokeAgentRuntimeCommand` — One-shot, non-interactive command execution over HTTP/2. IAM action: `bedrock-agentcore:InvokeAgentRuntimeCommand`. + + * `InvokeAgentRuntimeCommandShell` — Interactive WebSocket shell session with persistent PTY access. IAM action: `bedrock-agentcore:InvokeAgentRuntimeCommandShell`. + + + + +Both APIs operate within the same microVM isolation boundary and share the same security model. Apply these practices to both: + + * **Understand the security boundary** — Commands have full access to the container filesystem and any configured credentials or secrets within the microVM. The isolation boundary is the microVM itself. Under the shared responsibility model, you are responsible for the security of any code executed in your runtime container. @@ -320 +342 @@ When using `InvokeAgentRuntimeCommand`, apply these security practices: - * **Understand the security boundary** — Commands have full access to the container filesystem and any configured credentials or secrets within the microVM. The isolation boundary is the microVM itself. + * **Use deterministic operations for deterministic tasks** — Use `InvokeAgentRuntimeCommand` or `InvokeAgentRuntimeCommandShell` for operations like tests, git, and builds. Don’t route deterministic operations through the LLM via `InvokeAgentRuntime`. @@ -322 +344 @@ When using `InvokeAgentRuntimeCommand`, apply these security practices: - * **Use deterministic operations for deterministic tasks** — Use `InvokeAgentRuntimeCommand` for operations like tests, git, and builds. Don’t route deterministic operations through the LLM via `InvokeAgentRuntime`. + * **Restrict who can execute commands** — Use IAM policies to limit which principals can call `InvokeAgentRuntimeCommand` or `InvokeAgentRuntimeCommandShell`. Not all users who can invoke an agent should be able to execute arbitrary commands. Example resource ARN: `arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent`. @@ -324 +346 @@ When using `InvokeAgentRuntimeCommand`, apply these security practices: - * **Restrict who can execute commands** — Use IAM policies to limit which principals can call `InvokeAgentRuntimeCommand`. Not all users who can invoke an agent should be able to execute arbitrary commands. + * **WebSocket shell uses wss:// only** — `InvokeAgentRuntimeCommandShell` connections are established exclusively over WSS (WebSocket Secure). Plaintext `ws://` connections are not supported. Callers authenticate via SigV4 at WebSocket upgrade.