This document outlines the security improvements made to Caddy Knocker and best practices for secure deployment.
Issue: The X-Forwarded-For header was trusted without validating the source IP, allowing attackers to spoof their IP address.
Fix: Implemented trusted proxy validation that only honors X-Forwarded-For headers from configured trusted sources.
If the direct peer is a configured proxy, a missing, malformed, incomplete, or
proxy-only X-Forwarded-For chain resolves to no client IP. Knocker never
falls back to the proxy address. Direct clients whose peer is not trusted
continue to use their direct address and cannot influence forwarded headers.
Configuration:
server:
trusted_proxies:
- "172.16.238.2/32" # The reverse proxy's pinned IPv4 (single host)
- "fd00:dead:beef::2/128" # The reverse proxy's pinned IPv6 (single host)
- "127.0.0.1" # Localhost, only if something local calls knocker directlyAssign those addresses to the proxy container with ipv4_address /
ipv6_address on the shared Docker network so they are stable; do not
substitute the network's subnet (172.16.238.0/24, fd00:dead:beef::/64).
Issue: Attackers could whitelist overly broad IP ranges like 0.0.0.0/0 or ::/0, effectively disabling all access controls.
Fix: Added validation to reject CIDR ranges that exceed reasonable size limits.
Limits:
- IPv4: Maximum 65,536 addresses per range
- IPv6: Minimum /64 prefix (broader ranges are rejected)
POST /knock checks failure-bucket capacity before comparing API keys or reading
the body. An exhausted client receives 429 even with a correct key. Blocked
requests do not extend the window; requests admitted before exhaustion may
finish. Successful requests do not consume failure allowance, and setting
failed_requests: 0 disables this gate. Limits are per resolved client IP and
per process; multiple workers or instances do not share throttle state. Clients
sharing an IP also share its lockout, and the existing actor-cap eviction can
discard throttle history.
Admission for clients with no failure history skips global bucket pruning; attempt accounting still performs scheduled maintenance. Admission, failure, and success-limit denials share the same 429 JSON response and CORS headers.
Authentication then completes before body parsing. The body is optional, must
be application/json when present, may contain
only ip_address and ttl, and is bounded at 4096 bytes. Authenticated malformed
and oversized requests count as failures. The endpoint returns 413 for an
oversized body, 415 for non-JSON content, and 503 when the serialized firewall
mutation worker is unavailable or saturated.
After KnockRequest has validated the streamed body, /knock performs only
policy checks: remote-whitelist permission, safe CIDR width, and global/key TTL
limits. All failed responses use the same CORS and failure-rate-limit path.
Issue: The excluded paths feature used simple string prefix matching, potentially vulnerable to path traversal attacks.
Fix: Implemented path normalization that resolves .. and . components before checking exclusions.
Example: /api/status/../../../etc/passwd is normalized to /etc/passwd and properly rejected.
Normalization decodes percent-escapes once and folds only literal ./..
segments. Backends behind the proxy may normalize further: strip ; path
parameters (Tomcat, Jetty, Spring), double-decode %252e%252e, translate \
separators, truncate at a NUL byte, or read overlong UTF-8 as .. Such request
targets stay under an excluded prefix in Knocker's view while the backend routes
them onto a protected path.
PathExclusions.matches() therefore refuses the unauthenticated exclusion
shortcut for any request path that still contains one of % (residual
double-encoding), ; (path parameters), \ (separator translation), a NUL byte,
or U+FFFD (invalid UTF-8) after one decoding pass. This covers both global and
host-scoped exclusions, because /verify resolves exclusions through
matches(). Configured prefixes are normalized once when settings load and are
never rejected by this guard.
Refusing the shortcut fails closed: the request falls through to the normal IP
whitelist check, so legitimate clients can still knock and whitelisted IPs keep
access. The tradeoff is that rare legitimate URLs on public paths using ;
matrix parameters or encoded percents (%25) now require a whitelisted IP
instead of matching an exclusion. Leading // authority-form targets are a
separate concern and are deliberately not handled here.
Issue: Concurrent access to the whitelist file could cause data corruption or inconsistent state.
Fix: Added file locking and atomic writes using temporary files.
Features:
- Thread-safe operations with threading locks
- File locking (fcntl) for process-level safety
- Atomic file operations (write to temp, then rename)
The active whitelist is accessed through RuntimeState.whitelist, which keeps
authorization on the in-memory index while preserving locked, atomic persistence.
Issue: API key names were logged in plaintext, potentially exposing sensitive information.
Fix: Reduced logging verbosity to remove sensitive details from logs.
Issue: No limits on whitelist size could allow attackers to consume excessive disk space.
Fix: Configurable limits on whitelist entries with automatic cleanup of oldest entries.
Capacity enforcement now fails loudly instead of silently discarding grants:
- When the whitelist already holds
security.max_whitelist_entriesentries, a knock for a brand-new entry is rejected with503 Service Unavailable("Whitelist is at capacity. Try again later."). Knocker never returns success for an entry it could not persist, and any firewalld rule installed for that entry is rolled back on a best-effort basis. A failed rollback is logged at ERROR level, and the rule may remain active until its TTL expires. - Refreshing (re-knocking) an entry that is already in the whitelist keeps working at capacity, so existing clients do not lose access while the store is full.
- Background compaction still evicts the entries that expire soonest when the store exceeds the limit; if that eviction drops entries that had not expired yet, a WARNING naming the count and a few examples is logged.
Configuration:
security:
max_whitelist_entries: 10000 # Default limit
knock_rate_limit:
window_seconds: 60
successful_requests: 20
failed_requests: 30Issue: A hostile configuration could point whitelist persistence at an unexpected path on disk.
Fix: Whitelist storage is normalized with realpath and constrained to known-safe roots before any file operation.
Allowed roots:
- The current working directory
/data/tmp
Issue: Default CORS policy used wildcard origin (*), allowing any website to make requests.
Fix: Encourage explicit origin configuration in production.
Configuration:
cors:
allowed_origin: "https://your-trusted-domain.com"Issue: The knock rate limiter kept one bucket per resolved client IP with no
limit on distinct actors. A peer inside trusted_proxies controls the
X-Forwarded-For chain, so each invented-but-well-formed address allocated
persistent limiter state that outlived the window, allowing sustained floods to
grow process memory without bound.
Fix: Two bounds.
- Forwarded entries longer than 64 characters are rejected outright (fail closed), so implausibly long identity strings never reach actor state or logs.
max_tracked_actorscaps how many distinct actors are retained. When a new actor needs a slot at the cap, the least recently created actor and all of that actor's outcome buckets are evicted.
Tradeoff: Eviction fails open for the affected actors - they lose their throttle history and get fresh windows. An exhausted rate limiter must not become a memory-exhaustion primitive against Knocker itself.
Configuration:
security:
knock_rate_limit:
max_tracked_actors: 100000 # Default limit on tracked client IPs- Keep the trust scope minimal — just the proxy:
trusted_proxiesmust contain only the reverse proxy's own address(es) as single hosts (/32for IPv4,/128for IPv6). Threat note: every container inside a trusted range can forge client identity. Since Knocker derives the client IP from headers sent by a trusted peer, a compromised backend container or an SSRF bug in one could claim anyX-Forwarded-For, impersonate an already-whitelisted address to pass/verify, and use/knockwith a regular key (noallow_remote_whitelist) to whitelist arbitrary IPs. Never trust the proxy network's subnet. - Pin the proxy's addresses: Docker does not assign stable container IPs by default; set
ipv4_address/ipv6_addressfor the proxy on the shared network so its/32//128entries stay valid across restarts (see the commented-outcaddyservice indocker-compose.yml) - Leave proxy-header resolution to Knocker: Run Uvicorn with
--no-proxy-headersso Knocker can resolve the direct peer fromrequest.client.hostbefore consultingserver.trusted_proxies - Reject malformed forwarded chains: If a trusted proxy sends an invalid
X-Forwarded-Forchain, Knocker now treats the client IP as unresolved instead of falling back to the proxy IP - Use Docker networks: Isolate knocker service on a private Docker network
- Firewall rules: Restrict direct access to the knocker service port
- Use ASCII key material: Non-ASCII configured secrets are rejected at startup; rotate any such secret to a random ASCII value. Non-ASCII request headers are ordinary invalid-key failures (401, or 429 after lockout), with no comparison exception. Key material is not normalized or silently converted.
- Use strong, random API keys: Generate cryptographically secure random strings
- Do not reuse secrets across entries: Avoid configuring the same secret twice
- Principle of least privilege: Set
allow_remote_whitelist: falsefor most keys - Regular rotation: Rotate API keys periodically
- Separate keys for different purposes: Use different keys for admin vs user access
- Reject published placeholders: The old example secrets, plus values containing
CHANGE_MEorREPLACE_WITH, are rejected at startup.
- Restrict file permissions: Ensure knocker.yaml is only readable by the service user
- Environment variables: Store the config path in
KNOCKER_CONFIG_PATH - Always-allowed IPs: Minimize the always-allowed IP list to only essential systems as single hosts (
/32//128, e.g. the proxy itself and loopback) - Proxy networks are not allowlists: Keep
always_allowed_ipsempty unless every address in the range is meant to bypass verification. - Use host-scoped exclusions: Do not globally exclude
/knock; put the dedicated knock hostname on a direct proxy route and protect other hosts withforward_auth. - Host-scoped exclusions only accept one bare authority: Knocker derives the exclusion host from
X-Forwarded-Hostsent by a trusted proxy, so a comma-separated chain (which no single routing decision produced) or a decorated value (user@host,host?query,host#fragment, embedded/,\, C0 control character or DEL) is rejected instead of trimmed to its leftmost host. Such requests get no host-scoped exclusions and fall back to the global exclusions plus the normal IP whitelist verdict, and configuration keys of that shape are rejected during runtime-state construction.
- Monitor failed authentication attempts: Look for patterns that might indicate attacks
- Set up alerts: Alert on unusual whitelist activity or configuration changes
- Log rotation: Ensure logs don't consume excessive disk space
- Keep dependencies updated: Regularly update Python packages and base container images
- Review configurations: Periodically audit trusted_proxies and always_allowed_ips
- Test security controls: Regularly verify that security measures are working correctly
When firewalld.enabled is true, startup fails before readiness unless the
daemon, version, exact zone, configured priority/target/sources, default
blocking rules, reload, and all active whitelist restorations verify correctly.
/health is liveness-only and does not run firewall-cmd; /ready performs
the read-only storage and firewalld verification for readiness monitoring.
Firewall mutations run through one bounded in-process worker and return 503 when capacity is unavailable. A remaining architectural risk is privileged root container access to the host D-Bus and the root + host-firewalld trust boundary. Moving mutations into a separately confined helper service remains future work; this change intentionally does not implement that architecture.
The project includes comprehensive security tests in tests/test_security_fixes.py that validate:
- Trusted proxy validation
- CIDR range limits
- Path traversal prevention
- Ambiguous request paths refusing the exclusion shortcut
- Information disclosure protection
- Size limits and DoS prevention
- Rate limiting
Run security tests with:
uv run pytest tests/test_security_fixes.py -vIf you discover security vulnerabilities not covered by these protections:
- Do not open public issues for security vulnerabilities
- Contact the maintainers privately
- Provide detailed information about the vulnerability
- Allow time for responsible disclosure
This guide describes implemented controls and configuration requirements. It is not a claim that every deployment-specific or architectural risk has been eliminated.