AWS bedrock-agentcore high security documentation change
Summary
Added comprehensive list of restricted HTTP headers for security, clarified header validation rules, updated examples to use non-restricted headers, and added security-focused configuration requirements.
Security assessment
The change explicitly adds restrictions to prevent security risks including IP spoofing, authentication bypass, and sensitive data exposure by blocking headers like X-Forwarded-For, Authorization, and security policy headers. It introduces a dedicated 'Restricted headers' section with categories covering authentication, security policies, and attack vectors, and requires customJWTAuthorizer for Authorization headers.
Diff
diff --git a/bedrock-agentcore/latest/devguide/runtime-header-allowlist.md b/bedrock-agentcore/latest/devguide/runtime-header-allowlist.md index d36367125..538f5f3d3 100644 --- a//bedrock-agentcore/latest/devguide/runtime-header-allowlist.md +++ b//bedrock-agentcore/latest/devguide/runtime-header-allowlist.md @@ -7 +7 @@ -Step 1: Create your agentStep 2: Configure and deploy your agent with custom headersStep 3: Invoke your agent with custom headersStep 4: (Optional) Configure inbound JWT authentication +Restricted headersStep 1: Create your agentStep 2: Configure and deploy your agent with custom headersStep 3: Invoke your agent with custom headersStep 4: (Optional) Configure inbound JWT authentication @@ -11 +11 @@ Step 1: Create your agentStep 2: Configure and deploy your agent with custom hea -Custom headers let you pass contextual information from your application directly to your agent code without cluttering the main request payload. This includes authentication tokens like JWT (JSON Web Tokens, which contain user identity and authorization claims) through the `Authorization` header, allowing your agent to make decisions based on who is calling it. You can also pass custom metadata like user preferences, session identifiers, or trace context using headers prefixed with `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` , giving your agent access to up to 20 pieces of runtime context that travel alongside each request. This information can be also used in downstream systems like AgentCore Memory that you can namespace based on those characteristics like `user_id` or `aud` in claims like line of business. +Custom headers let you pass contextual information from your application directly to your agent code without cluttering the main request payload. You can pass any valid HTTP header that is not in the restricted headers list, including webhook signatures like `X-Custom-Signature`, API keys like `X-Api-Key`, trace context, or session identifiers. You can also pass the `Authorization` header for JWT-based authentication when your agent is configured with a custom JWT authorizer. Headers prefixed with `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` continue to be supported for backward compatibility. Up to 20 headers can be configured per runtime, and each header value is limited to 4KB. @@ -13 +13 @@ Custom headers let you pass contextual information from your application directl -Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agent code provided the headers match the following criteria: +Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agent code provided the headers meet the following criteria: @@ -15 +15 @@ Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agen - * Header name is one of the following: + * Header name is a valid HTTP header (alphanumeric characters, hyphens, and underscores) and is not in the restricted headers list. @@ -17 +17 @@ Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agen - * Starts with `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` + * Headers starting with `x-amz-` are not allowed (these are reserved for AWS SigV4 signing). @@ -19 +19,3 @@ Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agen - * Equal to `Authorization` . This is reserved for agents with OAuth inbound access to pass in the incoming JWT token to the agent code. + * Headers starting with `x-amzn-` are not allowed, except for headers prefixed with `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` . + + * The `Authorization` header requires the agent runtime to be configured with a `customJWTAuthorizer` for OAuth-based inbound access. @@ -24,0 +27,3 @@ Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agen + * Header names are case-insensitive and duplicates (by case-insensitive comparison) are not allowed. + + @@ -26,0 +32 @@ Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agen +## Restricted headers @@ -28 +34 @@ Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agen -###### Topics +To maintain security and prevent exposure of sensitive information, the following headers are restricted and cannot be configured for propagation: @@ -30 +36,20 @@ Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agen - * Step 1: Create your agent +Category | Headers +---|--- +Authentication & Authorization | Proxy-Authorization, WWW-Authenticate +Content Negotiation | Accept, Accept-Charset, Accept-Encoding, Accept-Language, Content-Type, Content-Length, Content-Encoding, Content-Language, Content-Location, Content-Range +Caching | Cache-Control, ETag, Expires, If-Match, If-Modified-Since, If-None-Match, If-Range, If-Unmodified-Since, Last-Modified, Pragma, Vary +Connection Management | Connection, Keep-Alive, Proxy-Connection, Upgrade +Request Context | Host, User-Agent, Referer, From +Range / Transfer | Range, Accept-Ranges, Transfer-Encoding, TE, Trailer +Server Information | Server, Date, Location, Retry-After +Cookies | Set-Cookie, Cookie +Security | Content-Security-Policy, Content-Security-Policy-Report-Only, Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, Permissions-Policy, Cross-Origin-Embedder-Policy, Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy +CORS | Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Allow-Credentials, Access-Control-Expose-Headers, Access-Control-Max-Age, Access-Control-Request-Method, Access-Control-Request-Headers, Origin +Client Hints | Accept-CH, Accept-CH-Lifetime, DPR, Width, Viewport-Width, Downlink, ECT, RTT, Save-Data +Experimental / Proposed | Clear-Site-Data, Feature-Policy, Expect-CT, Public-Key-Pins, Public-Key-Pins-Report-Only +Proxy | Via, Forwarded, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto, X-Real-IP, X-Requested-With, X-CSRF-Token +IP Spoofing / URL Manipulation | True-Client-IP, X-Client-IP, X-Cluster-Client-IP, X-Originating-IP, X-Source-IP, X-Original-URL, X-Original-Host, X-Rewrite-URL +CDN / Proxy | CF-Ray, CF-Connecting-IP, X-Amz-Cf-Id, X-Cache, X-Served-By +HTTP/2 Pseudo Headers | :method, :path, :scheme, :authority, :status +Server Push | Link +WebSocket | Sec-WebSocket-Key, Sec-WebSocket-Accept, Sec-WebSocket-Version, Sec-WebSocket-Protocol, Sec-WebSocket-Extensions @@ -32 +57 @@ Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agen - * Step 2: Configure and deploy your agent with custom headers +In addition to the restricted headers listed above: @@ -34 +59 @@ Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agen - * Step 3: Invoke your agent with custom headers + * All headers starting with `x-amz-` are restricted (for example, `x-amz-security-token` , `x-amz-date` , `x-amz-content-sha256` ). These are reserved for AWS request signing. @@ -36 +61 @@ Amazon Bedrock AgentCore Runtime lets you pass headers in a request to your agen - * Step 4: (Optional) Configure inbound JWT authentication + * All headers starting with `x-amzn-` are restricted, except for headers prefixed with `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` . @@ -91 +116,2 @@ AgentCore CLI - "X-Amzn-Bedrock-AgentCore-Runtime-Custom-H1", + "X-Custom-Signature", + "X-Api-Key", @@ -114 +140 @@ AWS SDK - client = boto3.client('bedrock-agentcore') + client = boto3.client('bedrock-agentcore-control', region_name='us-west-2') @@ -117,0 +144,3 @@ AWS SDK + roleArn='arn:aws:iam::123456789012:role/YourAgentRole', + agentRuntimeArtifact={'containerConfiguration': {'containerUri': 'your-container-uri'}}, + networkConfiguration={'networkMode': 'PUBLIC'}, @@ -120 +149,2 @@ AWS SDK - 'X-Amzn-Bedrock-AgentCore-Runtime-Custom-H1' + 'X-Custom-Signature', + 'X-Api-Key' @@ -124,0 +155,4 @@ AWS SDK +###### Note + +`update_agent_runtime` is a full PUT operation. You must include all required fields (`roleArn` , `agentRuntimeArtifact` , `networkConfiguration`) even if they haven’t changed. + @@ -142 +176 @@ AgentCore CLI - -H "X-Amzn-Bedrock-AgentCore-Runtime-Custom-H1: test header1" + -H "X-Custom-Signature: sha256=abc123def456" @@ -147 +181,2 @@ You can pass multiple headers by repeating the `-H` flag: - -H "X-Amzn-Bedrock-AgentCore-Runtime-Custom-H1: test header1" \ + -H "X-Custom-Signature: sha256=abc123def456" \ + -H "X-Api-Key: my-api-key" \ @@ -161 +196 @@ AWS SDK - agent_arn = YOUR_AGENT_ARN_HERE + agent_arn = 'YOUR_AGENT_ARN_HERE' @@ -164 +199 @@ AWS SDK - agent_core_client = boto3.client('bedrock-agentcore') + agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2') @@ -168,2 +203,2 @@ AWS SDK - CUSTOM_HEADER_NAME = 'X-Amzn-Bedrock-AgentCore-Runtime-Custom-H1' - CUSTOM_HEADER_VALUE = 'test header1' + CUSTOM_HEADER_NAME = 'X-Custom-Signature' + CUSTOM_HEADER_VALUE = 'sha256=abc123def456'