docs: add docs

Author: hoalongnatsu

config/config.yaml

@@ -197,7 +197,7 @@ agent:
 
   catalog:
     persist_interval: 30s
-    auto_promote_after: 50       # in detect mode, this many sightings = "known"
+    auto_promote_after: 100      # in detect mode, this many sightings = "known"
     # Spike detection: a known pattern is re-flagged when its tick-level
     # frequency suddenly exceeds the EWMA (Exponentially Weighted Moving Average) baseline by `spike_multiplier`.
     # Two safety floors keep noise out:

pkg/agent/brain_log.go

@@ -174,11 +174,15 @@ func (b *logBrain) Classify(obs core.Observation, mean, std float64, confident b
 	prevCount := postCount - tickFreq // recover the pre-fold count
 	prevVerdict := p.Verdict          // Upsert never mutates Verdict, so == pre-fold
 
+	// AutoPromoteAfter ≤ 0 disables count-based promotion entirely ("0 disables
+	// the promotion"): a pattern is never marked "known" by sighting count
+	// alone, so it keeps flowing to detect-AI however often it is seen. The 100
+	// default for an UNSET key is supplied by the embedded default_config layer
+	// (loaded as the base before user overrides), so an omitted key arrives here
+	// as 100 — only an explicit 0 (or negative) reaches the disabled branch. A
+	// pattern already promoted to "known" stays known regardless of threshold.
 	threshold := b.cat.AutoPromoteAfter
-	if threshold <= 0 {
-		threshold = 100
-	}
-	isKnown := prevVerdict == "known" || postCount >= threshold
+	isKnown := prevVerdict == "known" || (threshold > 0 && postCount >= threshold)
 	if isKnown {
 		if prevVerdict != "known" {
 			b.catalog.MarkKnown(obs.Key)

pkg/agent/brain_log_test.go

@@ -229,3 +229,135 @@ func TestLogBrain_ClassifyLifecycle(t *testing.T) {
 		t.Errorf("spike baseline = %v, want the pre-fold baseline > 0", v.Baseline)
 	}
 }
+
+// --- auto_promote_after threshold semantics (QA-028) --------------------------
+// Spike is left disabled (SpikeMultiplier == 0) throughout so it can never mask
+// the count-based promotion verdict under test.
+
+// (a) The shipped default (100, supplied by the embedded default_config layer
+// for an unset key) still promotes exactly at the 100th sighting.
+func TestLogBrain_AutoPromoteAfter_DefaultPromotesAt100(t *testing.T) {
+	b, c := newLogBrainForTest(t, config.AgentCatalogConfig{AutoPromoteAfter: 100})
+
+	for i := 0; i < 99; i++ {
+		classifyOnce(t, b, logObs("p", 1))
+	}
+	if got := c.Get("p").Count; got != 99 {
+		t.Fatalf("count = %d, want 99", got)
+	}
+	if c.Get("p").Verdict == "known" {
+		t.Fatalf("promoted early at count=99 (threshold 100)")
+	}
+
+	v := classifyOnce(t, b, logObs("p", 1)) // 100th sighting crosses the threshold
+	if got := c.Get("p").Count; got != 100 {
+		t.Fatalf("count = %d, want 100", got)
+	}
+	if v.Class != core.VerdictKnownPattern {
+		t.Fatalf("at-threshold verdict = %v, want known", v.Class)
+	}
+	if c.Get("p").Verdict != "known" {
+		t.Fatalf("catalog verdict = %q, want known (MarkKnown must fire at 100)", c.Get("p").Verdict)
+	}
+}
+
+// (b) A positive custom threshold promotes exactly at that count, not at 100.
+func TestLogBrain_AutoPromoteAfter_CustomThresholdPromotes(t *testing.T) {
+	b, c := newLogBrainForTest(t, config.AgentCatalogConfig{AutoPromoteAfter: 50})
+
+	for i := 0; i < 49; i++ {
+		classifyOnce(t, b, logObs("p", 1))
+	}
+	if c.Get("p").Verdict == "known" {
+		t.Fatalf("promoted before custom threshold 50 (count=%d)", c.Get("p").Count)
+	}
+
+	v := classifyOnce(t, b, logObs("p", 1)) // 50th sighting
+	if got := c.Get("p").Count; got != 50 {
+		t.Fatalf("count = %d, want 50", got)
+	}
+	if v.Class != core.VerdictKnownPattern {
+		t.Fatalf("at-custom-threshold verdict = %v, want known", v.Class)
+	}
+	if c.Get("p").Verdict != "known" {
+		t.Fatalf("catalog verdict = %q, want known at the custom threshold", c.Get("p").Verdict)
+	}
+}
+
+// (c) QA-028: auto_promote_after: 0 DISABLES count-based promotion — a pattern
+// is never marked "known" no matter how many times it is seen. Drives well past
+// the old 100 fallback to prove the explicit 0 is honoured, not re-mapped.
+func TestLogBrain_AutoPromoteAfter_ZeroDisablesPromotion(t *testing.T) {
+	cat := config.AgentCatalogConfig{
+		AutoPromoteAfter: 0, // documented: disables promotion
+		SpikeMultiplier:  0, // disable spike so it can't mask the verdict
+	}
+	b, c := newLogBrainForTest(t, cat)
+
+	var v core.TypedVerdict
+	for i := 0; i < 12; i++ {
+		v = classifyOnce(t, b, logObs("p", 10)) // 120 sightings, well past 100
+	}
+	if got := c.Get("p").Count; got != 120 {
+		t.Fatalf("count = %d, want 120", got)
+	}
+	if c.Get("p").Verdict == "known" {
+		t.Fatalf("auto_promote_after=0 promoted pattern to %q; 0 must disable promotion (QA-028)", c.Get("p").Verdict)
+	}
+	if v.Class != core.VerdictUnknown {
+		t.Fatalf("verdict at count=120 = %v, want unknown (0 disables promotion)", v.Class)
+	}
+}
+
+// (d) A negative threshold (any value ≤ 0) also disables promotion.
+func TestLogBrain_AutoPromoteAfter_NegativeDisablesPromotion(t *testing.T) {
+	cat := config.AgentCatalogConfig{
+		AutoPromoteAfter: -1,
+		SpikeMultiplier:  0,
+	}
+	b, c := newLogBrainForTest(t, cat)
+
+	var v core.TypedVerdict
+	for i := 0; i < 12; i++ {
+		v = classifyOnce(t, b, logObs("p", 10)) // 120 sightings
+	}
+	if c.Get("p").Verdict == "known" {
+		t.Fatalf("auto_promote_after=-1 promoted pattern to %q; any value ≤0 must disable promotion", c.Get("p").Verdict)
+	}
+	if v.Class != core.VerdictUnknown {
+		t.Fatalf("verdict = %v, want unknown (negative disables promotion)", v.Class)
+	}
+}
+
+// (e) An operator-labelled "known" pattern STAYS known even when count-based
+// promotion is disabled (threshold 0). This bites the `prevVerdict == "known"`
+// clause independently of the count clause: were the guard rewritten as
+// `threshold > 0 && (prevVerdict == "known" || postCount >= threshold)`, a
+// disabled threshold would silently un-suppress a hand-labelled pattern.
+func TestLogBrain_AutoPromoteAfter_AlreadyKnownStaysKnown(t *testing.T) {
+	cat := config.AgentCatalogConfig{
+		AutoPromoteAfter: 0, // count-based promotion disabled
+		SpikeMultiplier:  0, // disable spike so it can't mask the verdict
+	}
+	b, c := newLogBrainForTest(t, cat)
+
+	// Seed the pattern (stays Unknown — 0 disables count-based promotion), then
+	// label it known by hand as an operator would.
+	classifyOnce(t, b, logObs("p", 5))
+	if !c.MarkKnown("p") {
+		t.Fatalf("MarkKnown(p) did not mark the seeded pattern")
+	}
+	if c.Get("p").Verdict != "known" {
+		t.Fatalf("precondition: catalog verdict = %q, want known", c.Get("p").Verdict)
+	}
+
+	// Further sightings must keep it known — the prior "known" verdict wins even
+	// though the count threshold is disabled.
+	v := classifyOnce(t, b, logObs("p", 5))
+	if v.Class != core.VerdictKnownPattern {
+		t.Fatalf("already-known verdict = %v, want known (prior known must win with threshold 0)", v.Class)
+	}
+	if c.Get("p").Verdict != "known" {
+		t.Fatalf("catalog verdict = %q, want known (an already-known pattern must stay known)", c.Get("p").Verdict)
+	}
+}

pkg/agent/raw_leak_test.go

@@ -0,0 +1,126 @@
+package agent
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/VersusControl/versus-incident/pkg/agent/ai/detect"
+	"github.com/VersusControl/versus-incident/pkg/core"
+	"github.com/VersusControl/versus-incident/pkg/storage"
+)
+
+// rawOnlySecret is a sentinel that lives ONLY in Signal.Raw — never in the
+// redacted Message/Fields. No default redaction rule matches it, so ANY
+// appearance downstream is an unambiguous leak: it means a builder started
+// serializing Signal.Raw (the deliberately-unredacted original the worker
+// keeps for admin-only debug) into a prompt/log/persisted payload, exposing
+// the very secrets the redactor scrubs out of Message/Fields.
+//
+// These tests are the guard that a future snapshot / admin-dump /
+// enterprise-brain path cannot silently start emitting Signal.Raw. They
+// exercise the REAL builders (detect.BuildPrompt, ShadowLog, DetectLog) and
+// their real serializers, not a hand-rolled marshal.
+const rawOnlySecret = "RAW-ONLY-SENTINEL-DO-NOT-LEAK-42"
+
+// leakSignal returns a Signal in the exact post-redaction shape the worker
+// produces: Message/Fields carry no secret (already scrubbed), while Raw holds
+// the original secret-bearing document (left alone for admin debug).
+func leakSignal() core.Signal {
+	return core.Signal{
+		Source:  "es:prod",
+		Message: "service=api request failed id=<REDACTED:uuid>",
+		Fields: map[string]interface{}{
+			core.FieldService: "api",
+			core.FieldSignal:  "request failed",
+		},
+		Raw: map[string]interface{}{
+			"raw_line": "service=api request failed token=" + rawOnlySecret,
+			"headers":  map[string]interface{}{"authorization": "Bearer " + rawOnlySecret},
+		},
+	}
+}
+
+func TestSignalRaw_NeverLeaksIntoModelPrompt(t *testing.T) {
+	sig := leakSignal()
+	result := core.AgentResult{
+		Verdict:       core.VerdictUnknown,
+		PatternID:     "p1",
+		Template:      "service=api request failed id=<*>",
+		SampleSignals: []core.Signal{sig},
+		Frequency:     1,
+	}
+	// The worker feeds BuildPrompt the samples produced by sampleMessages,
+	// which reads .Message (redacted) — exercise that exact builder chain.
+	samples := sampleMessages(result.SampleSignals, 3)
+	system, user := detect.BuildPrompt(result, sig.Source, "api", samples)
+	if strings.Contains(system+user, rawOnlySecret) {
+		t.Fatalf("Signal.Raw leaked into the model prompt:\nsystem=%s\nuser=%s", system, user)
+	}
+}
+
+func TestSignalRaw_NeverLeaksIntoShadowLog(t *testing.T) {
+	sig := leakSignal()
+	store := storage.NewMemory()
+	sl, err := LoadShadowLog(store, 0)
+	if err != nil {
+		t.Fatalf("LoadShadowLog: %v", err)
+	}
+	// The worker records the redacted Message as the shadow sample.
+	sl.Record(sig.Source, "p1", "tmpl", sig.Message, "default", "unknown", 1)
+	if err := sl.Persist(); err != nil {
+		t.Fatalf("Persist: %v", err)
+	}
+	assertBlobHasNoRawSecret(t, store, "shadow")
+	// The in-memory snapshot the admin API serves must be clean too.
+	assertJSONHasNoRawSecret(t, "shadow.All", sl.All())
+}
+
+func TestSignalRaw_NeverLeaksIntoDetectLog(t *testing.T) {
+	sig := leakSignal()
+	store := storage.NewMemory()
+	dl, err := LoadDetectLog(store, 0)
+	if err != nil {
+		t.Fatalf("LoadDetectLog: %v", err)
+	}
+	// Build the DetectEvent exactly as emitDetect does: Samples come from
+	// sampleMessages (redacted Message), never from Raw.
+	evt := &DetectEvent{
+		Source:    sig.Source,
+		PatternID: "p1",
+		Template:  "tmpl",
+		Service:   "api",
+		Verdict:   "unknown",
+		Frequency: 1,
+		Samples:   sampleMessages([]core.Signal{sig}, 3),
+		Outcome:   "emitted",
+	}
+	dl.Record(evt)
+	if err := dl.Persist(); err != nil {
+		t.Fatalf("Persist: %v", err)
+	}
+	assertBlobHasNoRawSecret(t, store, "detect")
+	assertJSONHasNoRawSecret(t, "detect.All", dl.All())
+}
+
+func assertBlobHasNoRawSecret(t *testing.T, store storage.Provider, blob string) {
+	t.Helper()
+	data, err := store.ReadBlob(blob)
+	if err != nil {
+		t.Fatalf("ReadBlob(%s): %v", blob, err)
+	}
+	if strings.Contains(string(data), rawOnlySecret) {
+		t.Fatalf("Signal.Raw leaked into persisted %q blob:\n%s", blob, data)
+	}
+}
+
+func assertJSONHasNoRawSecret(t *testing.T, what string, v interface{}) {
+	t.Helper()
+	data, err := json.Marshal(v)
+	if err != nil {
+		t.Fatalf("marshal %s: %v", what, err)
+	}
+	if strings.Contains(string(data), rawOnlySecret) {
+		t.Fatalf("Signal.Raw leaked into %s payload:\n%s", what, data)
+	}
+}

pkg/agent/redact.go

@@ -25,28 +25,47 @@ type Redactor struct {
 type redactRule struct {
 	name string
 	re   *regexp.Regexp
+	// repl is an optional replacement template ($1 / ${1} capture refs). When
+	// empty the whole match is replaced by the fixed `<REDACTED:name>` token;
+	// when set it lets a rule preserve surrounding delimiters it had to match
+	// for context (e.g. basic_auth keeps the `://` and `@host` boundary).
+	repl string
 }
 
 // Default redaction patterns. Order matters — longer / more specific patterns
 // run first so an email isn't partially eaten by an IP rule.
 var defaultRedactors = []struct {
 	name    string
 	pattern string
+	repl    string // optional replacement template; empty ⇒ whole-match token
 }{
 	// JSON web tokens (header.payload.signature)
-	{"jwt", `eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+`},
+	{name: "jwt", pattern: `eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+`},
 	// AWS access keys (AKIA... / ASIA...)
-	{"aws_key", `\b(?:AKIA|ASIA)[0-9A-Z]{16}\b`},
+	{name: "aws_key", pattern: `\b(?:AKIA|ASIA)[0-9A-Z]{16}\b`},
+	// OpenAI-style API keys (sk-..., incl. project keys sk-proj-...). The
+	// {20,} floor keeps short "sk-foo" identifiers from matching.
+	{name: "openai_key", pattern: `\bsk-[A-Za-z0-9_\-]{20,}`},
+	// Slack tokens: bot (xoxb), user (xoxp), app (xoxa), refresh (xoxr),
+	// config (xoxc/xoxs), export (xoxe), legacy/cookie (xoxd). The letter
+	// class deliberately EXCLUDES "o" so a near-miss like "xoxo-…" stays
+	// untouched. The {10,} floor avoids matching a bare prefix.
+	{name: "slack_token", pattern: `\bxox[abcdeprs]-[A-Za-z0-9\-]{10,}`},
+	// Basic-auth credentials embedded in a URL (scheme://user:pass@host).
+	// The `://` and the trailing `@` are matched only for context and put back
+	// via the replacement template, so the credentials are fully scrubbed while
+	// the separators survive: `://user:pass@host` → `://<REDACTED:basic_auth>@host`.
+	{name: "basic_auth", pattern: `(://)[^/\s:@]+:[^/\s@]+(@)`, repl: `${1}<REDACTED:basic_auth>${2}`},
 	// Bearer / Authorization headers
-	{"bearer", `(?i)Authorization:\s*Bearer\s+[A-Za-z0-9._\-]+`},
+	{name: "bearer", pattern: `(?i)Authorization:\s*Bearer\s+[A-Za-z0-9._\-]+`},
 	// Generic password=... / token=...
-	{"password", `(?i)\b(?:password|passwd|pwd|secret|token|api[_-]?key)\s*[=:]\s*\S+`},
+	{name: "password", pattern: `(?i)\b(?:password|passwd|pwd|secret|token|api[_-]?key)\s*[=:]\s*\S+`},
 	// Email addresses
-	{"email", `[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}`},
+	{name: "email", pattern: `[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}`},
 	// UUIDs
-	{"uuid", `\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b`},
+	{name: "uuid", pattern: `\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b`},
 	// User-Agent strings
-	{"user_agent", `Mozilla/[0-9.]+\s*\([^)]*\)(?:[^"\n]*?(?:Gecko|Chrome|Safari|Firefox|Edg|Trident|OPR|MSIE)[^"\n]*)?`},
+	{name: "user_agent", pattern: `Mozilla/[0-9.]+\s*\([^)]*\)(?:[^"\n]*?(?:Gecko|Chrome|Safari|Firefox|Edg|Trident|OPR|MSIE)[^"\n]*)?`},
 }
 
 // IPv4/IPv6 redactor — opt-in because it removes a lot of useful context.
@@ -72,7 +91,7 @@ func NewRedactor(redactIPs bool, extra []string) (*Redactor, []error) {
 			errs = append(errs, fmt.Errorf("default redactor %q: %w", d.name, err))
 			continue
 		}
-		r.rules = append(r.rules, redactRule{name: d.name, re: re})
+		r.rules = append(r.rules, redactRule{name: d.name, re: re, repl: d.repl})
 	}
 	if redactIPs {
 		for _, d := range ipRedactors {
@@ -96,14 +115,18 @@ func NewRedactor(redactIPs bool, extra []string) (*Redactor, []error) {
 }
 
 // Scrub returns s with every match of every rule replaced by
-// `<REDACTED:<rule>>`.
+// `<REDACTED:<rule>>` (or the rule's own replacement template, when set, so a
+// rule like basic_auth can keep the delimiters it only matched for context).
 func (r *Redactor) Scrub(s string) string {
 	if r == nil || len(r.rules) == 0 || s == "" {
 		return s
 	}
 	for _, rule := range r.rules {
-		token := "<REDACTED:" + rule.name + ">"
-		s = rule.re.ReplaceAllString(s, token)
+		repl := rule.repl
+		if repl == "" {
+			repl = "<REDACTED:" + rule.name + ">"
+		}
+		s = rule.re.ReplaceAllString(s, repl)
 	}
 	return s
 }