Document browser egress allowlists by meliaj · Pull Request #657 · kernel/docs

meliaj · 2026-10-01T15:30:21Z

summary

document allowlist creation, matching rules, browser-visible denial behavior, and replacement/removal-only browser PATCH semantics.
qualify proxy_error coverage for cross-origin CORS/ORB failures and blocked CAPTCHA resources; generic loading errors alone don't identify allowlist denials.
cover pool create/update, whole-object network replacement, automatic idle-browser replacement, and restoring the pool baseline before reuse or replacing unsafe browsers.
describe custom-proxy context refusal over cdp and the remaining proxy-only security limitations.
preserve current navigation and align pool, private-networking, and proxy-error guidance.
add allowlists to security and trust: an agent egress restriction shared control and section in the shared responsibility model, including pool lease behavior, plus a security practices feature entry.

validation

mint validate, mint broken-links, json parsing, and git diff --check passed.
new allowlist page matches mint format.
mint dev: allowlist, pool, private-networking, shared responsibility, and security practices pages returned 200; new sections and anchors rendered.
typescript examples typechecked; browser and pool examples verified with mocked transports on typescript/python sdk v0.121.0.
cdp restriction and egress-policy unit tests passed during the earlier update.
local Chromium reproduction confirmed a visible same-origin 403, cross-origin fetch ERR_FAILED from CORS, and image ERR_BLOCKED_BY_ORB.
pool API tests and live-browser end-to-end tests were not run.

release

keep draft pending technical review and explicit launch authorization. don't merge until browser pool allowlist support is released. no changelog or ga changes.

Note

Low Risk
Documentation-only changes with no runtime or API implementation in this diff.

Overview
Adds a new Egress Allowlists guide under Configure → Proxies and wires it into the docs site navigation.

The page documents network.allowed_hosts: create/update/remove semantics (including replacement-only PATCH and pool whole-object network updates), entry validation, blocked-destination behavior (403 / network_policy_denied), CAPTCHA provider hosts, CDP proxy-context refusal, and proxy-only enforcement limits.

Related pages are updated so browser pools describe allowlist restore-on-reuse and automatic idle replacement when the pool list changes; proxy errors add network_policy_denied and clarify incomplete proxy_error telemetry for CORS/ORB; private networking cross-links differing pool update rules; security and the shared responsibility model frame agent egress restriction as a shared control.

^{Reviewed by Cursor Bugbot for commit dba4bc4. Bugbot is set up for automated code reviews on this repo. Configure here.}

mintlify · 2026-10-01T15:30:25Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Kernel	🟢 Ready	View Preview	Oct 9, 2026, 4:47 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

