SWG & Shadow Browsing

Secure Web Gateway APIs let you dry-run policy decisions, manage exceptions, and request adaptive shadow browsing (remote DOM rendering).

SWG decisions are now mirrored into the normalized Browser Security feed. For the shared browser-security event stream and direct browser-event ingest path, use the Browser Security API.

Authentication

Use a workspace API key (generate it via https://dralvia.tech/#/api-keys). Prefer Authorization: Api-Key <key> (legacy: X-API-KEY).
Signed-in browser sessions are supported for portal workflows. Workspace API keys are preferred for automation.
Optional X-Actor to tag automation and analysts.

Base URL

Workspace persona: https://dralvia.tech/api/tenant

Setup and health (`GET /swg/health`)

Returns a workspace-scoped Web Access Protection health snapshot for the admin console health card. Enforcement is browser-native through the Dralvia extension, not network-wide.

Response fields:

status and status_label: one headline state (not_configured, extension_not_detected, observe_mode, policy_active, sync_lagging, error).
mode: disabled, observe, or enforce.
configured, enforcement_enabled, policy_active: booleans.
extension: detected, last_seen, age_hours, sync_lagging.
event_count, exception_count.
last_event (domain, action, category, policy, dry_run, created_at), last_decision, last_error.
enforcement_note: a fixed honesty note that enforcement is browser-native and does not provide network-wide coverage.

Evaluate URL (`POST /swg/evaluate`)

{
  "url": "https://network.example/social",
  "context": {
    "hour_utc": 21,
    "user_department": "finance"
  },
  "triggered_by": "partner-playbook",
  "include_evidencepack": false
}

Response snippet:

{
  "url": "https://network.example/social",
  "category": "social",
  "policy": "warn_social_off_hours",
  "action": "warn",
  "reason": "Social browsing outside 08:00–18:00 UTC",
  "coaching_message": "This site is approved after hours for HR and Marketing only.",
  "exception_applied": false,
  "decision_coaching": {
    "trigger": "Policy: Social browsing outside 08:00–18:00 UTC",
    "data_risk": "social web access involving social.example",
    "safer_path": "Confirm business need and continue only if tenant policy allows it.",
    "operator_action": "Review policy"
  }
}

Every evaluation is logged in swg_dry_run_event so analysts can review impact before enforcing. Each evaluation is also mirrored into the normalized browser_security_event stream with source=swg and action_type=policy_decision.

If a SaaS session control matches the domain, the response includes policy=saas_control plus control metadata (control_action, control_app_id, control_applied). Non-allow actions can emit EvidencePack (Dralvia's exportable evidence report) fields (evidencepack_hash, evidencepack_log_index) when include_evidencepack=true.

decision_coaching is also persisted into swg_dry_run_event.decision_json and surfaced in GET /swg/dryrun/events. The current contract synthesizes Reason, Risk, Safer path, and Next step from existing fields such as:

reason
category
action
policy
control_applied, control_action, control_app_id
shadow_ai
app_visibility
coaching_cards

The SWG dashboard prefers the backend-provided decision_coaching object and falls back to local synthesis only for older events that do not yet carry it.

Exceptions (`/swg/exceptions`)

Payload:

{
  "pattern": "*.partner.example",
  "action": "allow",
  "tenant_id": "tenant-alpha",
  "coaching_message": "MSSP-approved marketing sandbox"
}

pattern accepts shell-style wildcards. Deleting an exception immediately restores default policy behavior.

SaaS session controls

Workspace admins can manage SaaS controls (allow/monitor/block) via /swg/saas/controls. Controls are workspace-scoped and override Web Access Protection decisions when a domain matches.

When the SWG dashboard sees SaaS-control metadata plus app_visibility, the returned decision_coaching contract can surface managed-workspace guidance for sanctioned AI or other workspace-bound SaaS apps without requiring a second API lookup.

SaaS inventory snapshot

GET /swg/saas/inventory returns a catalog-backed SaaS inventory that joins:

app catalog identity (name, vendor, category, sanctioned defaults)
active SaaS controls
shadow-IT signal counts from SWG dry-run activity
shadow tags applied in the SWG dashboard

Query params:

limit (default 200, max 500) limits the shadow signal aggregation
Workspace context is derived from your API key or signed-in session.

Response shape:

{
  "apps": [
    {
      "app_id": "drive.google.com",
      "name": "Google Drive",
      "vendor": "Google",
      "category": "storage",
      "sanctioned_status": "controlled",
      "control_action": "monitor",
      "control_note": "Monitor Drive usage",
      "owner": "Security",
      "review_status": "approved",
      "review_note": "Approved for corporate use",
      "sso_required": true,
      "tenant_bound": true,
      "rollback_note": "Revert to monitor for contractor exception workflows.",
      "decision_coaching": {
        "trigger": "Destination status: tenant-controlled app",
        "data_risk": "tenant activity involving Google Drive",
        "safer_path": "Move the workflow into an approved tenant workspace before allowing continued use.",
        "operator_action": "Review or tighten monitor control"
      },
      "signal_count": 4,
      "last_seen_at": "2026-04-09T08:40:00Z"
    }
  ],
  "shadow_unclassified": [
    {
      "domain": "shadow-app.test",
      "category": "unknown",
      "risk": "medium",
      "signal_count": 2,
      "last_seen_at": "2026-04-09T08:35:00Z",
      "shadow_tag": "unsanctioned"
    }
  ],
  "summary": {
    "catalog_apps": 42,
    "observed_apps": 6,
    "unclassified_shadow": 2
  }
}

Each app row can now also include decision_coaching so SWG inventory consumers can reuse the same governance rationale the Browser Protection shows for workspace-bound, SSO-required, shadow-AI, and active-control scenarios.

SaaS governance metadata

Use /swg/saas/governance to store owner and review status for catalog apps, plus binding hardening metadata.

GET /swg/saas/governance returns the list for the current workspace.
POST /swg/saas/governance upserts an entry.
DELETE /swg/saas/governance/{app_id} removes an entry.

GET and POST responses now also include:

app_visibility: resolved catalog/control view for the app when available
decision_coaching: normalized governance guidance with trigger, data_risk, safer_path, and operator_action

Example payload:

{
  "app_id": "drive.google.com",
  "owner": "Security",
  "review_status": "approved",
  "note": "Approved for corporate use",
  "sso_required": true,
  "tenant_bound": true,
  "rollback_note": "Revert to monitor for contractor exception workflows.",
  "approved_account_domains": ["dralvia.tech", "corp.dralvia.tech"],
  "approved_workspace_ids": ["u2"]
}

Field intent:

sso_required: app should be used only through workspace SSO instead of unmanaged personal logins.
tenant_bound: app should stay bound to the workspace-managed workspace/account boundary.
rollback_note: operator note describing the allowed rollback path or exception posture if policy needs to be relaxed temporarily.
approved_account_domains: corporate account domains that should count as valid business identity for the app.
approved_workspace_ids: allowed workspace/workspace identifiers for multi-workspace SaaS apps when the browser runtime can infer them from the URL or account index.

SaaS governance and control history

Use GET /swg/saas/history to read the workspace-scoped change timeline for SaaS controls and governance metadata.

Query params:

limit default 25, max 200
app_id optional
entity_type optional; control or governance
tenant_id optional for internal callers

Example response:

{
  "items": [
    {
      "id": "3e56c2f5...",
      "app_id": "drive.google.com",
      "entity_type": "governance",
      "change_type": "updated",
      "actor": "[email protected]",
      "previous": {
        "owner": "IT",
        "review_status": "pending",
        "note": "Pending review"
      },
      "current": {
        "owner": "Security",
        "review_status": "approved",
        "note": "Approved for corporate use"
      },
      "created_at": "2026-04-10T12:08:00Z"
    }
  ],
  "summary": {
    "total": 1,
    "filters": {
      "app_id": "drive.google.com",
      "entity_type": "governance",
      "tenant_id": "tenant-alpha",
      "limit": 25
    },
    "by_change_type": {
      "updated": 1
    },
    "by_entity_type": {
      "governance": 1
    }
  }
}

History rows are append-only. previous captures the state before the change and current captures the resulting state after create/update operations.

Adaptive shadow browsing (`POST /swg/shadow/render`)

{
  "url": "https://signin.example.com",
  "selectors": [
    { "selector": "form#login", "reason": "credential form" },
    { "selector": ".hero-banner", "reason": "impersonation" }
  ],
  "policy": "block_high_risk",
  "triggered_by": "extension:shadow-preview"
}

Response:

{
  "request_id": 42,
  "status": "rendered",
  "latency_ms": 180,
  "renderer_version": "rbi-0.1",
  "result_payload": {
    "elements": [
      {
        "selector": "form#login",
        "success": true,
        "snippet": "<form id=\"login\">…</form>",
        "text": "Welcome back, sign in to ExampleBank",
        "match_count": 1
      }
    ],
    "trace": {
      "fetch_ms": 120,
      "parse_ms": 40,
      "resolved_url": "https://signin.example.com/login"
    }
  }
}

Use GET /swg/shadow/requests?limit=50&tenant_id=tenant-alpha to audit past renders. The admin console (#/swg-policy) now exposes a visual control panel for launching renders and inspecting snippets.

Keyless TLS signing (operator/internal)

These endpoints are intended for gateway-side keyless TLS operations.

GET /fabric/gateway/keyless/status?tenant_id=<tenant>
POST /fabric/gateway/keyless/sign
POST /fabric/gateway/keyless/benchmark

Example sign request:

{
  "tenant_id": "tenant-alpha",
  "digest_b64": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
  "hash_algorithm": "sha2-256",
  "signature_algorithm": "pkcs1v15"
}

Response includes signature metadata and latency:

{
  "tenant_id": "tenant-alpha",
  "provider": "vault-transit",
  "attempted_providers": ["vault-transit"],
  "fallback_used": false,
  "key_name": "swg-keyless-tenant-alpha",
  "signature": "vault:v1:...",
  "duration_ms": 18
}

GET /fabric/gateway/keyless/status now also returns:

provider_chain: ordered provider list (primary first)
failover_enabled: true when a fallback provider is configured

SLO targets

Path	SLO	Notes
`/swg/evaluate`	p95 ≤ 150 ms	In-memory category DB; perf primarily CPU bound.
`/swg/shadow/render`	p95 ≤ 500 ms	Thread pool with configurable fetch/parse budgets; failures logged with reason codes.
`/swg/exceptions`	p95 ≤ 200 ms	Indexed lookups on `pattern` + `tenant_id`.

Authentication​

Base URL​

Setup and health (GET /swg/health)​

Evaluate URL (POST /swg/evaluate)​

Exceptions (/swg/exceptions)​

SaaS session controls​

SaaS inventory snapshot​

SaaS governance metadata​

SaaS governance and control history​

Adaptive shadow browsing (POST /swg/shadow/render)​

Keyless TLS signing (operator/internal)​

SLO targets​