Security Hardening & Anti-Spoofing

Rate limiters deployed at the edge or behind reverse proxies face common security threats, such as Header Forgery (IP Spoofing) and Redis Cluster Routing Collisions. distlimit builds defense mechanisms against both vectors natively.

---

🛡️ Anti-IP Spoofing Shield (WithTrustedProxies)

The Threat

When your Go application runs behind a CDN or Load Balancer (Cloudflare, Nginx, AWS ALB), the incoming socket RemoteAddr belongs to the proxy, not the end user. Naive rate limiters blindly trust HTTP headers like X-Forwarded-For or X-Real-IP.

An attacker can bypass IP-based rate limits by injecting fake headers:

GET /api/v1/resource HTTP/1.1
Host: api.example.com
X-Forwarded-For: 1.2.3.4, 5.6.7.8

If your server trusts these unverified headers, attackers can rotate the X-Forwarded-For value on every request to bypass quota enforcement completely.

---

The Solution: CIDR Proxy Verification

distlimit middleware adapters inspect X-Forwarded-For or X-Real-IP only if the immediate network peer (RemoteAddr) matches a trusted CIDR subnet.

Configuration Example

package main

import (
  "time"

  "github.com/balramadan/distlimit"
  "github.com/balramadan/distlimit/algorithm/tokenbucket"
  "github.com/balramadan/distlimit/driver/memory"
  distlimitnethttp "github.com/balramadan/distlimit/middleware/nethttp"
)

func main() {
  memDriver := memory.New(5 * time.Minute)
  limiter, _ := distlimit.New(
    memDriver,
    distlimit.WithLimit(100),
    distlimit.WithWindow(1*time.Minute),
    distlimit.WithAlgorithm(tokenbucket.New()),
  )

  // Configure Trusted Proxy Subnets (e.g. Cloudflare CIDRs, Internal VPC)
  middleware := distlimitnethttp.New(
    limiter,
    distlimitnethttp.WithTrustedProxies([]string{
      "10.0.0.0/8",      // Private VPC Subnet
      "172.16.0.0/12",    // Internal Docker Network
      "103.21.244.0/22", // Cloudflare IPv4 CIDR Block
    }),
  )
}

IP Resolution Flowchart

flowchart TD
    Req[Incoming Request] --> CheckProxy{Is RemoteAddr in Trusted Proxies?}
    
    CheckProxy -->|Yes| ParseHeader[Parse X-Forwarded-For / X-Real-IP]
    CheckProxy -->|No| Fallback[Use Raw RemoteAddr IP]
    
    ParseHeader --> Extract[Extract First Untrusted Client IP]
    Extract --> Limiter[Pass Real IP to Limiter]
    Fallback --> Limiter

---

🔐 Redis Cluster Safety via Hash Tags {}

The CROSSSLOT Vulnerability

In a Redis Cluster topology, data is sharded across 16,384 hash slots distributed over multiple master nodes. When executing multi-key atomic operations or Lua scripts in Redis Cluster, Redis requires all referenced keys to reside within the exact same hash slot.

Executing multi-key operations without hash tags causes Redis to throw a fatal error:

(error) CROSSSLOT Keys in request don't hash to the same slot

---

The Solution: Automatic Hash Tag Formatting

distlimit enforces Redis Hash Tags {} formatting on every key evaluated by the Redis driver:

$$\text{Formated Key} = \text{distlimit:}{ \text{key} }$$

How Hash Tags Work

When Redis encounters braces {} in a key name, it computes the CRC16 checksum using only the substring contained within {}:

• Key 1: distlimit:{user_123}:tokens $\rightarrow$ Slot calculated from user_123
• Key 2: distlimit:{user_123}:timestamp $\rightarrow$ Slot calculated from user_123

Because both keys share the same hash tag {user_123}, Redis guarantees both keys land on the same cluster node slot. This prevents CROSSSLOT errors completely while maintaining atomic Lua execution across distributed Redis clusters.