## Summary The metro egress proxy is gaining per-session egress allowlists. When a destination isn't on the allowlist, the proxy answers with a branded **403** carrying `X-Kernel-Proxy-Error: network_policy_denied`. Other proxy-layer failures still return 502. Before this change, the CDP monitor only checked branded 502s, so a denial produced no `proxy_error` event. This PR: - treats 403 as a branded-response status alongside 502. Only those two statuses pay for the header decode; other responses still cost just the status compare. A website's own 403 without the header emits nothing. - adds `network_policy_denied` to the published `proxy_error` code enum, so the event carries the typed code instead of `unknown` with a `raw_code`. The spec descriptions now mention the 403. - adds `destination_route_unavailable` and `origin_response_incomplete` to the enum as well. The proxy already serves both as branded 502s, but the image reported them as `unknown` with a `raw_code`. - updates the cdpmonitor README, which still described `proxy_error` as 502-only, and notes that a CONNECT the proxy refuses outright, such as a denied CONNECT to a port other than 443, shows up only as `network_loading_failed` because Chromium doesn't expose the refusal. The 403 handling can ship before or after the proxy change: until the proxy sends these 403s, nothing changes for them. The two added codes take effect as soon as an image with this change ships. It does need to be in a released image before kernel/docs#657 is published, since that PR says denials show up as `proxy_error` events and drops the proxy errors page's note that `origin_response_incomplete` isn't reported. ## Validation - `cd server && go test ./lib/cdpmonitor/... ./lib/events/... ./lib/oapi/...` - `KERNEL_CDPMONITOR_CHROME_E2E=1 go test ./lib/cdpmonitor/ -run TestProxyErrorE2E` against real Chromium, with new cases for `network_policy_denied` (403), `destination_route_unavailable` and `origin_response_incomplete`. The last two come back as `unknown` with the previous generated enum. - The new unit test fails with the old 502-only gate. - `lib/oapi/oapi.go` was regenerated by running the `oapi-generate` steps directly. Unrelated `go mod tidy` changes to `go.sum` were left out. - Container e2e tests pass in CI (`test-server-e2e`). 🤖 Generated with [Claude Code](https://claude.com/claude-code)  --- > [!NOTE] > **Medium Risk** > Changes network telemetry classification for 403 responses and expands the public proxy_error enum; mis-gating could false-positive on unrelated 403s, though the header gate limits that. > > **Overview** > Extends CDP monitor **`proxy_error`** detection so branded metro responses with **`X-Kernel-Proxy-Error`** are recognized on **403** as well as **502**, enabling typed telemetry when egress **network policy** blocks a destination (`network_policy_denied` with status 403). Plain site 403s without the header still do not emit **`proxy_error`**. > > The OpenAPI/`oapi` **`proxy_error` code enum** gains **`network_policy_denied`**, **`destination_route_unavailable`**, and **`origin_response_incomplete`**, with docs noting 403 vs 502 and that some CONNECT refusals remain **`network_loading_failed`** only. Unit and Chromium E2E tests cover the 403 gate and new codes; README event taxonomy is updated accordingly. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 493f2d3. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  --------- Co-authored-by: meliaj <17581886+meliaj@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Add a page for network.allowed_hosts: creating a browser with an allowlist, the entry rules, what a blocked request returns, changing or removing the list with update(), keeping it away from the agent, and the limitations. List network_policy_denied and its 403 on the proxy errors page, and narrow the private networking note now that allowed_hosts can change after creation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- Updating the allowlist: new requests are refused within seconds and open connections close within about 30 seconds, or up to 10 minutes during a Kernel deploy. - The WebRtcIPHandling and WebRtcIPHandlingUrl Chrome policies are rejected with an allowlist. - Public suffix rejections include provider domains such as *.cloudfront.net. - Limitations list what can leave the VM without the egress proxy: VM processes, CDP contexts with their own proxy, extensions with the proxy permission, and DNS lookups Chromium makes itself. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Blocked connections to ports other than 443 get a bare 403 that Chromium doesn't expose, so they show up as network_loading_failed, not proxy_error. The browser image release this page waits for reports origin_response_incomplete with its own code, so the proxy errors page no longer needs to say it isn't reported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…d one An allowlist is now set when the browser is created. update() can replace or remove it, but adding one to a browser created without it returns 400 not_supported, and one removed with null can't be added back.

AnnaXWang · 2026-10-09T16:13:07Z

This is great, can we also add to the appropriate place under "Security and Trust"? This is a differentiating feature and is strong evidence for our positioning that Kernel is the most secure browser for agent tasks. Something that enterprise companies always ask about. Maybe we add here? shared-responsibility-model?

meliaj · 2026-10-09T16:30:59Z

Folded in your suggestions. Is there any positioning language you want to add to the intro?

AnnaXWang

This looks good to me for first release! I may iterate with solutions eng + marketing in a future rev but non-blocking

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit dba4bc4. Configure here.}

cursor · 2026-10-09T23:02:20Z

+
+</CodeGroup>
+
+A pool update replaces the entire `network` object, unlike a browser update. Omit `network` to leave it unchanged. If you provide it, include every network setting you want to keep, including `private_hosts` and `proxy_routes`. Omitting `allowed_hosts` from that replacement removes the pool's allowlist; `network: {}` clears the entire network configuration. An empty allowlist (`[]`) is invalid. You can add an allowlist to a pool that doesn't have one because its unfiltered browsers are replaced rather than given a list in place.


Pool network rules packed together

Low Severity

Several independent pool network update rules sit in one paragraph: whole-object replacement, omit-versus-replace behavior, clearing via network: {}, rejecting [], and adding an allowlist to a pool. Readers can miss that omitting allowed_hosts from a replacement removes the list.

^{Triggered by learned rule: Use bullet lists when covering multiple distinct points in guides}

