SWG Policies & Shadow Browsing

This guide explains the Secure Web Gateway dry-run workflow, inline coaching, exceptions, and adaptive shadow browsing. If a term is unfamiliar (for example SWG, dry-run, or rate limit), open the Glossary.

Quick start (10 minutes)

1. Open #/swg-policy.
2. Review the Overview tab for dry-run, policy, SaaS, shadow render, and attestation counts.
3. Open Evaluate and evaluate one known-safe URL in dry-run mode.
4. Evaluate one known-risk URL and confirm decision/coaching text.
5. Review the latest dry-run feed entries in Evaluate.
6. Open Policy, create one temporary exception rule, then remove it.

SWG policy tabs

#/swg-policy opens on an overview-first layout so operators do not have to scan every SWG control on one page.

• Overview summarizes dry-run coverage, blocked/warned decisions, category and exception inventory, compiled browser rules, SaaS governance, shadow renders, and attestation feed counts.
• Evaluate contains the end-user exception contact, live URL dry-run tester, inline decision coaching, and recent dry-run event feed.
• Policy contains the category database, compiled browser navigation rules, and workspace exceptions.
• SaaS contains Shadow-IT discovery, SaaS inventory, session controls, governance ownership, and governance timeline.
• Shadow contains adaptive shadow browsing and remote render evidence.
• Attestation contains the CDN attestation feed and status summary.

Setup and health (is it on and working?)

The Overview tab opens with a Web Access Protection health card that answers, in one glance, whether protection is set up and working. It reads from GET /swg/health. Enforcement is browser-native through the Dralvia extension, so it protects the browsers where the extension is installed. It does not provide network-wide coverage.

Web Access Protection is browser-first by design: Dralvia enforces, coaches, and gathers evidence at the browser, which is where users actually act and where rollout is low-friction. It is not a network proxy, so unmanaged browsers and non-browser traffic are out of scope. Network-layer coverage is not included in this browser-first service and would be added only for teams that need it; it does not change how the browser-first path works today.

The card shows a single headline status, the current mode, the extension state, the policy state, the last decision, the last error, and a Test policy button that opens the Evaluate tab.

Status	Meaning	What to do
Not configured	No policy, controls, or events yet for this workspace.	Add a SaaS control or a policy exception, then install the extension.
Extension not detected	No recent activity from the extension.	Install or sign in to the extension, then revisit.
Observe mode (not enforcing)	The extension is active but block/warn enforcement is off, so decisions are recorded only.	Turn on enforcement when you are ready to warn or block.
Policy active (enforcing)	The extension is active and block/warn enforcement is on.	Nothing; review decisions in Evaluate and SaaS.
Sync lagging	The extension was seen but not recently, so its policy may be stale.	Reopen a managed browser, confirm the extension is signed in.
Error	The most recent decision recorded an error.	Open the Evaluate tab and review the latest decision detail.
Disabled	Web Access Protection is off for this workspace.	Configure a policy to turn it on.

Mode is shown separately as Enforcing, Observe only, or Disabled. Observe and Disabled do not stop traffic; only enforcing mode warns or blocks.

Reading a decision (why allow, warn, coach, or block)

When you evaluate a URL in the Evaluate tab, the result includes a Decision detail panel so you can understand the outcome at a glance without reading raw logs:

