AWS nova medium security documentation change
Summary
Modified IAM permissions section to require specific resource ARNs and address cross-region access conditions
Security assessment
Changed from generic bedrock:InvokeTool permission to granular resource-based policy (arn:aws:bedrock::{account}:system-tool/amazon.nova_grounding) and added aws:requestedRegion condition key guidance. This implements least-privilege access controls to limit tool usage.
Diff
diff --git a/nova/latest/nova2-userguide/web-grounding.md b/nova/latest/nova2-userguide/web-grounding.md index 24bf74209..eedcd65fd 100644 --- a//nova/latest/nova2-userguide/web-grounding.md +++ b//nova/latest/nova2-userguide/web-grounding.md @@ -5 +5 @@ -How Web Grounding worksEnable Web GroundingRegional availabilityResponse structure with citationsGrounding safetyError handlingIAM permissions +How Web Grounding worksHow to Use Web GroundingRegional availabilityResponse structureGrounding safetyError handlingPermissions Required for Built in Tools @@ -9 +9 @@ How Web Grounding worksEnable Web GroundingRegional availabilityResponse structu -Web Grounding enables Amazon Nova to search the web for current information and provide responses with citations. This feature is useful for queries requiring up-to-date information beyond the model's training data. +Web Grounding enhances Nova models by connecting them to real-time information beyond their knowledge cutoff, which results in more accurate and reliable responses. @@ -15 +15 @@ Web Grounding enables Amazon Nova to search the web for current information and - * Enable Web Grounding + * How to Use Web Grounding @@ -19 +19 @@ Web Grounding enables Amazon Nova to search the web for current information and - * Response structure with citations + * Response structure @@ -25 +25 @@ Web Grounding enables Amazon Nova to search the web for current information and - * IAM permissions + * Permissions Required for Built in Tools @@ -32 +32 @@ Web Grounding enables Amazon Nova to search the web for current information and -Web Grounding follows a five-step process: +When Web Grounding is enabled for a prompt, the following steps are performed: @@ -34 +34 @@ Web Grounding follows a five-step process: - 1. **Request configuration** \- You include the `systemTool` parameter with `nova_grounding` in your API request. + 1. **Request configuration** \- Your application sends a user prompt to the Amazon Bedrock API with nova_grounding enabled as a systemTool. @@ -36 +36 @@ Web Grounding follows a five-step process: - 2. **Search assessment** \- Amazon Nova analyzes the user query to determine if a web search would improve the response quality. + 2. **Search &Analysis** \- The model determines if search is needed, performs one or more searches es for relevant information, and evaluates whether additional searches are required to expand its understanding or dive deeper on specific subtopics. @@ -38 +38 @@ Web Grounding follows a five-step process: - 3. **Search execution** \- If beneficial, Amazon Nova generates search queries and retrieves relevant web content. + 3. **Response generation** \- Amazon Nova automatically synthesizes information from search results to generate a final API response grounded in real-time information, complete with citations to its sources. @@ -40 +39,0 @@ Web Grounding follows a five-step process: - 4. **Result analysis** \- Amazon Nova processes the search results and extracts relevant information. @@ -42 +40,0 @@ Web Grounding follows a five-step process: - 5. **Response generation** \- Amazon Nova generates a response incorporating the web content with citations. @@ -44,0 +43 @@ Web Grounding follows a five-step process: +## How to Use Web Grounding @@ -46,4 +45 @@ Web Grounding follows a five-step process: - -## Enable Web Grounding - -Enable Web Grounding by including the `systemTool` parameter in your Converse API request: +To include Web Grounding in your results, specify ty the following systemTool parameter in your toolConfig block: @@ -53,10 +48,0 @@ Enable Web Grounding by including the `systemTool` parameter in your Converse AP - from botocore.config import Config - - # Create the Bedrock Runtime client with extended timeout - bedrock = boto3.client( - "bedrock-runtime", - region_name="us-east-1", - config=Config(read_timeout=3600) - ) - - # Define the tool configuration @@ -65,3 +51 @@ Enable Web Grounding by including the `systemTool` parameter in your Converse AP - "systemTool": { - "name": "nova_grounding" - } + "systemTool": {"name": "nova_grounding"} @@ -71,2 +55 @@ Enable Web Grounding by including the `systemTool` parameter in your Converse AP - # Send the request - response = bedrock.converse( + response = client.converse( @@ -76 +59,3 @@ Enable Web Grounding by including the `systemTool` parameter in your Converse AP - "content": [{"text": "What are the latest developments in quantum computing?"}] + "content": [{ + "text": "What is the latest news about renewable energy sources?" + }] @@ -78,14 +63,2 @@ Enable Web Grounding by including the `systemTool` parameter in your Converse AP - toolConfig=tool_config - ) - - # Extract text with interleaved citations - output_with_citations = "" - content_list = response["output"]["message"]["content"] - for content in content_list: - if "text" in content: - output_with_citations += content["text"] - elif "citationsContent" in content: - citations = content["citationsContent"]["citations"] - for citation in citations: - url = citation["location"]["web"]["url"] - output_with_citations += f" [{url}]" + toolConfig=tool_config, + inferenceConfig={"maxTokens": 10000, "temperature": 0} @@ -97 +70 @@ Enable Web Grounding by including the `systemTool` parameter in your Converse AP -Web Grounding is available only in US regions. Requests from other regions return an error. Use CRIS profiles to route requests to supported regions when necessary. +Web Grounding is currently only available in US regions and supported only by US CRIS profiles. You can use Web Grounding by calling the specific Nova 2 model with the cross-region inference profile: "us.amazon.nova-2-lite-v1:0" @@ -99 +72 @@ Web Grounding is available only in US regions. Requests from other regions retur -## Response structure with citations +## Response structure @@ -101 +74 @@ Web Grounding is available only in US regions. Requests from other regions retur -Responses with Web Grounding include citation information in the `citationsContent` field: +The following is an example response. The response has been shortened for brevity: @@ -104,7 +77,5 @@ Responses with Web Grounding include citation information in the `citationsConte - { - "output": { - "message": { - "content": [ - { - "text": "Recent quantum computing developments include...", - "citationsContent": [ + n">{ + "text": ". + - **Solar energy** is leading growth with a 31% increase in generation in early 2025, outpacing wind's 7.7% growth", + "citationsContent": { + "citations": [ @@ -114,3 +85,2 @@ Responses with Web Grounding include citation information in the `citationsConte - "url": "https://example.com/quantum-news", - "domain": "example.com" - } + "url": "rfi.fr/en/environment/20251008-renewables-overtake-coal-but-growth-slows-amid-us-and-china-report-shows", + "domain": "rfi.fr" @@ -119 +88,0 @@ Responses with Web Grounding include citation information in the `citationsConte - ] @@ -124 +92,0 @@ Responses with Web Grounding include citation information in the `citationsConte - } @@ -138 +106 @@ Array of citations with source information. -location.web.url +citations @@ -141 +109 @@ location.web.url -The URL of the cited web source. +A container within citationsContent that holds the location of a citation. @@ -143 +111 @@ The URL of the cited web source. -location.web.domain +location @@ -146 +114,3 @@ location.web.domain -The domain name of the cited source. +A container within citations that holds the source of a citation. + +web @@ -148 +117,0 @@ The domain name of the cited source. -## Grounding safety @@ -150 +119 @@ The domain name of the cited source. -Web Grounding implements safety measures to protect data and ensure quality: +A container within location that holds the web source details. @@ -152 +121 @@ Web Grounding implements safety measures to protect data and ensure quality: - * **Data stays in AWS** \- All web search operations occur within AWS infrastructure. Your data never leaves AWS. +url @@ -154 +122,0 @@ Web Grounding implements safety measures to protect data and ensure quality: - * **Internal search index** \- Web Grounding uses an internal search index maintained by AWS, not external search engines. @@ -156 +124 @@ Web Grounding implements safety measures to protect data and ensure quality: - * **Runtime filtering** \- Content is filtered at runtime to exclude inappropriate or harmful material. +The full web address (URL) of the citation's source. @@ -157,0 +126 @@ Web Grounding implements safety measures to protect data and ensure quality: +domain @@ -159,0 +129,5 @@ Web Grounding implements safety measures to protect data and ensure quality: +The root domain of the source url. + +## Grounding safety + +Your data never leaves AWS infrastructure. Model-generated queries stay within AWS services and are never sent to the broader internet. Our expansive internal web search index and knowledge graphs prioritize trustworthy and high-quality sources and filter malicious content on ingress. Web Grounding further refines the information at runtime by cross-referencing from multiple sources. Finally, we protect your application against indirect prompt injection and misinformation with runtime filtering (note that this mitigation is limited for non-English.) @@ -163 +137 @@ Web Grounding implements safety measures to protect data and ensure quality: -Handle common Web Grounding errors: +Do not include a toolSpec entry with the name nova_grounding. Including a tool with this name will result in an error. The following is a list of potential errors that can occur when using Web Grounding: @@ -173 +147 @@ max_tokens -The response exceeded the maximum token limit. Increase `maxTokens` in `inferenceConfig` or simplify the query. +The response exceeded the maximum token limit. @@ -180 +154,7 @@ The model generated invalid output. This is typically a transient error - retry -## IAM permissions +## Permissions Required for Built in Tools + + 1. **Enable BedrockFullAccess on your IAM role** \- If your role has BedrockFullAccess, it will have automatic access to Web Grounding. + + 2. **Add Specific Permissions (if needed)** \- If you require more granular access control, add this policy to your role's IAM policy, replacing the account ID with your AWS account ID: + + @@ -182 +161,0 @@ The model generated invalid output. This is typically a transient error - retry -Web Grounding requires the `bedrock:InvokeTool` IAM action. Add this permission to your IAM policy: @@ -186 +164,0 @@ Web Grounding requires the `bedrock:InvokeTool` IAM action. Add this permission - "Version": "2012-10-17", @@ -190,5 +168,2 @@ Web Grounding requires the `bedrock:InvokeTool` IAM action. Add this permission - "Action": [ - "bedrock:InvokeModel", - "bedrock:InvokeTool" - ], - "Resource": "arn:aws:bedrock:*::foundation-model/amazon.nova-*" + "Action": ["bedrock:InvokeTool"], + "Resource": ["arn:aws:bedrock::{111122223333}:system-tool/amazon.nova_grounding"] @@ -198,0 +174,10 @@ Web Grounding requires the `bedrock:InvokeTool` IAM action. Add this permission +Web Grounding has the aws:requestedRegion condition key set to "unspecified". If your existing policies or Service Control Policies (SCPs) enforce this condition, you may encounter access issues. Updating the condition to allow an "unspecified" requestedRegion can resolve this problem. + +###### Note + +If you enable the Web Grounding tool, you are responsible for your use, and any use by your end users, of output that incorporates grounded information. You will know when your output includes grounded information from citations or links to the source material. You must retain and display these citations and links in the output you provide to your end users. + +###### Note + +Web Grounding is an additional cost. For more information see [Amazon Bedrock pricing page](https://aws.amazon.com/bedrock/pricing/). +