Skip to main content

Browser Extension Deployment

This guide is for admins rolling out the Control Zero browser extension to a team of developer or employee machines. The extension scans text typed or pasted into supported AI chat composers, records matches in the org audit feed, and denies a matched mask or block submission.

Pilot: manual distribution only (Chrome Web Store listing pending review)

Enterprise MDM force-install (Chrome Enterprise policy, Jamf, Intune, Google Workspace, Kandji) is temporarily unavailable and will return. The public Chrome Web Store listing is pending Chrome Web Store review -- one-click self-serve install is COMING SOON. For now, distribute the extension manually: a Teams admin downloads

the pre-configured bundle below and shares it, or users load the unpacked build via chrome://extensions -> Load unpacked.

If you are a developer just trying to install the extension to see it work, skip to the sign-up flow, then download the pre-configured bundle from the dashboard (Browser extension -> Download bundle) and load it via chrome://extensions -> Load unpacked. (The one-click Chrome Web Store install is COMING SOON, pending review.)

What the extension does, briefly​

The Control Zero browser extension scans text typed or pasted into AI chat composers on supported sites (Claude.ai, ChatGPT, Gemini, Perplexity) against your org's data-loss-prevention rules. Matches are logged to your org's audit feed. When a rule is configured to mask or block, the extension denies the submission or cancels the paste.

What the extension captures:

  • The matched text span (e.g., a specific SSN that tripped a rule)
  • 40 characters of context before and after the match
  • The host the user was on (e.g., claude.ai)
  • A device ID unique to this browser profile
  • Hostname, user agent, extension version
  • Optionally, the user's work email (opt-in)

What the extension does NOT capture:

  • The full contents of the composer when no rule fires
  • Keystrokes when the extension is paused (10-minute user override)
  • Any content on non-AI-chat surfaces (search bars, password fields, etc.)
  • Any content on sites outside the explicit allowlist

Network-level guard (v0.2.1)​

Starting in extension version 0.2.1, the extension installs a second line of defense alongside the DOM-level overlay: a network-level guard that observes every outgoing AI request and can block it before it leaves the browser.

The guard requires three additional Chrome permissions in the manifest:

  • webRequest -- used in observer-only mode. Manifest V3 forbids blocking webRequest listeners, so the listener only reads the request body, scans it against the org's DLP rules, and emits an audit entry on a hit.
  • declarativeNetRequest -- the only MV3-supported way to actually block a request. The extension synchronizes a dynamic ruleset against any DLP rule scoped to browser_ext_network that has status==='live' AND enabled AND action==='block'. A rule with action set to detect or mask does not install a network-level block; those actions are handled solely by the DOM overlay. The browser evaluates the installed rules in the network stack, which means a block still works even if the page disabled JavaScript or rewrote the textarea around the DOM overlay.
  • declarativeNetRequestFeedback -- lets the extension log which dynamic rule fired, so the audit entry can name the policy that blocked the call.

Why both: the DOM-level overlay is the user-facing UX (Grammarly-style underlines and tooltips). The network guard is the safety net for when the overlay is bypassed. Together they cover composer typing and XHR-level egress.

The new DLP rule scope browser_ext_network is distinct from the existing browser_ext (DOM-only). Admins can scope a rule to either, both, or neither. The backend API accepts browser_ext_network as a valid scope, but the dashboard DLP rule editor does not currently expose it in its scope selector. To create a rule with browser_ext_network scope, use the API directly.

What declarativeNetRequest cannot do​

  • It does not inspect request bodies. The dynamic ruleset matches on URL only, so the network-level block is a hammer ("block all browser AI calls that match a DLP block rule"), not a scalpel. Body-aware decisions still come from the DOM overlay.
  • The 30,000 dynamic rule cap (and 5,000 regex rule cap) is shared across all extensions in the profile. The extension only writes one rule per supported AI surface, so this is not a concern in practice.
  • Rules are evaluated at the network stack, not in the page, so a successful block surfaces to the page as a network error, not a friendly message. The audit entry is the source of truth for what happened.