• Outcome: the effective action (allow, monitor, warn, redact, block, or coach).
• Category matched: the web category that matched, or None.
• SaaS app matched: the recognized SaaS/AI app, or None.
• Sanctioned status: sanctioned, controlled, unsanctioned, or unknown.
• Control action: the SaaS control applied for this app, or None.
• Exception: whether an approved exception override was applied (with its ID).
• Evidence generated: whether a signed EvidencePack (Dralvia's exportable evidence report) was produced.
• Coaching: whether a user coaching message was attached.

Below it, the Why this happened card translates the decision into plain language (reason, risk, safer path, next step). Enforcement is browser-native through the Dralvia extension, so it applies on the browsers where the extension is installed; it does not provide network-wide coverage.

Deep dive setup flow (GUI + API parity)

Prerequisites

• Active workspace API key.
• Web Access Protection module enabled for workspace.
• Operator account with Web Access Protection write permissions.

Exact fields to fill

• URL evaluation: url, optional mode, optional context.
• Exception creation: pattern, action (allow|warn|block), optional coaching_message, optional expiry metadata.

Step-by-step flow

1. GUI: open Evaluate in SWG dashboard and run Evaluate for a baseline URL.
2. API parity: POST /api/swg/evaluate with the same URL.
3. GUI: stay on Evaluate, open the recent dry-run feed, and validate decision parity.
4. API parity: GET /api/swg/dryrun/events?limit=100.
5. GUI: open Policy, add an exception, then return to Evaluate and re-evaluate URL.
6. API parity: POST /api/swg/exceptions, verify with GET /api/swg/exceptions, then remove with DELETE /api/swg/exceptions/{id}.

Expected result

• Same URL yields consistent policy action in UI and API.
• Dry-run history records evaluations.
• Exception lifecycle is fully auditable.

Rollback path

1. Remove temporary exceptions.
2. Re-run evaluation and confirm default policy behavior returns.
3. Export dry-run entries before and after rollback for audit notes.

Annotated screenshot

Figure: Evaluate URL, review policy/coaching output, and validate dry-run feed.

Evaluate URLs

Via UI

1. Open Web Access Protection (#/swg-policy).
2. Open the Evaluate tab.
3. Use the SWG Dry-Run Tester form to enter a URL and click Evaluate.
4. Review the category, policy, action, and coaching message. The result now also includes a Why this happened panel with Reason, Risk, Safer path, and Next step.
5. If the result is unexpected, review the recent dry-run feed on the same tab to compare prior decisions and their derived Why this happened summaries side by side.

Via API

curl -X POST "$BASE_URL/swg/evaluate" \
  -H "X-API-KEY: $DRALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://social.example", "context": {"hour_utc": 23}}'

Response includes policy, action, coaching_message, and exception_applied.

Batch policy testing (validate before rollout)

To test many scenarios at once and validate a policy change before you roll it out, post a batch of scenarios to POST /swg/policy/test. Each scenario is a URL and an optional expect_action. The harness evaluates each URL with the live policy and SaaS controls, and where you supplied an expected action it reports pass/fail, plus a summary (total, asserted, passed, failed, all_passed).

curl -X POST "$BASE_URL/swg/policy/test" \
  -H "X-API-KEY: $DRALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenarios": [
        {"url": "https://social.example", "expect_action": "warn"},
        {"url": "https://drive.google.com"}
      ]}'

The harness is read-only: it does not record dry-run events, so it is safe to run as a policy regression check. Up to 100 scenarios per request.

CDN attestation in SWG decisions

If you use Dralvia edge plugins/CDN integrations, SWG decisions can show attestation status directly in the UI.

1. Ensure your edge integration is sending workspace Edge Activity Signals with metadata.attestation.
2. Run a URL evaluation in Web Access Protection.
3. Check the CDN attestation block in the result, the Attestation column in recent dry-run events, and the Attestation tab for workspace-wide status.

Expected status mapping:

• ok / pass / valid -> verified
• fail / invalid / error -> failed
• expired / stale -> expired
• anything else -> unknown

Example attestation metadata:

{
  "metadata": {
    "edge_version": "2026.02.04",
    "attestation": {
      "status": "ok",
      "provider": "cloudflare",
      "tee": "sgx",
      "sbom_digest": "sha256:..."
    }
  }
}

You can also query your workspace feed directly:

curl -H "X-API-KEY: $DRALVIA_API_KEY" \
  "$BASE_URL/swg/attestation/events?limit=50"

