Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

fix(install): derive the real client IP on a stock host install

Juan Denis0bb7e4ab549c
diff --git a/.env.example b/.env.example
index 5142fdb4..542efe2b 100644
--- a/.env.example
+++ b/.env.example
@@ -58,14 +58,27 @@ CORS_ORIGINS=http://localhost,https://your-domain.com
# ----------------------------------------
# Trusted reverse proxy (client IP)
# ----------------------------------------
-# The panel runs behind its bundled nginx, so the real client IP arrives in
-# X-Forwarded-For and the raw socket peer is nginx. Enable this so ServerKit
-# trusts the proxy and derives the real client IP (via Werkzeug ProxyFix) for
-# rate-limiting, login lockout and audit logs. Leave it FALSE / unset only for
-# a directly-exposed server with no proxy in front (otherwise a client could
-# forge X-Forwarded-For). TRUSTED_PROXY_HOPS = number of proxies in front of
-# Flask (bundled nginx = 1; raise it if you add e.g. Cloudflare on top).
-TRUST_PROXY_HEADERS=true
+# Derive the real client IP from X-Forwarded-For (via Werkzeug ProxyFix) for
+# rate limiting, login lockout and audit logs, instead of logging every request
+# as the proxy's address.
+#
+# Turn it on ONLY when a proxy you control is the sole route in. The header is
+# whatever the caller typed, so if anything can open a connection to the backend
+# port directly, this hands attackers the ability to forge the IP that those
+# very throttles key on.
+#
+# Off by default HERE because this file is the Docker/manual path, and
+# docker-compose.yml publishes port 5000 on all interfaces. Set it to true once
+# you put a proxy in front AND stop direct access to 5000 — bind it to loopback
+# (see docs/INSTALLATION.md → "Running behind your own reverse proxy") or
+# firewall it.
+#
+# Host installs do not use this file: install.sh writes its own .env and enables
+# this automatically, because there gunicorn binds loopback behind our nginx.
+#
+# TRUSTED_PROXY_HOPS = proxies in front of Flask. Your proxy alone = 1; your
+# proxy plus ServerKit's nginx = 2; add Cloudflare on top and it goes up again.
+TRUST_PROXY_HEADERS=false
TRUSTED_PROXY_HOPS=1
# ----------------------------------------
diff --git a/ROADMAP.md b/ROADMAP.md
index af344674..da249d7d 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -11,6 +11,7 @@ This document outlines the development roadmap for ServerKit. Features are organ
### Recently Completed (v1.7.x)
- **Run It Behind Your Own Reverse Proxy** - Already running Caddy, Traefik or Nginx Proxy Manager, with Let's Encrypt or a private CA of your own? That is now a supported, documented and tested way to run the panel rather than something you reverse-engineer from the install script. Two topologies are written up — keep ServerKit's nginx (full features, host install) or point your proxy straight at the panel (panel only, the Docker shape) — with proxy config snippets, the two environment variables that matter, and a symptom-to-cause table for the redirect loop, the rejected websocket and the wrong client IPs. A new installer switch sets a box up this way in one line, and an install-config file makes the whole thing re-runnable. Tests now pin the properties an external proxy depends on: the panel emits no redirect to HTTPS from any of its 352 routes, the public URL is honoured as a websocket origin while strangers are rejected, and HSTS stays off when TLS is somebody else's job.
+- **Rate Limits and Audit Logs See the Real Visitor** - The panel is always served through its own nginx, so every request arrived carrying nginx's address rather than the visitor's — and the installer never turned on the setting that recovers the real one. Per-IP rate limiting, the login brute-force block and every audit-log entry were therefore keyed on a single local address, which quietly weakened all three: one abusive client shared a bucket with everyone else. New installs now enable it, and re-running the installer backfills it on existing ones without touching a value you set yourself. It deliberately stays off when the backend port is exposed directly, because a visitor who can reach it without passing through nginx can simply claim any address they like.
- **Installing With a Domain No Longer Breaks nginx** - Setting a panel domain at install time wrote a bare-IP redirect that declared itself a second default server on port 80 — something nginx refuses outright, in both HTTP and HTTPS modes, so nginx would not start and the installer had no `nginx -t` to say why. The redirect now matches a bare IP by name pattern instead of competing for the default, verified against real nginx, with a regression guard.
- **Docker Actually Runs the Panel** - `docker compose up -d` started nothing at all: every service had ended up behind an opt-in profile while the README and install guide still gave that command as the way to install with Docker. It now runs the real all-in-one panel on port 5000 with a persistent volume for the database. The image itself could not boot either — it wrote its database to a directory it never created — and the developer docs pointed at a compose file that has never existed. All corrected, with a guard so a profile change cannot silently empty the default command again.
- **Uptime Monitors** - Monitoring is no longer only about the machine the panel runs on. A monitor watches anything you point it at — a website, an API endpoint, a database port, a mail server or a managed WordPress site — with HTTP, keyword, port, ping, DNS and SMTP checks, per-monitor intervals, expected status ranges, redirect and TLS-verification switches, and a retry threshold before anything is declared down. A scheduler polls them continuously (previously checks only ran when someone pressed a button), outages open and close an incident on their own, and each monitor gets a detail page with a response-time chart, a 90-day uptime strip, a live check log and TLS certificate expiry. Host CPU/memory/disk alerting is unchanged and now shares one Incidents timeline with monitor outages, so "something is wrong" is a single place. Status pages publish monitors you already have rather than defining their own duplicate probes.
diff --git a/SECURITY.md b/SECURITY.md
index 39212724..437a0cc9 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -67,14 +67,34 @@ never hand-parses it. Instead it derives the client IP through one trusted seam
| Variable | Default | Meaning |
|----------|---------|---------|
-| `TRUST_PROXY_HEADERS` | `false` | Trust forwarding headers to derive the client IP. **Set `true` only where a reverse proxy is guaranteed in front** (the shipped nginx deploy sets it). Leave `false` for a directly-exposed server so headers can't be forged. |
+| `TRUST_PROXY_HEADERS` | `false` in code; `true` written by `install.sh` | Trust forwarding headers to derive the client IP. **Only where a reverse proxy is guaranteed in front.** Leave `false` for a directly-exposed server so headers can't be forged. |
| `TRUSTED_PROXY_HOPS` | `1` | Number of trusted proxy hops in front of Flask (bundled nginx = 1). Raise it only if you add another proxy (e.g. Cloudflare on top). |
+The code default is `false` because a bare `create_app()` — a dev server, a test,
+an import — has nothing in front of it. A **host install is different**: it always
+serves the panel through its own nginx, and the systemd unit binds gunicorn to
+`127.0.0.1`, so nothing can reach Flask without passing through that nginx and
+`X-Forwarded-For` is ours. `install.sh` therefore writes `TRUST_PROXY_HEADERS=true`
+and `TRUSTED_PROXY_HOPS=1` into `.env`, and backfills them on a re-run of an
+install that predates this — without ever overriding a value you set yourself.
+
+Two cases where the installer deliberately does **not** enable it:
+
+- `SERVERKIT_BIND_HOST` set to anything but loopback. The raw backend port is then
+ reachable directly, a client can connect without traversing nginx, and
+ `X-Forwarded-For` becomes attacker-chosen. The installer says so and leaves it off.
+- `SERVERKIT_EXTERNAL_PROXY=1` uses `TRUSTED_PROXY_HOPS=2` instead — your proxy
+ appends the real client, then our nginx appends your proxy.
+
With trust on, `ProxyFix` takes the **rightmost** `TRUSTED_PROXY_HOPS` entries of
`X-Forwarded-For` — the hops your own proxies appended — so a forged *leftmost*
value is discarded. Setting a hop count higher than the real number of proxies,
or turning trust on for a directly-exposed panel, re-introduces spoofing — don't.
+⚠️ If you run the panel some other way — the Docker image with the port published,
+a custom unit, gunicorn by hand — you own this decision. Enable it only if a proxy
+you control is the sole path in.
+
> **Behavior change:** audit-log source IPs now record the real client IP
> instead of the proxy's address. Update any dashboards or alerts that were built
> on the old (proxy-IP-or-forged) values.
diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md
index 458759f4..133d0701 100644
--- a/docs/INSTALLATION.md
+++ b/docs/INSTALLATION.md
@@ -58,6 +58,7 @@ On a `minimal` install:
| `SERVERKIT_EXTERNAL_PROXY=1` | You run your own TLS-terminating reverse proxy in front. Selects the plain-HTTP nginx site (no redirect for the proxy to loop on), skips certbot, and sets `TRUST_PROXY_HEADERS=true` + `TRUSTED_PROXY_HOPS=2`. See [Running behind your own reverse proxy](#running-behind-your-own-reverse-proxy) |
| `SERVERKIT_PUBLIC_URL=https://panel.example.com` | The public URL browsers use. Required with `SERVERKIT_EXTERNAL_PROXY` — without it websocket connections are rejected on origin |
| `SERVERKIT_CONFIG=/path/install.conf` | Read the options above from a `KEY=VALUE` file instead of the command line. Explicit environment still wins |
+| `SERVERKIT_BIND_HOST=0.0.0.0` | Expose the raw backend port instead of binding it to loopback. ⚠️ Also disables trusted client IPs — with the port directly reachable, `X-Forwarded-For` is client-forgeable. Firewall it yourself |
| `INSTALL_FROM_RELEASE=1` | Install from the latest GitHub release tarball instead of cloning source |
| `SERVERKIT_VERSION=v1.7.0` | Pin a specific release version |
| `SERVERKIT_OFFLINE_TARBALL=/path/to/...tar.gz` | Use a local tarball instead of downloading |
diff --git a/install.sh b/install.sh
index 6f822ae3..47512e5d 100644
--- a/install.sh
+++ b/install.sh
@@ -1290,9 +1290,42 @@ build_virtualenv() {
# ---------------------------------------------------------------------------
# Application configuration and generated secrets
# ---------------------------------------------------------------------------
+# Where gunicorn listens. Loopback by default — host nginx fronts the panel on
+# :80/:443, so the raw gunicorn port must not be world-reachable. Operators who
+# front it differently override with SERVERKIT_BIND_HOST=0.0.0.0.
+#
+# One definition, two consumers: it renders the systemd unit AND decides whether
+# X-Forwarded-For is trustworthy. Those answers must never disagree.
+backend_bind_host() {
+ printf '%s' "${SERVERKIT_BIND_HOST:-127.0.0.1}"
+}
+
+# True when the only route to Flask is through our own nginx.
+#
+# This is the whole security condition behind TRUST_PROXY_HEADERS. ProxyFix
+# takes X-Forwarded-For at face value, which is safe exactly when a proxy we
+# control is guaranteed to have written it — i.e. when nothing can open a socket
+# to gunicorn directly. Loopback binding is what guarantees that; the installer
+# firewall also never opens the backend port (SSH + 80/443 + PANEL_PORT only).
+backend_is_loopback_only() {
+ case "$(backend_bind_host)" in
+ 127.0.0.1|localhost|::1|'[::1]') return 0 ;;
+ *) return 1 ;;
+ esac
+}
+
# Set KEY=value in an env file, replacing any existing definition (commented or
# not). Rewrites the file instead of `sed -i s|...|`: values here are URLs, and
# an unescaped '/', '&' or '|' in a sed replacement is syntax, not data.
+# Fill a gap without ever overriding a choice. An uncommented definition is the
+# operator's — someone may have turned trust off deliberately, and a re-run
+# silently turning it back on would be the worst kind of surprise.
+_env_default_key() {
+ local file="$1" key="$2" value="$3"
+ grep -qE "^[[:space:]]*${key}=" "$file" && return 0
+ _env_set_key "$file" "$key" "$value"
+}
+
_env_set_key() {
local file="$1" key="$2" value="$3" tmp
# Beside the target, not in /tmp: this file carries SECRET_KEY and the
@@ -1340,6 +1373,17 @@ write_config() {
_env_set_key "$INSTALL_DIR/.env" SERVERKIT_PUBLIC_URL "$PANEL_PUBLIC_URL"
fi
good "External-proxy settings applied to the existing .env."
+ elif backend_is_loopback_only; then
+ # Installs made before the trusted-proxy default existed have no
+ # TRUST_PROXY_HEADERS line at all, so they key rate limits, login
+ # lockout and audit logs on nginx's own address. Backfill it on a
+ # re-run — but only where the line is absent, never over an explicit
+ # setting.
+ if ! grep -qE '^[[:space:]]*TRUST_PROXY_HEADERS=' "$INSTALL_DIR/.env"; then
+ _env_default_key "$INSTALL_DIR/.env" TRUST_PROXY_HEADERS true
+ _env_default_key "$INSTALL_DIR/.env" TRUSTED_PROXY_HOPS 1
+ good "Enabled trusted-proxy client IPs (behind this install's own nginx)."
+ fi
fi
return
fi
@@ -1400,6 +1444,39 @@ TRUST_PROXY_HEADERS=true
TRUSTED_PROXY_HOPS=2
PROXYEOF
)
+ elif backend_is_loopback_only; then
+ proxy_block=$(cat <<'PROXYEOF'
+
+# Trusted reverse proxy — every host install serves the panel through its own
+# nginx, and gunicorn binds loopback (see the systemd unit), so X-Forwarded-For
+# is written by that nginx and nothing can reach Flask directly to forge it.
+# Without this the panel keys per-IP rate limits, the login brute-force throttle
+# and every audit-log entry on nginx's own address instead of the real client.
+# One hop: our nginx is the only proxy in front. Raise it if you add another
+# (e.g. Cloudflare on top ⇒ 2).
+TRUST_PROXY_HEADERS=true
+TRUSTED_PROXY_HOPS=1
+PROXYEOF
+)
+ else
+ # The raw gunicorn port is exposed, so a client can connect without
+ # passing through our nginx and X-Forwarded-For becomes attacker-chosen.
+ # Trusting it here would let anyone forge the IP that rate limits, login
+ # lockout and audit logs key on — strictly worse than logging one wrong
+ # address. Left off, and said out loud rather than silently.
+ proxy_block=$(cat <<'PROXYEOF'
+
+# Trusted reverse proxy — deliberately OFF. SERVERKIT_BIND_HOST exposes the
+# backend port directly, so X-Forwarded-For is client-controlled and cannot be
+# trusted. Client IPs will show as the proxy/socket peer. If you do front this
+# with a proxy AND block direct access to the backend port, set:
+# TRUST_PROXY_HEADERS=true
+# TRUSTED_PROXY_HOPS=<number of proxies in front of Flask>
+TRUST_PROXY_HEADERS=false
+PROXYEOF
+)
+ warn "SERVERKIT_BIND_HOST=${SERVERKIT_BIND_HOST:-} exposes the backend port directly."
+ warn "Leaving TRUST_PROXY_HEADERS off: X-Forwarded-For would be client-forgeable."
fi
cat > "$INSTALL_DIR/.env" <<EOF
@@ -2184,10 +2261,8 @@ EOF
render_service_unit() {
local out="$1"
local template="$INSTALL_DIR/templates/serverkit-backend.service.in"
- # Bind the API to loopback by default — host nginx fronts it on :80/:443, so
- # the raw gunicorn port must not be world-reachable. Operators who front it
- # differently can override with SERVERKIT_BIND_HOST=0.0.0.0.
- local bind_host="${SERVERKIT_BIND_HOST:-127.0.0.1}"
+ local bind_host
+ bind_host="$(backend_bind_host)"
if [ -f "$template" ]; then
sed -e "s|@SERVERKIT_DIR@|$INSTALL_DIR|g" \
-e "s|@SERVERKIT_VENV_DIR@|$VENV_DIR|g" \
diff --git a/scripts/test/test_install.sh b/scripts/test/test_install.sh
index 209fa2e6..51caa15f 100644
--- a/scripts/test/test_install.sh
+++ b/scripts/test/test_install.sh
@@ -2046,6 +2046,116 @@ for site in serverkit.conf serverkit-insecure.conf; do
fi
done
+# --------------------------------------------------------------------------
+# T44 — every install must derive the REAL client IP.
+#
+# install.sh wrote no TRUST_PROXY_HEADERS line at all, so the config default
+# (False) applied while the panel always sits behind its own nginx: per-IP rate
+# limits, the login brute-force throttle and every audit-log entry keyed on
+# 127.0.0.1. .env.example claimed `true`, so the two disagreed.
+#
+# Trusting X-Forwarded-For is only safe because nothing can reach gunicorn
+# without passing through that nginx — render_service_unit binds loopback and
+# the firewall never opens the backend port. Expose the port and the header
+# becomes attacker-chosen, so the switch must follow the bind host.
+# --------------------------------------------------------------------------
+printf '\nT44 — trusted client IP on a stock install\n'
+t44="$WORK/t44"; mkdir -p "$t44"
+
+# -- the stock install: loopback-bound gunicorn behind our own nginx.
+out="$( set -Eeuo pipefail
+ unset SERVERKIT_BIND_HOST SERVERKIT_EXTERNAL_PROXY || true
+ source "$INSTALL_SH" >/dev/null 2>&1
+ rm -rf "$t44/a"; mkdir -p "$t44/a"
+ INSTALL_DIR="$t44/a"; SSL_MODE=insecure; PROFILE=standard
+ write_config >/dev/null 2>&1
+ cat "$t44/a/.env" )"
+if printf '%s' "$out" | grep -q '^TRUST_PROXY_HEADERS=true' \
+ && printf '%s' "$out" | grep -q '^TRUSTED_PROXY_HOPS=1'; then
+ ok "a stock install trusts its own nginx and derives the real client IP (1 hop)"
+else
+ bad "stock install produced: [$(printf '%s' "$out" | grep -i proxy | tr '\n' ' ')]"
+fi
+
+# -- exposing the raw backend port must turn it OFF: X-Forwarded-For is then
+# client-controlled, and a forged IP defeats the very throttles it feeds.
+out="$( set -Eeuo pipefail
+ unset SERVERKIT_EXTERNAL_PROXY || true
+ SERVERKIT_BIND_HOST=0.0.0.0
+ source "$INSTALL_SH" >/dev/null 2>&1
+ rm -rf "$t44/b"; mkdir -p "$t44/b"
+ INSTALL_DIR="$t44/b"; SSL_MODE=insecure; PROFILE=standard
+ write_config >/dev/null 2>&1
+ cat "$t44/b/.env" )"
+if printf '%s' "$out" | grep -q '^TRUST_PROXY_HEADERS=false' \
+ && ! printf '%s' "$out" | grep -q '^TRUST_PROXY_HEADERS=true'; then
+ ok "SERVERKIT_BIND_HOST=0.0.0.0 leaves trust OFF (the header would be forgeable)"
+else
+ bad "an exposed backend port still trusted X-Forwarded-For: [$(printf '%s' "$out" | grep -i proxy | tr '\n' ' ')]"
+fi
+
+# -- the external-proxy switch still wins, with its own hop count.
+out="$( set -Eeuo pipefail
+ SERVERKIT_EXTERNAL_PROXY=1
+ source "$INSTALL_SH" >/dev/null 2>&1
+ rm -rf "$t44/c"; mkdir -p "$t44/c"
+ INSTALL_DIR="$t44/c"; SSL_MODE=insecure; PROFILE=standard
+ write_config >/dev/null 2>&1
+ cat "$t44/c/.env" )"
+if printf '%s' "$out" | grep -q '^TRUSTED_PROXY_HOPS=2'; then
+ ok "SERVERKIT_EXTERNAL_PROXY still overrides the default with 2 hops"
+else
+ bad "external proxy did not set 2 hops: [$(printf '%s' "$out" | grep -i proxy | tr '\n' ' ')]"
+fi
+
+# -- backfill on a re-run: pre-existing installs are the ones actually suffering.
+mkdir -p "$t44/old"
+printf 'SECRET_KEY=keep-me\nSERVERKIT_SSL_MODE=insecure\n' > "$t44/old/.env"
+( set -Eeuo pipefail
+ unset SERVERKIT_BIND_HOST SERVERKIT_EXTERNAL_PROXY || true
+ source "$INSTALL_SH" >/dev/null 2>&1
+ INSTALL_DIR="$t44/old"; SSL_MODE=insecure; PROFILE=standard
+ write_config >/dev/null 2>&1 )
+if grep -q '^TRUST_PROXY_HEADERS=true' "$t44/old/.env" \
+ && grep -q '^TRUSTED_PROXY_HOPS=1' "$t44/old/.env" \
+ && grep -q '^SECRET_KEY=keep-me' "$t44/old/.env"; then
+ ok "a re-run backfills the trust setting into an install that predates it"
+else
+ bad "re-run backfill produced: [$(tr '\n' ' ' < "$t44/old/.env")]"
+fi
+
+# -- but an explicit operator choice is never overridden. Someone who turned
+# trust off did it for a reason, and a re-run flipping it back on silently
+# would be the worst possible surprise.
+mkdir -p "$t44/explicit"
+printf 'SECRET_KEY=keep-me\nTRUST_PROXY_HEADERS=false\n' > "$t44/explicit/.env"
+( set -Eeuo pipefail
+ unset SERVERKIT_BIND_HOST SERVERKIT_EXTERNAL_PROXY || true
+ source "$INSTALL_SH" >/dev/null 2>&1
+ INSTALL_DIR="$t44/explicit"; SSL_MODE=insecure; PROFILE=standard
+ write_config >/dev/null 2>&1 )
+if grep -q '^TRUST_PROXY_HEADERS=false' "$t44/explicit/.env" \
+ && ! grep -q '^TRUST_PROXY_HEADERS=true' "$t44/explicit/.env"; then
+ ok "a re-run never overrides an explicit TRUST_PROXY_HEADERS=false"
+else
+ bad "a re-run overrode the operator's explicit setting: [$(tr '\n' ' ' < "$t44/explicit/.env")]"
+fi
+
+# -- the two consumers of the bind host must agree. The systemd unit and the
+# trust decision reading different values is exactly how this class of bug
+# comes back.
+unit="$t44/unit.service"
+( set -Eeuo pipefail
+ unset SERVERKIT_BIND_HOST || true
+ source "$INSTALL_SH" >/dev/null 2>&1
+ INSTALL_DIR="$REPO_DIR"; VENV_DIR="$REPO_DIR/venv"; LOG_DIR="$t44"
+ render_service_unit "$unit" >/dev/null 2>&1 ) || true
+if grep -q -- '-b 127.0.0.1:5000' "$unit" 2>/dev/null; then
+ ok "render_service_unit and the trust decision share one bind host (loopback)"
+else
+ bad "the rendered unit does not bind loopback: [$(grep ExecStart "$unit" 2>/dev/null)]"
+fi
+
# -- static guard: the documented insecure site must keep shipping, since both
# the docs and SERVERKIT_EXTERNAL_PROXY point operators straight at it.
if [ -f "$REPO_DIR/nginx/sites-available/serverkit-insecure.conf" ] \