Skip to content

Security and hardening

This page states, without marketing, what the deployment protects, how it protects it, and what is left to the operator. Every "enforced" line names the file that enforces it, so the claim can be checked.

Threat model

pygslb serves internal, authoritative DNS: it answers for one or more zones of your own, to clients on your own networks. The assets worth protecting are, in order:

  1. The answer itself — a wrong or missing answer is an outage for every service behind the name;
  2. The configuration — whoever writes the YAML decides where traffic goes;
  3. The statistics — which network queried what and when, which is a map of your internal usage.

It is not an Internet-facing resolver, and nothing in it is designed for a hostile network. Treating it as a public authority would be a misconfiguration, not a missing feature.

What is enforced

Property How Where
The DNS does not run as root Image user gslb, UID 1000; cap_drop: ALL, cap_add: NET_BIND_SERVICE only Dockerfile, docker-compose.lot2.yml
The container filesystem is read-only read_only: true, tmpfs: /tmp same
No privilege escalation no-new-privileges:true same
No Docker socket anywhere The DNS/API link is two files in a shared volume, never a daemon call gslb/bridge.py, gslb/sync.py
The API refuses to work unauthenticated No credential configured → every data route answers 503, not 200 api/auth.py
A credential does not cross the network in clear by default Plain HTTP is refused unless the deployment opts in explicitly (GSLB_ALLOW_PLAINTEXT_AUTH=1, lab only); TLS terminates in front of the console nginx, which must itself receive HTTPS api/auth.py, api/clientinfo.py
The audit trail names where a save came from source_ip on every configuration version, from X-Real-IP only behind GSLB_TRUST_PROXY=1 api/clientinfo.py, api/apply.py
Proxy headers cannot be spoofed into a claim X-Forwarded-Proto and X-Real-IP are read only when GSLB_TRUST_PROXY=1 api/clientinfo.py
Credential comparison is constant-time hmac.compare_digest on Basic and Bearer api/auth.py
A person is named in the audit trail when OIDC is on The ID token's email (else preferred_username, else sub) becomes the actor, and the group decides the role api/oidc.py, api/identity.py
Identity is delegated, not re-implemented The provider authenticates and can enforce MFA; the console keeps no password, only a signed cookie. The provider can be configured from the console, and every change names its actor and address api/oidc.py, api/settings_routes.py, api/settingstore.py
Provider secrets do not enter the database GSLB_OIDC_CLIENT_SECRET and GSLB_SESSION_SECRET stay in the environment; a backup or a VACUUM INTO never carries them, and the API returns only whether they are set api/idsettings.py
Nobody enters without a mapped role No group and no default role → 403; group overage (Entra) → explicit refusal, never silently granted; an allowed-domain list is checked before the role api/claims.py
A stolen cookie is not enough to write Signed HttpOnly, SameSite=Lax, Secure cookie, plus X-Requested-With and an origin check on every unsafe method api/session.py, api/csrf.py
A token minted for someone else cannot sign in Signature against the provider's JWKS, iss, aud, exp, iat and the per-attempt nonce; PKCE S256 on the code exchange api/idtoken.py, api/oidc.py
The API is not reachable from outside in the HA topology Only nginx publishes a port; the API container publishes none docker-compose.ha-api.yml
Probe secrets stay out of the YAML headers_env maps a header to an environment variable name; a test asserts the value never appears in the canonical output gslb/probe.py, tests/
No raw client address is kept Counters bucket by /24, capped at 256 distinct networks, overflow under other gslb/mapper.py, gslb/manager.py
The database is bounded Routing and health events purged after GSLB_RETENTION_DAYS (7 by default); configuration versions kept api/store.py
A statistics backlog never blocks an answer The event queue is bounded at 5 000; when full, events are dropped, never queries gslb/events.py
An HA node survives an API outage The outbox is bounded at 5 000 and the node serves its local configuration meanwhile gslb/outbox.py, gslb/sync.py
A configuration cannot be half-applied Validate → atomic write → acknowledgement → rollback, on one path shared by the console, a restore and the first-start wizard api/apply.py
A supervision outage is not a DNS outage A probe that cannot conclude leaves the previous state and logs a warning; it never marks DOWN gslb/probe.py, gslb/manager.py

What is not protected