CaseGraph linkage (workspace scope)

Attestation signals also appear in the Threat Graph/CaseGraph data for your workspace.

• Query GET /graph?entity=<domain> and check for edges:
  • attestation_status -> attestation_status:*
  • attested_by -> attestation_provider:*
  • attested_edge_version -> edge_version:*
• You can also pivot back by querying a provider node, for example:
  • /graph?entity=attestation_provider:cloudflare

Category database

• Search the patterns table to confirm how a site is classified.
• To request a category change, create an exception (see below) or contact support with the desired pattern/action.
• The category table is in the Policy tab.

Exceptions

• Use the Exceptions section to add allow/warn/block overrides for specific patterns (wildcards allowed) and optional workspace ID.
• URL-style patterns can also carry a path prefix for browser navigation enforcement, for example https://wiki.example/admin, when you need to block or exempt only one area of a host instead of the whole site.
• Include a coaching message so end users know why the exception exists.
• Delete exceptions when they expire; the dry-run feed will show that the default policy is back in effect.
• Exception creation and compiled navigation rule review both live in the Policy tab.

SaaS session controls (pilot)

• Use the SaaS session controls panel to set allow/monitor/block actions for specific SaaS domains.
• Controls are workspace-scoped and apply during /swg/evaluate and SWG enforcement workflows.
• monitor will surface as a warn action in dry-run responses; block generates an EvidencePack entry for auditability.
• Shadow-IT discovery, SaaS inventory, controls, governance ownership, and governance history live together in the SaaS tab.
• The SaaS inventory also returns a policy_proof summary so you can prove control coverage, not just list discovered apps. It reports how many controls exist, the action mix (allow/monitor/block), how many controls have governance ownership, the governance coverage percent, and the specific gaps (controls without an owner, and governed apps that have no control). Use it as audit evidence and to close coverage gaps.

Browser navigation enforcement

Managed Chrome/Edge deployments can now sync the workspace-scoped compiled warn/block feed into the Dralvia browser extension. The extension translates host rules into local declarativeNetRequest entries so enforcement can happen in the browser without uploading every visited URL. Firefox can use an explicit fallback path through webRequest when a managed rollout enables it.

Important rollout notes:

• The extension version that includes this runtime is 1.0.13.
• Workspace block rules now enforce by default. If you want rollout validation to stay audit-only first, set managed/local extension config swgNavigationEnforcement=false / swg_navigation_enforcement=false, or set swg_navigation_enforcement=false in workspace browser policy, until the compiled rules for the workspace look correct in the Compiled browser navigation rules panel inside Web Access Protection.
• Workspace SaaS monitor rules now compile to browser warn interstitials, so the user must explicitly continue before the tab reaches that destination.
• Dry-run state records how many rules would block, but does not redirect page loads.
• If the rule feed becomes stale after repeated failures, the extension purges its own SWG navigation DNR rules and fails open rather than ghost-blocking work.
• Enforced redirects land on #/blocked for hard denies and #/warn for confirm-then-continue reviews. Those pages show the host and server-resolved why this happened, while the extension records a swg_navigation Browser Security event back into Dralvia.
• The blocked page's Request exception action opens SWG Policy Dashboard with the blocked host already prefilled in the Exceptions form.
• The extension deduplicates interstitial event reporting once per (rule_id, host, policy_version, action) in the current browser session, so a page refresh does not spam duplicate Browser Security events.
• Browser Protection shows an SWG navigation enforcement strip with recorded blocks, deduped rule/host/hour groups, top blocked hosts, top rule ids, registered rule count, and dry-run/degraded/truncated state from extension beacon metadata.
• Web Access Protection now also shows the exact compiled browser rule feed, including policy_version, workspace scope, rule sources, and the trusted coaching summary the extension will pair with each block.
• Browser navigation rules can now also stay scoped to a path prefix such as https://wiki.example/admin, so workspace policy does not have to block an entire host when only one route tree should be denied.
• Firefox rollout is explicit. Set managed config swgNavigationFirefoxFallback=true or swg_navigation_firefox_fallback=true only for the workspaces or device groups that should use the fallback path.
• If you choose a staged rollout, keep the workspace in dry-run until one managed browser validation run passes end-to-end: compiled feed looks correct, blocked-page interstitial appears for the test host, and Browser Protection reflects the event within one ingest cycle.
• To opt a workspace out of live blocking and return to dry-run, set swg_navigation_enforcement=false in workspace browser policy or set managed/local extension config swgNavigationEnforcement=false / swg_navigation_enforcement=false.

