scanblock

README

Scan Block Traefik Plugin

Traefik plugin that blocks scanner IPs by counting 4xx status codes until a limit is hit.

Can also play games with scanners.

Config

// MinScanRequests defines the minimum 4xx responses to observe before
// blocking an IP.
MinScanRequests uint64

// MinTotalRequests defines the minimum requests to observe before blocking
// an IP.
MinTotalRequests uint64

// MinScanPercent defines the minimum percent of 4xx responses of total
// requests before blocking an IP.
MinScanPercent float64

// BlockPrivate defines if private IP ranges (RFC1918, RFC4193) should be
// blocked too.
BlockPrivate bool

// PlayGames defines if the the plugin should respond with random 4xx status
// codes or even kill the connection sometimes.
PlayGames bool

// BlockSeconds defines for how many seconds an IP should be blocked.
BlockSeconds int

// RememberSeconds defines for how many seconds information about an IP
// should be cached after it was last seen.
RememberSeconds int

// A list of IP prefixes to exclude from blocking.
ExcludePrefixes []netip.Prefix

// The list of HTTP status codes to exclude from tracking.
ExcludeStatusCodes []int

Documentation

Index

• Constants
• func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
• type Cache
  • func NewCache() *Cache
  • func (c *Cache) CleanEntries(maxAge time.Duration) (removedEntries int)
  • func (c *Cache) CreateEntry(key string) *CacheEntry
  • func (c *Cache) GetEntry(key string) *CacheEntry
• type CacheEntry
• type Config
  • func CreateConfig() *Config
• type ResponseWriter
  • func (rw *ResponseWriter) WriteHeader(code int)
• type ScanBlock
  • func (sb *ScanBlock) ServeHTTP(w http.ResponseWriter, r *http.Request)

Constants

const (
	DefaultMinScanRequests = 10
	DefaultMinScanPercent  = 25       // %
	DefaultBlockSeconds    = 600      // 10m
	DefaultRememberSeconds = 6 * 3600 // 6h
)

Default config values.

Functions

func New

func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

New created a new plugin.

Types

type Cache

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

Cache holds entries about remote IPs and their status.

func NewCache

func NewCache() *Cache

NewCache creates and returns a new cache.

func (*Cache) CleanEntries

func (c *Cache) CleanEntries(maxAge time.Duration) (removedEntries int)

CleanEntries removes all cache entries that weren't touched for at least maxAge. Only executes if cache was not recently cleaned. Write-locks the cache.

func (*Cache) CreateEntry

func (c *Cache) CreateEntry(key string) *CacheEntry

CreateEntry creates a new entry in the cache. Write-locks the cache.

func (*Cache) GetEntry

func (c *Cache) GetEntry(key string) *CacheEntry

GetEntry returns an entry from the cache. Read-locks the cache.

type CacheEntry

type CacheEntry struct {
	TotalRequests atomic.Uint64
	ScanRequests  atomic.Uint64
	FirstSeen     atomic.Int64
	LastSeen      atomic.Int64
	Blocking      atomic.Bool
}

CacheEntry holds status information about a remote IP.

type Config

type Config struct {
	// MinScanRequests defines the minimum 4xx responses to observe before
	// blocking an IP.
	MinScanRequests uint64

	// MinTotalRequests defines the minimum requests to observe before blocking
	// an IP.
	MinTotalRequests uint64

	// MinScanPercent defines the minimum percent of 4xx responses of total
	// requests before blocking an IP.
	MinScanPercent float64

	// BlockPrivate defines if private IP ranges (RFC1918, RFC4193) should be
	// blocked too.
	BlockPrivate bool

	// PlayGames defines if the the plugin should respond with random 4xx status
	// codes or even kill the connection sometimes.
	PlayGames bool

	// BlockSeconds defines for how many seconds an IP should be blocked.
	BlockSeconds int

	// RememberSeconds defines for how many seconds information about an IP
	// should be cached after it was last seen.
	RememberSeconds int

	// A list of IP prefixes to exclude from blocking.
	ExcludePrefixes []netip.Prefix

	// The list of HTTP status codes to exclude from tracking.
	ExcludeStatusCodes []int
}

Config is the plugin configuration.

func CreateConfig

func CreateConfig() *Config

CreateConfig creates the default plugin configuration.

type ResponseWriter

type ResponseWriter struct {
	http.ResponseWriter
	// contains filtered or unexported fields
}

ResponseWriter is used to wrap given response writers.

func (*ResponseWriter) WriteHeader

func (rw *ResponseWriter) WriteHeader(code int)

WriteHeader adds custom handling to the wrapped WriterHeader method.

type ScanBlock

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

ScanBlock is a scan blocking plugin.

func (*ScanBlock) ServeHTTP

func (sb *ScanBlock) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles a http request.