Security

Operator-focused overview of what dvb-WarpPool protects, how it does so, and which responsibilities remain with the operator.

Threat Model

The pool sits between four actor classes with different levels of trust:

Threat → Mitigation Matrix

Auth Stack

dvb-WarpPool has three orthogonal auth paths:

1. JWT cookie — browser UI, normal login flow
2. API tokens — bearer token for scripts (wpat_<32hex> prefix)
3. 2FA-TOTP — optional additional factor for (1)

Login Flow

POST /api/auth/login {username, password, totp_code?}
  -> verify Argon2id hash against admin_password_hash
  -> 2FA active? check totp_code (RFC 6238, ±1 step skew)
  -> mint JWT mit sub=username, exp=now+24h
  -> set HttpOnly Cookie warppool_session=<jwt>
  -> audit: login.ok | login.fail

API Token Flow

POST /api/admin/tokens {name, ttl_secs?, scope?}  (auth required)
  -> generate token: format "wpat_" + 32 hex chars (128 bits entropy)
  -> store sha256(token) + name + scope + expires_at
  -> response: {id, name, scope, token, expires_at}
  -> CLIENT MUST STORE THE TOKEN IMMEDIATELY — only the hash is kept afterwards
  -> audit: token.create

Authorization: Bearer wpat_abc123...   (subsequent requests)
  -> sha256(token) lookup in api_tokens WHERE revoked_at IS NULL AND (expires_at IS NULL OR expires_at > now)
  -> match found → AuthIdentity{sub: "token:<name>", exp: ...}
  -> fire-and-forget touch_api_token (last_used_at = now)

2FA Setup

POST /api/auth/2fa/setup
  -> mint_2fa_setup(issuer="dvb-WarpPool", account=username)
  -> generate base32 secret + otpauth:// URL
  -> persist with enabled=0
  -> audit: 2fa.setup

(User scans QR or enters secret in Authenticator app)

POST /api/auth/2fa/enable {code}
  -> verify_totp(secret, code) → ok
  -> UPDATE admin_2fa SET enabled=1, enabled_at=now
  -> issue single-use recovery codes (hashed at rest, shown once)
  -> audit: 2fa.enable

2FA Recovery Codes

Enabling 2FA also issues a set of single-use recovery codes. They are shown exactly once at enable time and only their hashes are stored — the same one-shot rule as API tokens. Write them down before leaving that screen.

At login, the totp_code field also accepts a recovery code: a plausible- looking code is checked against the unused set, and on match it is consumed (one use, never again) and the login succeeds. This is the way back in when the authenticator device is lost — without it, a lost phone means losing admin access to the pool.

GET /api/auth/2fa/status reports recovery_remaining, so the UI can warn as the pile runs low. POST /api/auth/2fa/recovery/regenerate rotates the set (invalidating all outstanding codes); this is also the way to refresh codes while 2FA stays active, since enable refuses to run twice.

Recovery-code logins are audited separately as login.recovery, including how many codes remain — an unexpected entry there is a strong signal of account compromise.

Key Material

Audit Logging

All state-changing admin actions are persisted in audit_log:

Fields: at (timestamp), actor (user, or token:<name>, or ? for failed login), action, target (optional, action-specific), peer_ip (with X-Forwarded-For resolution when trust_proxy_headers=true), ok (boolean), details (optional, e.g. error description).

Retrieve via GET /api/admin/audit?limit=100&actor=admin or CLI:

dvb-warppool-cli audit --limit 50 --actor admin

The table has indexes on at, actor, action for fast filtering.

Eviction is automatic. The daemon’s retention loop calls evict_audit_older_than([retention].audit_log_secs) — default 90 days — at most once per hour, so the DELETE does not run on every 60 s tick. Set [retention].audit_log_secs to change the window. (Earlier releases had no daemon-side eviction and required a cron job; that is no longer the case.)

TLS

dvb-WarpPool has two separate TLS surfaces:

Stratum-V1 TLS (port :3334 typical)

Optional. If stratum.tls_cert_path + stratum.tls_key_path are set, a second listener runs alongside the plain port. Rustls 0.23, default suite (TLS 1.2 + 1.3, no TLS 1.0/1.1).

