Security Guide

This guide summarizes security-related settings and best practices when deploying Nexus GSLB.

Principles

• Secure by default: HTTPS health checks verify TLS by default; GitOps requires signed commits when enabled.
• Least privilege: limit credentials and subject permissions to the minimum required.
• Defense in depth: mTLS for NATS, signed GitOps config, and restricted runtime privileges.

1. HTTP/HTTPS health checks

• Default behavior: when health.http.tls: true, TLS certificates are verified.
• Only set health.http.insecureSkipVerify: true for lab/testing or when using self-signed certs and you fully understand the risk.
• Prefer using proper certificates (internal CA or public CA) and correct http.host to match the cert.

Example (secure):

health:
  type: http
  port: 443
  checkinterval: 10s
  timeout: 2s
  http:
    path: "/healthz"
    expectedstatus: 200
    tls: true
    insecureSkipVerify: false

2. GitOps signing and access

• gitops.requireSignature: true enforces signature verification on the latest commit checked out.
• gitops.allowedSigners restricts accepted signatures to a set of GPG key fingerprints.
• Deploy key: provide a read-only SSH key at gitops.auth.sshKeyPath; permissions should be 0600 and owned by the service user.
• Trust model: ensure the signer keys are trusted on hosts or rely on allowedSigners allowlist.

3. NATS and JetStream

• Use TLS with server authentication at minimum; prefer mTLS (client cert auth) or NATS accounts with JWT.
• Restrict subjects and KV permissions to the cluster namespace: gslb.<cluster>.*.
• Rotate client certificates and credentials regularly. Plan for CA rotation.
• Monitor gslbd_state_nats_connected and set alerts on disconnect.

4. Runtime privileges

• Binding to high ports (≥1024) avoids root. Default DNS port is 5353; if you must use port 53, either:
  • run as root (not preferred), or
  • grant cap_net_bind_service to the binary: setcap 'cap_net_bind_service=+ep' /usr/local/bin/gslbd and run as non-root.
• Limit file system permissions for /etc/gslb and any private keys.

5. Secrets and licensing

• Provide license secrets via environment variables when possible:
  • GSLB_LICENSE_SECRET
  • GSLB_LICENSE_KEY
• Use environment management in systemd (Environment=) or container secrets.

6. Supply chain and binaries

• Build from source in a controlled CI/CD or use signed release artifacts (future work).
• Pin container base images and scan them for vulnerabilities.

7. Logging and PII

• Logs contain operational info (e.g., commit SHAs, signer fingerprints) but not sensitive payloads. Avoid logging credentials.

0. Authentication and user accounts

• Set GSLB_API_KEY (32-byte hex, openssl rand -hex 32) in the systemd EnvironmentFile before exposing the API. Without it, the daemon runs in dev mode — all requests are treated as system admin.
• Set GSLB_SECRET_KEY (also 32-byte hex) before enrolling any TOTP devices. The daemon will refuse to start if TOTP users exist and the key is absent.
• Store both values in /etc/gslb/env with chmod 600, owned by the service user. Reference it from the systemd unit with EnvironmentFile=/etc/gslb/env.
• Create named user accounts (tenant_admin, operator, viewer) instead of sharing the system API key. The system key is a break-glass credential, not a day-to-day login.
• Treat GSLB_API_KEY as a root password: rotate it if it is ever exposed, and restrict who knows it.
• Keep bcryptCost at 12 or higher in production.

See Authentication & User Management for full setup instructions.

Checklist

• TLS verified for HTTPS health checks (no insecureSkipVerify in prod)
• GitOps enabled with requireSignature: true and allowedSigners configured
• NATS uses TLS/mTLS; subjects restricted
• Non-root run or capability for port 53; secure file permissions
• License secrets provided via env/secrets manager
• GSLB_API_KEY set; named user accounts created; system key not used for day-to-day access
• GSLB_SECRET_KEY set before enrolling TOTP devices
• EnvironmentFile has chmod 600 and is owned by the service user
• health.allowScriptChecks left off unless every health-check author is trusted
• health.webhookAllowedHosts lists only the internal hosts webhook checks must reach
• api.trustedProxies set when the API runs behind a reverse proxy (and empty when not)

