Customer Policy Surface

6.1 What policy controls #

BrowserBox policy is the customer-facing runtime control surface that answers two distinct questions:

• Which sensitive actions are allowed or denied?

• Which browsing targets may the remote browser reach?

The canonical persisted policy file lives at:

~/.config/dosaygo/bbpro/policy/policy.json

BrowserBox normalizes and validates that file before applying it. If a field is omitted, BrowserBox fills in safe defaults for the current schema.

The allowed values listed in this section are based on BrowserBox’s current runtime validation and normalization surface, not on a separate aspirational specification. In practice, customers should be able to trust this section because these values are the same ones BrowserBox validates at load time.

6.2 Canonical policy fields #

The customer-relevant policy bundle currently includes these high-level surfaces:

6.3 Allowed values and defaults #

The most important values customers need to know are listed here directly.

6.3.1 Binary feature controls #

Unless stated otherwise, feature controls are binary decisions:

6.3.2 Enumerated policy fields #

6.3.3 Identity and access configuration #

Three fields govern identity integration for authenticated BrowserBox deployments:

6.3.4 List-valued policy fields #

6.3.5 Where customers can verify allowed values #

Customers do not have to guess. BrowserBox exposes the current policy surface through the customer-facing policy CLI:

• bbx policy show --scope global|user prints one persisted policy source.

• bbx policy show prints the normalized effective policy that BrowserBox is actually using.

• bbx policy validate --file policy.json validates a candidate policy file against the current code and reports invalid enum values directly.

For example, if a customer uses an unsupported mode, BrowserBox validation reports the current accepted set, such as:

featureControls.browserChrome must be one of:
toggle, api, always-show, always-hide

6.4 Sensitive actions BrowserBox can allow or deny #

These actions currently route through BrowserBox’s policy authorization layer:

All of these controls are binary allow / deny decisions except featureControls.browserChrome, which uses explicit UI visibility modes described below.

6.5 Navigation, browser-internal and private-network policy #

BrowserBox separates ordinary browsing, browser-internal access and private/local reachability:

• navigation.allowlist answers “where may the RBI tab browse?”

• navigation.internalAllowlist answers “which explicitly named browser-internal origins may open?”

• navigation.privateNetwork.allowlist answers “which private or local destinations may any request reach?”

• ALLOWED_EMBEDDING_ORIGINS is separate and only controls which parent pages may embed BrowserBox

Browser-internal navigation is denied by default, independently of navigation.mode. To permit an internal page, add its exact origin, for example chrome://extensions. To permit an extension’s pages, add the exact extension origin, for example chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa; BrowserBox then permits paths within that extension. chrome://inspect, chrome://newtab, chrome://omnibox-popup, and devtools:// remain forbidden even if listed. If global and user policies are both active, both must list the origin. about:blank is structurally accepted so BrowserBox can stage safe tab creation, but a user-requested blank tab still follows the configured navigation mode.

The BrowserBox Extensions button is shown only when the effective internal allowlist contains chrome://extensions or a valid exact extension origin. This visibility check uses the policy snapshot only; it does not scan the installed extensions directory.

6.5.1 Navigation modes #

6.5.2 How allowlist entries match #

Allowlist and blocklist entries take four forms. The form of the entry decides how it matches:

Avoid these mistakes:

