Security & Architecture

OmniSight is designed around local data ownership, private artifact delivery, signed entitlement leases, and strict agent transport.

Runtime Architecture

textEndpoint Agent
  -> HTTPS /api/ingest/heartbeat
  -> HTTPS /api/ingest/events
  -> WSS /api/ingest/metrics/ws for aggregate metrics and runtime interval control
  -> optional /api/agents/control/ws for remote terminal

Self-hosted Server
  -> Local API service
  -> Local event store in native mode
  -> React console
  -> macOS menu bar status app

OmniSight Managed Services
  -> account and subscription state
  -> signed entitlement leases
  -> private artifact catalog
  -> update metadata and telemetry

The self-hosted server stores local operational data. OmniSight managed services decide package access, entitlement state, private installer delivery, and update visibility. Managed email relay delivery is restricted to verified recipients and carries aggregate summary or bounded alert metadata only.

The browser console also uses a separate nudge-only WebSocket for realtime freshness. Browser WebSocket frames carry channel names and lifecycle messages only; the console still reads metrics, events, alerts, and other data through permission-gated REST APIs. The same metadata-only boundary applies to Dashboard, Events, and Alerts freshness signals.

The public website is separate from customer deployments. Secrets, artifact policy, vulnerability lookup routing, and entitlement decisions remain in managed OmniSight services rather than in public website assets.

TLS and Trust Model

All normal agent and browser traffic uses HTTPS.

Agent transport:

requires HTTPS for remote servers
permits http:// only for localhost/development
validates server certificates
supports explicit CA PEM trust for local/LAN server certificates

Native macOS server installs generate local TLS certificates with localhost and LAN IP SANs.

Important trust boundary:

Browser trust on the server Mac is not the same as endpoint agent runtime trust.
Normal macOS agent onboarding uses the public Agent Installer app plus an invite URL.
The invite manifest delivers the server CA PEM to the agent.
Users should not be instructed to bypass browser TLS warnings as the normal install path.

Operator Authentication

The console uses a dual-token model:

Token	Storage	Purpose
Access token	HttpOnly secure cookie	Short-lived API access
Refresh token	HttpOnly secure cookie, hashed in DB	Rotates to mint new access tokens

Refresh token reuse triggers token-family invalidation. Password changes invalidate that user's existing sessions.

Cookie-authenticated mutating requests require:

textX-Requested-With: XMLHttpRequest

Bearer-token integrations are not subject to that CSRF header requirement.

Agent Authentication

First enrollment requires a bootstrap credential:

short-lived bootstrap token from the console
or trusted ENROLLMENT_SECRET for controlled automation

After enrollment:

the agent stores a persistent agent_token
the server stores token lookup/hash material
all heartbeat, event, and control-channel requests authenticate with the agent token
aggregate system metrics can use the dedicated metrics WebSocket with the same agent authentication model
server-to-agent metrics control frames can change the runtime metric interval or start a time-limited diagnostic interval
config files are restricted to owner read/write where the platform supports it

Entitlement Enforcement

OmniSight issues signed leases to self-hosted servers. The local server verifies and caches the lease, then derives runtime capabilities.

Common entitlement states:

State	Meaning
`trialing`	Trial active
`active`	Current subscription
`delinquent_grace`	Subscription needs attention; growth and downloads may be blocked
`restricted`	Runtime degraded; event ingest may be blocked
`revoked`	Hard stop
`cancelled` / `expired`	Access must be restored through the account workspace

Capabilities include:

heartbeat_allowed
event_ingest_allowed
new_enrollment_allowed
downloads_allowed
updates_allowed
admin_read_only

Package policy matters:

combined Starter keeps separate enrollment disabled
split packages allow separate enrollment while healthy and within seat limits

RBAC

User-facing capabilities map to internal permissions.

Capability	Internal permission
`dashboard`	`dashboard:read`
`agents`	`agents:read`
`agents_manage`	`agents:manage`
`agents_deploy`	`agents:deploy`
`agents_remote_terminal`	`agents:remote_terminal`
`agents_remote_connect`	`agents:remote_connect`
`agents_remote_approve`	`agents:remote_approve`
`events`	`events:read`
`alerts`	`alerts:read`
`alerts_manage`	`alerts:manage`
`audit_logs`	`audit:read`
`users_manage`	`users:manage`
`notifications_manage`	`notifications:manage`

The root admin has all permissions and cannot be deleted by other users.

alerts_manage includes alert-read inheritance so operators assigned only Manage Alerts can enter the Alerts workspace and use management controls. alerts does not imply alerts_manage; read-only alert users cannot create maintenance windows, disable suppressions, evaluate rules, or mutate alert workflow state.

Reports do not introduce a separate capability in the current release. Summary preview and schedule visibility reuse dashboard; Events CSV export reuses events; Alerts CSV export reuses alerts; schedule management and one-off email report sends require users_manage. This keeps report viewing aligned with the data surfaces an operator can already view while treating outbound delivery administration as a user/system-management action.