8. DNSSEC Pleiades signs DNS responses online using ECDSA P-256 (algorithm 13). KSK signs the DNSKEY RRset; ZSK signs all other RRsets.

Key generation:

# KSK
openssl ecparam -name prime256v1 -genkey -noout | \
  openssl pkcs8 -topk8 -nocrypt -out /etc/gslb/ksk.pem

# ZSK
openssl ecparam -name prime256v1 -genkey -noout | \
  openssl pkcs8 -topk8 -nocrypt -out /etc/gslb/zsk.pem

chmod 640 /etc/gslb/ksk.pem /etc/gslb/zsk.pem
chown root:gslbd /etc/gslb/ksk.pem /etc/gslb/zsk.pem

Configuration:

dnssec:
  enabled: true
  zone: "example.com."
  ksk:
    pemFile: "/etc/gslb/ksk.pem"
    expiryDate: "2027-01-01"
  zsk:
    pemFile: "/etc/gslb/zsk.pem"
    expiryDate: "2026-07-01"
  signatureValidityDays: 7

Alternatively load keys from environment variables:

dnssec:
  enabled: true
  zone: "example.com."
  ksk:
    envVar: "GSLB_KSK_PEM"
  zsk:
    envVar: "GSLB_ZSK_PEM"

Key rotation:

1. Generate new ZSK; update config to point at new file.
2. Restart gslbd — new signatures use new ZSK immediately.
3. For KSK rotation, generate new KSK, export new DS record, submit to registrar, wait for TTL expiry, then restart.
4. Monitor gslbd_dnssec_key_days_remaining and alert before expiry.

DS record export:

gslbctl dnssec ds --zone example.com. --ksk-file /etc/gslb/ksk.pem

9. Health-check safety (script and webhook checks) Health checks can execute code or make outbound requests from the node, so both kinds are hardened by default.

• Script checks (type: script) run arbitrary commands as the gslbd user on every node and are disabled by default. Enable them only if you trust every operator who can create a health check:

  health:
    allowScriptChecks: true   # off by default

  Even when enabled, a script check may only be created via the API by a system administrator — never a tenant/operator key. Prefer a webhook check to run custom logic off-node.

• Webhook checks (type: webhook) make gslbd request a URL you supply. To prevent Server-Side Request Forgery (SSRF) they may target public addresses only by default — loopback, link-local (including the cloud metadata IP 169.254.169.254), private/ULA, and CGNAT ranges are blocked. This is enforced both when the check is created and at request time on the resolved address (defeating DNS rebinding; redirects are not followed). To allow a specific internal host, list its CIDR/IP:

  health:
    webhookAllowedHosts:
      - "10.20.0.0/24"   # internal monitoring subnet
      - "192.0.2.50"     # a single host

  Public destinations remain allowed; entries override the deny list for those ranges only. See Health Checks for details.

10. API behind a reverse proxy If gslbd's API sits behind a reverse proxy (Caddy, nginx, a load balancer), set api.trustedProxies to the proxy's CIDR(s). The real client IP is then read from X-Forwarded-For (rightmost entry that is not itself a trusted proxy) for requests originating from those sources; otherwise the connection address is used and X-Forwarded-For is ignored (so it cannot be spoofed by direct clients).

api:
  trustedProxies:
    - "10.0.0.0/8"

This is required for correct RUM client attribution and per-client rate limiting behind a proxy — without it every visitor collapses into the proxy's single IP. Leave it empty when the API is exposed directly.

11. WebSocket authentication The live-event WebSocket endpoint (/api/v1/ws) is gated by a short-lived JWT signed with GSLB_WS_SECRET, falling back to GSLB_API_KEY. When neither is set (dev mode) the daemon generates a random per-process secret and logs a warning — it never signs tokens with a shipped constant. Setting GSLB_API_KEY in production (section 0) covers this automatically.

NSEC3: denial-of-existence records are generated on-the-fly per RFC 5155 §7.1. No static NSEC3 chain is maintained.