Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

geolocation fix (#1018)

Goldflagec0c5c30e3d9
diff --git a/docs/content/docs/proxy-guide/get-started.mdx b/docs/content/docs/proxy-guide/get-started.mdx
index 1b568b763..604465f00 100644
--- a/docs/content/docs/proxy-guide/get-started.mdx
+++ b/docs/content/docs/proxy-guide/get-started.mdx
@@ -169,17 +169,17 @@ For accurate tracking, ensure these headers are forwarded to the Rybbit backend:
| Header | Purpose | Required |
|--------|---------|----------|
| `User-Agent` | Device and browser detection | Yes |
-| `X-Forwarded-For` or `X-Real-IP` | IP address for geolocation | Yes |
+| `X-Real-IP` or `X-Forwarded-For` | IP address for geolocation | Yes |
| `Referer` | Referrer tracking | Recommended |
| `Accept-Language` | Language detection | Optional |
<Callout type="warn">
-**IP Forwarding**: Rybbit uses IP addresses for geolocation (country/city) and creating anonymous user identifiers (hashed IP + User Agent). If you don't forward the `X-Forwarded-For` or `X-Real-IP` header, all traffic will appear to come from your proxy server's IP.
+**IP Forwarding**: Rybbit uses IP addresses for geolocation (country/city) and creating anonymous user identifiers (hashed IP + User Agent). If you don't forward the `X-Real-IP` or `X-Forwarded-For` header, all traffic will appear to come from your proxy server's IP.
</Callout>
### Forwarded IP Headers
-If your proxy runs on infrastructure such as Cloudflare Workers, AWS CloudFront, Fastly, or another edge/CDN provider, make sure the proxy sets `X-Forwarded-For` or `X-Real-IP` to the original visitor IP. Rybbit reads these headers before the connecting edge IP, so this prevents traffic from being geolocated to the proxy or classified by the proxy's ASN.
+If your proxy runs on infrastructure such as Cloudflare Workers, AWS CloudFront, Fastly, or another edge/CDN provider, make sure the proxy sets `X-Real-IP` to the original visitor IP. Rybbit also falls back to `X-Forwarded-For`, but `X-Real-IP` is preferred because Cloudflare-fronted requests may include intermediary IPs in `X-Forwarded-For`.
**Cloudflare Worker example:**
diff --git a/docs/content/docs/proxy-guide/troubleshooting.mdx b/docs/content/docs/proxy-guide/troubleshooting.mdx
index e9eb46faf..369861e88 100644
--- a/docs/content/docs/proxy-guide/troubleshooting.mdx
+++ b/docs/content/docs/proxy-guide/troubleshooting.mdx
@@ -178,7 +178,7 @@ proxy_pass https://app.rybbit.io;
**Solutions:**
<Callout type="warn">
-**Critical**: The `X-Forwarded-For` and `X-Real-IP` headers must contain the original client IP for accurate geolocation and user identification.
+**Critical**: The `X-Real-IP` header should contain the original client IP for accurate geolocation and user identification. `X-Forwarded-For` is supported as a fallback, but may include intermediary edge IPs.
</Callout>
**Nginx:**
@@ -225,7 +225,7 @@ proxyHeaders.set('X-Real-IP', clientIp);
**Cause:** Rybbit is seeing the proxy IP instead of the original visitor IP. This is common when a first-party proxy is hosted on CDN or cloud infrastructure. Those networks use hosting/datacenter ASNs, so traffic can look like bot infrastructure if the visitor IP is not passed in a trusted way.
-Set `X-Forwarded-For` or `X-Real-IP` to the original visitor IP before forwarding the request to Rybbit. Rybbit reads those headers before the connecting edge IP.
+Set `X-Real-IP` to the original visitor IP before forwarding the request to Rybbit. Also setting `X-Forwarded-For` is fine, but `X-Real-IP` is the preferred header for first-party proxies.
**Cloudflare Workers:**
diff --git a/server/src/services/tracker/botBlocking/README.md b/server/src/services/tracker/botBlocking/README.md
index 19e528a9f..b922857aa 100644
--- a/server/src/services/tracker/botBlocking/README.md
+++ b/server/src/services/tracker/botBlocking/README.md
@@ -100,6 +100,6 @@ This catches obvious floods and fast crawlers, but it is local to a Node process
## Trust Boundaries
-Bot blocking assumes the resolved IP is meaningful. The tracker resolves IPs from `X-Forwarded-For`, then `X-Real-IP`, then `CF-Connecting-IP`, then the Fastify request IP. Public tracking requests ignore client-supplied `ip_address` and `user_agent`; those overrides are only honored for trusted server-side ingestion.
+Bot blocking assumes the resolved IP is meaningful. The tracker resolves IPs from `X-Real-IP`, then `CF-Connecting-IP`, then `X-Forwarded-For`, then the Fastify request IP. Public tracking requests ignore client-supplied `ip_address` and `user_agent`; those overrides are only honored for trusted server-side ingestion.
Client-supplied `_bs` and `_bsm` are useful inputs but are not secure proof.
diff --git a/server/src/utils.test.ts b/server/src/utils.test.ts
index c6a6190bf..ccbb8d2ac 100644
--- a/server/src/utils.test.ts
+++ b/server/src/utils.test.ts
@@ -7,27 +7,32 @@ function requestWithHeaders(headers: Record<string, string | string[]>, ip = "19
}
describe("getIpAddress", () => {
- it("uses the first X-Forwarded-For IP before Cloudflare's connecting IP", () => {
+ it("uses X-Real-IP before Cloudflare's connecting IP", () => {
const request = requestWithHeaders({
"cf-connecting-ip": "198.51.100.20",
"x-forwarded-for": "203.0.113.10, 198.51.100.20",
"x-real-ip": "192.0.2.10",
});
- expect(getIpAddress(request)).toBe("203.0.113.10");
+ expect(getIpAddress(request)).toBe("192.0.2.10");
});
- it("uses X-Real-IP before Cloudflare's connecting IP when X-Forwarded-For is missing", () => {
+ it("uses Cloudflare's connecting IP before X-Forwarded-For", () => {
const request = requestWithHeaders({
- "cf-connecting-ip": "198.51.100.20",
- "x-real-ip": "203.0.113.10",
+ "cf-connecting-ip": "203.0.113.10",
+ "x-forwarded-for": "198.51.100.20, 10.0.0.1",
});
expect(getIpAddress(request)).toBe("203.0.113.10");
});
- it("falls back to Cloudflare's connecting IP and then the request IP", () => {
- expect(getIpAddress(requestWithHeaders({ "cf-connecting-ip": "198.51.100.20" }))).toBe("198.51.100.20");
+ it("uses the first X-Forwarded-For IP when higher-priority headers are missing", () => {
+ expect(getIpAddress(requestWithHeaders({ "x-forwarded-for": "203.0.113.10, 198.51.100.20" }))).toBe(
+ "203.0.113.10"
+ );
+ });
+
+ it("falls back to the request IP", () => {
expect(getIpAddress(requestWithHeaders({}))).toBe("198.51.100.10");
});
});
diff --git a/server/src/utils.ts b/server/src/utils.ts
index 5820c005e..d4b557a56 100644
--- a/server/src/utils.ts
+++ b/server/src/utils.ts
@@ -239,7 +239,21 @@ export const normalizeOrigin = (input: string): string => {
// Helper function to get IP address
export const getIpAddress = (request: FastifyRequest): string => {
- // Priority 1: X-Forwarded-For - use the first IP, which should be the original client.
+ // Priority 1: X-Real-IP. First-party proxies can set this to the original
+ // visitor IP even when our Cloudflare edge sees the proxy's egress IP.
+ const realIp = request.headers["x-real-ip"];
+ if (realIp && typeof realIp === "string") {
+ return realIp.trim();
+ }
+
+ // Priority 2: Cloudflare header. In our Cloudflare-fronted direct path this
+ // is authoritative; X-Forwarded-For may contain intermediary edge IPs.
+ const cfConnectingIp = request.headers["cf-connecting-ip"];
+ if (cfConnectingIp && typeof cfConnectingIp === "string") {
+ return cfConnectingIp.trim();
+ }
+
+ // Priority 3: X-Forwarded-For - use the first IP, which should be the original client.
const forwardedFor = request.headers["x-forwarded-for"];
if (forwardedFor && typeof forwardedFor === "string") {
const ips = forwardedFor
@@ -247,22 +261,9 @@ export const getIpAddress = (request: FastifyRequest): string => {
.map(ip => ip.trim())
.filter(Boolean);
if (ips.length > 0) {
- // Always use the first IP - the original client
return ips[0];
}
}
- // Priority 2: X-Real-IP
- const realIp = request.headers["x-real-ip"];
- if (realIp && typeof realIp === "string") {
- return realIp.trim();
- }
-
- // Priority 3: Cloudflare header
- const cfConnectingIp = request.headers["cf-connecting-ip"];
- if (cfConnectingIp && typeof cfConnectingIp === "string") {
- return cfConnectingIp.trim();
- }
-
return request.ip;
};