bedrockagentcore: BrowserCustom.grantUse() is missing ConnectBrowserAutomationStream, so the grantee cannot connect to a browser session
- Dominant language
- TypeScript
- Stars
- 12.9k
- Forks
- 4.6k
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 83
Description
## 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
```ts
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
Contributor guide
Research direction
Start in packages/aws-cdk-lib/aws-bedrockagentcore/lib/tools/perms.ts, then read the BrowserCustom grant tests around packages/aws-cdk-lib/aws-bedrockagentcore/test/agentcore/tools/browser.test.ts:1164-1173. Verify which actions the grant emits and compare them with the documented browser permissions. Done means the automation stream action is covered and the unit test checks the complete grant action set.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, typescript
- Domain
- cloud
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100