Skip to content

Security hardening

This page explains Falak’s security model and what you should do on top of the defaults.

  • TLS everywhere: Let’s Encrypt for the panel, HSTS (max-age=31536000), the agent API on its own host with mutual TLS against Falak’s Fleet CA.
  • Secrets (site variables, the secret store, git and provider credentials, database passwords, DNS tokens, GitHub App keys, two-factor secrets) are encrypted with AES-256-GCM under data keys wrapped by the key-encryption key (see Encryption keys), and never sent to the UI unless explicitly revealed. Reveals need a recent re-authentication and are audited.
  • Session, CSRF and remember-me cookies are __Host- prefixed (host-only, Secure, Path=/) whenever the panel runs on HTTPS, so a site on a sibling subdomain (a preview, say) can’t plant cookies the panel would read.
  • /opt/falak/.env is mode 600; backups/ is mode 700.
  • Containers run with no-new-privileges. The app trusts proxy headers only from the edge subnet (FALAK_EDGE_SUBNET).
  • Outbound requests the control plane makes on users’ behalf are guarded: alert webhooks, backup storage endpoints and template URL imports refuse private, loopback and link-local addresses by default.
  • The agent dials out; it listens only on loopback (OTLP) and a unix socket.
  • Firewall: nftables, inbound drop by default; only SSH, plus 80/443 on servers that serve HTTP.
  • SSH: keys only (PasswordAuthentication no, PermitRootLogin prohibit-password, MaxAuthTries 4), fail2ban running, unattended security upgrades on.
  • The falak user has no sudo. Sites can run as isolated Linux users.
  • Release and shared/ directories are mode 0750 with an ACL for the edge only; other local users cannot read bootstrap/cache/config.php. Site .env files live on a tmpfs, never on persistent disk, and secret values are masked in deploy, hook and build output.
  • The edge’s Caddy admin API listens on a root-only unix socket, never a TCP port.
  • Database containers run pinned image digests, get passwords as files and publish ports only to their consumers.
  • Deploys verify downloaded runtimes and agent binaries by SHA-256.
  • Compose files are checked against a policy (no privileged containers, host namespaces, extra capabilities, host mounts, devices or Docker socket) unless an admin allows privileged Compose.

Every secret Falak stores is encrypted at rest with AES-256-GCM under a data key. Data keys are stored in the database, wrapped by the key-encryption key (KEK). The KEK is not APP_KEY and is never in .env or the database, so a copy of the database together with .env reveals no secrets. Each value is bound to its row: copied elsewhere, it no longer decrypts.

  • Where. /opt/falak/secrets/kek: 32 random bytes, mode 0400, mounted read-only into the PHP containers only. They refuse to start without a usable KEK. falak-ctl kek status and falak-ctl doctor check it.
  • Emergency kit. Right after installing, and after every rotation: falak-ctl kek export /root/falak-emergency-kit.txt, move the file to a password manager or offline storage, and delete it from the host. falak-ctl kek import <file> puts the KEK back.
  • Rotation. falak-ctl kek rotate creates a new KEK, keeps the old one as secrets/kek.previous (older backups need it) and re-wraps every data key; the secrets themselves are not re-encrypted.
  • KMS / Vault. Set FALAK_KEK_PROVIDER=aws-kms or vault-transit in .env to keep the KEK in AWS KMS or a Vault/OpenBao transit key, where it never leaves; the provider’s settings go in custom.env.
  • Backups. A control plane backup contains the KEK only when it is encrypted with the DR passphrase. See Back up and restore Falak.
Action
☐ Restrict sign-up. By default anyone who can reach the panel can create an account (with its own empty organization; it cannot see yours). On a public panel, set FALAK_REGISTRATION=invite (sign-up only through an invitation link) or closed (accounts only via falak-ctl admin create) in /opt/falak/.env, then falak-ctl up. See Who can sign up.
☐ Turn on two-factor authentication for every member (per user; not enforceable per organization yet).
☐ Give members the lowest role that works. recipes.run, terminal.*, fleet.agents.manage and sites.compose.policy are admin-only because they amount to root on your servers.
☐ Create scoped API tokens with expiry for CI and agents, never * tokens for automation.
☐ Save the emergency kit (falak-ctl kek export) off the host, and set up disaster recovery (falak-ctl dr setup): encrypted, scheduled backups in a bucket of their own.
☐ Check each server’s security baseline and apply the safe fixes.
☐ Restrict Grafana to operators: dashboards are not filtered per organization inside Grafana.
☐ Keep database public access off; when you need it, list only the sources that need it. See Remote access.
☐ Use your own domains in production, not shared sslip.io names (no cookie isolation between their users).
☐ Keep Allow privileged compose off unless you trust everyone who can create sites.
☐ Protect staging with basic auth or IP allow lists (routing rules).
☐ Limit SSH on servers to your IPs with a firewall rule if possible (the SSH port itself always stays open to avoid lock-out).
☐ Bind the panel to one address with FALAK_BIND if the host has several interfaces.
☐ Configure mail so password resets and alerts work.
☐ Watch the Audit log (audit.view).
  • The alert webhook SSRF guard checks the host but does not resolve DNS, so DNS rebinding is not blocked.
  • Deleting an organization revokes its agents but does not destroy provider machines.
  • Octane’s FrankenPHP server binds its port on all interfaces; the default-drop firewall blocks it from outside.