3.5 Security hardening

Part 3 · Architecture & operationsArchitect⏱ ~25 min✓ Knowledge check

A fresh install is built to get you running, not to be locked down: it seeds admin/admin, ships with account lockout off, and leaves the appliance Web UI open to any source. This module is the checklist to work through before an install carries production DNS and DHCP. Each step says why it matters, where the control lives, and which doc backs it. Work through them in order; the early steps close the biggest gaps.

What you’ll learn

• Close the defaults that ship open: the admin account, lockout, sessions and install secrets
• Apply least privilege to people, API tokens and Windows service accounts
• Protect transport and keys: Web UI TLS, agent bootstrap keys, TSIG and dynamic-update ACLs
• Keep evidence and recovery durable with forwarded audit, a verified hash chain and drilled backups
• Shrink the attack surface: network exposure, outbound calls, DEMO_MODE, support bundles and unused features

What ships open

Setting	Ships as	For production
Admin account	admin/admin, with a forced change at first sign-in	Named accounts for each admin, with MFA
Account lockout	Threshold 0 (off)	A non-zero threshold
API token expiry	90 days suggested, Never allowed	Always an expiry
Appliance Web UI access	Open to any source	Your management CIDRs
Appliance SSH	Open to any source	Your management CIDRs, once console access is tested
Appliance fleet firewall	Off, behind two gates	On, once every node is hardened
GitHub release check	On	Off if the install must stay offline
DNS agent approval	Off	On only after you’ve tested it (see the note after step 6)
Service start/stop control	Off, except on the appliance	Leave it off on Compose and Helm

Several defaults now ship closed. They explain errors you may meet after an upgrade from 2026.09.04-1:

