Data Flow & Egress
This page answers three questions security teams ask before deploying Surface Security:
- What data crosses my tenant boundary, and when?
- How does the browser extension talk to the backend, and how is that traffic protected?
- 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:
- Transport (mTLS) -- Envoy authenticates the device certificate and the device authenticates the server. Standard TLS in both directions.
- 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.
| Layer | Algorithm | Purpose |
|---|---|---|
| Key agreement | ECDH (P-256) | Shared secret from a fresh ephemeral key + the tenant's server channel key |
| Key derivation | HKDF-SHA256 | Separate AES keys for request and response |
| Body encryption | AES-256-GCM | Encrypt POST/PUT/PATCH bodies (and responses) |
| Request signing | ECDSA-P256-SHA256 | Authenticate 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 (
apiEndpointin managed storage) -- your own Envoy gateway.
When it happens (extension ↔ backend cadence)
| Flow | Direction | Timing | Notes |
|---|---|---|---|
| Event batches | Extension → Backend | ~60s, or ~15s once ≥25 events are queued | Up to 50 events per batch (server limit). Persistent IndexedDB queue survives service-worker restarts; oldest events are dropped past the per-queue cap. |
| Device heartbeat | Extension → Backend | Every 1 minute | Liveness + managed-storage metadata (e.g. hostname). |
| Policy sync | Extension → Backend | Hourly | Pulls the tenant's current policy set. |
| Signature sync | Extension → Backend | Every ~4-6 hours | Phishing-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
| Traffic | Direction | Timing | Payload |
|---|---|---|---|
| Heartbeat | Backend → Portal | First 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 sync | Backend → Portal (GET) | Only when the heartbeat response reports a newer version | Pulls signature data down. Sends nothing but a version header. |
| Extension-config sync | Backend → Portal (GET) | Only when the heartbeat response reports a newer version | Pulls 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:
| Service | Called from | What leaves | Privacy |
|---|---|---|---|
| Have I Been Pwned (HIBP) | Extension (device) | 5-char SHA-1 prefix of a hash | k-anonymity -- no full hash or password ever leaves the endpoint; only a breach-count bucket is stored |
| URLScan.io / VirusTotal | Backend | A domain / URL under investigation | Used 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:
- Portal disabled -- set
SURFACE_PORTAL_URL=""(empty). With no Portal URL, the heartbeat goroutine never starts and no sync ever runs. - Egress blocked -- Helm network policies (
networkPolicies.airGapped: true) block all external egress at the cluster level, so nothing can leave even by misconfiguration.
| Capability | Air-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 |