rrl

Documentation

Overview

Package rrl implements high-performance, zero-allocation Response Rate Limiting (RRL) for authoritative DNS servers in accordance with BCP 140 specifications.

DNS over UDP is inherently susceptible to source IP spoofing, enabling Distributed Reflection and Amplification Denial of Service attacks against third-party victims, as well as Pseudo-Random Subdomain (PRSD / Water Torture) floods targeting authoritative zones. RRL protects both the DNS infrastructure and reflection victims by enforcing token bucket rate limits per client subnet prefix, response classification, and FQDN.

Index

• Constants
• type Action
  • func (a Action) String() string
• type Config
  • func DefaultConfig() Config
• type Limiter
  • func New(cfg Config) *Limiter
  • func (l *Limiter) Check(clientIP netip.Addr, domain string, rCode dns.RCode) Action

Constants

const (
	// DefaultResponsesPerSecond defines the token bucket capacity for successful (NOERROR) responses
	// allocated per second per client subnet prefix.
	DefaultResponsesPerSecond = 50

	// DefaultErrorsPerSecond defines the token bucket capacity for error and NXDOMAIN responses.
	// Error budgets are intentionally smaller to rapidly suppress PRSD attacks.
	DefaultErrorsPerSecond = 10

	// DefaultSlipRate defines the cadence at which rate-limited responses are returned with the
	// DNS TC (Truncated) bit set to prompt legitimate recursive resolvers to retry over TCP.
	DefaultSlipRate = 2

	// DefaultTableSize defines the total pre-allocated slot capacity across all memory shards.
	DefaultTableSize = 65536

	// DefaultIPv4Prefix defines the standard CIDR prefix length for IPv4 source aggregation (/24).
	DefaultIPv4Prefix = 24

	// DefaultIPv6Prefix defines the standard CIDR prefix length for IPv6 source aggregation (/56).
	DefaultIPv6Prefix = 56
)

Types

type Action

type Action uint8

Action defines the enforcement decision returned by the RRL engine per BCP 140.

const (
	// ActionAllow transmits the response normally to the client.
	ActionAllow Action = iota

	// ActionDrop drops the response silently to eliminate amplification bandwidth toward spoofed targets.
	ActionDrop

	// ActionSlip returns a response with the TC (Truncated) bit set, prompting legitimate resolvers
	// to retry over stateful TCP while dropping spoofed attacker traffic.
	ActionSlip
)

func (Action) String

func (a Action) String() string

String returns the canonical BCP 140 string representation of the action.

type Config

type Config struct {
	ResponsesPerSecond int
	ErrorsPerSecond    int
	SlipRate           int
	TableSize          int
	IPv4Prefix         int
	IPv6Prefix         int
}

Config defines the operational parameters for rate evaluation and subnet grouping.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the standard BCP 140 recommended configuration parameters.

type Limiter

type Limiter struct {
	// contains filtered or unexported fields
}

Limiter coordinates partitioned token buckets to mitigate DNS reflection and PRSD water-torture attacks. All operations are lock-striped across memory shards and execute with zero heap allocations.

func New

func New(cfg Config) *Limiter

New initializes an RRL Limiter with pre-allocated memory shards and validated configuration limits.

func (*Limiter) Check

func (l *Limiter) Check(clientIP netip.Addr, domain string, rCode dns.RCode) Action

Check evaluates an outbound DNS response against rate policies without heap allocations.