The operator provides cert+key themselves — typically via Let’s Encrypt (certbot with DNS challenge when the pool is not publicly reachable) or mkcert for LAN-only setups.

Stratum-V2 NOISE (sv2_listen, :3336 in the reference deployment)

NOISE-NX handshake (Stratum V2 2024 spec: secp256k1 + EllSwift + Schnorr) via the noise_sv2 crate, pure Rust. Static authority key in secrets.sv2_authority_priv_key_hex. The public key the V2 miner needs as its server-pubkey is available three ways:

• Pool UI: dashboard → “⛏ Miner verbinden” button → the connect modal shows the V2 endpoint and the server pubkey with a copy button.
• API: GET /api/overview → field sv2_authority_pubkey_b58 (Base58, unauthenticated; the public key is by design not a secret).
• CLI: dvb-warppool-cli sv2-pubkey reads secrets.toml, derives the pubkey and prints it on stdout — handy for headless / SSH setups where the UI is not reachable.

In contrast to classic TLS, NOISE has no PKI — the miner must learn the pool pubkey OOB (out of band). That is the Sv2 standard.

API TLS (HTTPS for /api + UI)

Optional via server.status_tls_listen. Operators frequently put a reverse proxy (Caddy with auto-LetsEncrypt) in front instead and let the daemon speak only HTTP on 127.0.0.1. In that case: set server.trust_proxy_headers = true so that the audit log sees real client IPs.

Reproducible Builds + Signing

Phase 8b: cargo [profile.release] with lto = "fat" (single-threaded LTO, deterministic) + RUSTFLAGS=--remap-path-prefix=... + cargo-home + cargo-git remap. CI builds twice in matrix jobs and compares sha256 — fails on drift.

Local end-user verification:

scripts/verify-reproducible.sh v1.24.0
# fetches the release tarball, extracts the daemon binary, rebuilds locally
# with the same flags + compares sha256

Phase 8g: POST /api/admin/update accepts cosign_verify: bool. If true, cosign verify-blob runs as an external subprocess before atomic_swap. The operator must set the WARPPOOL_COSIGN_BIN env var — otherwise hard-fail (500), not a silent skip.

Cosign verify uses the project cosign key (cosign.pub in the repo root): cosign verify-blob --key cosign.pub --bundle. (GitHub-era releases ≤ v1.15.0 were keyless via GitHub Actions OIDC + Fulcio; that path is GitHub-bound and gone since the move to the self-hosted forge.) For anyone who wants a second path: the GPG workflow has been available since Phase 6, but is not enabled by default.

Stratum Hardening

Rate Limiting (Phase 3)

Token bucket per peer IP. Defaults:

To a rate-limited auth the server responds with result: false (no disconnect) so that the miner does not enter a reconnect loop — that would only keep loading the limit bucket and fill the connection cap.

idle_evict_secs (default 300) clears limiter state buckets for IPs that have had no traffic for 5 min — so that server memory stays linearly bounded and does not grow with the unique-IP count.

Auto-ban + manual ban list ([ratelimit])

A public IP that repeatedly trips the connect limit (default: 10 strikes / 60 s) is fully banned — rejected before the TLS/handshake — for an escalating duration (base 5 min, doubling, capped at 1 h). Loopback and private LAN (10/8, 172.16/12, 192.168/16, link-local) are never auto-banned, so local miners that reconnect in bursts can’t lock themselves out. Tunable via [ratelimit].autoban_* (off via autoban_enabled = false). On top, an operator-curated [ratelimit].manual_bans list (admin API /api/admin/ratelimit/{bans,ban,unban} + UI panel) blocks specific IPs permanently — these apply to any IP including LAN, but loopback stays exempt (so the operator can’t lock out the local UI); a deliberate ban overrides only the auto-ban’s LAN exemption.

Reject-ratio auto-ban ([ratelimit].reject_ban_*)