Degraded and bypass behavior

Because Web Access Protection is browser-first, it is important to know exactly when it does not enforce, so there are no silent gaps.

Degraded states (enforcement is intended but weakened):

• Extension not detected: no recent activity from a device. That device is unprotected until the extension is installed or signed in. The Overview health card surfaces this state.
• Sync lagging: the extension was seen but not recently, so its policy may be stale and enforce an older rule set. Reopen a managed browser and confirm the extension is signed in.
• Observe mode: the extension is active but block/warn enforcement is off, so decisions are recorded only and nothing is stopped. This is expected during staged rollout.
• Keyless inspection unavailable: TLS keyless signing fails closed. If the signing provider is down, inspection that depends on it does not fall back to an insecure path; it simply does not inspect. Check the keyless readiness state.

Bypass behavior (traffic that is intentionally or structurally out of scope):

• Unmanaged browsers and non-browser traffic: browser-first enforcement only covers browsers where the managed extension is installed. Other browsers, apps, and network egress are not covered. This is a structural bypass of the browser-first model, not a failure.
• Firefox without the fallback enabled: Firefox joins enforcement only when a managed rollout explicitly enables the webRequest fallback; otherwise it is not enforced.
• Approved exceptions: an allow exception is a deliberate, audited bypass for a specific pattern. Exceptions are visible in the dry-run feed and should be removed when they expire.

For every bypass path, Dralvia still analyzes and records what it can see; it does not present an unprotected surface as protected.

Adaptive shadow browsing

• The Adaptive Shadow Browsing card lets you fetch sanitized DOM snippets remotely.
• Enter the URL, selectors (one per line), and reason. Click Run remote render to queue the job.
• The results pane shows each selector, match counts, sanitized HTML, and fetch/parse latency; the activity log keeps every render for auditing.
• Use this to review credential forms or impersonation attempts without exposing analysts to malicious pages.
• Adaptive shadow browsing lives in the Shadow tab.

Shadow-IT discovery (pilot)

The Shadow-IT discovery panel summarizes the most common domains seen in SWG dry-run events for your workspace.

• Results are workspace-scoped and labeled with category + risk from the SWG category database.
• Use tags to record disposition (approved, review, block). Tags are per-workspace.
• If you are not seeing entries, ensure your edge plug-in, device agent, or extension is calling /swg/evaluate so dry-run events are logged.
• This feed is currently a browser/SWG domain summary with tagging. It is not yet a full SaaS governance inventory with owner assignment, account posture, or lifecycle review.

SaaS inventory snapshot

The Web Access Protection now includes a SaaS inventory snapshot panel that joins the catalog, shadow-IT signal counts, SaaS controls, and governance hardening metadata. Use it to see which sanctioned apps are active, which controls are already applied, which apps require workspace SSO or workspace-bound usage, and which catalog apps are generating shadow-IT signals before you apply policy changes.

SaaS governance notes

Use the governance form in the Web Access Protection to capture owner and review status for catalog apps. The same form now also records whether the app must stay behind workspace SSO, whether usage should remain workspace-bound, what rollback path is acceptable if policy must be loosened during an exception window, which corporate account domains are allowed, and which workspace ids are approved for multi-workspace SaaS apps. This metadata feeds the SaaS inventory snapshot and gives operators a clear place to record who owns an app and whether it is approved, pending review, or rejected.

