fix(bedrockagentcore): browser grantUse is missing ConnectBrowserAutomationStream

[badmintoncryer]

Issue # (if applicable)

Closes #38656.

Reason for this change

BrowserCustom.grantUse() does not grant enough permissions for the grantee to actually use the browser.

Granting grantUse() to an agent runtime and then driving the browser, StartBrowserSession succeeds, but the subsequent connection to the automation stream is rejected with 403 Forbidden:

INFO bedrock_agentcore.tools.browser_client ✅ Session started: 01M0T9ME4FBJQY2QCXZ1M33ADP
INFO bedrock_agentcore.tools.browser_client Generating websocket headers...
→ 403 Forbidden

This is unpleasant to debug, because the session is created successfully and reaches READY. Only the WebSocket connection to the returned stream endpoint fails, so nothing in the logs points at IAM.

The cause is that BROWSER_USE_PERMS is missing bedrock-agentcore:ConnectBrowserAutomationStream:

https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-bedrockagentcore/lib/tools/perms.ts#L61-L65

Connecting to the automation stream over the Chrome DevTools Protocol is not an optional extra — it is how you interact with a browser session at all. The devguide describes the automation endpoint as the way an agent performs browser actions, and both published IAM policies for the browser tool include the action:

• https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-resource-session-management.html (Permissions)
• https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-security.html (AgentCoreBrowserCustom)

So grantUse() currently grants a set of permissions that cannot be used for anything.

Description of changes

Added bedrock-agentcore:ConnectBrowserAutomationStream to BROWSER_USE_PERMS, and updated the JSDoc on IBrowserCustom.grantUse(), the @default block on BrowserCustomBase.grantUse() and the README to match. The interface doc previously mentioned an Invoke action, which does not exist for this resource.

On ConnectBrowserLiveViewStream: I deliberately did not add it. perms.ts already contains an unused BROWSER_STREAM_PERMS constant that bundles the automation stream and the live view stream together:

https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-bedrockagentcore/lib/tools/perms.ts#L21-L28

It is not referenced anywhere in the repository. Wiring it into grantUse() wholesale would also grant the live view stream, which serves a different consumer — the devguide presents the automation endpoint as the agent's interface and the live view endpoint as the way an end user watches and takes over a session. An agent does not need the latter, so including it would go against least privilege. That is possibly why the constant was never wired up: no single consumer needs exactly that set.

That does leave ConnectBrowserLiveViewStream reachable only through grant(). I would be happy to follow up with a companion BrowserCustomGrants class (per the no-grants awslint rule) that exposes the live view path as its own grant, but I could not find documentation specifying which actions that consumer needs — the published policies grant everything in one statement — so I did not want to guess at a public API in a stable module. Guidance welcome.

Describe any new or updated permissions being added

BrowserCustom.grantUse() now additionally grants bedrock-agentcore:ConnectBrowserAutomationStream, scoped to the browser's ARN. This action supports resource-level permissions; the AgentCoreBrowserCustom policy linked above scopes it to arn:aws:bedrock-agentcore:<region>:<accountId>:browser-custom/<browserCustomId>. No permissions are removed, and no other grant is affected.

Description of how you validated changes

Added unit tests that pin the exact action list and resource scope produced by grantUse() and grantRead(). The existing grant tests only asserted grant.success and principalStatements.length > 0, which is why a missing action went unnoticed.

Updated integ.browser.ts to grant a role against the browser, and deployed it to us-east-1 — the test passes and the snapshot matches.

Originally found while building an agent on AgentCore Runtime + Browser, where the 403 above disappears once this action is granted.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[lpizzinidev]

Ty!

[badmintoncryer]

Thanks @lpizzinidev !