Off by default. When enabled, a worker whose rejected-share ratio (rejected / (accepted + rejected)) is at or above reject_ban_ratio once at least reject_ban_min_samples shares have been observed is banned for the same escalating auto-ban duration as the connect auto-ban. Public-IP-only — loopback and private LAN are never banned this way, so a noisy local miner can’t lock itself out. Because a ban is an access-control decision, an active ban is enforced on the next connect even if the token-bucket rate-limit (enabled = false) is turned off, as long as the ban mechanism that produced it (autoban_enabled or reject_ban_enabled) is set.

IP-gate — CIDR deny-list + allow-only whitelist ([ratelimit])

Off by default. ban_cidrs is a deny-list of IPv4/IPv6 CIDR ranges (a bare IP is treated as /32 / /128) — any connect from a listed range is refused before TLS/handshake. Setting allow_only = true flips the listener into a whitelist: only IPs matching allow_cidrs may connect. Loopback always passes regardless of the gate, so the operator can never lock out the local UI / local miners. Malformed CIDR entries are skipped (logged once at load). Like the bans, the gate is an access-control decision and applies even when the rate-limit is disabled.

Per-IP connection cap ([stratum].max_connections_per_ip)

Default 0 (unlimited). When set, a single peer IP may hold at most that many concurrent Stratum connections; further connects from the same IP are dropped at accept time. This bounds single-host connection exhaustion independently of the profile-wide connection cap. Loopback is exempt.

Payout-address allowlist ([mining].address_allowlist)

Empty by default (open — any Bitcoin address may mine). When populated, only the listed payout addresses may mine: the address is everything before the first . in the worker name. Enforced identically on Stratum V1 (mining.authorize is rejected) and Stratum V2 (the channel-open returns an error for Standard and Extended channels). Useful for a private “pool for friends” deployment.

Public-exposure privacy switches ([privacy])

Two booleans control what an anonymous visitor may read. Both default to true, i.e. the historical open behaviour — a solo or friends pool keeps working unchanged after an upgrade. A public deployment should review them explicitly, because the defaults publish more than a public pool usually wants:

[privacy]
wallet_directory_public      = false
leaderboard_addresses_public = false

The authenticated operator always sees the unmasked data — these switches only affect the anonymous view. They complement the tab-visibility gating added in v1.19.1 (see the residual-risk table at the end of this page for what is still open on the unauthenticated read surface).

HTTP-API rate limit (api_rpm)

Separately from Stratum, the whole HTTP API is per-IP token-bucket limited (profile-driven api_rpm); over the limit returns HTTP 429 + Retry-After. Loopback and private LAN are exempt so the operator’s own UI is never throttled; the limit targets public remote clients only.

Connection Cap

Profile-dependent (klein: 16, mittel: 64, gross: 256, enterprise: 4096). Over-limit connects are dropped at accept time; semaphore-based, no per-connection allocation beforehand. The profile is hot-switchable, so this is a tuning knob rather than a fixed ceiling.

Conservative Mode (safe_mode)

When stratum.safe_mode = true (default): the share validator rejects unusual shares (unusual version bits, suspicious ntime drift). The operator can set this to false when testing experimental hardware.

Audit-Friendly Defaults

Backup & Restore

GET /api/admin/backup exports the SQLite DB as plain, unencrypted SQLite bytes. Restore via POST /api/admin/restore. There is no built-in encryption — the export contains 2FA secrets and API-token hashes (see below), so encrypt it yourself (age, gpg, an encrypted volume) before it leaves the host.

Audit: backup.export + backup.restore. On backup.restore a fresh migration runs after the import so that schema drifts between the backup version and the current version are resolved.

What is in the backup: all DB tables incl. admin_2fa.secret_base32, api_tokens.token_hash, audit_log. What is NOT included: secrets.toml, config.toml, ~/.bitcoin/.cookie. Anyone backing up both must protect them separately.

Sandbox + Privileges

Pool listen ports are all >1024 (3333/3334/…) — no CAP_NET_BIND_SERVICE required.

Disclosure

Please report security findings via coordinated disclosure: email first to dvbprojekt@gmx.de, an issue on git.warppool.org only after a fix. We are a small crew without a formal bug bounty — good-faith reports are acknowledged with credit.

SECURITY.md in the repo root holds the official policy

• PGP key on request.

What is intentionally NOT implemented

Accepted residual risks after the security audit (Phase 32)