botguard

type Action string

type BatchSignal struct {
	IP      string   `json:"ip"`      // IP address
	Score   int      `json:"score"`   // Behavioral score (0-100)
	Reasons []string `json:"reasons"` // Why flagged (e.g., "404_flood", "wp_probe")
	Action  string   `json:"action"`  // "ban", "grey", "allow_demote", "allow_extend"
	TS      int64    `json:"ts"`      // Unix timestamp
}

type BotConfig struct {
	Name       string   // e.g. "GOOGLEBOT"
	Domains    []string // Suffix match domains (e.g. ["googlebot.com", "google.com"])
	VerifyMode string   // Verification method: "fcrdns"
	MaxConn    int      // Max concurrent connections allowed
	MaxRate    string   // nft rate string (e.g. "80/second")
	Burst      int      // nft burst value
}

type BotGuardStatusExtra struct {
	LoopInterval          string `json:"loop_interval"`
	PressureMode          bool   `json:"pressure_mode"`
	TrackedIPs            int64  `json:"tracked_ips"`
	TotalTicks            int64  `json:"total_ticks"`
	SuspectsFound         int64  `json:"suspects_found"`
	Classified            int64  `json:"classified"`
	AllowCount            int64  `json:"allow_count"`
	GreyCount             int64  `json:"grey_count"`
	BanCount              int64  `json:"ban_count"`
	EmergencyCount        int64  `json:"emergency_count"`
	LastTickDuration      string `json:"last_tick_duration"`
	VerifyEnqueued        int64  `json:"verify_enqueued"`
	VerifyCompleted       int64  `json:"verify_completed"`
	VerifyVerified        int64  `json:"verify_verified"`
	VerifyFailed          int64  `json:"verify_failed"`
	BatchSignalsProcessed int64  `json:"batch_signals_processed"`
}

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

type ClassifyResult struct {
	State   IPState      // Target state (allow, ban, grey, pending)
	Reason  string       // Why this decision was made
	BotName string       // Identified bot name (if any)
	Verify  VerifyStatus // FCrDNS verification result
}

type Config struct {
	// Module control
	Enabled bool

	// Classification loop intervals
	LoopInterval         time.Duration // Normal: 60s
	LoopPressureInterval time.Duration // Under pressure: 40s

	// Hysteresis thresholds (per IP connection count)
	TripConn      int // Start analyzing (default 200)
	ClearConn     int // Stop analyzing (default 150)
	EmergencyConn int // Immediate block (default 500)

	// Kernel suspect marking config (informational — actual values in nft rules)
	SuspectRate    string        // e.g. "30/second"
	SuspectBurst   int           // e.g. 60
	SuspectTimeout time.Duration // e.g. 5m

	// TTLs for classification sets
	AllowTTL     time.Duration // 24h initial
	BanTTL       time.Duration // 96h
	GreyTTL      time.Duration // 30m
	EmergencyTTL time.Duration // 30m
	PendingTTL   time.Duration // 60s

	// Auto-tuning
	AutoTune bool

	// Batch integration
	BatchSignalFile string
	BatchInterval   time.Duration

	// FCrDNS verification
	VerifyWorkers   int           // Max concurrent DNS workers (default 8)
	VerifyRateLimit int           // Max new lookups per second (default 10)
	VerifyTimeout   time.Duration // Timeout per DNS lookup (default 3s)
	VerifyCacheTTL  time.Duration // Positive cache TTL (default 24h)
	VerifyNegTTL    time.Duration // Negative cache TTL (default 1h)

	// Crawler config files
	AllowedCrawlersFile string
	DeniedCrawlersFile  string

	// Logging
	LogLevel     string
	LogDecisions bool
}

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

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

type FeatureFlags struct {
	// Scoring enables the v2 scoring engine.
	// When false, classic rate-based classification is used.
	Scoring bool

	// Profiles enables YAML profile loading.
	// When false, no profiles are loaded and path scoring is skipped.
	Profiles bool

	// Pressure enables pressure-based threshold adjustments.
	// When false, thresholds are static regardless of traffic.
	Pressure bool

	// Prefix enables /24 (v4) and /64 (v6) prefix tracking.
	// When false, only per-IP tracking is used.
	Prefix bool

	// PathScoring enables rule-based path scoring.
	// When false, only rate signals contribute to score.
	PathScoring bool

	// Distributed enables distributed attack detection signals.
	// When false, distributed patterns are not tracked.
	Distributed bool
}

type GroupConfig struct {
	Mode       GroupMode // How to handle rules in this group
	Multiplier float64   // Score multiplier (1.0 = normal)
}

type GroupMode string

type GuardStats struct {
	TickCount             int64         // Total classification ticks
	SuspectsFound         int64         // Total unique IPs found in suspect set
	Classified            int64         // Total IPs classified
	AllowCount            int64         // IPs classified as allow
	GreyCount             int64         // IPs classified as grey
	BanCount              int64         // IPs classified as ban
	EmergencyCount        int64         // IPs classified as emergency
	PendingCount          int64         // IPs currently pending
	TrackedIPs            int64         // Currently tracked IPs in state map
	LastTickDuration      time.Duration // Duration of last tick
	LastTickTime          time.Time     // When last tick completed
	PressureMode          bool          // Whether currently in pressure mode
	VerifyEnqueued        int64         // IPs enqueued for FCrDNS verification
	VerifyCompleted       int64         // FCrDNS verifications completed
	VerifyVerified        int64         // IPs that passed FCrDNS
	VerifyFailed          int64         // IPs that failed FCrDNS
	BatchSignalsProcessed int64         // Batch signals consumed from Clock 3
}

