Skip to main content

Data Flow & Egress

This page answers three questions security teams ask before deploying Surface Security:

  1. What data crosses my tenant boundary, and when?
  2. How does the browser extension talk to the backend, and how is that traffic protected?
  3. In an air-gapped deployment, does anything leave at all? (No.)

Surface Security is self-hosted. The backend, databases, event bus, and dashboard all run inside your environment. Almost all data flow happens inside your tenant boundary and never touches the internet. The only traffic that leaves is a small, deployment-initiated health heartbeat to the Surface Portal -- and even that is disabled entirely in air-gapped mode.

Two Trust Boundaries​

  • Solid lines stay inside your network. All employee telemetry -- navigation, credential events, auth-flow signals, phishing detections -- flows only along these paths.
  • Dashed lines cross the internet. They carry no employee data: only aggregate health counts to the Portal, and (if you opt in) domain/hash lookups to threat-intel providers.

Inside Your Tenant: Extension → Backend​

This is where essentially all data lives and moves. None of it leaves your environment.

What the extension collects​

The extension captures metadata about authentication activity, never secrets:

  • Navigation telemetry, technology fingerprints
  • Credential-attempt events (that a login happened, where, on what field) -- never the password. Credentials are reduced to an HMAC-SHA256 fingerprint on the device using a secret stored in the OS keychain.
  • Auth-flow signals (SSO/MFA/IdP detection), phishing/AiTM/ClickFix detections, clipboard-threat, download/print/GenAI events

Sensitive domain categories (banking, healthcare, etc.) are filtered out before anything is queued.

How it's protected: Layer-7 end-to-end encryption​

Every request from the extension is protected by two independent layers:

  1. Transport (mTLS) -- Envoy authenticates the device certificate and the device authenticates the server. Standard TLS in both directions.
  2. Application / Layer 7 (E2E encryption) -- the request body is separately encrypted and signed before it enters the TLS tunnel, so it stays confidential even if TLS is terminated, proxied, or inspected upstream.
LayerAlgorithmPurpose
Key agreementECDH (P-256)Shared secret from a fresh ephemeral key + the tenant's server channel key
Key derivationHKDF-SHA256Separate AES keys for request and response
Body encryptionAES-256-GCMEncrypt POST/PUT/PATCH bodies (and responses)
Request signingECDSA-P256-SHA256Authenticate the sending device on every request

Requests travel as a self-describing envelope (Content-Type: application/x-surfacesec-e2e) carrying { v, ek, iv, ct, sig, ts } -- version, ephemeral public key, IV, ciphertext, signature, and timestamp. A fresh ephemeral key pair is generated per request, so compromising one request's key material reveals nothing about any other request.

Fail-closed: once E2E is negotiated for a request, any crypto failure blocks the request. It is never transparently downgraded or sent in plaintext.

All of the above happens inside your tenant. The extension talks only to the endpoint you configure (apiEndpoint in managed storage) -- your own Envoy gateway.

When it happens (extension ↔ backend cadence)​

FlowDirectionTimingNotes
Event batchesExtension → Backend~60s, or ~15s once ≥25 events are queuedUp to 50 events per batch (server limit). Persistent IndexedDB queue survives service-worker restarts; oldest events are dropped past the per-queue cap.
Device heartbeatExtension → BackendEvery 1 minuteLiveness + managed-storage metadata (e.g. hostname).
Policy syncExtension → BackendHourlyPulls the tenant's current policy set.
Signature syncExtension → BackendEvery ~4-6 hoursPhishing-kit / ClickFix signature data, 304-cached by version (multiple alarms: 4h and 6h).

If the backend is unreachable, the extension keeps working and queues events locally (graceful degradation) -- nothing is lost until the bounded queue overflows.


Leaving Your Tenant: Backend → Surface Portal​

The only component that talks to the internet by default is the backend's Portal client. Communication is always deployment-initiated (pull-based) -- the Portal never pushes to your deployment -- and authenticated with a per-deployment Bearer token over HTTPS.

What is sent, and when​