System Monitoring follows existing read permissions. Local server-host metrics require dashboard; agent metrics require agents. Users with agent-management permission can adjust fleet default and per-agent metric intervals, including time-limited diagnostic mode. Metrics remain aggregate-only and expose live/stale/unavailable states rather than raw endpoint data.

Storage & Retention controls require users_manage. They expose bounded storage sizes, retention settings, cleanup state, and aggregate result counts only; file contents, log contents, database rows, environment values, certificates, and secrets are not returned by the storage APIs.

Notifications administration requires notifications_manage. Email recipients, webhook endpoints, test sends, and delivery history are managed through that capability. Notification and webhook payloads carry bounded alert metadata only; webhook URLs are masked in API responses and optional signing secrets are stored encrypted.

Deployment Lifecycle and Seat Protection

OmniSight managed services are authoritative for deployment seats and installation lifecycle:

Each package install reserves a deployment seat through a short-lived bootstrap session. The deployment moves through reserved, claimed, and active states.
A second bootstrap for an occupied seat is rejected; failed installs expire their reservation so retries are not blocked indefinitely.
Installer browser handoff is tokenless in URLs: authorization completes through a local form POST, and installer payload downloads require bearer authentication tied to the install session.
Server uninstall requests a cloud release. The deployment enters a release quarantine (release_pending) before capacity frees; continued heartbeat or enrollment activity after a release request flags the deployment for review instead of silently freeing or reusing the seat.
A server_id registered to one subscription cannot be bound or released by another subscription.
Separate agent installs on split/team packages use single-use enrollment grants; a consumed grant cannot be replayed.
Account owners/admins can request a manual release from the Account page; manual release preserves the same quarantine semantics.

Remote Terminal Security

Remote terminal is not part of base Starter combined. It is available for split/team packages when enabled by package and server policy.

Controls:

server-level REMOTE_ACCESS_ENABLED
agent capability advertisement
remote-control websocket authentication
user permission checks
reason-required session request
approval step
short-lived browser websocket token
audit logs for request, approval, start, close, and kill request

Linux root-shell guard:

root-running agents refuse root terminal sessions by default
remote_terminal_user must be a non-root local account
remote_terminal_user=root is rejected

Remote desktop/RDP is not implemented yet. Current desktop capability should remain unsupported until Phase 2 routes and agent handlers exist.

Update and Release Trust

Production delivery uses managed OmniSight services and signed artifact storage.

OmniSight provides:

account/server-aware update visibility
private artifact catalog
short-lived download sessions
rollout metadata
update telemetry

TUF-style metadata verification is supported in source through the update TUF settings. Native update apply runs through administrator-approved macOS service control for system LaunchDaemon installs. The local menubar relay requires a bearer token and only accepts update wrapper scripts from OmniSight's managed update directory.

Audit Trail

Audit logs record:

authentication success/failure/logout/refresh
user creation, deletion, permission changes, password changes
deploy token generation and denial
agent install session creation/revocation
enrollment success/denial
entitlement refreshes
update apply actions
alert evaluation, rule changes, status/verdict updates, notes, and assignment changes
remote terminal request/approval/start/close/kill-requested

Audit rows include timestamp, actor, action, resource type/id, status, source IP, and details.

Agent Security Boundaries

Boundary	Guarantee
No payload capture	Only connection metadata is collected
No TLS interception	No MITM, SSL bumping, or certificate spoofing
No traffic modification	The agent observes, it does not redirect or inject
Secure transport	Agent data uses HTTPS with certificate validation
Config protection	Token-bearing config files use restrictive permissions
Root shell guard	Remote terminal refuses unsafe root-shell defaults
Update relay guard	Local update approval relay requires a bearer token and wrapper path allowlist
Alert ownership	Assignment changes are permission-checked and audited
CVE privacy	Vulnerability matching uses package metadata only; raw CVE detail shows public NVD metadata, not endpoint files or payloads
System metrics privacy	Host metrics are aggregate numeric values only, not command lines, per-connection tuples, ports, destinations, payloads, or secrets
DNS protocol metadata privacy	Optional Linux DNS visibility parses bounded DNS traffic in memory and keeps query metadata only (name, type, response code, answer count); raw packet bytes are never stored, logged, or transmitted
Notification privacy	Email and webhook notifications carry bounded alert metadata only; no raw events, payloads, tokens, or secrets
Public site boundary	Public website assets do not contain secrets, artifact policy, or entitlement decision logic

Production Hardening Checklist

Keep SECRET_KEY, ENROLLMENT_SECRET, and license keys out of chat, logs, commits, and screenshots.
Use the package-specific installer workspace instead of public static artifact links.
Restrict network access to the self-hosted server.
Assign least-privilege RBAC capabilities.
Review audit logs after administrative and remote terminal activity.
Keep update/entitlement checks enabled.
Use explicit CA PEM delivery for local/LAN agent trust.
Back up local data, .env, TLS cert/key, and installer metadata.
Keep debug mode disabled in production.