Update System

Surface Security provides a comprehensive zero-downtime update system designed for 100% uptime.

Update Modes

Mode	Description	Use Case
Automatic	Periodic polling with auto-deployment	Standard deployments
Manual	Upload signed bundles via admin UI	Change-controlled environments
Air-Gapped	Offline deployment, local verification	Isolated networks

Update Planes

Updates are managed across three planes:

1. Platform -- Kubernetes services, APIs, ingestion workers, admin dashboard
2. Browser Extension -- Chrome, Edge, Firefox with enterprise policy support
3. Native Companion -- Optional OS-level keychain helper

Platform Updates (Kubernetes)

Deployment Strategy

Surface Security uses rolling updates by default to ensure zero downtime:

• New pods are created before old ones are removed
• A PodDisruptionBudget ensures minimum availability during updates
• HorizontalPodAutoscaler adjusts replica count based on load

Preflight Checks

Before any update, the system validates:

Check	Description
Database version compatible	PostgreSQL/ClickHouse version meets requirements
Disk space sufficient	Minimum 10GB free space
Node capacity available	Kubernetes nodes ready
License valid	License not expired, tier sufficient
Schema migrations safe	Migrations pass safety validation

Postflight Checks

After deployment, the system verifies:

Check	Description
All pods ready	All deployment pods healthy
API health OK	API endpoints responding
Ingestion pipeline OK	Kafka connectivity verified
Alert pipeline OK	Alert service healthy
Smoke queries pass	Basic queries succeed

Automatic Updates

Configure automatic updates via environment variables or Kubernetes ConfigMap:

# Environment variables
SURFACESEC_AUTO_UPDATE=true
SURFACESEC_UPDATE_REGISTRY=https://updates.surface-security.com

# Or Kubernetes ConfigMap
kubectl create configmap surfacesec-config \
  --from-literal=AUTO_UPDATE=true \
  --from-literal=UPDATE_POLL_INTERVAL=60m

Manual Updates

1. Download the signed update bundle from the admin portal
2. Navigate to Settings > Updates in the admin dashboard
3. Click Upload Update Bundle
4. Review the preflight check results
5. Click Apply Update to begin deployment

Air-Gapped Updates

For isolated environments:

1. Download the update bundle on a connected machine
2. Transfer the bundle and its signature file to the air-gapped environment via secure media
3. Upload via the admin dashboard: Settings > Updates > Upload Update Bundle
4. The bundle signature is verified automatically during upload -- at least 2 of the approved keyholders must have signed the bundle (Ed25519 threshold verification)

Prerequisite: Air-gapped deployments must have verification keys (keyholder public keys) embedded into the binary at build time. Without these keys, the API cannot verify update signatures and will reject all bundles. See the Air-Gapped Deployment Guide for instructions on fetching and embedding verification keys. If the Portal rotates keyholder keys, you must rebuild and redeploy the binary with the updated keys.

Database Migrations

Surface Security uses the Expand-Migrate-Contract pattern for safe schema changes:

Phase 1: EXPAND   - Add new columns/tables, keep old ones
Phase 2: MIGRATE  - Backfill data, validate
Phase 3: CONTRACT - Remove old columns (separate release, forward-only)

Safety rules:

• Schema changes are always backward compatible for at least one release
• New code never depends on a column not yet created
• Columns are never dropped in the same release they are deprecated
• Destructive migrations are forbidden

Rollback

Automatic rollback occurs when:

• Postflight health checks fail
• Critical errors detected during deployment
• Manual rollback triggered by an administrator

To perform a manual rollback:

1. Navigate to Settings > Updates > Rollback in the admin dashboard
2. Select the previous version
3. Confirm the rollback

Note: Schema rollbacks after the CONTRACT phase are not supported (forward-only). This is by design -- the Expand-Migrate-Contract pattern ensures the previous application version remains compatible during the EXPAND and MIGRATE phases.

Browser Extension Updates

Public Store Distribution

Extensions auto-update via browser stores with staged rollouts:

• Chrome Web Store
• Edge Add-ons
• Firefox AMO

Enterprise Managed Distribution

For enterprise deployments with version control, configure a self-hosted update feed:

{
  "ExtensionSettings": {
    "YOUR_EXTENSION_ID": {
      "installation_mode": "force_installed",
      "update_url": "https://updates.yourdomain.com/api/v1/extension/update.xml",
      "override_update_url": true
    }
  }
}

Tenant Version Pinning

Control extension versions per tenant through the admin dashboard or API:

• Channel selection: stable, beta, or canary
• Version pinning: lock to a specific version
• Staged rollout: deploy to a percentage of devices before full rollout
• Auto-update control: enable or disable automatic updates per tenant

Native Companion Updates

The Native Companion supports automatic updates with rollback:

Feature	Description
Atomic Replace	Binary replaced atomically via symlink swap
Auto Rollback	Automatic rollback on startup failure
Health Check	Post-update health verification
Platform Support	Windows (MSI), macOS (PKG)

Update flow:

1. Poll update endpoint for new versions
2. Download signed binary
3. Verify vendor signature (Ed25519)
4. Verify license validity
5. Create backup of current version
6. Atomic replacement (symlink swap)
7. Restart service
8. Health check ping
9. Rollback on failure

Update Dashboard

The admin dashboard provides a comprehensive update view:

Section	Information
Current Versions	Platform, extension, companion versions
Available Updates	New versions with release notes
License Status	Tier, expiry, entitlements
Update History	Audit trail of all updates

Available actions:

• Check for Updates
• Upload Update Bundle
• Schedule Update (maintenance window)
• Rollback to Previous Version

Licensing and Updates

Updates require a valid license. On every update, the system verifies:

• Tenant ID matches
• License is not expired
• Entitlements are sufficient for the update tier

If license validation fails, existing functionality continues during a 7-day grace period, but new updates are blocked until the license is renewed.