• The api refuses to start on the .env.example placeholder SECRET_KEY, or on a key under 32 characters (#1222).
• Compose publishes the API port on 127.0.0.1 only (API_BIND, #1221).
• Remote agents verify the control plane’s TLS certificate (#1220).
• /metrics needs a bearer token, /api/openapi.json needs a session or an API token, and an anonymous GET /api/v1/version answers only restricted (#1159, #2935).
• Sign-in is throttled: 30 attempts a minute per source, 20 failed passwords per 15 minutes per username, and 500 per 15 minutes across the install. The budgets fail open when Redis is down, and the install-wide one is a bounded denial of service that anyone who reaches the sign-in page can spend.
• Recursive BIND9 and Technitium groups answer recursive queries only from localhost and private networks; add public or CGNAT client ranges to the group’s allow_recursion if they need it (#1817).
• A fresh install turns on 16 of the 57 feature modules (#1069).

Tip

Before you harden anything, switch on the Environment banner (Settings → Application → Branding & URL) on every install: a colored strip on every page, the login page included, that names the environment. Hardening, restores and deletes then happen on the box everyone thinks they’re on. The same page has a Login banner for an acceptable-use notice, with an optional Require acknowledgement.

The checklist

People and access

1. Replace the default admin, and set the password, lockout and session policy.

   Why: every install seeds admin/admin, and account lockout ships off. Where: create a named account for each administrator, then work through Settings → Security: Password Policy (by default at least 12 characters with an uppercase letter, a lowercase letter and a digit, a history of 5, and no maximum age), Account Lockout (set a failure threshold; the lockout and reset windows default to 15 minutes) and Session & Security (session timeout, 60 minutes by default). A fresh install applies that policy and timeout from the first password, before anyone saves Settings (#3203).

   On Compose, change POSTGRES_PASSWORD (default changeme) and set SECRET_KEY from openssl rand -hex 32 before the first start; the api won’t start on the placeholder. To replace a key an install already uses, follow Rotating SECRET_KEY, which re-encrypts every stored credential; if the old key was a placeholder, review API tokens, users and superadmins afterwards. On Helm, pin the key with auth.existingSecret. Source: Auth, System administration §6, Docker Compose §3 and §8.

2. Turn on MFA, for SSO admins too.

   Why: TOTP adds a second factor to local sign-in. SSO users still sign in at their identity provider, but secret reveals (agent bootstrap keys, pairing codes, the appliance kubeconfig, the SNMP community) and minting an API token re-check the operator, and an SSO account has no local password to check (#1355). Where: the two-factor section of your Account page (Set up authenticator). Store the ten recovery codes somewhere safe; each works once. Wrong step-up answers spend a per-account budget, after which the API answers 429 for a while.

   If an account enrolled MFA on a release from 2026.05.05-1 to 2026.06.13-1, disable and re-enroll it: that enrollment screen sent the TOTP secret to a third-party QR-code service. Source: Auth: TOTP MFA, Privacy.

3. Grant least privilege, to people and to tokens.

   Why: a role is a list of {action, resource_type, resource_id} entries, and an entry scoped to one resource never satisfies a check on the whole type. You can hand out one subnet or zone without handing out all of them. Where: put people in groups that carry built-in roles (Viewer, IPAM Editor, DNS Editor, DHCP Editor, Auditor and others), and keep Superadmin for the few who need it; Ridgeline’s Helpdesk group gets Viewer. A custom role needs a grant on each type it reads: since 1.0.0-beta.3 one IPAM or DNS grant no longer reads the rest of IPAM or DNS (#3058, #3073).

   For automation, create tokens under Administration → Identity → API Tokens with scopes (read, ipam:write, dns:write, dhcp:write) and an expiry; creating one asks for your password, or an authenticator code on an SSO account. A token can never do more than both its scopes and its owner’s roles allow. Windows service accounts belong in DnsAdmins for DNS and DHCP Administrators for DHCP writes and failover (DHCP Users only for read-only mirroring), never Domain Admins. Source: Permissions, Auth: API tokens, Windows setup §5.

From the field

Reveals of the kubeconfig, pairing codes, agent keys and SNMP community used to demand a password re-entry, which SSO users couldn’t give. Since 2026.06.13-2, local users re-enter their password and SSO users enter a TOTP code instead. That only works once they’ve enrolled an authenticator, so make enrollment part of onboarding an SSO admin.

Source: GitHub issue #408

Transport and keys

4. Serve the Web UI over TLS, and set the External URL.

   Why: sign-in, tokens and secret reveals all cross this connection, and SAML with a hosted identity provider only works over HTTPS (#873). Where: on the appliance, replace the self-signed certificate under Appliance → Fleet → Web UI Certificate: upload one, generate a CSR, or issue one from Let’s Encrypt with the built-in ACME client, which can renew it automatically. On Compose, put a reverse proxy or Caddy in front, or enable TLS in the frontend’s nginx; on Helm, use an Ingress with cert-manager. Then set the public https:// address as the External URL (Settings → Application → Branding & URL), which OIDC and SAML need.

   Behind your own reverse proxy, list only the proxy in FRONTEND_TRUSTED_PROXY_CIDRS (Helm frontend.trustedProxyCidrs), leave TRUSTED_HOSTS unset or exact, and turn response buffering off with a read timeout of at least an hour for the streaming features. Without the trusted proxy, every user shares one login-throttle bucket and SSO callbacks are built as http://.

   Agents verify the control plane’s certificate by default. For a private CA, mount it into standalone agents and set TLS_CA_PATH; skipping verification is for labs only. Appliances pin the certificate on first contact: compare the fingerprint the supervisor logs with Appliance → Fleet → Web UI Certificate. Source: ACME client, Running behind a reverse proxy, Docker Compose §5 and §10, Auth: SAML.

5. Guard the agent bootstrap keys and pairing codes.

   Why: the bootstrap key is what lets a DNS or DHCP server register with your control plane. Where: generate DNS_AGENT_KEY and DHCP_AGENT_KEY with openssl rand -hex 32 and keep them in your secret store. Reveal them only through Settings → Security → Agent bootstrap keys, which re-checks your password or TOTP code and writes an audit row. Rotating a key doesn’t disturb agents that already hold a token.

   Standalone Docker and Kubernetes agents use the bootstrap key; an appliance Additional node pairs with an 8-digit code instead. Ephemeral codes are single-use and expire (15 minutes by default). Persistent codes expire after 30 days by default (0 means never), so give them a max_claims limit and revoke them when you’re done. Wrong codes are throttled (#1356). Source: DNS agent §6, OS appliance §9.

6. Sign updates and transfers with TSIG, and scope dynamic updates.

   Why: an unsigned RFC 2136 update or zone transfer is only as safe as the source address it trusts, and the docs flag IP-based entries as spoofable over UDP. Where: agent-managed BIND9 already signs every record change with TSIG over loopback, and the control plane signs its own zone transfers from BIND9 and Technitium with the group’s key. That group key has been encrypted at rest since 1.0.0-beta.1. On an install upgraded from 2026.09.04-1, rotate it once in the group’s Edit Group dialog (Group TSIG key, Rotate…), because the old plaintext copy is kept for one release (#1364).

   For external writers (a domain controller, a DHCP server), set the zone’s dynamic-update ACL and grant by TSIG key rather than IP; on BIND9 you can also limit a key to certain names and record types. On Windows, any IP entry becomes NonsecureAndSecure, which accepts any nonsecure client, and the API warns you. Source: DNS drivers §8, DNS §12, System administration §2.9.

From the field

The DNS agent design recommends requiring approval for agents in production, so an agent that re-registers with a changed key fingerprint waits in pending_approval. Before 2026.10.02-1 that gate (DNS_REQUIRE_AGENT_APPROVAL=true) had no way back for DNS.

Since 2026.10.02-1 a superadmin can clear the hold with POST /api/v1/dns/groups/{group_id}/servers/{server_id}/approve, which accepts the agent’s new identity and writes a dns.server.approve audit row. The DNS pages still have no approve button in 1.0.0-beta.3 (DHCP servers have one), so test the whole flow in a lab before you turn it on.

Source: GitHub issue #1121

Evidence and recovery

7. Forward the audit log, and watch the hash chain.

   Why: an audit trail that lives only on the box it describes can be lost with the box. Where: Settings → Security → Audit Event Forwarding sends audit rows to syslog (UDP, TCP or TLS; RFC 5424 with JSON, CEF or LEEF, RFC 3164, or JSON lines), an HTTP webhook, or SMTP. Delivery is best-effort after commit, so for at-least-once delivery point a webhook at a queue, and know that some scheduled-task audit rows may not forward yet. Credential-shaped values arrive as [redacted].

   The Audit Log page shows Chain verified or Tampering detected. A nightly job checks the rows added since its last run and re-walks the whole chain about once a week, so an edit to an old row can take about eight days to raise the critical audit-chain-broken alert; GET /api/v1/audit/integrity walks the chain on demand. Source: Observability §5, System administration.

8. Back up with a passphrase you keep elsewhere, and drill the restore.

   Why: each archive carries your install’s encryption keys wrapped in your passphrase. Lose the passphrase and you can’t restore the archive. And only that key envelope (secrets.enc) is encrypted: the database dump beside it isn’t, so anyone who can read an archive can read the whole database, although the stored credentials inside stay encrypted. Where: the Backup page under Administration. Schedule archives to a remote destination whose access you restrict, with a retention rule, and keep the passphrase (8 characters or more) in your password manager, not beside the archive.

   Schedule Restore Drills (weekly drills against nightly backups is the documented shape) so a broken archive raises restore_drill_failed; the backup_failed and backup_stale alerts are on by default. Take a manual backup before every upgrade. On the appliance, also keep a copy of the spatium-control-app-keys Secret, which holds SECRET_KEY.

   On Docker Compose the release file mounts the spatium_backups volume on the api and worker for Local volume targets, and Test connection warns when a target’s path isn’t on a mounted volume. The 2026.09.04-1 file shipped that volume commented out, so before upgrading from it, copy existing archives out of both containers (docker compose cp api:/var/lib/spatiumddi/backups ./backups-api, and the same for worker). Source: System administration §2.9, Docker Compose §9.

How secrets survive a backup and restore

Stored credentials (identity-provider secrets, WinRM passwords, cloud API keys, TSIG secrets) are Fernet-encrypted with keys derived from SECRET_KEY or CREDENTIAL_ENCRYPTION_KEY. A backup’s secrets.enc carries both keys, wrapped with your passphrase (PBKDF2-HMAC-SHA256 at 600,000 iterations, then AES-256-GCM). When you restore onto a different install, SpatiumDDI unwraps the source keys and re-encrypts every stored secret under the new install’s key. That’s why a plain pg_dump is only a fallback: it holds the ciphertext but not the key.

Exposure

9. Expose only what clients need.

   Why: PostgreSQL, Redis and the raw API port have no business on the network. Where: keep 5432 and 6379 internal, and publish only the Web UI, DNS and DHCP. On Compose the API port is published on 127.0.0.1 only by default (API_BIND=127.0.0.1); if you ever widen API_BIND, narrow TRUSTED_PROXY_CIDRS to the frontend’s address. An .env that sets API_PORT=127.0.0.1:8000, as this course once advised, breaks the port mapping from 2026.10.02-1 on: set API_PORT back to a bare port number before you upgrade.

   The interactive API docs (/api/docs, /api/redoc) work through the web port for signed-in users, and /api/openapi.json needs a session or an API token. /metrics needs a bearer token, either the scrape token (PROMETHEUS_METRICS_TOKEN) or any API token, so give each Prometheus a read-only token of its own.

   On appliances, enable the fleet firewall (module 3.3) and restrict Web UI access to your management CIDRs; its guard refuses a list that doesn’t cover your own address. SSH on 22 stays open by default, so a bad Web UI scope is recoverable over SSH, unless you also restrict SSH with Enforce source restriction (#1009). A change that would leave no remote way in at all needs an explicit console-only acknowledgement, and then the console is your last resort. For Windows, allow WinRM (5986, HTTPS) and port 53 only from the SpatiumDDI host, and restrict zone transfers to it. Source: Docker Compose §1 and §3, Observability §6, OS appliance: fleet firewall, Windows setup §5.

10. Decide on outbound connections, or go air-gapped.

    Why: a DDI server shouldn’t talk to the internet unless you chose that. Where: the one outbound connection that’s on by default is a daily GitHub release check: an anonymous GET to GitHub’s public API that sends nothing about your install. Turn it off under Settings → Application → Updates → Check for GitHub Releases. The privacy page lists every feature that reaches a third party (Fingerbank device profiling, the Copilot’s LLM provider, Let’s Encrypt, blocklist feeds, cloud DNS and integration mirrors, the whois and RBL tools), and each stays off until you configure it.

    The appliance boots from baked images without contacting any registry and takes upgrades from uploaded images. Its host uses pool.ntp.org for time and Debian’s APT mirrors unless you point them at your own (the installer’s Time source screen, then Appliance → Fleet → Services). Source: Privacy §2 and §3, System administration §7, OS appliance.

11. Never run DEMO_MODE in production.

    Why: DEMO_MODE exists for the public demo. It locks the abusable surfaces server-side (nmap, AI provider creation, webhook and integration targets, outbound mail, audit forwarding and backups, factory reset and password change), switches off a set of feature modules, skips the forced password change, and keeps sign-in at admin/admin. Where: make sure no production .env, Helm values or automation ever sets DEMO_MODE, and treat a demo-mode banner on a real install as an incident. Source: the project README.

12. Review a support bundle before you share it.

    Why: bundles tend to end up attached to public GitHub issues, where attachments are effectively world-readable. Where: Administration → Diagnostics → Support bundle. Secrets (keys, password hashes, JWTs, PSKs, API tokens, TSIG keys) are removed in every mode, and IPs, hostnames, MACs and usernames become stable synthetic values. Scrubbing is best-effort, so read the preview before you download, and keep the decode map, which is never inside the archive, to yourself. The unscrubbed variant needs a typed confirmation and carries UNSCRUBBED in its file name. Source: System administration §9.

13. Switch off what you don’t use.

    Why: every module you leave on is surface that a mistake, or an attacker, can reach. Where: the feature-module catalog, Features & Integrations near the bottom of the sidebar. A disabled module disappears from the sidebar, and its API returns 404, as if it weren’t installed. After a migration, turn off the importers and the Windows cutover module (migration.cutover). Leave service start/stop control off on Compose and Helm: a restart-capable docker.sock is equivalent to root on the host. Source: REST API §5, Getting Started: project status.

Knowledge check

Knowledge check · 6 questions

Security hardening

1. Which of these ships off on a new install, so you need to turn it on yourself?

Password historyAccount lockoutThe minimum password lengthSession timeout

Account lockout ships with a failure threshold of 0, which disables it. The password policy already defaults to a 12-character minimum with an uppercase letter, a lowercase letter and a digit, and a history of 5, and sessions time out after 60 minutes.

2. An SSO superadmin wants to reveal the agent bootstrap keys. What does SpatiumDDI ask them for?

Their identity provider's passwordA TOTP code from an authenticator they've enrolled in SpatiumDDINothing: an active session is enoughA local password that another admin sets for them

Secret reveals re-verify the operator. Local users prove their password; SSO users have no local password, so they prove a current TOTP code, which means enrolling an authenticator first. Minting an API token asks for the same step-up.

3. A token with the read scope is owned by a user who holds IPAM Editor. What can the token do?

Create subnets, because its owner canList subnets, but not create themNothing, because scopes and roles cancel each other outAnything a Superadmin can

Scopes narrow a token first, and the owner's RBAC still applies on top. A read scope limits the token to safe methods, so it can list but never mutate, whatever the owner could do.

4. Why is a plain pg_dump only a fallback compared with the in-app backup?

It's much slower to createIt doesn't carry the encryption keys, so stored credentials can't be decrypted on a different installIt leaves out the audit logIt can only be restored onto the same release

The in-app archive wraps SECRET_KEY and CREDENTIAL_ENCRYPTION_KEY with your passphrase and re-encrypts secrets on a cross-install restore. A raw dump holds the ciphertext but not the key, which lives in the api's environment.

5. What's the right way to share a support bundle on a GitHub issue?

Attach the unscrubbed variant so support sees real namesRead the preview, share the scrubbed bundle, and keep the decode map to yourselfPut the decode map inside the archive so support can read itAttach it without review, because bundles contain no identifiers

Attachments on a public repository are effectively world-readable. Secrets are always removed and identifiers are replaced with synthetic values, but scrubbing is best-effort, so read the preview first. The decode map is never inside the archive, by design.

6. Which of these belong on a production install?

Select all that apply.

DEMO_MODE turned on, to lock risky featuresAn expiry on every API tokenAudit forwarding to a SIEM or a queueAgents that skip TLS verification, to avoid dealing with a private CA

DEMO_MODE is for the public demo: it blocks password change and keeps sign-in at admin/admin. Agents verify the control plane's TLS certificate by default; with a private CA, mount it into the agents and set TLS_CA_PATH rather than skipping verification, which is for labs only.

Check answers

Go deeper

• Auth and permissions: local auth, TOTP, sign-in throttles, identity providers and API tokens
• Permissions model: the grammar, evaluation rules and built-in roles
• System administration: password and lockout settings, backup and restore, the support bundle
• Rotating SECRET_KEY: replacing a placeholder or leaked key on Compose without losing stored credentials
• Running behind a reverse proxy: trusted proxies, the External URL, headers and streaming
• Observability: the audit log, forwarding and the /metrics token
• DNS agent: security: bootstrap keys, tokens, approval and TSIG handling
• Privacy: every outbound connection and how to turn it off

Finished 3.5 Security hardening?

Mark it complete to track your progress (stored only in this browser).

Mark complete