feat: integrate Cookie Guard BotD telemetry

Persist BotD verdict/kind/confidence/request_id in the public session table and propagate the cached verdict plus age back to HAProxy.

Document that match.botd.* rules run against the cached session snapshot so detections survive beyond Cookie Guard's 5-minute cache.

Author: Miguel Medinilla

README.md

@@ -20,6 +20,7 @@ Decision maintains an in‑memory "public" session entry keyed by a durable iden
 - `session.public.rate` (logged as `rate`): per‑second rate over the rolling window, computed as `recent_hits / rate_window_seconds`. For per‑minute, multiply by 60.
 - `session.public.idle_seconds`: time since this key last appeared.
 - `session.public.first_path` + `first_path_deep`: first path seen for the key and a boolean indicating whether it looks like a "deep" path.
+- `session.public.botd_*`: the most recent FingerprintJS BotD verdict (`verdict`, `kind`, `confidence`, `request_id`) plus `botd_age_seconds`, captured whenever Cookie Guard shares telemetry. Decision keeps this alongside the session so verdicts persist beyond Cookie Guard’s 5‑minute cache, and any `match.botd.*` condition reads this cached snapshot rather than requiring the live `cookieguard.*` vars to be present on the current request.
 
 Configuration knobs:
 
@@ -278,6 +279,10 @@ The tables below list the request/response variables exchanged between HAProxy a
 | `cookieguard_age` | Optional | `var(txn.cookieguard.age_seconds)` | Age of the verified token |
 | `cookieguard_level` | Optional | `var(txn.cookieguard.challenge_level)` | Challenge tier just issued (only set during challenge) |
 | `cookieguard_session` | Optional | `var(txn.cookieguard.session_hmac)` | Durable hb_v3 session hash (requires issue-token) |
+| `botd_verdict` | Optional | `var(txn.cookieguard.botd_verdict)` | Latest Fingerprint BotD verdict (`good`, `bad`, `suspect`). |
+| `botd_kind` | Optional | `var(txn.cookieguard.botd_kind)` (alias `var(txn.cookieguard.botd_tool)`) | BotD classification string describing the detected tool/kind of automation. |
+| `botd_confidence` | Optional | `var(txn.cookieguard.botd_confidence)` | BotD confidence score (`0`–`1`). |
+| `botd_request_id` | Optional | `var(txn.cookieguard.botd_request_id)` | Fingerprint BotD `requestId` for correlating detections. |
 | `session.public.key` *(response → request handoff)* | Optional | Resent by HAProxy if you capture it between calls | Keeps session continuity through restarts |
 | `res.hdrs` *(response message)* | Optional | Full response headers on `decide_response` | context.yml allowlist (special/public tables) |
 
