Browser Extension Guide

If a term is unfamiliar, open the Glossary.

The Dralvia extension gives analysts inline verdicts and DOM intent capture inside Chromium-based browsers.

Installation

1) Download the bundle

• In the admin console, open Browser Extension Downloads and download the latest ZIP.
• Verify the SHA-256 checksum if your security policy requires it.
• Unzip the bundle locally.

2) Install in Chrome (manual)

• Open chrome://extensions and enable Developer mode.
• Click Load unpacked and select the unzipped folder.
• Pin the extension via the puzzle menu so analysts can see the badge.

3) Pair the extension to your workspace

• Sign in to https://dralvia.tech once; the extension will automatically enroll to your workspace.
• Enrolment is part of the Starter plan and above (including the 7-day Starter trial). In a free workspace the extension does not enrol. It keeps working without an account: it warns on risky pages and sends only the site and path of each page.
• After enrollment, browser activity signals are workspace-scoped and visible in Browser Activity Signals.
• To connect manually, open the extension settings, paste your workspace token, then click Check connection. The settings page verifies the connection and shows three steps: Reaches Dralvia, Workspace token accepted, and Policy synced. Use this any time to confirm the browser is connected and your policy is in effect.
• If you use managed deployment, you can skip this step by providing an extensionToken via policy.
• For manual ZIP install, do not edit extension files and do not paste API key into the ZIP.

4) Managed rollout (recommended)

• Publish the ZIP to the Chrome Web Store (or your enterprise update URL).
• Deploy via Intune/Jamf/GPO so the extension stays up to date.
• For zero-touch enrollment and token auto-renewal, configure managed policy key dralviaExtensionConfig with:
  • tenantApiKey (workspace-scoped API key; used only to mint/refresh extension tokens)
  • optional extensionToken (pre-seeded bootstrap token)
  • optional deviceLabel (PC name or asset tag)
  • optional deviceId (your internal device ID)
  • optional deviceTrust (managed or unmanaged)
  • optional deviceOwnership (corporate or byod)
  • optional workforceType (employee or contractor)
  • optional autoScanInIncognito (true to also check pages in incognito windows automatically; off by default from version 1.1.0)

Managed policy example:

{
  "dralviaExtensionConfig": {
    "apiBase": "https://dralvia.tech/api",
    "tenantApiKey": "CHANGE_THIS_TO_YOUR_TENANT_API_KEY",
    "deviceLabel": "OPTIONAL_HOSTNAME_OR_ASSET_TAG",
    "deviceId": "OPTIONAL_INTERNAL_DEVICE_ID",
    "deviceTrust": "managed",
    "deviceOwnership": "corporate",
    "workforceType": "employee"
  }
}

5) Install / update prompt expectations

• Manual unpacked install in Chrome/Edge can show the standard browser extension install prompt when the bundle is first loaded.
• Manual unpacked installs can also show the usual developer-mode warning banner in Chromium browsers; that is expected for local test validation.
• Managed enterprise rollout should not require each user to approve the extension interactively after policy is applied.
• If a new extension build adds or changes permissions, Chrome/Edge can require the updated permission grant before the new behavior becomes active.

Scale guidance:

• A single workspace API key can enroll many endpoints in the same workspace.
• For large fleets (for example 1000+ endpoints), keep one workspace key in managed policy and set unique deviceLabel/deviceId per device from MDM variables.
• This keeps enrollment zero-touch and avoids per-user ticket-driven setup.

Features

• Popup risk review: clicking the pinned Dralvia extension opens a 380px browser-native popup for the active tab. It scans the page, shows a risk score, top findings, recent local scan history, and links into the platform report.
• Risk indicator: shows live score + flags for the active tab; clicking opens the admin console at #/phishing.
• DOM intent capture: collects form/button intent and sends it into the signed preview pipeline when the feature is enabled.
• Shadow browsing hooks: analysts can highlight risky forms and request remote shadow renders from the platform.
• Safe-link preview: surfaces detonation results for any rewritten links.
• Header signal: every page load emits a trimmed header/HAR sample so you can audit posture from Browser Activity Signals.
• Extension inventory (observe mode): managed rollouts can grant the optional browser management permission so Dralvia can report installed extension metadata (plus linked-domain intel from Dralvia scans, trusted-publisher matching, and update-channel reputation) into #/browser-security.
• Browser data movement guardrails: after workspace enrollment, the extension can now load the workspace-scoped browser DLP policy and apply browser-time warnings or blocks to uploads, explicit file-download clicks, paste events, print, and high-signal form submissions when the current destination is in scope.
• Decision guidance in browser prompts: those warn/block interventions now also explain the dominant trigger, summarize the data at risk without exposing raw secrets, and suggest the safer allowed path directly in the extension modal before the user retries the action.
• Scan-aware interventions: those same browser-time controls now also consume the page's unified Dralvia scan verdict so high-risk and impersonation-heavy pages can elevate upload, clipboard, print, or form-submission interventions before the user completes the action.
• Runtime account-posture inference: the extension now also infers likely personal vs corporate posture from visible page identity context so personal_or_unsanctioned policy scope can work in more real browser sessions without sending raw account emails to Dralvia.
• Destination-risk adaptation: browser-time DLP now also consumes SaaS governance control_action, destination sanctioned_status, and workspace risk_note so workspace block controls block, monitor controls warn, and risky unknown/unsanctioned destinations can warn even when the normal DLP scope did not otherwise match.
• Adaptive access context: managed rollouts can now also pass deviceTrust, deviceOwnership, and workforceType so browser-time DLP rules can elevate enforcement on unmanaged, BYOD, or contractor contexts even when the destination itself is otherwise sanctioned.
• Workspace-binding enforcement: when a sanctioned SaaS app is marked tenant_bound or sso_required, the extension can now also elevate browser-time intervention for personal or mixed runtime posture instead of leaving that governance metadata as console-only context.
• SWG navigation rule sync: managed Chrome/Edge rollouts can sync workspace SWG warn/block rules from the platform and translate them into local declarativeNetRequest rules. Workspace block rules now enforce by default, workspace monitor rules compile to a warn interstitial, and use swgNavigationEnforcement=false or swg_navigation_enforcement=false in managed/local extension config only when you want to keep a rollout in dry-run while validating the compiled rule set in Web Access Protection's Compiled browser navigation rules panel.
• Those compiled rules can also stay scoped to a path prefix, such as https://wiki.example/admin, so browser blocking can target one area of a site instead of the full host.
• When live enforcement is enabled, page-load blocks redirect users to the Dralvia blocked-page interstitial and page-load warns redirect to a confirm-then-continue interstitial. Use dry-run first if you want operators to audit the compiled feed and rule counts without changing user navigation yet.
• Operator-visible DLP telemetry: browser-time data-movement interventions now write normalized scope context back to the Browser Protection so operators can see target labels, destination status, and the runtime blind spots that still need stronger enforcement.

Current scope and limits

• The current extension is Dralvia's own risk and telemetry extension, and it can now observe third-party extension inventory when the browser grants the optional management permission.
• The popup uses extension-native popup.html, popup.css, and popup.js; it does not load remote React, Babel, or hosted font scripts, so it can run under MV3 extension CSP.
• Managed enrollment, browser activity signals, and policy sync are live today; enforcement attempts are best-effort and reported back to the Browser Protection. Current enforcement actions are block, prevent_install, and remove.
• The extension can now warn or block selected browser actions, and it will also use the current page scan verdict plus SaaS governance destination risk to elevate interventions on high-risk, impersonation-heavy, workspace-blocked, monitored, or risk-noted destinations. Runtime destination matching is still strongest for all_activity policies and clearly unsanctioned apps. Personal-vs-corporate posture is now inferred from visible page identity signals, but that inference is still heuristic rather than guaranteed.
• Adaptive unmanaged / BYOD / contractor controls now exist, but their certainty still depends on managed-policy hints and any matching Device Agent / device activity context you provide for the endpoint.
• Workspace-binding and SSO-required browser-time enforcement now exists for sanctioned apps, but the runtime still relies on posture inference rather than definitive browser identity APIs.
• SWG navigation enforcement requires the new MV3 DNR permissions. Workspace block rules now register redirect rules by default, workspace monitor rows now produce warn interstitials, and the blocked/warn interstitials, Browser Protection enforcement strip, and SWG Policy Dashboard compiled-rule preview remain available for rollout validation and optional dry-run staging.
• To opt a workspace out and return to dry-run without uninstalling the extension, set workspace browser policy swg_navigation_enforcement=false or managed/local config swgNavigationEnforcement=false / swg_navigation_enforcement=false.
• Firefox can join this path only when managed rollout config explicitly sets swgNavigationFirefoxFallback=true or swg_navigation_firefox_fallback=true.
• Browser-time DLP telemetry now reports scope match vs coverage-gap context to the console, but those gaps are expected until runtime posture resolution is stronger for personal_or_unsanctioned.
• The browser prompt coaching currently covers extension warn/block modals. SWG and SaaS response surfaces still need the same shared coaching contract for full cross-surface parity.

Privacy & controls

• Only tabs that match your configured domain patterns are scanned (set through the extension's managed match-pattern policy).
• DOM payloads are sanitized locally before leaving the browser; no passwords or secrets are transmitted.
• Header signals include the URL, referrer, <meta http-equiv> entries, and the first 25 performance.getEntriesByType('resource') results. No cookies, DOM contents, or keystrokes are transmitted, and the payload is capped on the server.
• Extension inventory mode sends extension id, name, version, install source, requested permissions, requested host access, homepage/update-channel metadata, and optional managed device/user labels. Dralvia links host access to known scan results to flag risky domains and uses the update channel to separate store-signed or publisher-aligned extensions from homepage-only claims. It does not read browser history, cookies, or the contents of other extensions.
• Browser data-movement interventions report normalized action metadata back to Dralvia, including destination scope reason, sanctioned-status context, destination-risk reason, scan-driven risk context such as impersonated brand or top scan reasons, and runtime posture summaries based on matched domains. The current runtime does not ship clipboard contents, file contents, typed text, or raw account emails to Dralvia.
• When configured, managed-policy posture hints (deviceTrust, deviceOwnership, workforceType) are also sent to Dralvia's browser DLP context route so last-mile enforcement can distinguish unmanaged, BYOD, and contractor contexts without shipping clipboard contents, file contents, or typed text.
• Use the Tenant Playbook + Security Operations section to define who can trigger captures vs read-only users. The Browser Activity Signals workspace lists the last 25 samples so you always know what was collected.
• The extension cannot read Windows/macOS hostnames directly. If you need PC names, provide a deviceLabel via managed policy or pair with the Device Agent for authoritative host metadata.

Browser activity signals

• The extension sends browser activity signals with a workspace-scoped enrollment token stored in the extension.
• Extension version, pilot email/domain, device labels, and resource timing metrics are included so SecOps can verify builds and opt-in status.
• The Browser Activity Signals workspace is workspace-scoped; you only see captures from your workspace.
• To disable the feature for a workspace, block browser-activity signal ingestion at your API gateway; the extension will simply log a warning and continue scanning locally.

Self-check playbook

Use this 5-step isolation flow before escalating:

1. Configuration: confirm required inputs are present and formatted correctly.
2. Permission: confirm your role can perform the action (401/403 usually indicates authz/authn mismatch).
3. License/feature: confirm the feature is enabled for your workspace plan and module toggles.
4. Quota/rate limit: check for 429 responses and cooldown windows.
5. Service health: if you see 5xx, retry once after 30-60 seconds and capture exact error text.

If still failing, escalate with workspace ID, UTC timestamp, route, action, payload shape (no secrets), and screenshot/error response.

Troubleshooting

Symptom	Fix
"Cannot reach API" banner	Check API base URL, ensure HTTPS certificate is trusted, and confirm your workspace sign-in session is active if the route requires sign-in.
Check connection shows "Could not reach Dralvia"	Confirm the API base address and your network. The settings page could not reach the service.
Check connection shows "Workspace token was rejected"	The token is wrong or expired. Copy a fresh token from Dralvia Admin, API Keys, and save again.
Not enrolled / no device in the fleet view	Sign in to https://dralvia.tech once, or provide an extensionToken via managed policy, then run Check connection.
Enrolment refused with plan_required	The workspace is on the free plan. Enrolment needs Starter or above, or an active Starter trial. The extension keeps warning on risky pages without enrolment.
Pasting a secret does nothing	Confirm the connection is healthy, the data class is enabled, and the mode is Warn, Redact, or Block rather than Allow.
Redact did not strip a file	Redact applies to text paste and drop. Files cannot be redacted inline and fall back to a warning. Use Block to stop files.
No badge updates	Verify extensions/browser/manifest.json has permission for the site pattern.
DOM capture disabled	Ensure domIntentCaptureEnabled flag is true for the workspace and the user has the necessary role.

Document this guide in your internal wiki and distribute via onboarding emails so every analyst knows how to install and update the extension safely.

Who this is for

This guide is for workspace owners, workspace admins, and security operators who need clear, repeatable steps without support intervention for day-to-day execution.

Role-based start here

• Workspace Owner: Start with Before you start, then complete Step-by-step and Known limits and rate limits.
• Workspace Admin: Focus on Step-by-step, What each button does, and API and automation.
• Security Analyst: Start at Day-2 operations and Troubleshooting, then use API error quick reference.
• Integrator/Engineer: Start at API and automation, then validate with Step-by-step and FAQ.

Before you start

Use this short checklist before making changes:

1. Confirm you are signed into the correct workspace account.
2. Confirm your role includes the permissions needed for this page.
3. Confirm your browser session is fresh (if pages behave unexpectedly, sign out/in once).
4. Confirm required prerequisites (API keys, agent enrollment, license, upstream integrations) are already in place.

Step-by-step

Follow this sequence for predictable results:

1. Open the workspace from the workspace menu.
2. Review current status/health/last update indicators before making changes.
3. Apply one change at a time and save.
4. Run the available validate/probe/refresh action.
5. Confirm the expected output appears (status change, new event, successful result).
6. If behavior is not as expected, use Troubleshooting below before repeating actions.

Day-2 operations

After initial setup, keep this surface healthy with a simple routine:

1. Daily: verify data freshness and error banners.
2. Weekly: review trends, limits, and failed actions.
3. Monthly: review permissions, keys/tokens, and stale entities.
4. After any incident: capture evidence and update your internal operating notes.

Managed rollout playbook and support path

A repeatable, self-serve managed rollout:

1. Stage the policy. Push the managed policy (dralviaExtensionConfig) with your workspace API key and per-device deviceLabel from MDM, as in Managed rollout above. Keep the rollout in observe or warn while you validate.
2. Confirm enrollment. Use the devices view to confirm endpoints are enrolling. Re-pushing the policy is safe and idempotent.
3. Prove coverage. Check the rollout proof view: active versus stale devices, the version distribution, and the percent of devices already on the latest published version. Treat the coverage percent and stale count as your deployment evidence.
4. Watch for drift. The rollout view's deployment status flags drift_detected with reasons (stale devices, version fragmentation, a fleet behind the latest version). Re-push or re-enroll the called-out endpoints.
5. Check extension health. The extension health telemetry shows endpoints where the extension is installed but degraded or unhealthy (policy not loaded, missing permissions, recent errors). Fix those before promoting the rollout to block.
6. Promote enforcement. Once coverage is high, drift is clear, and health is ok, move the rollout mode from observe/warn to block.

Support path

• Most of the rollout is self-serve: install, enroll, prove coverage, watch drift and health, then promote enforcement. No support ticket is required for these steps.
• Use Troubleshooting and the API error quick reference below first.
• Contact support when: enrollment fails for endpoints whose policy and key are confirmed correct, coverage stays low after a re-push, health stays unhealthy after reinstall, or you need a managed pilot enabled (for example Microsoft 365 or Google Workspace mailbox runtime, which are support-gated). Capture the workspace, a device label, the timestamp, and the relevant route or banner text so support can act without back-and-forth.

What each button does

Button labels can vary by module, but behavior is consistent:

• Refresh: reloads the latest data from backend APIs without changing configuration.
• Save: persists workspace-scoped configuration changes.
• Run/Probe/Validate: executes a non-destructive health or verification action.
• Download: fetches workspace-scoped artifact(s) (for example bundle, checksum, signature, or report).
• Verify: checks integrity/consistency and returns pass/fail details.
• Enable/Disable: toggles module behavior for your workspace; audit evidence should be recorded.

If a button appears disabled, check role permissions, required fields, and workspace license/feature entitlement first.

API and automation

Everything in this page should remain workspace-scoped. If your team prefers automation, use the corresponding API endpoints with the same guardrails as the UI:

• Use authenticated requests bound to your workspace context.
• Use idempotency/retry controls where available.
• Validate outcomes in the UI after automated runs.

Rollout proof

The Browser Protection area exposes a managed-rollout proof view for your workspace so you can confirm the extension is actually deployed and current, not just configured. It reports:

• active enrolled and revoked device counts
• recently-active versus stale devices (those that have not checked in within a configurable window, 7 days by default)
• how many active devices run each extension version
• the latest published extension version and the share of active devices already on it (coverage percent)
• the most recent enrollment and check-in times

Use the coverage percent and stale count as rollout evidence and to find devices that need a re-push or re-enroll.

Extension health telemetry

The managed extension can report its own health (whether it loaded the workspace policy, whether required browser permissions are granted, and recent runtime error counts). Dralvia normalizes each report into a redacted health record with an overall level of ok, degraded, or unhealthy plus the specific reasons (for example policy not loaded, missing permissions, or recent errors), and records it in the Browser Protection event feed. Use it to spot endpoints where the extension is installed but not actually working before they become silent coverage gaps.

Deployment status and drift

The same view also reports an operator deployment status with drift detection. It rolls the numbers above into a single status (healthy, drift_detected, or no_deployment) plus a list of drift signals, for example: a high share of stale devices, too many extension versions in the field (fragmentation), a fleet that is behind the latest published version, or devices that did not report a version. Use it to catch a rollout that has decayed or fragmented before it becomes a coverage gap.

If your endpoint mapping is not obvious, start from Help Center and follow the linked API docs.

Next best actions

After finishing this page, continue with related workflows so your workspace setup stays end-to-end complete:

• EDR response and host actions
• Web Access Protection and dry-run events
• Identity risk and OAuth response
• EvidencePack verification and transparency log
• Risk economics and plan recommendation

FAQ

Q: I clicked save but nothing changed. A: Refresh once, confirm permissions, and verify required fields.

Q: Why do I see missing API key/unauthorized errors? A: Confirm your workspace API key/session is valid and mapped to the correct workspace scope.

Q: Can non-admin users use this page? A: Usually read-only access is possible; write actions require workspace-admin or equivalent roles.

Next steps

After finishing this guide:

1. Validate the result in the related dashboard/workspace.
2. Export or capture evidence if this affects compliance/incident operations.
3. Share the same runbook internally so other operators follow identical steps.
4. Return to Help Center for adjacent workflows.

API error quick reference

Use this matrix when a UI action fails with an HTTP/API error.

Error	Meaning	What to do now
401 Unauthorized	Session token is missing/expired or request is not authenticated.	Sign out/in, refresh once, then retry. Confirm your session is active in the correct workspace.
403 Forbidden	You are authenticated but your role is not allowed to perform this action.	Confirm your role includes the required permission for this button/action. Ask a workspace admin to grant access.
404 Not Found	The route/resource does not exist in current workspace context (or feature not enabled).	Confirm URL/route, workspace context, and feature availability. Refresh and retry; if persistent, capture timestamp and route and contact support.
429 Too Many Requests	Rate limit/quota window was exceeded.	Wait for cooldown/reset window, retry once, then reduce burst traffic/backoff if automated.
500 Internal Server Error	Backend failed unexpectedly while processing the request.	Retry after 30-60 seconds. If still failing, escalate with workspace ID, UTC time, route, action, and full error text.

Known limits and rate limits

These limits can vary by plan and feature, but behavior is consistent:

• Burst traffic can trigger 429 Too Many Requests.
• Workspace quotas apply per feature/module and reset on configured windows.
• Repeated retries without backoff can extend recovery time during saturation.

Recommended operator behavior:

1. Retry once after cooldown for 429 responses.
2. Use exponential backoff in automation.
3. Monitor usage/quota dashboards for sustained high utilization.
4. Request quota review when normal workload regularly approaches limits.