These are known, documented limits. Do not read the table above as a guarantee that covers them.

  • Port 53 has no authentication and no allow-list. Anyone who can reach the address gets an answer for your zone, or REFUSED for a name outside it. The control is the network: bind the LAN address (GSLB_ADDR), firewall UDP/TCP 53 to the client networks that need it, and never publish it to the Internet.
  • No rate limiting. The optional circuit breaker (gslb/breaker.py) reroutes a spiking pool to the default one; it does not drop or throttle queries. A flood is absorbed by the kernel, then the process, then nothing.
  • No DNSSEC. Answers can be forged by anyone on the path, and cached poisoning-style attacks are not detectable by the client. That is a design choice of this lot, not a bug to report.
  • No DoT/DoH. The traffic is plaintext UDP/TCP on your network.
  • The configuration and the state directory are the trust boundary. Whoever can write /config/gslb.yaml or /state can change where traffic goes. The console is authenticated; the filesystem is not.
  • Without OIDC there is no per-user identity in the audit trail. A configuration version then records the content, the trigger (api, setup, restore, template), one account name — the Basic user, or token when the shared token was used — and the administrator's address. That is one write credential for the whole console. With GSLB_OIDC_ISSUER set, each operator signs in at your provider and the audit trail names their e-mail (the ID token's email, else sub); the group they belong to decides whether they may read, operate or write. The limit that remains is the lifetime of a session: a role change applies at the next sign-in, not to an open session, because the session is a signed cookie and not a database row. The provider settings themselves are stored in SQLite, so the operator configures sign-in from the console; losing that database loses the overrides and the environment becomes the configuration again — never a lockout, and neither secret was ever stored there.
  • The API speaks plain HTTP on its own listener. The built-in guard refuses to authenticate over it; it does not encrypt anything. TLS terminates in front of the console nginx, and that hop must itself be HTTPS: $scheme is computed by that nginx, never taken from an incoming header. With GSLB_TRUST_PROXY=1 the API must not be reachable except through it.
  • Trusted proxies are not selected by address. GSLB_TRUST_PROXY is a boolean: when it is on, the headers are believed from whoever connects. That is safe only while the API is reachable from the proxy alone (the HA compose publishes no API port). Per-CIDR trust would need the variable to take a list and the chain validated hop by hop; it is not implemented, and pretending otherwise would be worse than the boolean.
  • No protection inside the host. A compromised Docker host, a leaked GSLB_API_TOKEN or a mounted volume read by another container is out of the software's reach.
  • SO_REUSEPORT lets another process share port 53 with a node. With network_mode: host, any process in the same network namespace that binds the same address and port with the same option is served a share of the datagrams by the kernel, and can answer in place of the GSLB. This is how GSLB_WORKERS and a one-container-per-core deployment work, so the option cannot be removed; it is safe on a host that runs only this service, and it is a reason not to co-locate unrelated workloads on a DNS host. Without the option (the default), a second bind fails loudly instead.

Hardening checklist

Operator actions, roughly in order of value:

  1. Bind the LAN address, not 0.0.0.0: GSLB_ADDR=192.0.2.10 (and the node address first in a VIP list: GSLB_ADDR=192.0.2.10,192.0.2.40).
  2. Firewall 53 to the client networks the name is meant for; keep the management console on a management network and behind a TLS reverse proxy.
  3. Rotate the credentials (GSLB_API_USER, GSLB_API_PASSWORD, GSLB_API_TOKEN) away from the examples, keep them in the host environment or a mode-600 env file, never in the repository or in a compose file.
  4. Keep probe secrets in the environment (headers_env), never inline in the YAML.
  5. Point the health check at the node, not the VIP: GSLB_HEALTHCHECK_ADDR=<node address> — otherwise a node reports the health of whichever node holds the VIP.
  6. Watch the drift and snapshot age: the console shows when the running configuration differs from the file and when a node stopped reporting; both are early warnings of a control-plane problem.
  7. Back up the YAML and the SQLite file; the YAML is the only thing needed to rebuild a node.
  8. Keep images pinned to a version tag, and check the release signature when the signed appliance images are published.

Reporting a vulnerability

See SECURITY.md at the root of the repository: a confidential issue on the tracker, no public disclosure before a fix is available. The same channel is described on the contact page.