@@ -298,8 +303,10 @@ Each output becomes `var(txn.decision.<name>)` because the SPOE agent uses `opti
 | `session.public.key`, `.req_count`, `.rate`, `.idle_seconds`, `.first_path`, `.first_path_deep`, `.recent_hits`, `.rate_window_seconds` | Inspect/limit session behaviour directly in HAProxy (e.g., `http-request deny if { var(txn.decision.session.public.req_count) gt 1000 }`). |
 | `session.public.suspicious_score` | Decision-managed score that accumulates via `session.suspicious.increment/reset`. Use it to gate ALTCHA re-challenges or hard denies once a threshold is reached. |
 | `session.public.suspicious_ignored` | `true` when the session is marked via `session.suspicious.ignore: true` (no further increments). Helpful for gating rules so trusted bots/networks are exempt. |
+| `session.public.botd_verdict`, `.botd_kind`, `.botd_confidence`, `.botd_request_id`, `.botd_age_seconds` | Last BotD verdict stored in Decision’s session tracker (age expresses seconds since telemetry was seen). Lets HAProxy/policy rules reuse detections even after Cookie Guard evicts its 5‑minute cache, and `match.botd.*` rules evaluate against this cached state. |
 | `session.special.role`, `.groups`, `.idle_seconds` | Trusted user hints (from context.yml). Skip challenges or grant bypass for known roles. |
 | `cookieguard.valid`, `.age_seconds`, `.challenge_level` | Mirror of Cookie Guard telemetry (validity/age/challenge mode). |
+| `cookieguard.botd_verdict`, `.botd_kind`, `.botd_confidence`, `.botd_request_id` | Mirror of Cookie Guard’s BotD verdict cache so HAProxy ACLs can reuse Decision’s normalized view (`cookieguard.botd_tool` aliases `.botd_kind`). |
 
 All outputs are optional except the ones your HAProxy logic relies on; use `-m bool`/`-m found` guards before acting on them. Defaults + fallback in `policy.yml` ensure the variables you care about are always present.
 
@@ -409,6 +416,11 @@ This section documents every supported field in `policy.yml` and how matches are
     - `valid`: boolean
     - `age_seconds`: numeric comparator map
     - `challenge_level`: array of levels (strings)
+  - `botd`: BotD verdict cache from Cookie Guard
+    - `verdict`: array of verdicts (`good`, `bad`, `suspect`, etc.)
+    - `kind`: array of automation tool labels (case-insensitive)
+    - `confidence`: numeric comparator map (matches `botd_confidence`)
+    - `request_id`: array of exact Fingerprint request IDs
 
 - Return map
   - `reason` (string): optional human‑readable reason. If omitted, the fallback reason applies (default `"default-policy"`).
@@ -429,7 +441,7 @@ Notes on session‑driven inputs
   - Suspicion score: `session.public.suspicious_score` reflects the accumulated score managed by Decision; use `session.suspicious.increment/reset` to mutate it.
   - Suspicion ignore flag: `session.public.suspicious_ignored` is `true` after a rule sets `session.suspicious.ignore: true`, preventing future increments for that session.
   - Special session (trusted profile): `session.special.role`, `session.special.groups`, `session.special.idle_seconds`.
-  - Cookie‑Guard: `cookieguard.valid` (bool), `cookieguard.age_seconds` (float), `cookieguard.challenge_level` (string).
+  - Cookie‑Guard: `cookieguard.valid` (bool), `cookieguard.age_seconds` (float), `cookieguard.challenge_level` (string), BotD verdict metadata (`cookieguard.botd_verdict`, `.botd_kind`/`.botd_tool`, `.botd_confidence`, `.botd_request_id`), and the session-cached copies under `session.public.botd_*`.
 Examples using session and Cookie‑Guard matchers
 ```yaml
 - name: bursty-client
@@ -457,6 +469,15 @@ Examples using session and Cookie‑Guard matchers
   return:
     reason: cg-fresh
 
+- name: botd-bad-high-confidence
+  match:
+    botd:
+      verdict: ["bad"]
+      confidence: { ge: 0.9 }
+  return:
+    deny: true
+    reason: botd-bad
+
 - name: allow-search-bots
   match:
     asn: [15169, 8075]
