Summary
HomeBox's authentication rate limiter incorrectly trusts client-supplied IP headers, allowing attackers to bypass per-IP throttling of failed login attempts.
By forging X-Real-IP or X-Forwarded-For headers when connecting directly to HomeBox, an attacker can obtain a fresh rate-limit identity for each request, enabling large-scale password guessing attacks.
Affected context
This vulnerability affects HomeBox deployments that:
- Expose the application directly to clients or the internet (without a trusted reverse proxy enforcing IP headers), and
- Rely on IP-based rate limiting to slow down or detect failed login attempts.
In affected versions, the authentication rate limiter:
- Always reads X-Real-IP and X-Forwarded-For headers, regardless of trust configuration
- Applies chi's RealIP middleware unconditionally, which rewrites r.RemoteAddr using potentially forged header values
As a result, any client able to set arbitrary HTTP headers can control the identity used for rate limiting.
Exploit preconditions
- Attack surface: Public or internal HomeBox HTTP interface, specifically the authentication endpoints protected by authRateLimiter.
- Required access: Network access to the HomeBox instance and the ability to send crafted HTTP requests with custom headers (X-Real-IP, X-Forwarded-For).
- Trigger point: Repeated authentication attempts where the rate limiter evaluates the client IP based on request headers and r.RemoteAddr.
- Why exploitation is possible:
- IP determination logic reads X-Real-IP and X-Forwarded-For unconditionally from the request.
- The TrustProxy configuration flag is not consulted by the rate limiting or middleware logic.
- chi's RealIP middleware is applied unconditionally, overwriting r.RemoteAddr with header-derived values even for direct client connections.
- This allows an attacker to forge a new "client IP" each request, defeating per-IP rate limits on failed logins.
Why this happens
The core issue is a mismatch between the trust model and the implementation of IP-based rate limiting.
From a bug-class perspective, this maps to CWE-307: Improper Restriction of Excessive Authentication Attempts:
- The security control (rate limiter) is implemented, but its enforcement depends on an identifier derived from untrusted input (client-controlled IP headers).
- The system assumes that X-Real-IP and X-Forwarded-For reflect a trusted upstream proxy, yet these headers are honored even when no such proxy is configured.
- The TrustProxy configuration flag exists but is never enforced in the middleware or limiter, causing the application to always treat IP headers as trustworthy.
Abstractly, this pattern is: "Authentication throttling keyed off untrusted identity attributes," where a security control is present but can be trivially bypassed by manipulating the attribute used as the key (in this case, the client IP).
Potential impact
- Attackers may perform large-scale credential stuffing and password guessing against user accounts without being slowed by per-IP rate limits.
- Lockout, alerting, or anomaly-detection mechanisms that rely on IP-based thresholds can be evaded.
- User accounts could be compromised if weak, reused, or guessable passwords are in use.
- Application logs and monitoring may reflect misleading or spoofed IP addresses, complicating incident investigation.
- Downstream security controls that treat client IP as a reliable identity signal can be weakened or bypassed.
General mitigation guidance
Effective mitigation focuses on enforcing a clear trust boundary for client identity and decoupling authentication protection from trivially spoofable signals:
- Harden IP trust semantics:
- Respect a TrustProxy-style configuration flag to determine whether IP headers such as X-Real-IP and X-Forwarded-For should influence client identification.
- When no trusted proxy is configured, derive client IP solely from the underlying TCP connection address (e.g., r.RemoteAddr) and ignore proxy headers.
- Apply RealIP or similar middleware conditionally, only when running behind a known, controlled proxy layer.
- Strengthen rate limiting and lockout semantics:
- Key rate limiting on more than just IP, combining factors such as username, IP, and possibly device or session identifiers, while being careful to avoid new privacy or DoS issues.
- Implement exponential backoff, progressive delays, or hard caps on failed attempts per account in addition to IP-based thresholds.
- Reduce trust in client-controlled fields:
- Treat all HTTP headers as untrusted unless explicitly verified by an upstream component.
- Centralize request identity derivation in a single, well-reviewed component so all security features rely on the same, validated identity.
- Defense in depth for authentication:
- Encourage or enforce strong password policies and multi-factor authentication where possible.
- Ensure authentication endpoints are monitored and that anomaly detection does not rely solely on IP-based patterns.
These patterns help ensure that authentication protections remain effective even when clients can freely manipulate request headers.
How teams detect issues like this
Detection typically involves both code-centric and operational approaches:
- Static and code review signals:
- Search for middleware or helper functions that:
- Always read X-Real-IP, X-Forwarded-For, or other proxy headers without checking a configuration flag.
- Rewrite r.RemoteAddr (or equivalent) based on header values unconditionally.
- Review authentication code and rate limiter implementations for:
- Reliance on IP-derived identifiers where the IP source can be influenced by untrusted headers.
- Existence of a TrustProxy or similar setting that is declared but not actually referenced in enforcement logic.
- Configuration and architecture checks:
- Compare deployment architecture with code behavior: verify that IP-trusting behavior matches the presence of a real, controlled reverse proxy.
- Flag deployments where applications that trust proxy headers are directly exposed to the internet.
- Runtime and log-based detection:
- Analyze authentication logs for:
- Many failed attempts with a broad variety of distinct "client IPs" but correlated user-agents and timestamps.
- Repeated login failures where IP addresses appear synthetically distributed or sequential.
- Implement monitoring rules that alert when the volume of authentication failures per time window is inconsistent with rate limit expectations.
Automated code scanning tools or custom linters can be configured to highlight unguarded usage of RealIP-style middleware and direct consumption of proxy headers in authentication and rate limiting logic.

