bedrockagentcore: BrowserCustom.grantUse() is missing ConnectBrowserAutomationStream, so the grantee cannot connect to a browser session

[badmintoncryer]

Describe the bug

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

The grant covers StartBrowserSession, UpdateBrowserStream and StopBrowserSession, but not bedrock-agentcore:ConnectBrowserAutomationStream. Connecting to the automation stream is how you interact with a browser session over the Chrome DevTools Protocol, so without it the granted permissions cannot be used for anything.

What makes this hard to diagnose is that the failure happens after the session is already up. StartBrowserSession succeeds, the session reaches READY, and only the WebSocket connection to the returned stream endpoint is rejected. Nothing in the logs points at IAM.

Regression Issue

• Select this option if this issue appears to be a regression.

Expected Behavior

After browser.grantUse(role), a principal assuming that role can start a browser session and connect to its automation stream.

Current Behavior

The session starts, then the connection to the automation stream fails with 403 Forbidden:

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

Reproduction Steps

const browser = new agentcore.BrowserCustom(this, 'Browser', {
  networkConfiguration: agentcore.BrowserNetworkConfiguration.usingPublicNetwork(),
});

const runtime = new agentcore.Runtime(this, 'Runtime', { /* ... */ });

browser.grantUse(runtime);

Deploy, then have the runtime start a browser session and connect to the automation stream (for example with the bedrock-agentcore Python SDK, or Playwright over CDP). The session starts; the connection is rejected with 403.

Adding bedrock-agentcore:ConnectBrowserAutomationStream to the role by hand makes it work.

Possible Solution

Add bedrock-agentcore:ConnectBrowserAutomationStream to BROWSER_USE_PERMS:

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

Both published IAM policies for the browser tool include this 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)

I would not add ConnectBrowserLiveViewStream to grantUse(). 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, so bundling both into the grant an agent needs would go against least privilege.

Additional Information/Context

perms.ts already contains a BROWSER_STREAM_PERMS constant that includes the missing action:

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 (grep -rn "BROWSER_STREAM_PERMS" --include="*.ts" only finds the declaration). The same is true of BROWSER_SESSION_PERMS and BROWSER_ADMIN_PERMS, so three of the six BROWSER_* constants are currently unused.

The existing unit tests did not catch this because they only assert that a grant was produced, not which actions it contains:

https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-bedrockagentcore/test/agentcore/tools/browser.test.ts#L1164-L1173

I have a fix ready and will open a PR.

AWS CDK Library version (aws-cdk-lib)

2.266.0

AWS CDK CLI version

2.1138.0

Node.js Version

v20.19.2

OS

macOS 14.6.1

Language

TypeScript

[pahud]

Hi @badmintoncryer,

┌────────────────────────────────────────────────────────────┐
│ 🔴 Reported State                                          │
│ grantUse() starts a session but CDP/WebSocket connect      │
│ to the automation stream fails with 403 Forbidden          │
└─────────────────────────────┬──────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────┐
│ 🔍 Root Cause                                              │
│ BROWSER_USE_PERMS omits ConnectBrowserAutomationStream     │
│ aws-bedrockagentcore/lib/tools/perms.ts#L62                │
└─────────────────────────────┬──────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────┐
│ 🟢 Suggested Fix                                           │
│ Add ConnectBrowserAutomationStream to BROWSER_USE_PERMS    │
│ (in flight via PR #38657)                                  │
└────────────────────────────────────────────────────────────┘

Thanks for the thorough report — this is a good catch, and the analysis made it easy to verify. I was able to reproduce this at synth time on aws-cdk-lib 2.263.0: the policy statement generated by grantUse() contains only StartBrowserSession, UpdateBrowserStream, and StopBrowserSession — ConnectBrowserAutomationStream is indeed missing, even though the (currently unreferenced) BROWSER_STREAM_PERMS constant in the same file already lists it:

aws-cdk/packages/aws-cdk-lib/aws-bedrockagentcore/lib/tools/perms.ts

Lines 62 to 66 in 51234fd

	export const BROWSER_USE_PERMS = [
	'bedrock-agentcore:StartBrowserSession',
	'bedrock-agentcore:UpdateBrowserStream',
	'bedrock-agentcore:StopBrowserSession',
	];

From my view, your proposed fix is the right shape: add the action to BROWSER_USE_PERMS, and keep ConnectBrowserLiveViewStream out of grantUse() since the devguide treats live view as the human-observer interface rather than something an agent needs — that keeps the grant least-privilege. Tightening the unit tests to assert the exact action list (instead of just that a grant exists) would also prevent this class of drift going forward.

I see you've already opened #38657 with the fix — much appreciated! Until it ships, anyone hitting this can work around it with:

browser.grant(role, 'bedrock-agentcore:ConnectBrowserAutomationStream');

Marking this as p2 since a workaround exists and a fix PR is already in review.

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.