reflex

Documentation

Overview

Package reflex detects DNS amplification/reflection attacks.

This middleware focuses specifically on identifying spoofed source IPs used in DNS amplification attacks. It does NOT duplicate:

• Rate limiting (handled by ratelimit middleware)
• Blocklist/whitelist (handled by blocklist middleware)
• ANY query blocking (handled by resolver middleware)

Detection strategy:

1. Track amplification ratio per IP (response size / request size)
2. Identify IPs with suspicious query patterns (only high-amp types, no normal queries)
3. Score IPs based on reflection attack likelihood
4. Block or challenge IPs exceeding threshold

Index

• Variables
• type IPEntry
• type IPTracker
  • func NewIPTracker(maxSize int) *IPTracker
  • func (t *IPTracker) Cleanup()
  • func (t *IPTracker) Count() int
  • func (t *IPTracker) GetEntry(ip string) *IPEntry
  • func (t *IPTracker) RecordQuery(ip string, qtype uint16, ampFactor float64, reqSize int) float64
  • func (t *IPTracker) RecordResponse(ip string, reqSize, respSize int)
  • func (t *IPTracker) RecordTCP(ip string)
• type Reflex
  • func New(cfg *config.Config) *Reflex
  • func (r *Reflex) Close() error
  • func (r *Reflex) Name() string
  • func (r *Reflex) ServeDNS(ctx context.Context, ch *middleware.Chain)

Variables

var (
	// ReflexDetections counts suspected amplification attack sources.
	ReflexDetections = promauto.NewCounterVec(
		prometheus.CounterOpts{
			Name: "reflex_detections_total",
			Help: "Total suspected amplification attack detections by query type",
		},
		[]string{"qtype"},
	)

	// ReflexBlocked counts blocked queries.
	ReflexBlocked = promauto.NewCounter(
		prometheus.CounterOpts{
			Name: "reflex_blocked_total",
			Help: "Total queries blocked due to amplification attack suspicion",
		},
	)

	// ReflexTrackedIPs shows current tracked IP count.
	ReflexTrackedIPs = promauto.NewGauge(
		prometheus.GaugeOpts{
			Name: "reflex_tracked_ips",
			Help: "Number of IPs currently being tracked",
		},
	)
)

Types

type IPEntry

type IPEntry struct {
	FirstSeen time.Time
	LastSeen  time.Time

	// Query statistics
	TotalQueries   uint32
	HighAmpQueries uint32  // Queries for high-amplification types
	TotalAmpFactor float64 // Sum of amplification factors

	// Response statistics
	TotalRequestBytes  uint64
	TotalResponseBytes uint64

	// Reputation signals
	HasTCP     bool   // Has made TCP connection (proves real IP)
	HasNormalQ bool   // Has made normal queries (A, AAAA)
	QueryTypes uint16 // Bitmap of query types seen (first 16 types)
}

IPEntry tracks statistics for a single IP.

type IPTracker

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

IPTracker tracks IP behavior for amplification attack detection.

func NewIPTracker

func NewIPTracker(maxSize int) *IPTracker

NewIPTracker creates a new tracker.

func (*IPTracker) Cleanup

func (t *IPTracker) Cleanup()

Cleanup removes old entries.

func (*IPTracker) Count

func (t *IPTracker) Count() int

Count returns number of tracked IPs.

func (*IPTracker) GetEntry

func (t *IPTracker) GetEntry(ip string) *IPEntry

GetEntry returns entry for testing.

func (*IPTracker) RecordQuery

func (t *IPTracker) RecordQuery(ip string, qtype uint16, ampFactor float64, reqSize int) float64

RecordQuery records a UDP query and returns suspicion score (0.0-1.0).

func (*IPTracker) RecordResponse

func (t *IPTracker) RecordResponse(ip string, reqSize, respSize int)

RecordResponse records response size for amplification ratio tracking.

func (*IPTracker) RecordTCP

func (t *IPTracker) RecordTCP(ip string)

RecordTCP records that IP made a TCP connection (proves real IP).

type Reflex

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

Reflex detects DNS amplification/reflection attacks.

func New

func New(cfg *config.Config) *Reflex

New creates a new Reflex instance.

func (*Reflex) Close

func (r *Reflex) Close() error

Close shuts down the middleware.

func (*Reflex) Name

func (r *Reflex) Name() string

Name returns middleware name.

func (*Reflex) ServeDNS

func (r *Reflex) ServeDNS(ctx context.Context, ch *middleware.Chain)

ServeDNS processes queries for amplification attack detection.