Cross-browser caveats​

  • Chrome / Edge / Brave / other Chromium: full support, this is the target.
  • Firefox: Firefox still supports blocking webRequest listeners under MV2 semantics, and its declarativeNetRequest implementation is partial. A Firefox port of the extension would use blocking webRequest directly and skip the DNR sync entirely. The manifest.json shipped here is Chromium-MV3-only.
  • Safari: Safari Web Extensions support declarativeNetRequest but not declarativeNetRequestFeedback. A Safari port would drop that permission and lose the per-rule attribution in audit entries.

Enterprise bundle download (Teams tier)​

Teams-tier admins can download a pre-configured extension bundle from the dashboard or via API. The bundle is a ZIP containing the full extension source with an embedded config.json that pre-populates the org ID, API key, and backend URL. This eliminates the need for users to manually configure the extension.

Dashboard​

  1. Navigate to Integrations > Browser Extension in the dashboard.
  2. Select the target platform (Chrome or Firefox).
  3. Click Download Bundle. A ZIP file downloads with the extension source and embedded configuration.
  4. Share the ZIP with your team (internal download link, shared drive, or an unlisted store listing) so each user can install it.

API​

# Download the Chrome bundle
curl -H "Cookie: cz_session=<your dashboard session cookie>" \
  -o controlzero-extension-chrome.zip \
  "https://api.controlzero.ai/api/orgs/<ORG_ID>/browser-extension/bundle?platform=chrome"

# Download the Firefox bundle
curl -H "Cookie: cz_session=<your dashboard session cookie>" \
  -o controlzero-extension-firefox.zip \
  "https://api.controlzero.ai/api/orgs/<ORG_ID>/browser-extension/bundle?platform=firefox"

The ZIP contains a config.json with the structure:

{
  "api_url": "https://api.controlzero.ai",
  "org_id": "<ORG_ID>",
  "api_key": "cz_extension_ext_<generated>"
}

Each bundle download generates a fresh extension-scoped API key (scoped to browser_ext:report and browser_ext:config). Revoke unused bundle keys from the dashboard or API.

Bulk key generation (Teams tier)​

For large fleet deployments where each device needs a unique key, use the bulk key generation API.

Generate keys​

curl -X POST \
  -H "Cookie: cz_session=<your dashboard session cookie>" \
  -H "Content-Type: application/json" \
  -d '{"count": 50, "prefix": "fleet", "expiry_days": 365}' \
  "https://api.controlzero.ai/api/orgs/<ORG_ID>/browser-extension/keys"

Response:

{
  "keys": [
    {
      "id": "uuid",
      "key_prefix": "cz_extension_fleet_abcd1234",
      "secret": "cz_extension_fleet_<full_secret>",
      "scopes": ["browser_ext:report", "browser_ext:config"],
      "expires_at": "2027-04-11T00:00:00Z",
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "count": 50
}

Parameters:

  • count (required): number of keys to generate, 1-100
  • prefix (optional): key name prefix, default "ext"
  • expiry_days (optional): days until expiry, default 365

List keys​

curl -H "Cookie: cz_session=<your dashboard session cookie>" \
  "https://api.controlzero.ai/api/orgs/<ORG_ID>/browser-extension/keys"

Returns all extension keys for the org (prefix only, never the full secret).

Revoke a key​

curl -X DELETE \
  -H "Cookie: cz_session=<your dashboard session cookie>" \
  "https://api.controlzero.ai/api/orgs/<ORG_ID>/browser-extension/keys/<KEY_ID>"

Key rotation procedure​

  1. Generate a new batch of keys via the bulk endpoint.
  2. Re-issue the updated bundle (or distribute the new keys) to your team.
  3. Monitor the audit feed for 24 hours to confirm devices are reporting with the new keys.
  4. Revoke the old keys.

Deployment modes​

During the pilot the extension is distributed manually:

Pre-configured Teams bundle / load unpacked (available today)​

A Teams admin downloads the pre-configured bundle from the dashboard (Browser extension -> Download bundle) and shares it internally, or users load the unpacked build via chrome://extensions -> Load unpacked. Users then paste their org ID and a cz_live_* API key into the options page (the bundle can pre-fill these). Best for teams experimenting with Control Zero before a company-wide rollout.

Chrome Web Store self-install (COMING SOON)​

The public Chrome Web Store listing is pending Chrome Web Store review. Once it is live, users will be able to install the extension themselves from the store and paste their org ID and cz_live_* API key into the options page. Until then, use the pre-configured bundle / load-unpacked flow above.

Compliance checklist (pre-rollout)​

Do not deploy this extension to employee devices without completing this checklist. Monitoring software, even cooperative DLP, has legal implications in many jurisdictions.

EU (GDPR, ePrivacy, codetermination law)​

  • Works council approval (Germany, Austria, France, Italy) — codetermination law requires Betriebsrat / Conseil Social / RSU approval before deploying any system that can log employee activity. Have a signed minutes entry approving the rollout.
  • Data Processing Addendum (DPA) updated — your DPA with employees (or union agreement) must name keystroke scanning in AI chat composers as a processing activity.
  • Privacy notice updated — add a section to your employee privacy notice describing what the extension captures, retention, and employee rights.
  • Data residency verified — if EU employees' audit entries cross a border (e.g., US-hosted backend), ensure SCCs are in place or use an EU-hosted backend instance.
  • DPO (Data Protection Officer) sign-off — document that the DPO has reviewed the deployment.

US (CCPA, BIPA, state-specific monitoring laws)​

  • California employees — CCPA requires disclosure of data collection at or before collection. The extension opens its options page with a first-run tutorial on install, and that page carries a standing monitoring notice; decide with your counsel what disclosure your deployment requires, and cover it in your employee handbook.
  • Illinois employees — BIPA covers biometric data, not keystrokes directly, but the Illinois Electronic Monitoring Act (2022) requires written notice of electronic monitoring. Signed acknowledgment from the employee is recommended.
  • Connecticut employees — similar notice requirements under C.G.S. § 31-48d.
  • New York employees — NY Labor Law § 52-c requires prior written notice of electronic monitoring.

Universal​

  • User disclosure banner — the extension's options page shows a monitoring notice. Verify it is present and accurate for your org.
  • First-run tutorial reviewed — the extension opens the options page on first install and shows a tutorial. Comms / enablement team should approve the copy.
  • Rule review — review every rule manually against a sample of your own content for over-broad matching. The backend rejects a pattern shorter than 6 characters, an unbounded quantifier that is not anchored by a literal token of at least 4 characters, and a pure-literal pattern below 2.5 bits of entropy. Those are structural checks only: Control Zero does not measure a rule's false-positive rate.
  • Ignore list policy — decide which rule categories users are allowed to ignore. Default: only custom and ip ignorable; secret and pii always enforced.
  • Audit retention — set a retention cap on the audit log. Default and maximum: 90 days.
  • Heartbeat alert runbook — assign an on-call rotation to respond to "browser extension silenced" alerts from the backend.
  • Panic delete procedure documented — when an employee typos a password into a chat composer and a rule captures it, what's the process to remove that audit entry? Document the SOP.

Troubleshooting​

"Heartbeat alerts are firing but the user is still using Claude.ai"​

Check whether the extension is in paused state (user has hit the "Pause 10 min" button in the popup). Paused extensions continue posting heartbeats so this should not happen, but it's worth verifying. Also check the device clock — if it is more than 15 minutes skewed, the backend may see the heartbeats as stale.

What's NOT in v0.2​

  • LLM-assisted rewrite — "scrub this for me" button that uses the org's gateway to rewrite captured content. Deferred to v0.3.
  • Safari support — Apple's extension model requires a different build and distribution path. Planned for v1.0.
  • Mobile browser support — iOS / Android extensions are a different platform. Planned for v1.0.
  • Per-employee identity via SSO/SCIM — current v0.2 identifies devices, not users. SSO-claimed identity comes in v1.0.
  • Admin-controlled continuous-scan toggle — v0.2 always enables continuous scan on the 4 supported surfaces when the extension is configured. v0.3 adds a managed-storage flag to disable it for orgs that want paste-only mode.

Operational defaults​

SettingDefaultOverride
Heartbeat interval5 minutesHardcoded
Heartbeat-missing alert threshold15 minutesBackend config
Rule cache refresh5 minutesHardcoded
Scan debounce150 msHardcoded
Scan performance budget16 ms per passHardcoded
Circuit breaker3 consecutive scans > 50 msHardcoded
Session activity buffer cap10 entriesHardcoded
Audit entry context window40 chars before + 40 afterHardcoded
Default audit retention90 daysBackend config