security overview

Security Overview

You will learn the security design of update-ipsets, how the two surfaces are protected, and what the threat model covers.

Design principles

update-ipsets follows a fail-closed daemon security model:

• The daemon CLI default requires admin authentication
• Unsafe modes require explicit opt-in
• Misconfiguration blocks access rather than opening it

Two surfaces

The daemon exposes two distinct surfaces:

Public surface — the website, API, and feed downloads.

• Read-only. No authentication required.
• Serves precomputed artifacts from disk. Public requests do not trigger downloads, processing, or recomputation.
• Rate-limited to prevent abuse.
• No secrets in URLs or logs.

Admin surface — the operator dashboard and control API.

• Requires authentication by default in the daemon CLI.
• Exposes feed status, queue state, integrity findings, and operator actions (recheck, reprocess, enable, disable).
• Available on the same listener as public, or on a separate admin-only listener.

Public surface protections

• Rate limiting: 240 requests/minute per client IP for /api/ and /mcp. IP search endpoints also have a stricter 10 requests/minute search bucket.
• Excluded from rate limiting: /healthz and the /admin browser shell. Admin API routes under /api/v1/admin/* still use the general /api/ rate limit.
• No secrets in URLs: Feed data, metadata, and search results never embed credentials.
• Path traversal protection: All artifact and file routes validate paths against traversal attacks.

Admin surface protections

See Admin Authentication for the full authentication model.

• Daemon default mode is required — HTTP Basic Auth with configured credentials.
• Missing or empty credentials block admin access entirely.
• Disabling auth requires two explicit flags, not one.
• The admin SPA shell itself is protected behind authentication.

The installed systemd unit is different from the daemon CLI default: install.sh generates a private-network service configuration that disables admin authentication with both required unsafe flags. Treat that installed mode as safe only when localhost or tailnet membership is the intended admin access control layer. For shared, untrusted, or internet-reachable networks, switch the installed unit back to --admin-auth-mode=required and configure credentials.

Security considerations by deployment

Deployment	Recommendation
Local testing	Use --admin-auth-mode=disabled with both flags, on loopback only
Staging	Use required auth on the default listener
Production	Use split listener with admin on localhost, behind a firewall

See Production Deployment for the recommended setup.