• A path without a scheme allows the whole site. An entry such as example.com/maps or example.com/maps/* is read as the host example.com. To allow only certain pages, list each page as an exact URL, scheme included. There are no path-prefix entries.

• Only a leading *. is a wildcard. An entry such as *example.com or www.*.example.com is read as a literal host name and matches nothing.

• bbx policy validate does not flag either mistake. Before you rely on an entry, test the addresses you mean to allow and refuse:

  bbx policy check --action navigate --url https://www.example.com/

• Every page load is checked, including links, redirects and new windows opened from an allowed page. If a site sends users through another host, such as a sign-in or media host, that host needs its own entry.

The page a user reaches when a navigation is denied can be replaced with your own; see §5.8.

6.5.3 Private-network controls #

Private-network policy defaults to deny. Customer policy may widen that boundary explicitly:

IPv4-mapped IPv6 addresses such as ::ffff:10.0.0.5 are classified as the IPv4 address they carry, so they cannot be used to bypass an IPv4 rule. An allowlist entry containing / must be a valid IPv4 CIDR; an invalid or IPv6 CIDR is ignored rather than treated as a host. Run bbx policy validate after editing the allowlist and bbx policy check --action navigate --url <url> to confirm the result for a specific destination.

6.6 Certificate-error policy #

Certificate handling is now policy-driven rather than hidden behind a permanent launch flag.

6.7 Browser chrome policy modes #

featureControls.browserChrome does not allow or deny a risky action. Instead, it governs whether BrowserBox’s own visible browser chrome, the tab bar and address bar, is shown, hidden, or user-toggleable.

If the embedder sets ui-visible or allow-user-toggle-ui, those values may further restrict the experience. They cannot widen what the server policy allows.

Navigation in always-hide mode: when chrome is hidden, BrowserBox’s built-in back/forward buttons are not visible to the user. However, tab history is preserved internally. Embedders can navigate the remote browser’s history programmatically through the webview API:

await webview.callApi('goBack');
await webview.callApi('goForward');

The remote-page context menu has no back option. Embedders that need end-user back navigation in always-hide mode should add their own back button wired to the goBack API call above.

6.8 Locking kiosk mode #

A kiosk that users must not leave needs two settings in the server policy. The user’s browser cannot override either of them.

• featureControls.browserChrome set to always-hide. The chrome stays hidden: a ui=true login link, an edited address bar, the context menu and the webview API cannot show it.

• A navigation allowlist naming the kiosk’s sites (§6.5). The server refuses every page load outside it: typed addresses, new tabs, and links, redirects and new windows opened from inside an allowed site.

The allowlist is the boundary; always-hide removes the controls. Hiding the chrome alone is not a boundary, because a user who modifies the browser client could show it again. The allowlist still limits that user to the listed sites, so always set both.

Set them in the global policy, /etc/browserbox/policy.json. The global browserChrome setting takes precedence over a per-user policy, and the global policy applies to every BrowserBox Fleet seat on the host.

# If there is no global policy yet:
sudo bbx policy init --scope global --baseline regulated
sudo cp /etc/browserbox/policy.json kiosk.json
# In kiosk.json set:
#   "featureControls": { ..., "browserChrome": "always-hide" }
#   "navigation": { "mode": "allowlist", "allowlist": ["www.example.org"], ... }
sudo bbx policy set --scope global --file kiosk.json

New sessions start with the policy. In always-hide mode a user who follows a link off the allowlist has no back button, so install a blocked-policy.html page (§5.8.2) with a link back to the kiosk’s start page.

6.9 Per-destination feature controls #

featureControls settings such as downloads and paste are currently global — the same setting applies to all browsing destinations regardless of which site the user is on. Different featureControls per allowlist entry are not supported. If your use case requires different download or clipboard behavior on different sites, the recommended approach is to run separate BrowserBox instances each with a distinct policy configuration.

6.10 Server policy versus embedder policy #

BrowserBox has three relevant policy layers:

1. Global server policy, stored in /etc/browserbox/policy.json, which applies to every Unix user and Fleet seat.

2. User server policy, stored in the user’s existing BrowserBox policy directory, which may tighten but never loosen the global policy.

3. Embedder policy hints, supplied through the canonical webview surface, which may only restrict and never widen the effective server policy.

• An action is allowed only when every active server-policy scope allows it.

• With no global policy, the user policy behaves exactly as before.

• User and embedder restrictions may narrow capabilities further.

• An embedder cannot override a server-side deny into an allow.

6.11 Customer policy CLI #

BrowserBox ships a policy CLI so customers can inspect, initialize, validate, and test the effective policy surface.

bbx policy help
bbx policy where [--scope global|user] [--json]
bbx policy baselines
bbx policy controls [--json]
bbx policy show [--scope global|user]
bbx policy get [--scope global|user]
bbx policy resolve
bbx policy check --action <name> [--url <https://...>] [--source <tag>]
bbx policy trace [--last <n>]
bbx policy init [--scope global|user] [--baseline regulated|compat]
bbx policy reset [--scope global|user] [--baseline regulated|compat]
bbx policy set [--scope global|user] --file <path/to/policy.json>
bbx policy validate [--scope global|user] [--file <path/to/policy.json>]

6.11.1 Useful commands #

6.11.2 Recipe: global policy with a per-user tightening #

Set the administrator-owned policy that applies to every BrowserBox Unix user and Fleet seat:

bbx policy set --scope global --file global-policy.json

Optionally set a stricter policy for one Unix user. The operator reads the source file and BrowserBox writes it in the target user’s policy store, so the target account does not need access to the operator’s file:

bbx policy set --scope user --file policy.json --for user-bbx-0901

Inspect the effective policy actually enforced for that user, then inspect the raw user layer if needed:

bbx policy show --for user-bbx-0901
bbx policy show --scope user --for user-bbx-0901
bbx policy where --for user-bbx-0901

The user layer may tighten the global policy but cannot weaken it. Reset only that user’s layer to a named baseline with:

bbx policy reset --scope user --baseline compat --for user-bbx-0901

6.12 Operational visibility #

When policy blocks an action, BrowserBox emits both customer-visible and operator-visible signals:

• a policy-denied notification in the client UI when a connected client is present at the time of the block

• server log entries prefixed with [policy-decision]

• a persistent trace file at /̃.config/dosaygo/bbpro/policy/decisions.ndjson

Actions that currently produce client-visible notifications include:

Tab-limit blocks that occur during service startup are silent—they close excess tabs without showing a client notification, since no client is connected yet.