Security & Architecture

Hierarchy Overview

OR (Org Root Key)
 +-- PR (Policy Root Keys) -- one per compliance profile
 |    +-- standard
 |    +-- hipaa
 |    +-- fedramp
 |    +-- pci
 |    +-- irap
 +-- TR (Tenant Root Key) -- per-tenant, rotatable
      +-- Agent Keys (Ed25519) -- per-device identity

Org Root (OR)

The OR key is the root of trust for the entire organisation. It is generated during the initial key ceremony using the tools/go/keygen/ utility and is stored offline. The OR key signs Policy Root keys and is never used in online operations.

Policy Root (PR)

PR keys provide compliance-segmented trust anchors. Each PR maps to a compliance profile (standard, HIPAA, FedRAMP, PCI, IRAP), enabling organisations to maintain separate cryptographic roots for different regulatory environments. PR keys are signed by the OR key.

Tenant Root (TR)

Each tenant receives a unique TR key derived from the appropriate PR. TR keys are rotatable and are distributed via gossip protocol across mesh nodes. The TR signs agent enrollment certificates and tenant-scoped artifacts.

Agent Keys

Each enrolled device generates an Ed25519 keypair locally. The private key is stored using OS-native protection: DPAPI on Windows, Keychain on macOS. Agent keys never leave the host device and are used for mesh authentication, message signing, and identity binding.

In Transit

• Noise Protocol (NNpsk0) — All mesh traffic uses the Noise framework with pre-shared key authentication for forward secrecy and identity binding
• Ed25519 Identity Binding — Each Noise session is bound to the device's Ed25519 identity key, preventing MITM attacks even if PSKs are compromised
• HMAC-SHA256 Integrity — All control plane messages include HMAC integrity verification

At Rest

• Column-Level AES-GCM — Sensitive fields (credentials, keys, PII) are encrypted per-column using AES-256-GCM with tenant-scoped keys
• libSQL Encrypted Database — The local agent database uses libSQL's built-in encryption for the entire data store
• OS-Native Key Storage — DPAPI (Windows) and Keychain (macOS) protect local cryptographic material

Key Storage Model

Agent Key Storage:
  Windows  ->  DPAPI (CurrentUser scope)
  macOS    ->  Keychain (application-specific)

Tenant Data:
  Column-level AES-GCM with per-tenant derived keys
  Key derivation from TR (Tenant Root)

VL1 Overlay

ORBTR's mesh operates on a Virtual Layer 1 (VL1) UDP overlay. Each node maintains encrypted peer connections using Noise protocol sessions. The overlay supports direct peer-to-peer communication when possible, with automatic relay fallback when NAT traversal fails.

LAD Role-Based Discovery

The Local Area Discovery (LAD) protocol enables nodes to find each other by role (anchor, relay, DDNS authority, egress). LAD snapshots are Ed25519-signed and include an RDEpoch field for rotation tracking. Discovery routes requests to the correct node type without central coordination.

NAT Traversal

1. STUN hole-punching (UDP)  -- preferred, direct P2P
2. TURN relay fallback       -- via relay.orbtr.io or tenant Edge Endpoints
3. WebSocket fallback        -- for restrictive firewalls

Multipath Failover

Connectivity automatically fails over through three transport paths:

1. VL1 (UDP) — Primary mesh transport, lowest latency
2. QUIC — Reliable transport when UDP is blocked
3. WebSocket — HTTP-compatible fallback for restrictive networks

Edge Endpoints

Edge Endpoints are promoted agents, not separate infrastructure. Any enrolled agent can be promoted to serve mesh roles (anchor, relay, DDNS, egress) via config-driven activation. This enables tenants to run their own relay and anchor infrastructure on their own hardware.

Enrollment

Enrollment uses self-describing JWTs that embed tenant context — no slug or manual configuration needed. The enrollment token is generated server-side and contains all the information the agent needs to bootstrap trust.

Dual Authentication

Every device maintains two independent authentication channels:

• HSTLES Platform Token — Organisation-level authentication via the shared platform identity
• ORBTR Machine JWT — Device-specific authentication with per-device Ed25519 identity

Both tokens must be valid for any control plane operation. Compromise of one channel does not grant access.

Per-Device Identity

Each device generates a unique Ed25519 keypair during enrollment. This key is used for:

• Mesh authentication and session establishment
• Message signing and integrity verification
• Certificate pinning for TLS connections
• Policy-based access control decisions

No Implicit Trust

Network position does not imply trust. Devices on the same subnet, in the same group, or behind the same firewall still authenticate individually. Policy decisions are evaluated per-device, per-connection, per-request.

Artifact Signing

All update artifacts are signed with Ed25519 keys. The agent verifies signatures before applying any update. SHA256 manifest verification ensures integrity of the complete update package.

Update Channels

stable   -- production releases, full testing
beta     -- pre-release, opt-in testing
canary   -- early access, limited rollout

Enterprise plans can define custom update channels for internal testing and staged deployment.

Staged Rollouts

Updates are deployed progressively — a small percentage of devices receive the update first, with automatic monitoring for failure signals. If the failure rate exceeds the configured threshold, the rollout pauses automatically.

Automatic Rollback

If an update causes agent health checks to fail, the agent automatically rolls back to the previous known-good version. Rollback is local and immediate — no server coordination required.

Distribution

Update artifacts are distributed via get.orbtr.io with channel-based routing. The agent polls for updates on a configurable interval and downloads only the delta when possible.

Cryptographic Isolation

Each tenant has its own Tenant Root (TR) key, derived from the compliance-appropriate Policy Root (PR). This provides full cryptographic isolation between tenants — one tenant's data cannot be decrypted with another tenant's keys, even by the platform operator.

Sovereignty Modes

• Standard — Platform-managed keys, data stored in ORBTR infrastructure
• Enhanced — Tenant-managed TR rotation, data residency constraints
• Full — Customer-controlled key ceremony, on-premises Edge Endpoints for all data processing

Data Residency

Enterprise tenants can constrain data storage and processing to specific geographic regions. Edge Endpoints deployed on tenant infrastructure enable full local data processing without cross-region transfers.

Key Export

Tenants can export their cryptographic material for backup, migration, or compliance audit purposes. Exported keys are wrapped with a tenant-provided passphrase using AES-256-GCM.

Emergency Standalone

In Full sovereignty mode, tenant Edge Endpoints can operate as standalone controllers if connectivity to ORBTR infrastructure is lost. Devices continue to enforce cached policies and maintain mesh connectivity through local anchors.

Enforcement Pipeline

Policy enforcement runs in-process within the agent. The PacketFilter and CompositeEnforcer evaluate every network connection against compiled policy rules without requiring external proxy infrastructure.

Scope Compiler

Policies are compiled through a hierarchical scope chain:

Tenant -> Network -> Group -> Device -> User

More specific scopes override broader ones. The scope compiler resolves the effective policy set for each device at evaluation time, supporting port/protocol ACLs, DNS-to-IP mapping, address groups, and exclusions.

Hook Dispatch

The enforcement engine uses a 3-tier hook system:

• Pre-hooks — Evaluate before action (can block)
• Post-hooks — Execute after action (audit, logging)
• Async hooks — Fire-and-forget (telemetry, notifications)

Policy Types

• Network ACL — Port/protocol allow/deny rules per scope
• DNS Policy — Domain blocklists, allowlists, and redirect rules
• Address Groups — Reusable IP/CIDR sets referenced by policies
• Exclusions — Override rules for specific devices or users

File Integrity Monitoring (FIM)

Monitors critical system files and directories for unauthorized changes. FIM generates alerts on file creation, modification, deletion, and permission changes with configurable paths and exclusions.

Sigma Rule Engine

Evaluates log events against Sigma detection rules for threat identification. Supports custom rule loading and community rulesets for detecting known attack patterns.

YARA Malware Scanning

On-demand and scheduled YARA scanning for malware detection. Supports custom YARA rules and integrates with the job orchestration system for fleet-wide scans.

Vulnerability Scanning

Concurrent CVE aggregation from 5 sources with deduplication:

• NVD — NIST National Vulnerability Database
• OSV — Open Source Vulnerability database
• GitHub Advisories — GitHub Security Advisory database
• CIRCL — Computer Incident Response Center Luxembourg
• OpenCVE — Community CVE tracking platform

Event Collection

• ETW (Windows) — Event Tracing for Windows for real-time OS event collection
• Log Collection — Structured log ingestion from system and application sources
• Rootkit Detection — Checks for hidden processes, modules, and filesystem inconsistencies
• SCA — Software Composition Analysis for dependency vulnerability tracking