Skip to content

v1.2.1

Latest
Latest

Choose a tag to compare

View all tags
@balramadan balramadan released this 01 Oct 06:40
v1.2.1
b5a21bd
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

🛡️ Release Notes - distlimit v1.2.1

Release Date: October 1, 2026
Tag: v1.2.1
Type: Patch Release (Security Patch & Middleware IP Extraction Hardening)

📌 Overview

distlimit version v1.2.1 is a critical security patch addressing IP spoofing vulnerabilities in the X-Forwarded-For header parsing logic across all supported middleware adapters (net/http, Gin, Fiber v3, Echo v4, Echo v5, and gRPC).

Prior to this patch, taking the leftmost element (parts[0]) of the X-Forwarded-For header allowed untrusted clients to bypass IP-based rate limiting by prepending spoofed IP addresses to the header. This release resolves the vulnerability by implementing a robust, RFC-compliant Rightmost Non-Trusted Proxy Traversal algorithm consolidated in internal/xff.

This patch introduces zero breaking changes to the public API surface.

🔒 Security Fix Details (CVE / CWE-345 Mitigation)

1. Rightmost Non-Trusted Proxy Traversal

  • The Issue: Standard reverse proxies (Nginx, AWS ALB, Cloudflare, HAProxy) append the actual incoming client IP to the right side of the X-Forwarded-For header. The leftmost entry is controlled by the external client. Selecting the leftmost element allowed attackers to evade per-IP rate limits by rotating arbitrary spoofed IPs.
  • The Fix: The algorithm now scans X-Forwarded-For in reverse order (right-to-left) using slices.Backward, returning the first IP address that does not match any configured trusted proxy IP or CIDR block.

2. IP Port Stripping & Malformed Entry Sanitization

  • Headers containing ports (e.g. 198.51.100.1:443 or [2001:db8::1]:8080) are automatically stripped and normalized before parsing.
  • Malformed strings, non-IP garbage, or injected payloads in header entries are safely rejected and skipped during chain traversal.
  • X-Real-IP and RemoteAddr fallbacks are strictly validated with net.ParseIP and verified against the trusted proxy list.

🏗️ Architectural Improvements

  • Consolidated internal/xff Package: Eliminated 6 redundant copies of isTrustedProxy and IP extraction logic across all adapter packages (middleware/nethttp, middleware/gin, middleware/fiber, middleware/echo, middleware/echov5, middleware/grpc).
  • Single Source of Truth: Any future proxy normalization or CIDR optimization is now centralized in one maintainable package.
  • Public API Stability: Exported ExtractClientIP and ExtractPeerIP signatures remain unchanged as lightweight adapters delegating to xff.ClientIP.

🧪 Verification & Quality Control

  • Comprehensive Matrix Testing: Added 12 dedicated test scenarios in internal/xff/xff_test.go covering:
    • Leftmost spoofed IP prevention (core security validation)
    • Multi-hop trusted proxy chains
    • IPv4 and IPv6 address with ports and brackets
    • Garbage and injection payload handling
    • Trusted proxy CIDR subnet matching
    • Fallbacks for direct connections and empty headers
  • Static Analysis & Data Race Verification:
    • go vet ./... executed cleanly with 0 issues.
    • Concurrency & race detector passed: 
      go test -v -race ./...

📦 Upgrade Instructions

To upgrade to v1.2.1:

go get github.com/balramadan/distlimit@v1.2.1

Note

Behavioral Note: Clients connecting behind trusted reverse proxies with multiple X-Forwarded-For entries will now be correctly keyed by their actual public IP rather than any prepended spoofed IP. This represents the intended security behavior.

Assets 2
Loading