Skip to content

Security: fatihbtw/orbit

Security

docs/SECURITY.md

πŸ”’ Orbit Security Guide

Threat Model (Phase 0 β†’ 1)

Assets

  • Docker socket (/var/run/docker.sock) β€” root-equivalent access on the host
  • Container secrets / environment variables
  • Orbit user credentials
  • Audit logs

Threat Actors

  • Unauthenticated external users
  • Authenticated low-privilege users trying to escalate
  • Compromised container attempting socket escape

Implemented Controls (Phase 0)

Control Implementation Status
Socket isolation Socket only accessible to backend container βœ…
JWT authentication HS256, 1h expiry, refresh tokens βœ…
RBAC Admin / Operator / ReadOnly middleware βœ… skeleton
Rate limiting 100 req/min per IP βœ…
Audit logging Structured JSON to stdout βœ…
CORS Explicit origin whitelist βœ…
Input validation Zod schemas on all endpoints βœ…

Phase 1 TODOs (Security)

HIGH priority

  • Rotate JWT secret β€” expose /api/auth/rotate-secret (admin only)
  • HTTPS enforcement β€” add Caddy or Traefik reverse proxy config
  • Secret scanning β€” add trufflehog to CI pipeline
  • Container image pinning β€” use SHA digests in docker-compose.yml
  • Read-only rootfs β€” add read_only: true to backend compose service

MEDIUM priority

  • LDAP/OIDC integration β€” integrate passport-ldapauth / openid-client
  • HMAC webhooks β€” sign outgoing webhook payloads with X-Orbit-Signature
  • CSP headers β€” strict Content-Security-Policy via helmet.js
  • Dependency audit β€” weekly npm audit in CI
  • Session revocation β€” Redis-backed token blocklist for logout

LOW priority

  • Prometheus auth β€” protect /metrics behind bearer token
  • 2FA / TOTP β€” optional TOTP for admin accounts
  • Immutable audit log β€” forward to external syslog / SIEM

Docker Socket Security

The Docker socket grants root-equivalent access. Mitigations:

  1. Network isolation β€” backend is on an internal Docker network; socket never exposed to frontend or internet
  2. Docker socket proxy (recommended for production) β€” replace direct socket mount with docker-socket-proxy to allow only specific API calls
  3. User namespacing β€” enable Docker user namespace remapping on the host

Example socket proxy integration (Phase 1):

socket-proxy:
  image: tecnativa/docker-socket-proxy
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
  environment:
    CONTAINERS: 1
    IMAGES: 1
    NETWORKS: 1
    VOLUMES: 1
    POST: 1   # set to 0 for read-only mode
  networks:
    - internal

Environment Variable Checklist

Before going to production:

# βœ… Check these are set and non-default
ORBIT_SECRET        # Must be >= 32 chars, random
ORBIT_ADMIN_PASSWORD  # Must be changed from default

There aren’t any published security advisories