TrafficDirectionTimingPayload
HeartbeatBackend → PortalFirst at +30s after start, then every 5 min (packaged K8s/Helm default; code default is 6h, set via PORTAL_HEARTBEAT_INTERVAL_SECONDS)Aggregate counts + versions only (see below). HTTP timeout 30s; exponential backoff on failure, capped at 30 min.
Signature / ClickFix syncBackend → Portal (GET)Only when the heartbeat response reports a newer versionPulls signature data down. Sends nothing but a version header.
Extension-config syncBackend → Portal (GET)Only when the heartbeat response reports a newer versionPulls update channel/pin config.

A representative heartbeat body -- every field is an aggregate count or an infrastructure metric, never per-employee data:

{
"platform_version": "1.0.0",
"extension_version": "2.3.1",
"total_users": 150,
"total_devices": 450,
"total_alerts_24h": 12,
"critical_alerts_24h": 2,
"error_count_1h": 0
}

Depending on tier and opt-in settings, the heartbeat may also include additional aggregate/infra metrics -- active extension count, CPU/memory/disk usage, database connection counts, and ingestion lag. None of these carry PII; metrics reporting is gated behind explicit opt-in (MetricsOptIn / SupportOptIn).

What is never sent to the Portal​

  • Passwords or password hashes
  • Credential fingerprints (HMAC-SHA256)
  • Employee usernames, emails, or any PII
  • Navigation events or browsing history
  • mTLS certificates or private keys
  • Raw alert details

Only aggregate counts (total users, total devices, 24h alert totals) and infrastructure version strings leave. License verification makes no network call at all -- it's a local Ed25519 signature check.

Optional third-party threat intel​

If you enable them per-tenant, the backend may also call out to external reputation services. These are off by default and disabled in air-gapped mode:

ServiceCalled fromWhat leavesPrivacy
Have I Been Pwned (HIBP)Extension (device)5-char SHA-1 prefix of a hashk-anonymity -- no full hash or password ever leaves the endpoint; only a breach-count bucket is stored
URLScan.io / VirusTotalBackendA domain / URL under investigationUsed only for phishing-domain reputation enrichment

Air-Gapped: Nothing Leaves​

In an air-gapped deployment, every dashed line in the diagram above is severed. Surface Security runs fully offline -- credential reuse detection, policy enforcement, phishing detection, alerting, dashboard, and SIEM forwarding (to your internal SIEM) all work with zero external connectivity.

Two independent controls enforce this:

  1. Portal disabled -- set SURFACE_PORTAL_URL="" (empty). With no Portal URL, the heartbeat goroutine never starts and no sync ever runs.
  2. Egress blocked -- Helm network policies (networkPolicies.airGapped: true) block all external egress at the cluster level, so nothing can leave even by misconfiguration.
CapabilityAir-gapped behavior
Credential fingerprinting & reuse detection✅ Fully local (HMAC-based)
Policy enforcement, phishing/AiTM detection✅ Works offline
Alerting, dashboard, reporting✅ Works offline
SIEM log forwarding✅ To your internal destinations
License verification✅ Local Ed25519 signature check (no network)
Update signature verification✅ Threshold Ed25519 keys embedded at build time
Portal heartbeat / update hints⛔ Disabled
HIBP / URLScan / VirusTotal⛔ Disabled (silently skipped, no error)

Because signatures and updates normally arrive via the Portal, air-gapped deployments receive them through offline media instead. See the deployment guides for the full procedure:


Egress Cheat-Sheet​

DataStays in tenantLeaves tenant (connected)Leaves tenant (air-gapped)
Employee telemetry (navigation, credential events, auth flows)✅----
Credential fingerprints / passwords✅nevernever
Aggregate health counts + version strings✅Portal heartbeat--
Signature / config updates (inbound)✅pulled from Portaloffline media
Credential-breach check✅HIBP prefix (opt-in)--
Domain reputation✅URLScan / VirusTotal (opt-in)--

See also: Architecture for the full component topology and Security for the encryption and key-management model.

Surface Security

This documentation is protected. Enter the password to continue.