Client IP Headers

BotStopper appends the connecting peer address to X-Forwarded-For, then scans the chain from right to left. It forwards the first valid address outside these categories:

• Private (XFF_STRIP_PRIVATE, enabled by default)
• Loopback (always stripped)
• CGNAT (always stripped)
• Link-local Unicast (always stripped)

Incoming: X-Forwarded-For: 1.2.3.4, 5.6.7.8, 10.0.0.1
Upstream: X-Forwarded-For: 5.6.7.8

This behavior will cause problems if the proxy in front of BotStopper is from a public IP, such as Cloudflare, because BotStopper will use the Cloudflare IP instead of your client's real IP. You will likely see all requests from your browser being blocked and/or an infinite challenge loop.

Incoming: X-Forwarded-For: REAL_CLIENT_IP, CF_IP
Upstream: X-Forwarded-For: CF_IP

Configure your ingress to derive the client address from a trusted source, such as Cloudflare’s CF-Connecting-IP header. Overwrite client-supplied IP headers before the request reaches BotStopper. For a public connecting peer, also set X-Real-IP or configure --custom-real-ip-header. A single incoming X-Forwarded-For address does not prevent BotStopper from appending and selecting the public peer address.

If you do not control the web server upstream of BotStopper, the custom-real-ip-header command line flag accepts a header value that BotStopper will read the real client IP address from. BotStopper will set the X-Real-IP header to the IP address found in the custom header.

If X-Real-IP is absent, BotStopper infers it from X-Forwarded-For. An explicit X-Real-IP value takes precedence. The ingress must replace spoofed values.

These address exclusions are not a list of authenticated proxy identities. Restrict direct access to BotStopper when your configuration relies on ingress headers.

See Cloudflare for an example configuration.

See configuration for deployment configuration.