Count IPv6 clients by network in the per-IP rate limits

What does this MR do and why?

Per-IP rate limits count each client address separately. IPv6 clients are usually given a whole network prefix, so this MR lets the per-IP rate limits count an IPv6 client by its network.

The MR adds:

  • The ipv6_rate_limit_prefix_length application setting, in the rate_limits JSONB column. The default is 64. Values must be between 48 and 128. 128 counts each address separately.
  • Gitlab::RateLimit::IpBucket, which masks an IPv6 address to its network and keeps IPv4 addresses (including IPv4-mapped IPv6 addresses) exact.
  • The rate_limiter_bucket_ipv6_by_prefix feature flag (beta, disabled by default).

When the flag is enabled, these limits count an IPv6 client by its network at ipv6_rate_limit_prefix_length:

Limit Change
Rack throttles that Labkit enforces, and plan rules The ip fact in Gitlab::RackAttack::LabkitRateLimit::ClassifiedRequest. For a cohort where Labkit only shadows, Rack::Attack keeps counting by the exact address.
Application rate limits The :ip characteristic in Gitlab::ApplicationRateLimiter::LabkitAdapter.identifier_for
Git authentication IP ban Gitlab::Auth::IpRateLimiter, on both the Rack::Attack::Allow2Ban and the Labkit path

IPv4 behavior does not change.

The exact address stays in the logs. The rack request facts carry it as a new remote_ip fact next to the counted ip, and the Rate_Limit_Block line logs remote_ip from it. counted_by.ip shows the network that the rule counted.

The ban allowlist (trusted_ip?) still matches the exact address, so an allowlist entry does not exempt other addresses in its network.

Rollout

Enable the flag as a boolean, not as a percentage. The flag uses Feature.current_request as its actor, so a percentage rollout would count some requests of one client by its exact address and others by its network. That splits the client across two counters and loosens every IP-keyed limit during the rollout.

Two more effects of a change:

  • Enabling or disabling the flag changes the keys for IPv6 clients. Their current Git authentication bans stop applying, and their counters start again from zero.
  • A change to ipv6_rate_limit_prefix_length reaches each process when its application settings cache expires (application_settings_cache_seconds, default 60 seconds). Until then, one client can be split across two keys.

References

Screenshots or screen recordings

Not applicable. This MR has no UI change.

How to set up and validate locally

  1. In the Rails console, enable the flag and check the bucket:

    Feature.enable(:rate_limiter_bucket_ipv6_by_prefix)
    
    Gitlab::RateLimit::IpBucket.for('2001:db8:1:2:3:4:5:6') # => "2001:db8:1:2::"
    Gitlab::RateLimit::IpBucket.for('1.2.3.4')              # => "1.2.3.4"
  2. Change the prefix length and check the bucket again:

    ApplicationSetting.current.update!(ipv6_rate_limit_prefix_length: 48)
    Gitlab::CurrentSettings.expire_current_application_settings
    
    Gitlab::RateLimit::IpBucket.for('2001:db8:1:2:3:4:5:6') # => "2001:db8:1::"
  3. Check that a prefix length outside 48..128 is rejected:

    ApplicationSetting.current.update(ipv6_rate_limit_prefix_length: 32) # => false
  4. Disable the flag and check that the exact address comes back:

    Feature.disable(:rate_limiter_bucket_ipv6_by_prefix)
    
    Gitlab::RateLimit::IpBucket.for('2001:db8:1:2:3:4:5:6') # => "2001:db8:1:2:3:4:5:6"
  5. Reset the setting:

    ApplicationSetting.current.update!(ipv6_rate_limit_prefix_length: 64)

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

🤖 Generated with Claude Code

Edited by Hardik Gala

Merge request reports

Loading
Loading