^{Reviewed by Cursor Bugbot for commit dba4bc4. Configure here.}

hiroTamada

Should we wait public GA?

mintlify Bot deployed to staging October 1, 2026 15:31 View deployment

mintlify Bot deployed to staging October 1, 2026 19:41 View deployment

mintlify Bot deployed to staging October 1, 2026 19:54 View deployment

mintlify Bot deployed to staging October 1, 2026 20:32 View deployment

mintlify Bot deployed to staging October 5, 2026 17:29 View deployment

meliaj marked this pull request as ready for review October 5, 2026 18:14

meliaj requested a review from hiroTamada October 5, 2026 18:14

andrewleesteele mentioned this pull request Oct 5, 2026

Restructure How it works: Configure, Control, Scale, Observe, Manage #671

Merged

meliaj mentioned this pull request Oct 5, 2026

Report network policy denials as proxy_error events kernel/kernel-images#429

Merged

mintlify Bot deployed to staging October 5, 2026 23:33 View deployment

meliaj marked this pull request as draft October 5, 2026 23:44

meliaj mentioned this pull request Oct 5, 2026

Document the destination_route_unavailable proxy error #676

Closed

mintlify Bot deployed to staging October 7, 2026 18:52 View deployment

meliaj and others added 8 commits October 8, 2026 21:16

Say that browsers acquired from a pool can't get an allowlist

75c8cb6

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

List the secure DNS policies rejected with an allowlist

9386ba6

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Note that CAPTCHA providers need to be on the allowlist

b853ed4

docs(browsers): align egress allowlists with released behavior

1c93ee2

meliaj force-pushed the hypeship/egress-allowlists branch from 59fa63a to 1c93ee2 Compare October 8, 2026 21:22

mintlify Bot deployed to staging October 8, 2026 21:24 View deployment

docs(browsers): document egress allowlists on browser pools

f964ed5

mintlify Bot deployed to staging October 8, 2026 21:55 View deployment

docs(browsers): qualify allowlist denial telemetry

75a38be

mintlify Bot deployed to staging October 8, 2026 23:16 View deployment

docs(security): add egress allowlists to shared responsibility model

f59203c

mintlify Bot deployed to staging October 9, 2026 16:21 View deployment

AnnaXWang approved these changes Oct 9, 2026

View reviewed changes

docs(security): describe allowlists on browser pools

dba4bc4

mintlify Bot deployed to staging October 9, 2026 16:47 View deployment

meliaj marked this pull request as ready for review October 9, 2026 22:58

cursor Bot reviewed Oct 9, 2026

View reviewed changes

hiroTamada approved these changes Oct 10, 2026

View reviewed changes

Navigation Menu

Repository navigation

Document browser egress allowlists - #657

Document browser egress allowlists#657
meliaj wants to merge 12 commits into
mainfrom
hypeship/egress-allowlists

meliaj commented Oct 1, 2026 •

edited by cursor Bot

Loading

Uh oh!

mintlify Bot commented Oct 1, 2026 •

edited

Loading

Uh oh!

AnnaXWang commented Oct 9, 2026

Uh oh!

meliaj commented Oct 9, 2026

Uh oh!

AnnaXWang left a comment

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Oct 9, 2026

Uh oh!

hiroTamada left a comment

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		</CodeGroup>

		A pool update replaces the entire `network` object, unlike a browser update. Omit `network` to leave it unchanged. If you provide it, include every network setting you want to keep, including `private_hosts` and `proxy_routes`. Omitting `allowed_hosts` from that replacement removes the pool's allowlist; `network: {}` clears the entire network configuration. An empty allowlist (`[]`) is invalid. You can add an allowlist to a pool that doesn't have one because its unfiltered browsers are replaced rather than given a list in place.

Conversation

meliaj commented Oct 1, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

summary

validation

release

Uh oh!

mintlify Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AnnaXWang commented Oct 9, 2026

Uh oh!

meliaj commented Oct 9, 2026

Uh oh!

AnnaXWang left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Oct 9, 2026

Choose a reason for hiding this comment

Pool network rules packed together

Uh oh!

hiroTamada left a comment

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

meliaj commented Oct 1, 2026 •

edited by cursor Bot

Loading

mintlify Bot commented Oct 1, 2026 •

edited

Loading