type IPRecord struct {
	IP           netip.Addr   // Parsed IP address (IPv4 or IPv6)
	State        IPState      // Current classification
	Score        int32        // Accumulated threat score
	FirstSeen    time.Time    // When first detected as suspect
	LastSeen     time.Time    // Last time seen in suspect set
	ExpiresAt    time.Time    // When current state expires
	HitCount     int64        // Number of times seen in suspect set
	Reasons      []string     // Why this IP was flagged (for logging)
	BotName      string       // Identified bot name (empty if unknown)
	VerifiedAt   time.Time    // When FCrDNS verification completed (zero if not verified)
	VerifyStatus VerifyStatus // Result of FCrDNS verification
}

type IPScore struct {
	IP             netip.Addr        // IP address
	TotalScore     int               // Current accumulated score
	RuleHits       map[string]int    // Count of hits per rule ID
	GroupScores    map[RuleGroup]int // Score contribution per group
	Signals        []Signal          // Recent signals (bounded buffer)
	State          IPState           // Current classification state
	FirstSeen      time.Time         // When first observed
	LastSeen       time.Time         // Last activity time
	WindowStart    time.Time         // Start of current scoring window
	ExpiresAt      time.Time         // When score expires (decay complete)
	HighWaterMark  int               // Peak score in current window
	StateHeldUntil time.Time         // Minimum time to hold current state
}

type IPState int

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

type MatchTargetType string

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

type PressureConfig struct {
	// Enabled controls whether pressure adjustments are active.
	Enabled bool

	// ElevatedRPS is the requests-per-second threshold for elevated pressure.
	ElevatedRPS int

	// CriticalRPS is the requests-per-second threshold for critical pressure.
	CriticalRPS int

	// Multiplier adjusts thresholds during elevated pressure.
	// Example: 1.5 makes thresholds 50% stricter.
	Multiplier float64
}

type PressureLevel int

type Rule struct {
	ID          string    `yaml:"id"`           // Unique rule identifier
	Profile     string    `yaml:"profile"`      // Which profile owns this rule
	Group       RuleGroup `yaml:"group"`        // Protection domain
	Pattern     string    `yaml:"pattern"`      // Regex pattern to match
	MatchTarget string    `yaml:"match_target"` // raw_target/normalized_path/decoded_path/query_string
	Methods     []string  `yaml:"methods"`      // HTTP methods (empty = all)
	StatusCodes []int     `yaml:"status_codes"` // Response codes to match (empty = all)
	Score       int       `yaml:"score"`        // Base score for this rule
	RateLimit   string    `yaml:"rate_limit"`   // nft rate string (e.g., "10/minute")
	Burst       int       `yaml:"burst"`        // nft burst value
	Action      Action    `yaml:"action"`       // What to do on match
	Exempt      bool      `yaml:"exempt"`       // If true, exempts from further scoring
	Description string    `yaml:"description"`  // Human-readable description
}

type RuleGroup string

type ScoreDecay struct {
	// Window is the scoring window duration.
	// Scores older than this are fully decayed.
	Window time.Duration

	// DecayRate is the per-tick decay multiplier (0.0-1.0).
	// Example: 0.1 means 10% decay per tick.
	DecayRate float64

	// HighSeverityHoldTime prevents decay for high-severity events.
	// If an IP hit a high-severity rule, decay is paused for this duration.
	HighSeverityHoldTime time.Duration

	// MinimumStateHoldTime prevents rapid state oscillation.
	// IP must stay in a state for at least this long before transitioning.
	MinimumStateHoldTime time.Duration

	// FloorScore is the minimum score after decay.
	// Prevents full decay for IPs with recent activity.
	FloorScore int
}

type ScoreThresholds struct {
	// Suspect is the score at which an IP becomes a suspect.
	// Below this, IP is UNKNOWN.
	Suspect int

	// Grey is the score at which an IP is throttled.
	Grey int

	// Ban is the score at which an IP is banned.
	Ban int

	// Emergency is the score at which an IP is emergency-blocked.
	Emergency int
}

type ScoringResult struct {
	IP        netip.Addr  // IP that was evaluated
	OldScore  int         // Score before this evaluation
	NewScore  int         // Score after this evaluation
	OldState  IPState     // State before this evaluation
	NewState  IPState     // State after this evaluation
	Changed   bool        // Whether state changed
	TopRules  []string    // Top contributing rule IDs
	TopGroups []RuleGroup // Top contributing groups
	Reason    string      // Human-readable reason for decision
}

type Signal struct {
	Type      SignalType     // Detection mechanism
	IP        netip.Addr     // Source IP address
	Score     int            // Score contribution from this signal
	Rule      *Rule          // Rule that triggered this signal (if path-based)
	Timestamp time.Time      // When signal was generated
	Metadata  map[string]any // Additional context (path, method, status, etc.)
}

type SignalType string

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

type V2Config struct {
	Features       FeatureFlags
	Thresholds     ScoreThresholds
	Decay          ScoreDecay
	Pressure       PressureConfig
	Groups         map[RuleGroup]GroupConfig
	ProfilesDir    string
	ActiveProfiles []string
}

type VerifyResult struct {
	IP       netip.Addr   // The IP that was verified
	Status   VerifyStatus // Verification outcome
	BotName  string       // Matched bot name (empty if not matched)
	Hostname string       // Reverse DNS hostname (empty if lookup failed)
}

type VerifyStatus int