The dashboard now also includes a SaaS governance timeline panel. Use it to review recent create, update, and delete actions for both SaaS controls and governance metadata, including actor, note, and before/after state. The existing app filter applies to the timeline as well, so you can drill into one app before changing policy again.

Inline coaching

• When action = warn, the coaching text appears in your browser extension or proxy response so users understand the risk.
• Update the coaching text in exceptions or policy definitions to keep messaging consistent with your internal brand guidelines.
• /swg/evaluate now returns a normalized decision_coaching object, and recent SWG dry-run events persist the same block for replay and audit views.
• The SWG dashboard prefers the returned decision_coaching contract and only falls back to local synthesis for older events that do not yet carry that field.

Current limits of the SWG pilot

• These controls do not yet provide browser DLP for uploads, clipboard, print, or text submission.
• SaaS session controls are still app/domain policy entries, not full corporate-vs-personal account enforcement.
• Adaptive shadow browsing is an operator evidence surface, not a direct end-user enforcement path.

Tips

• Keep policies in dry-run for at least a week and monitor the Dry-Run Feed to ensure you aren’t blocking legitimate business apps.
• Export the dry-run feed for audits or weekly governance meetings.
• Combine SWG results with the browser extension: the extension can automatically call /swg/evaluate for every tab and show the action badge.

TLS keyless inspection

• TLS keyless inspection is managed by Dralvia for your workspace.
• You do not need to upload or manage private TLS keys in the workspace UI.
• If your compliance team needs proof, request the operator report for keyless SLO/attestation.
• The keyless path has a published readiness state with explicit completion criteria: a configured signing provider, fail-closed behavior (no private key is held or used as a fallback), supported hash and signature algorithms, workspace-scoped signing keys, and a signing audit trail. The keyless status report shows ready, incomplete, or not_configured plus any unmet criteria, so operators can confirm the path is complete before relying on it.

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.

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.

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

Use this quick triage order to reduce time-to-fix:

1. Auth/session: refresh token by signing out/in.
2. Workspace context: confirm you are in the correct workspace.
3. Inputs/config: verify required fields and formats.
4. Quota/license: confirm limits and feature entitlement.
5. Service health: retry after short delay if backend is transiently degraded.

For escalation, include workspace ID, timestamp (UTC), route name, action attempted, and full error message.

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.

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

GUI -> API quick map

GUI action	API endpoint	Expected outcome
Evaluate URL/domain	POST /api/swg/evaluate	Returns allow/warn/block decision and rationale.
Load dry-run events	GET /api/swg/dryrun/events?limit=100	Shows latest simulation events.
List exception rules	GET /api/swg/exceptions	Returns current exception set.
Add exception rule	POST /api/swg/exceptions	New scoped exception is persisted.
Remove exception rule	DELETE /api/swg/exceptions/{id}	Exception is removed from policy evaluation.

Copy-paste curl examples

BASE_URL="https://dralvia.tech"
API_KEY="YOUR_TENANT_API_KEY"

curl -sS -X POST "$BASE_URL/api/swg/evaluate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"url":"https://example.com","mode":"dry_run"}'

curl -sS "$BASE_URL/api/swg/dryrun/events?limit=50" \
  -H "X-API-Key: $API_KEY"

Postman collection notes

• Define base_url and api_key once at collection level.
• Store one saved request per workflow: evaluate, list exceptions, create exception, delete exception.
• Use environment examples for both dry-run and enforce modes.

Idempotency and retry guidance

• GET endpoints are safe to retry.
• POST /api/swg/evaluate can be retried; use backoff on 429.
• For exception writes, read current exceptions first to avoid duplicate intent.

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
• Identity risk and OAuth response
• EvidencePack verification and transparency log
• Risk economics and plan recommendation
• Autonomous readiness and probes

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