@@ -538,6 +559,10 @@ The policy engine consumes the following inputs (see `internal/policy/engine.go:
   - `CookieGuardValid` → `match.cookie_guard.valid`.
   - `CookieAgeSeconds` → `match.cookie_guard.age_seconds`.
   - `ChallengeLevel` → `match.cookie_guard.challenge_level`.
+  - `BotdVerdict` → `match.botd.verdict` (case-insensitive).
+  - `BotdKind` → `match.botd.kind` (case-insensitive; `botd_tool` alias is folded here).
+  - `BotdConfidence` → `match.botd.confidence`.
+  - `BotdRequestID` → `match.botd.request_id`.
 
 - Geo dependencies
   - `Country` and `ASN` require GeoIP DBs to be present (`--city-db`, `--asn-db`). When missing, matches on these fields never fire.

cmd/decision-spoa/main.go

@@ -461,6 +461,16 @@ func handleRequestMessage(args map[string]string, raw map[string]string, cfg pol
 	}
 	challengeLevel := strings.ToLower(strings.TrimSpace(args["cookieguard_level"]))
 	cookieSession := args["cookieguard_session"]
+	botdVerdict := strings.TrimSpace(args["botd_verdict"])
+	botdKind := strings.TrimSpace(args["botd_kind"])
+	if botdKind == "" {
+		botdKind = strings.TrimSpace(args["botd_tool"])
+	}
+	rawBotdConfidence := strings.TrimSpace(args["botd_confidence"])
+	botdConfidence := parseFloat(rawBotdConfidence)
+	botdConfidenceProvided := rawBotdConfidence != ""
+	botdRequestID := strings.TrimSpace(args["botd_request_id"])
+	hasBotdInput := botdVerdict != "" || botdKind != "" || botdRequestID != "" || botdConfidenceProvided
 
 	var publicSnapshot session.PublicSnapshot
 	var publicRate float64
@@ -484,14 +494,36 @@ func handleRequestMessage(args map[string]string, raw map[string]string, cfg pol
 		publicKey = trust.publicSessionKey(baseToken, ip, ua)
 		if publicKey != "" {
 			decisionSessionKeySourceTotal.WithLabelValues(keySource).Inc()
-			publicSnapshot = trust.public.Record(publicKey, path, now)
+			var botdTelemetry *session.BotdTelemetry
+			if hasBotdInput {
+				botdTelemetry = &session.BotdTelemetry{
+					Verdict:    botdVerdict,
+					Kind:       botdKind,
+					Confidence: botdConfidence,
+					RequestID:  botdRequestID,
+					SeenAt:     now,
+				}
+			}
+			publicSnapshot = trust.public.RecordWithBotd(publicKey, path, now, botdTelemetry)
 			if publicSnapshot.RecentWindowSec > 0 {
 				publicRate = float64(publicSnapshot.RecentHits) / publicSnapshot.RecentWindowSec
 			}
 			if !publicSnapshot.LastSeen.IsZero() {
 				publicIdle = now.Sub(publicSnapshot.LastSeen).Seconds()
 			}
 			firstPathDeep = pathLooksDeep(publicSnapshot.FirstPath)
+			if !hasBotdInput && !publicSnapshot.Botd.SeenAt.IsZero() {
+				botdVerdict = publicSnapshot.Botd.Verdict
+				if botdKind == "" {
+					botdKind = publicSnapshot.Botd.Kind
+				}
+				if !botdConfidenceProvided {
+					botdConfidence = publicSnapshot.Botd.Confidence
+				}
+				if botdRequestID == "" {
+					botdRequestID = publicSnapshot.Botd.RequestID
+				}
+			}
 		}
 	}
 
@@ -550,6 +582,10 @@ func handleRequestMessage(args map[string]string, raw map[string]string, cfg pol
 		CookieAgeSeconds:               cookieAgeSeconds,
 		ChallengeLevel:                 challengeLevel,
 		CookieGuardValid:               cookieGuardValid,
+		BotdVerdict:                    botdVerdict,
+		BotdKind:                       botdKind,
+		BotdConfidence:                 botdConfidence,
+		BotdRequestID:                  botdRequestID,
 	}
 
 	out := cfg.Evaluate(input, promRuleCounter{CounterVec: decisionRulesHitTotal}, metricsHostLabel)
@@ -610,6 +646,13 @@ func handleRequestMessage(args map[string]string, raw map[string]string, cfg pol
 		setResp(resp, "session.public.rate_window_seconds", publicSnapshot.RecentWindowSec)
 		setResp(resp, "session.public.suspicious_score", publicSnapshot.SuspiciousScore)
 		setResp(resp, "session.public.suspicious_ignored", publicSnapshot.SuspiciousIgnored)
+		if !publicSnapshot.Botd.SeenAt.IsZero() {
+			setResp(resp, "session.public.botd_verdict", publicSnapshot.Botd.Verdict)
+			setResp(resp, "session.public.botd_kind", publicSnapshot.Botd.Kind)
+			setResp(resp, "session.public.botd_confidence", publicSnapshot.Botd.Confidence)
+			setResp(resp, "session.public.botd_request_id", publicSnapshot.Botd.RequestID)
+			setResp(resp, "session.public.botd_age_seconds", now.Sub(publicSnapshot.Botd.SeenAt).Seconds())
+		}
 	}
 	if specialSnapshot.Key != "" {
 		setResp(resp, "session.special.role", specialSnapshot.Role)
@@ -619,6 +662,11 @@ func handleRequestMessage(args map[string]string, raw map[string]string, cfg pol
 	setResp(resp, "cookieguard.valid", cookieGuardValid)
 	setResp(resp, "cookieguard.age_seconds", cookieAgeSeconds)
 	setResp(resp, "cookieguard.challenge_level", challengeLevel)
+	setResp(resp, "cookieguard.botd_verdict", botdVerdict)
+	setResp(resp, "cookieguard.botd_kind", botdKind)
+	setResp(resp, "cookieguard.botd_tool", botdKind)
+	setResp(resp, "cookieguard.botd_confidence", botdConfidence)
+	setResp(resp, "cookieguard.botd_request_id", botdRequestID)
 
 	if cfg.Debug {
 		// Optional verbose line with raw inputs and snapshots
@@ -627,8 +675,9 @@ func handleRequestMessage(args map[string]string, raw map[string]string, cfg pol
 			entries := trusted.Entries()
 			hb2 := cookies["hb_v2"] != ""
 			hb3 := cookies["hb_v3"] != ""
-			log.Printf("policy-verbose: raw_input=%v fe=%s be=%s src=%s xff=%s ip=%v xff_used=%t xff_stripped=%d trusted_peer=%t trusted_entries=%v asn=%d c=%s m=%s host=%s path=%s query=%q sni=%s ja3=%s hb2=%t hb3=%t key_src=%s public={key=%s req=%d hits=%d rate=%.6f idle=%.3f first_path=%s deep=%t sus=%d ignore=%t} special={role=%s idle=%.3f groups=%s} reason=%s bucket=%s elapsed=%.6f ua=%q vars=%v",
+			log.Printf("policy-verbose: raw_input=%v fe=%s be=%s src=%s xff=%s ip=%v xff_used=%t xff_stripped=%d trusted_peer=%t trusted_entries=%v asn=%d c=%s m=%s host=%s path=%s query=%q sni=%s ja3=%s hb2=%t hb3=%t key_src=%s botd={verdict=%s kind=%s confidence=%.3f request_id=%s} public={key=%s req=%d hits=%d rate=%.6f idle=%.3f first_path=%s deep=%t sus=%d ignore=%t} special={role=%s idle=%.3f groups=%s} reason=%s bucket=%s elapsed=%.6f ua=%q vars=%v",
 				sortedRaw(raw), frontend, backend, src, xff, ip, xffUsed, strippedHops, pt, entries, asn, country, strings.ToUpper(method), host, truncatePath(path, 200), query, sni, ja3, hb2, hb3, keySource,
+				botdVerdict, botdKind, botdConfidence, botdRequestID,
 				publicSnapshot.Key, publicSnapshot.RequestCount, publicSnapshot.RecentHits, publicRate, publicIdle, publicSnapshot.FirstPath, firstPathDeep, publicSnapshot.SuspiciousScore, publicSnapshot.SuspiciousIgnored,
 				specialSnapshot.Role, specialIdle, strings.Join(specialSnapshot.Groups, ","), out.Reason, bucketLabel, elapsed, ua, resp)
 		}