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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
fix(install): derive the real client IP on a stock host install
Juan Denis0bb7e4ab549c
diff --git a/.env.example b/.env.exampleindex 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=falseTRUSTED_PROXY_HOPS=1# ----------------------------------------diff --git a/ROADMAP.md b/ROADMAP.mdindex 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.mdindex 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.mdindex 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.shindex 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"figood "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)."+ fifireturnfi@@ -1400,6 +1444,39 @@ TRUST_PROXY_HEADERS=trueTRUSTED_PROXY_HOPS=2PROXYEOF)+ 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."ficat > "$INSTALL_DIR/.env" <<EOF@@ -2184,10 +2261,8 @@ EOFrender_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" ]; thensed -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.shindex 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; dofidone+# --------------------------------------------------------------------------+# 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" ] \