Customer Policy Surface

5.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.

5.2 Canonical policy fields #

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

5.3 Allowed values and defaults #

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

5.3.1 Binary feature controls #

Unless stated otherwise, feature controls are binary decisions:

5.3.2 Enumerated policy fields #

5.3.3 Identity and access configuration #

Three fields govern identity integration for authenticated BrowserBox deployments:

5.3.4 List-valued policy fields #

5.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

5.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.

5.5 Navigation and private-network policy #

BrowserBox separates public browsing control from private/local reachability:

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

• 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

5.5.1 Navigation modes #

Allowlist and blocklist entries support:

• exact host names, for example example.com

• exact origins, for example https://secure.example.com

• exact URLs, for example https://secure.example.com/tools?mode=estimate

• wildcard host patterns, for example *.customer.example

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

Note on path-prefix wildcards: patterns such as google.com/maps/* are not yet supported. Matching is currently against the host, origin, or full URL, not against a partial URL path. To permit a specific subdomain, use a subdomain entry such as maps.google.com instead of a path-prefix form. Path-prefix wildcard support is planned for a future release.

5.5.2 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.

5.6 Certificate-error policy #

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

5.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 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');

A context-menu back option is not currently available; it is planned for a future release. In the meantime, embedders that need end-user back navigation in always-hide mode should add their own back button wired to the goBack API call above.

5.8 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. Per-destination feature controls (different featureControls per allowlist entry) are planned but not yet 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.

5.9 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.

5.10 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>]

5.10.1 Useful commands #

5.10.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

5.11 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.