rules

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package rules implements the merlon rule grammar (spec §5): structured, AND-ed matchers with bypass/deny/redirect/challenge/coraza/route/queue/score actions across four phases (score nudge is phase 4 — an enum label that evaluates *before* phases 1–3, see Rule.Phase). Deliberately not an expression language; machine-checkable and UI-form-friendly. All three late action families are live: route invokes the named worker (handlers/workerrouter.go), coraza runs the embedded WAF request-phase (handlers/waf.go), and queue grants a per-rule concurrency permit (app/queues.go, handlers/waf.go).

Rule and its sub-structs are the admin-API wire shape: their json tags are admin API JSON keys — FROZEN per docs/dev/style.md, never renamed or re-spelled; the mode, action-type and sensor_state strings are the same wire-visible enums on the value side.

Index

Constants

View Source
const ListNameGrammar = `^[a-z0-9][a-z0-9_-]{0,63}$`

ListNameGrammar is the textual form of the name grammar below. Exported because the refusal messages quoting it live in two packages (this one and adminapi's list lane): with the matcher compiled here and the message text spelled out in three places, a grammar change could ship a 400 that described a different rule than the one that fired (final-review Minor 6). The pattern is a frozen surface — docs/usage/{rules,admin-api}.md quote it verbatim — so regex and messages now read it from this one definition.

View Source
const SiteUnmatched = "unmatched host"

SiteUnmatched is the sentinel site key of Merlon's unmatched-traffic bucket (item 39, R-39-else): requests whose Host matches no configured site are rated and tallied in bot_rollups under this one honest key, so the denominator never silently excludes them. It is NOT a site — no CRUD door may store anything under it (see IsReservedSiteKey), and the WAF's unmatched arm is its only writer. The value doubles as the display label in /stats rows and the Grafana legend, rendered verbatim.

The value carries a SPACE, and the vhost hostname grammar refuses spaces (adminapi/vhosts.go validateVhostBody), so no configured site key can ever equal it and no Configured() hit can impersonate the bucket. It is also a fixed point of NormalizeSite (no port, no trailing dots, no brackets, already lowercase), so doors that fold first stay exact.

Variables

This section is empty.

Functions

func DetectWS

func DetectWS(r *http.Request) bool

DetectWS reports whether the request is a WebSocket upgrade. Two shapes: the h1 GET + `Upgrade: websocket` handshake (case-insensitive — this path also carries the deliberate h2/h3 GET-Upgrade spoof class, semantics unchanged since M1), and the RFC 8441 extended-CONNECT handshake (B9-T1 F1 gap): h2 CONNECT with the `:protocol` pseudo-header, h3 CONNECT where quic-go surfaces the protocol as r.Proto (ExtendedConnect defaults on). The EC half mirrors Caddy's own recognition so ws_upgrade rules see exactly the handshakes Caddy will proxy as WebSocket (reverseproxy.go:521-522).

func IsReservedSiteKey

func IsReservedSiteKey(key string) bool

IsReservedSiteKey reports whether key is the reserved sentinel. Exact match on the NORMALIZED form by design: every CRUD door runs the candidate through NormalizeSite BEFORE this check, so case and trailing-dot spellings ("Unmatched Host.") have already folded to the sentinel at the door — calling this on a raw spelling is a door-ordering bug, and hiding a second fold in here would break the single-normalizer law. No store lane calls it either — the cascade never consults the sentinel (its bot_rollups skip is structural: the plane is out of the rename list whatever the site is, pinned by literal in store/cascade_test.go). That is a CALL-SITE law, not an import-graph one: store/bridge.go imports rules for the wire types (the old parenthetical here claimed the import graph, and the import graph said otherwise — backlog 63.2 honesty fix).

func NormalizeSite

func NormalizeSite(v string) string

NormalizeSite canonicalizes a Host header or admin-supplied site path value into the single key form shared by every plane: port stripped, bracketed IPv6 literals unwrapped, case folded to lowercase. SQLite collates TEXT as BINARY and Rulesets keys are case-sensitive, so the control plane (rule CRUD) and the data plane (WAF default-site lookup) MUST funnel site keys through this function or lookups silently miss stored rules (M2 review finding C1: Host-case WAF bypass).

Item 39 (R-39-dot) amends the contract: ALL trailing dots are stripped, so a trailing-dot (fully-qualified) Host is the same site key as its bare spelling and the function stays idempotent — `foo..` → `foo`, and a lone `.` becomes `""`, which stays an honest miss. The strip order is pinned: port strip, dot strip, bracket unwrap, lowercase — order is pinned by `[::1].`, which must answer `::1` (trimming after the bracket unwrap would strand an unterminated `[::1`).

func ValidListName

func ValidListName(s string) bool

ValidListName reports whether s is a legal client_lists name (item 32) — the same workerNameRe grammar, exported so adminapi validates list names with a single source of truth (no second regex to drift).

Types

type Action

type Action struct {
	Type   string `json:"type"`
	Policy string `json:"policy,omitempty"` // challenge only: ""|"progressive" (spec §6)
	Status int    `json:"status,omitempty"` // deny default 403; redirect default 302; queue: 0⇒429 | 429 | 503
	URL    string `json:"url,omitempty"`    // required for redirect
	Worker string `json:"worker,omitempty"` // route only: per-site worker name
	Delta  int    `json:"delta,omitempty"`  // score only: nudge amount, non-zero and |delta| <= 19
	Reason string `json:"reason,omitempty"` // score only: free-form audit provenance, <= 200 bytes
	// Profile (B9-T6) selects a named coraza rule-set profile to run the
	// request through; "" runs the default engine. coraza-only: rejected
	// non-empty on every other action type. The name must match the frozen
	// pool grammar, but profile EXISTENCE is not validated here — profiles
	// live in settings, and an unknown/removed profile fails open at request
	// time exactly like a nil engine (handlers/waf.go case "coraza").
	Profile string `json:"profile,omitempty"`
	// queue only (B7-T6): capacity = concurrent permits (default 20),
	// max_wait_ms = wait budget for a permit (default 5000), max_waiters =
	// hard bound on parked arrivals (default 4×capacity, capped at 1000),
	// retry_after_s = Retry-After seconds on rejection (default 5 for 429;
	// a 503 rule omits the header unless set).
	Capacity    int `json:"capacity,omitempty"`
	MaxWaitMs   int `json:"max_wait_ms,omitempty"`
	MaxWaiters  int `json:"max_waiters,omitempty"`
	RetryAfterS int `json:"retry_after_s,omitempty"`
}

Action is one of bypass | deny | redirect | challenge | coraza | route | queue | score. Coraza (M5b) is phase-2 only: the request runs through the embedded Coraza WAF when it matches; B9-T6 adds the coraza-only Profile field (named rule-set profile, "" = default). Route is phase-3 only and names the worker to invoke (Worker field, ruling R4). Queue (B7-T6) is phase-2 only — a concurrency permit with bounded waiters (design §3); its four knobs are optional (zero = unset, defaults computed at use in app/queues.go + handlers/waf.go, never stored). Score (item 32, R-32) is phase-4 (nudge) only and type⇔phase both ways: Delta shifts the effective bot score (non-zero, |delta| ≤ 19) and Reason is free-form audit provenance for it.

type BotScoreCond

type BotScoreCond struct {
	Min int `json:"min"`
}

BotScoreCond matches requests whose computed bot_score >= Min.

type Compiled

type Compiled struct {
	Rule
	// contains filtered or unexported fields
}

Compiled is a validated rule with precompiled regexes/prefixes.

func Compile

func Compile(r Rule) (*Compiled, error)

Compile validates and precompiles a rule. Equivalent to CompileWith with no resolver: list-free rules compile exactly as before, while any rule with a client_lists condition errors — a reference nobody resolved must not boot.

func CompileWith

func CompileWith(r Rule, lists map[string][]netip.Prefix) (*Compiled, error)

CompileWith validates and precompiles, resolving client_lists against lists (map list name → canonical prefixes). A named list absent from the map is a compile ERROR: a dangling reference must never compile into a rule that silently means something else (ReplaceFromWire keep-old law does the rest). Resolution arrives as a plain map so this package stays store-free; the snapshot build (T3) owns producing it from the net_lists table.

func (*Compiled) Match

func (c *Compiled) Match(in MatchInput) bool

Match reports whether the input satisfies every present condition (AND).

type Counters

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

Counters accumulates per-rule match statistics in memory (M2: no SQLite rollup; restart resets them — accepted per spec §10 ephemeral state).

func NewCounters

func NewCounters() *Counters

NewCounters builds an empty counter set.

func (*Counters) IncAction

func (c *Counters) IncAction(id int64)

IncAction records an applied enforcement action for rule id.

func (*Counters) IncObserve

func (c *Counters) IncObserve(id int64)

IncObserve records a would-have-matched observation for rule id.

func (*Counters) Prune

func (c *Counters) Prune(id int64)

Prune drops all counters for a deleted rule id.

func (*Counters) Snapshot

func (c *Counters) Snapshot() []RuleCounts

Snapshot returns counters sorted by rule id.

type KVMatcher

type KVMatcher struct {
	Name  string `json:"name"`
	Regex string `json:"regex,omitempty"`
}

KVMatcher matches a header/cookie value by regex; empty Regex = presence check.

type MatchInput

type MatchInput struct {
	R           *http.Request
	BotScore    int // 0 when no rating handler ran
	IP          netip.Addr
	JA4         string   // lowercase JA4 string, "" when unknown
	JA4H        string   // lowercase JA4H string, "" when unknown
	JA4T        string   // lowercase JA4T string, "" when unknown
	JA4X        []string // per-element JA4X chain (internal/ja4x.Chain, chain order); nil when the lane is dark
	WSUpgrade   bool     // advisory hint; request header detection wins when present (effective WS = hint || DetectWS(R), ruling R11)
	SensorState string   // Result.SensorState; "" when trust not configured — never matches a sensor_state cond
	ASN         uint32   // origin ASN from feeds; 0 = unknown (asn cond never matches)
	Country     string   // lowercased ISO country from feeds; "" = unknown
}

MatchInput carries everything matchers need; the WAF handler fills it once.

type Matchers

type Matchers struct {
	Path         *PathMatcher  `json:"path,omitempty"`
	Methods      []string      `json:"methods,omitempty"`
	Header       *KVMatcher    `json:"header,omitempty"`
	Cookie       *KVMatcher    `json:"cookie,omitempty"`
	BotScore     *BotScoreCond `json:"bot_score,omitempty"`
	ClientCIDRs  []string      `json:"client_cidrs,omitempty"`
	ClientLists  []string      `json:"client_lists,omitempty"` // named network lists (item 32); resolved at compile via CompileWith — existence lives outside this package
	JA4Prefixes  []string      `json:"ja4_prefixes,omitempty"`
	JA4HPrefixes []string      `json:"ja4h_prefixes,omitempty"` // lowercase JA4H prefixes (MatchInput.JA4H; wired in T6)
	JA4TPrefixes []string      `json:"ja4t_prefixes,omitempty"` // lowercase JA4T prefixes (MatchInput.JA4T; wired in T6)
	JA4XPrefixes []string      `json:"ja4x_prefixes,omitempty"` // lowercase JA4X chain-element prefixes (MatchInput.JA4X, any element; M14-T4)
	ASNs         []uint32      `json:"asn,omitempty"`           // origin ASN set (feeds)
	Countries    []string      `json:"country,omitempty"`       // ISO 3166-1 alpha-2, case-insensitive
	SensorState  string        `json:"sensor_state,omitempty"`  // absent|valid|stale|replayed (spec §5 L3)
	WSUpgrade    *bool         `json:"ws_upgrade,omitempty"`    // true|false; negation landed in M5a (ruling R11)
}

Matchers is a conjunction of conditions; an absent condition passes. At least one condition must be present (no match-all rules).

type PathMatcher

type PathMatcher struct {
	Exact  string `json:"exact,omitempty"`
	Prefix string `json:"prefix,omitempty"`
	Regex  string `json:"regex,omitempty"`
}

PathMatcher matches the request path; its exact, prefix and regex variants are OR-ed within the condition.

type Rule

type Rule struct {
	ID       int64  `json:"id,omitempty"`
	Site     string `json:"site,omitempty"`
	Position int    `json:"position,omitempty"`
	// Phase is an ENUM LABEL, not an evaluation order: phase-4 nudge rules
	// are a pre-pass that runs BEFORE phases 1–3 (Snapshot.Nudge), so the
	// integer reads after route while evaluation does not (R-32).
	Phase    int      `json:"phase"` // 1 bypass, 2 enforce, 3 route, 4 nudge
	Name     string   `json:"name,omitempty"`
	Enabled  bool     `json:"enabled"`
	Mode     string   `json:"mode"` // "enforce" (default) | "observe"
	Matchers Matchers `json:"matchers"`
	Action   Action   `json:"action"`
	Version  int64    `json:"version,omitempty"`
}

Rule is the wire/storage shape of one rule.

func (Rule) ActionJSON

func (r Rule) ActionJSON() string

ActionJSON encodes the action sub-struct for storage.

func (Rule) MatchersJSON

func (r Rule) MatchersJSON() string

MatchersJSON encodes the matcher sub-struct for storage.

func (Rule) Validate

func (r Rule) Validate() error

Validate checks the rule against the grammar. Called at every write path (admin API) and again by Compile.

type RuleCounts

type RuleCounts struct {
	RuleID   int64  `json:"rule_id"`
	Observed uint64 `json:"observed"`
	Actions  uint64 `json:"actions"`
}

RuleCounts is one observe-counter row for the admin API.

type Rulesets

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

Rulesets holds per-site snapshots with atomic replacement.

func NewRulesets

func NewRulesets() *Rulesets

NewRulesets builds an empty container.

func (*Rulesets) Get

func (rs *Rulesets) Get(site string) *Snapshot

Get returns the current snapshot for site, or nil when never loaded.

func (*Rulesets) ReplaceFromWire

func (rs *Rulesets) ReplaceFromWire(site string, r []Rule) error

ReplaceFromWire compiles rs and atomically swaps in the new snapshot for site with a nil list resolver (behavior-identical delegate for existing callers). See ReplaceFromWireWith for the law.

func (*Rulesets) ReplaceFromWireWith

func (rs *Rulesets) ReplaceFromWireWith(site string, r []Rule, lists map[string][]netip.Prefix) error

ReplaceFromWireWith compiles rs — resolving every client_lists condition against lists (name → canonical prefixes, produced by the caller: rules stays store-free) — and atomically swaps in the new snapshot for site, bumping its generation. An empty rs clears the site's rules. The generation read, compile and swap all happen under the write lock so concurrent writers can never mint two snapshots sharing one generation.

func (*Rulesets) Sites

func (rs *Rulesets) Sites() []string

Sites lists loaded site names (sorted).

type Snapshot

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

Snapshot is an immutable compiled rule set for one site. Readers get the pointer; writers replace it wholesale (spec §5 atomic hot-swap), so an immutable snapshot is safe for concurrent readers.

func NewSnapshot

func NewSnapshot(rs []Rule) (*Snapshot, error)

NewSnapshot compiles rules into a snapshot; any compile error fails the whole build. Rules are ordered by (phase, position, id). It passes a nil list resolver: list-free rules compile as always, any client_lists rule fails — a reference nobody resolved must not boot.

func (*Snapshot) Evaluate

func (s *Snapshot) Evaluate(in MatchInput) (act *Compiled, observed []*Compiled)

Evaluate walks phases 1→2 only (route phase 3 is invisible to the WAF path, ruling R4; see Route; the nudge pre-pass is likewise invisible here — it lives in Nudge). Within each phase the first enabled matching rule wins that phase. An enforce-mode match acts immediately and stops evaluation (returned as act). An observe-mode match is appended to observed and evaluation continues with the next phase. Returns (nil, observed) when nothing enforces.

func (*Snapshot) Gen

func (s *Snapshot) Gen() int64

Gen returns the generation counter of this snapshot.

func (*Snapshot) Len

func (s *Snapshot) Len() int

Len returns the number of compiled rules.

func (*Snapshot) Nudge

func (s *Snapshot) Nudge(in MatchInput) (sum int, applied, shadow []*Compiled)

Nudge walks EVERY enabled phase-4 rule and returns the summed delta, the enforcing matches, and the observe-mode (shadow) matches. This walk is DELIBERATELY cumulative — every match contributes — deliberately inverting the house first-match-wins rule: "it's me −8" and "known scraper +6" must compose. Nudging is applied by the caller (handlers/waf.go), never here: the handler owns rating vs effective score.

func (*Snapshot) Route

func (s *Snapshot) Route(in MatchInput) (act *Compiled, observed []*Compiled)

Route returns the first matching phase-3 rule (worker routing, spec §5). Phase-4 nudges are invisible here too — the nudge pre-pass lives in Nudge. Disabled and non-matching rules are skipped; observe-mode matches join observed and iteration continues past them (unlike Evaluate, which takes only the first observe match per phase).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL