AWS bedrock documentation change
Summary
Updated Amazon Bedrock Guardrails enforcements documentation to reflect general availability (removed preview note), restructured content from tutorial format to guide format, added new configuration options for selective content guarding and model enforcement controls, updated example policy JSON, and revised FAQ section.
Security assessment
The changes are documentation updates for a feature that is now generally available. They introduce new security controls (selective_content_guarding and model_enforcement) that allow administrators to fine-tune guardrail behavior, such as deciding whether to honor caller tags and which models to include/exclude. While these are security enhancements, there is no evidence in the diff that these changes address a specific, disclosed security vulnerability or incident. The changes improve security documentation by detailing new configuration options.
Diff
diff --git a/bedrock/latest/userguide/guardrails-enforcements.md b/bedrock/latest/userguide/guardrails-enforcements.md index 84267b9be..f0bdefd72 100644 --- a//bedrock/latest/userguide/guardrails-enforcements.md +++ b//bedrock/latest/userguide/guardrails-enforcements.md @@ -5 +5 @@ -Implementation GuideMonitoringPricingFrequently Asked Questions +Implementation guideMonitoringPricingFrequently Asked Questions @@ -9,5 +9 @@ Implementation GuideMonitoringPricingFrequently Asked Questions -###### Note - -Amazon Bedrock Guardrails enforcements is in preview and subject to change. - -Amazon Bedrock Guardrails enforcements enable you to automatically apply safety controls at an AWS account level and at an AWS Organizations level (across accounts) for all model invocations with Amazon Bedrock. This centralized approach maintains consistent safeguards across multiple accounts and applications, eliminating the need to configure guardrails for individual accounts and applications. +Amazon Bedrock Guardrails allows you to automatically apply safeguards across multiple accounts in an organization through [AWS Organizations Amazon Bedrock policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_bedrock.html). This enables uniform protection across all accounts with centralized control and management. Additionally, this capability also offers flexibility to apply account-level and application-specific controls depending on use-case requirements. @@ -19 +15 @@ The following are the key capabilities of guardrails enforcements: - * Organization-level enforcement – Apply guardrails for all model invocations with Amazon Bedrock across organization units (OUs), individual accounts, or your entire organization using Amazon Bedrock policies (in preview) with AWS Organizations. + * Organization-level enforcement – Apply guardrails for all model invocations with Amazon Bedrock across organization units (OUs), individual accounts, or your entire organization using Amazon Bedrock policies with AWS Organizations. @@ -32 +28 @@ The following topics describe how to use Amazon Bedrock Guardrails enforcements: - * Implementation Guide + * Implementation guide @@ -43 +39 @@ The following topics describe how to use Amazon Bedrock Guardrails enforcements: -## Implementation Guide +## Implementation guide @@ -45 +41 @@ The following topics describe how to use Amazon Bedrock Guardrails enforcements: -The tutorials below walk through the steps needed to enforce guardrails for accounts with an AWS Organization and for a single AWS account. With these enforcements, all model invocations to Amazon Bedrock will enforce the safeguards configured within the designated guardrail. +The steps below provide details on implementing guardrails enforcements for accounts within an AWS Organization and for a single AWS account. With these enforcements, all model invocations to Amazon Bedrock will enforce the safeguards configured within the designated guardrail. @@ -47 +43 @@ The tutorials below walk through the steps needed to enforce guardrails for acco -### Tutorial: Organization-Level Enforcement +### Organization-level enforcement @@ -49 +45 @@ The tutorials below walk through the steps needed to enforce guardrails for acco -This tutorial walks you through setting up guardrail enforcement across your AWS organization. By the end, you'll have a guardrail that automatically applies to all Amazon Bedrock model invocations across specified accounts or OUs. +This section details setting up guardrail enforcement across your AWS organization. Once set up, you'll have a guardrail that automatically applies to all Amazon Bedrock model invocations across specified accounts or OUs. @@ -51 +47 @@ This tutorial walks you through setting up guardrail enforcement across your AWS -###### Who should follow this tutorial +###### Prerequisites @@ -57 +53 @@ AWS Organization administrators (with management account access) with permission -The following are required to complete this tutorial: +The following are required: @@ -59 +55 @@ The following are required to complete this tutorial: - * An [AWS organization ](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html) with management account access + * [AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html) with management account access @@ -78 +74,3 @@ The following are required to complete this tutorial: - * **Note:** Do not include the automated reasoning policy, as it is unsupported for guardrail enforcements and will cause runtime failures. + * ###### Important + +Do not include the automated reasoning policy, as it is unsupported for guardrail enforcements and will cause runtime failures. @@ -108 +106 @@ Once created, you should see it in the list of guardrails on the Guardrails land - 3. ###### Create a Guardrail Version + 3. ###### Create a guardrail version @@ -118 +116 @@ Create a numeric version to ensure the guardrail configuration remains immutable - 3. Note the guardrail ARN and the version number (e.g., "1", "2", etc.) + 3. Note the guardrail ARN and the version number (for example, "1", "2") @@ -126 +124 @@ Confirm the version was created successfully by checking the list of versions on - 4. ###### Attach a Resource-Based Policy + 4. ###### Attach a resource-based policy @@ -134 +132 @@ Enable cross-account access by attaching a resource-based policy to your guardra - 2. Click **Add** to add a resource-based policy + 2. Choose **Add** to add a resource-based policy @@ -144 +142 @@ Test access from a member account using the [ApplyGuardrail](https://docs.aws.am - 5. ###### Configure IAM Permissions in Member Accounts + 5. ###### Configure IAM permissions in member accounts @@ -164 +162 @@ Confirm that roles with scoped down permissions in member accounts can successfu - 3. Choose **Amazon Bedrock policies** (currently in preview) + 3. Choose **Amazon Bedrock policies** @@ -174 +172 @@ Confirm the Amazon Bedrock policy type shows as enabled in the AWS Organizations - 7. ###### Create and Attach an AWS Organizations Policy + 7. ###### Create and attach an AWS Organizations policy @@ -186 +184,17 @@ Create a management policy that specifies your guardrail and attach it to your t - 4. Configure the `input_tags` setting (set to ignore to prevent member accounts from bypassing the guardrail on the input via [guardrails input tags](./guardrails-tagging.html)). +###### Important + +Ensure you are specifying the accurate guardrail ARN in the policy. Specifying an incorrect or invalid ARN will result in policy violations, non-enforcement of safeguards, and the inability to use the models in Amazon Bedrock for inference. + + 4. Configure selective content guarding controls (optional). + + * Amazon Bedrock APIs allow callers to [tag specific content within their input prompts](./guardrails-tagging.html) for guardrail evaluation. + + * Selective content guarding controls let administrators decide whether to honor tagging decisions made by API callers. + + * The `system` and `messages` controls determine how system prompts and message content are processed by guardrails. Each accepts one of the following values: + + * **Selective** : Only evaluate content within guard content tags. When no tags are specified, the behavior depends on the control. For `system`, no content is evaluated, and for `messages`, all content is evaluated. + + * **Comprehensive** : Evaluate all content, regardless of guard content tags. + + * If not configured, both controls default to **Comprehensive**. @@ -194 +208 @@ Create a management policy that specifies your guardrail and attach it to your t - "@@assign": "arn:aws:bedrock:us-east-1:account_id:guardrail/guardrail_id:1" + "@@assign": "arn:aws:bedrock:us-east-1:123456789012:guardrail/guardrail-id:1" @@ -196,2 +210,15 @@ Create a management policy that specifies your guardrail and attach it to your t - "input_tags": { - "@@assign": "honor" + "selective_content_guarding": { + "system": { + "@@assign": "selective" + }, + "messages": { + "@@assign": "comprehensive" + } + }, + "model_enforcement": { + "included_models": { + "@@assign": ["ALL"] + }, + "excluded_models": { + "@@assign": ["amazon.titan-embed-text-v2:0", "cohere.embed-english-v3"] + } @@ -223 +250 @@ Test that the guardrail is being enforced on member accounts. - * Using the AWS Management Console – From a member account, navigate to the Amazon Bedrock console, click on **Guardrails** in the left panel. On the Guardrails home page, you should see the organization enforced guardrail under the section **Organization-level enforcement configurations** in the management account and **Organization-level enforced guardrails** in the member account + * Using the AWS Management Console – From a member account, navigate to the Amazon Bedrock console, choose **Guardrails** in the left navigation panel. On the Guardrails home page, you should see the organization enforced guardrail under the section **Organization-level enforcement configurations** in the management account and **Organization-level enforced guardrails** in the member account @@ -238 +265 @@ Test that the guardrail is being enforced on member accounts. -### Tutorial: Account-Level Enforcement +### Account-level enforcement @@ -240 +267 @@ Test that the guardrail is being enforced on member accounts. -This tutorial walks you through setting up guardrail enforcement within a single AWS account. By the end, you'll have a guardrail that automatically applies to all Amazon Bedrock model invocations in your account. +This section details setting up guardrail enforcement within a single AWS account. Once set up, you'll have a guardrail that automatically applies to all Amazon Bedrock model invocations in your account. @@ -242 +269 @@ This tutorial walks you through setting up guardrail enforcement within a single -###### Who should follow this tutorial +###### Prerequisites @@ -248 +275 @@ AWS account administrators with permissions to create guardrails and configure a -The following are required to complete this tutorial: +The following are required: @@ -259 +286 @@ The following are required to complete this tutorial: - 1. ###### Plan you guardrail configuration + 1. ###### Plan your guardrail configuration @@ -269 +296,3 @@ To define your safeguards: - * **Note:** Do not include the automated reasoning policy, as it is unsupported for guardrail enforcements and will cause runtime failures + * ###### Important + +Do not include the automated reasoning policy, as it is unsupported for guardrail enforcements and will cause runtime failures @@ -311 +340 @@ To create a guardrail version using the console: - 3. Note the guardrail ARN and the version number (e.g., "1", "2", etc.) + 3. Note the guardrail ARN and the version number (for example, "1", "2") @@ -331 +360 @@ To attach a resource-based policy using the console: - 2. Click **Add** to add a resource-based policy + 2. Choose **Add** to add a resource-based policy @@ -353 +382,13 @@ To enable account-level enforcement using the console: - 5. Configure the `input_tags` setting (set to IGNORE to prevent member accounts from bypassing the guardrail on the input via Guardrails input tags) + 5. Configure selective content guarding controls (optional). + + * Amazon Bedrock APIs allow callers to [tag specific content within their input prompts](./guardrails-tagging.html) for guardrail evaluation. + + * Selective content guarding controls let administrators decide whether to honor tagging decisions made by API callers. + + * The `system` and `messages` controls determine how system prompts and message content are processed by guardrails. Each accepts one of the following values: + + * **Selective** : Only evaluate content within guard content tags. + + * **Comprehensive** : Evaluate all content, regardless of guard content tags. + + * If not configured, both controls default to **Comprehensive**. @@ -393 +434 @@ To test enforcement from your account: -Amazon Bedrock Guardrails enforcement follows the current pricing model for Amazon Bedrock Guardrails based on the number of text units consumed per configured safeguard. Charges apply to each enforced guardrail according to its configured safeguards. For detailed pricing information on individual safeguards, please refer to [Amazon Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/). +Amazon Bedrock Guardrails enforcement follows the current pricing model for Amazon Bedrock Guardrails based on the number of text units consumed per configured safeguard. Charges apply to each enforced guardrail according to its configured safeguards. For detailed pricing information on individual safeguards, refer to [Amazon Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/). @@ -404 +445,2 @@ Member account calls using the Amazon Bedrock Policy will count towards the Serv -**How do I prevent member accounts from bypassing guardrails using input tags?** +**What happens if I have both organization-level and account-level enforced guardrails as well as a guardrail in my request?** + @@ -405,0 +448 @@ Member account calls using the Amazon Bedrock Policy will count towards the Serv +All 3 guardrails will be enforced at runtime. The net effect is a union of all guardrails, with the most restrictive control taking precedence. @@ -407 +450 @@ Member account calls using the Amazon Bedrock Policy will count towards the Serv -Use the `input_tags` control available in: +**When should I use selective or comprehensive guarding control?** @@ -409 +451,0 @@ Use the `input_tags` control available in: - * Amazon Bedrock AWS Organizations policies @@ -411 +453 @@ Use the `input_tags` control available in: - * The [PutEnforcedGuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PutEnforcedGuardrailConfiguration.html) API +Use **Selective** when you trust callers to tag the right content and want to reduce unnecessary guardrail processing. This is useful when callers handle a mix of pre-validated and user-generated content, and only need guardrails applied to specific portions. Use **Comprehensive** when you want to enforce guardrails on everything, regardless of what the caller tags. This is the safer default when you don't want to rely on callers to correctly identify sensitive content. @@ -412,0 +455 @@ Use the `input_tags` control available in: +**How can I include or exclude certain models from enforcement?** @@ -414,0 +458 @@ Use the `input_tags` control available in: +Use the model enforcement control to scope which models on Amazon Bedrock a guardrail applies to for inference. If not configured, enforcement applies to all models on Amazon Bedrock by default. This control accepts the following lists: @@ -416 +460 @@ Use the `input_tags` control available in: -Set the value to ignore to prevent member accounts from tagging partial content. + * **Included models:** Models to enforce the guardrail on. Accepts specific model identifiers or the keyword `ALL` to explicitly include all models. When empty, enforcement applies to all models. @@ -418 +462 @@ Set the value to ignore to prevent member accounts from tagging partial content. -**What happens if I have both organization-level and account-level enforced guardrails as well as a guardrail in my request?** + * **Excluded models:** Models to exclude from guardrail enforcement. When empty, no models are excluded. @@ -421 +464,0 @@ Set the value to ignore to prevent member accounts from tagging partial content. -All 3 guardrails will be enforced at runtime. The net effect is a union of all guardrails, with the most restrictive control taking precedence. @@ -423 +466,10 @@ All 3 guardrails will be enforced at runtime. The net effect is a union of all g -**What happens with models that don't support guardrails?** + +If a model appears in both lists, it is excluded. + +**When should I use include versus exclude models?** + + + * Use **Included models** when you want to enforce the guardrail on only specific models. + + * Use **Excluded models** when you want broad enforcement but need to carve out exceptions for specific models. + @@ -426 +477,0 @@ All 3 guardrails will be enforced at runtime. The net effect is a union of all g -For models where Guardrails aren't supported (such as embedding models), a runtime validation error will be thrown.