diff --git a/changelog.d/added-session-taint-observe-only.md b/changelog.d/added-session-taint-observe-only.md new file mode 100644 index 0000000000..d05ea7887c --- /dev/null +++ b/changelog.d/added-session-taint-observe-only.md @@ -0,0 +1 @@ +- New opt-in `session_taint` recorder, the observe-only first slice of session taint ([#18987](https://github.com/hivecommons/hive/issues/18987)). A pattern scan checks each outgoing message alone, so it cannot see that an agent earlier read something it should not repeat in a wider audience; this adds the memory half of the answer, as a measurement only. With `session_taint.enabled: true` the hive keeps a bounded in-memory record of the coarse labels each agent session has accrued (a canary hit sets `secret`) and, when that session later asks the issue, comment, PR or review relay to write, logs and audits which rule would have held the write (`session_taint_label` and `session_taint_would_act` audit entries, plus per-rule counters). It never blocks, holds, restricts or changes any request or action, stores labels, counts and ids only (no credential or content), takes effect at restart, starts every session clean after a restart, and does nothing at all when the key is absent. `max_sessions`, `max_labels_per_session` and `max_decisions` bound the store. Enforcement is a later, separately decided phase; see `docs/design/session-taint.md` and `docs/security-model.md`. diff --git a/src/cmd/hive/boot.go b/src/cmd/hive/boot.go index f8c0976c45..813fdbc5f4 100644 --- a/src/cmd/hive/boot.go +++ b/src/cmd/hive/boot.go @@ -10,6 +10,7 @@ import ( "github.com/hivecommons/hive/crux" "github.com/hivecommons/hive/crux/proxy" cruxruntime "github.com/hivecommons/hive/crux/runtime" + "github.com/hivecommons/hive/crux/sessiontaint" "github.com/hivecommons/hive/crux/toolapprove" "github.com/hivecommons/hive/crux/trajectory" "github.com/hivecommons/hive/crux/watchdog" @@ -160,6 +161,8 @@ type boot struct { dashSrv *dashboard.Server writeback *writeback.Gate writebackOnce sync.Once + sessionTaintOnce sync.Once + sessionTaint *sessiontaint.Observer beadStores map[string]*beads.Store beadStoreLoadFailures int tokenCollector *tokens.Collector diff --git a/src/cmd/hive/github_client_config.go b/src/cmd/hive/github_client_config.go index b8b68ecba2..ec324ca684 100644 --- a/src/cmd/hive/github_client_config.go +++ b/src/cmd/hive/github_client_config.go @@ -474,12 +474,15 @@ func (b *boot) applyGitHubClientDashboardHooks(client *github.Client) { }) client.SetAgentActionHook(func(a github.AgentAction) { kickOutcomeAgentAction(kickOutcomesFor(b.cfg, b.logger), a) }) client.SetCanaryScanner(b.cfg.Ioscan.IsEnabled() && b.cfg.Ioscan.CanariesEnabled(), b.cfg.Ioscan.FailClosedAtLevel(b.cfg.ACMMLevelOrZero()), ioscan.DefaultCanaries, b.handleCanaryLeak) + // Observe-only session taint (#18987, phase 0): nil unless enabled. + client.SetSessionTaint(b.sessionTaintObserver()) } // handleCanaryLeak records an ioscan canary leak on the audit log and as a // critical advisory bead for the leaking agent. Shared by the GitHub client // and the GitHub proxy scanners. func (b *boot) handleCanaryLeak(leak ioscan.CanaryLeak) { + b.recordCanaryTaint(leak) detail := fmt.Sprintf("rule=%s, agent=%s, source=%s", ioscan.CanaryLeakRule, leak.Agent, leak.Source) b.dashSrv.AuditLog(leak.Agent, "ioscan_canary_leak", detail, leak.Agent) if store, ok := b.beadStores[leak.Agent]; ok && store != nil { diff --git a/src/cmd/hive/session_taint_wire.go b/src/cmd/hive/session_taint_wire.go new file mode 100644 index 0000000000..f24b44f0e0 --- /dev/null +++ b/src/cmd/hive/session_taint_wire.go @@ -0,0 +1,50 @@ +package main + +import ( + "github.com/hivecommons/hive/crux/sessiontaint" + "github.com/hivecommons/hive/pkg/ioscan" +) + +// canaryTaintOrigin is the origin recorded on the `secret` label a canary hit +// sets. It is the logscrub category name of the planted marker, never the +// token itself. +const canaryTaintOrigin = "hive-canary" + +// sessionTaintObserver returns the process-wide observe-only session taint +// observer (#18987, phase 0), building it on first use. It is nil unless +// `session_taint.enabled` is true, and every sessiontaint method is a no-op on +// nil, so a hive that sets nothing records nothing. The observer is shared by +// every GitHub client rebuild, so labels survive a credential re-delivery; a +// config change takes effect at the next restart. +func (b *boot) sessionTaintObserver() *sessiontaint.Observer { + b.sessionTaintOnce.Do(func() { + if b.cfg == nil { + return + } + cfg := b.cfg.SessionTaint + b.sessionTaint = sessiontaint.New(sessiontaint.Options{ + Enabled: cfg.Enabled, + MaxSessions: cfg.MaxSessionsOrDefault(), + MaxLabelsPerSession: cfg.MaxLabelsPerSessionOrDefault(), + MaxDecisions: cfg.MaxDecisionsOrDefault(), + Logger: b.logger, + Audit: b.sessionTaintAudit, + }) + }) + return b.sessionTaint +} + +// sessionTaintAudit writes one observer entry to the audit log. The detail +// carries labels and ids only. +func (b *boot) sessionTaintAudit(agent, action, detail string) { + if b.dashSrv == nil { + return + } + b.dashSrv.AuditLog(agent, action, detail, agent) +} + +// recordCanaryTaint is source S3: a canary hit means the agent whose token it +// is has been exposed to a secret-shaped marker. Observe only. +func (b *boot) recordCanaryTaint(leak ioscan.CanaryLeak) { + b.sessionTaintObserver().RecordLabel(leak.Agent, sessiontaint.LabelSecret, canaryTaintOrigin, sessiontaint.SourceCanaryHit) +} diff --git a/src/cmd/hive/session_taint_wire_test.go b/src/cmd/hive/session_taint_wire_test.go new file mode 100644 index 0000000000..60d616d1bd --- /dev/null +++ b/src/cmd/hive/session_taint_wire_test.go @@ -0,0 +1,54 @@ +package main + +import ( + "log/slog" + "testing" + + "github.com/hivecommons/hive/crux/sessiontaint" + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/ioscan" +) + +func TestSessionTaintOffByDefaultRecordsNothing(t *testing.T) { + b := &boot{cfg: &config.Config{}, logger: slog.Default()} + if b.sessionTaintObserver() != nil { + t.Fatal("session taint must be off unless session_taint.enabled is set") + } + // A canary hit with the feature off is a no-op. + b.recordCanaryTaint(ioscan.CanaryLeak{Agent: "agent-a", Source: "test"}) + if got := b.sessionTaintObserver().Labels("agent-a"); got != nil { + t.Errorf("labels = %v, want none", got) + } +} + +func TestSessionTaintCanaryHitSetsSecretLabel(t *testing.T) { + cfg := &config.Config{} + cfg.SessionTaint.Enabled = true + b := &boot{cfg: cfg, logger: slog.Default()} + obs := b.sessionTaintObserver() + if obs == nil { + t.Fatal("expected an observer when enabled") + } + if b.sessionTaintObserver() != obs { + t.Error("the observer must be built once and shared") + } + // The token itself is never passed on or stored. + b.recordCanaryTaint(ioscan.CanaryLeak{Agent: "agent-a", Token: "HIVE-CANARY-synthetic", Source: "hive-comment:o/r"}) + labels := obs.Labels("agent-a") + if len(labels) != 1 { + t.Fatalf("labels = %v, want one", labels) + } + if l := labels[0]; l.Label != sessiontaint.LabelSecret || l.Origin != canaryTaintOrigin || l.Source != sessiontaint.SourceCanaryHit { + t.Errorf("label = %+v", l) + } +} + +// The config defaults and the observer's own bounds are the same numbers, so +// `enabled: true` alone gives the documented limits. +func TestSessionTaintConfigDefaultsMatchObserver(t *testing.T) { + if config.DefaultSessionTaintMaxSessions != sessiontaint.DefaultMaxSessions || + config.DefaultSessionTaintMaxLabelsPerSession != sessiontaint.DefaultMaxLabelsPerSession || + config.DefaultSessionTaintMaxDecisions != sessiontaint.DefaultMaxDecisions { + t.Fatal("pkg/config defaults drifted from crux/sessiontaint defaults") + } +} diff --git a/src/crux/sessiontaint/observer.go b/src/crux/sessiontaint/observer.go new file mode 100644 index 0000000000..6c3cf664d6 --- /dev/null +++ b/src/crux/sessiontaint/observer.go @@ -0,0 +1,427 @@ +package sessiontaint + +import ( + "fmt" + "log/slog" + "strings" + "sync" + "time" +) + +// Audit action names the observer reports through Options.Audit. Snake_case to +// match the audit log's existing vocabulary. +const ( + // AuditLabelSet is written once per (session, label, origin). + AuditLabelSet = "session_taint_label" + // AuditWouldAct is written once per distinct would-act decision per + // session (rule, sink kind, destination), not once per request. + AuditWouldAct = "session_taint_would_act" +) + +const ( + // maxFieldLen bounds every identifier the observer stores or logs. + maxFieldLen = 128 + // invalidField replaces an identifier that fails sanitisation, so + // free-form text can never be smuggled into the store, the log or the + // audit trail through an origin, source or agent name. + invalidField = "invalid" + // maxCategoryLen bounds a secret label's origin, which must be a + // category slug (letters and hyphens), so a credential value, which + // carries digits, upper case or underscores and is longer, is refused as + // an origin and stored as invalidField instead. + maxCategoryLen = 40 + // unspecifiedOrigin is the origin recorded when a caller gives none. + unspecifiedOrigin = "unspecified" + // modeObserve is the only mode this phase has; it is reported in Stats, + // the log and the audit detail so a reader cannot mistake it for + // enforcement. + modeObserve = "observe" +) + +// Options configures an Observer. The zero value of every bound means its +// default. +type Options struct { + // Enabled gates the whole feature. New returns nil when it is false, and + // every Observer method is a no-op on nil, so a hive that sets nothing + // records nothing and runs byte-for-byte as before. + Enabled bool + // MaxSessions, MaxLabelsPerSession and MaxDecisions override the default + // bounds when positive. + MaxSessions int + MaxLabelsPerSession int + MaxDecisions int + // Logger receives one line per new label and per new would-act decision. + // Nil means no log lines; counters and the store still work. + Logger *slog.Logger + // Audit, when set, receives the AuditLabelSet and AuditWouldAct entries. + // The detail carries ids and labels only. It must not block. + Audit func(agent, action, detail string) + // Now is the clock; nil means time.Now. + Now func() time.Time +} + +// Decision is one recorded would-act result. It names the rule, the label and +// ids; it carries no content. +type Decision struct { + At time.Time + Agent string + Rule string + Verdict Verdict + Sink SinkKind + DestRepo string + Label Label + Origin string +} + +// Stats is a point-in-time copy of the observer's counters and recent +// decisions, for tests and for the read-only API a later phase adds. +type Stats struct { + Mode string + Sessions int + Labels int + SessionsEvicted uint64 + LabelsRecorded uint64 + LabelsDropped uint64 + SinksObserved uint64 + SinksClean uint64 + Panics uint64 + // WouldAct counts would-act findings per rule id, every request counted. + WouldAct map[string]uint64 + // Recent is the bounded ring of the latest would-act decisions, oldest + // first. + Recent []Decision +} + +// Observer records labels and would-be verdicts. It is observe-only: no +// method returns a verdict or an error, so nothing the host does can depend +// on it, and it holds no reference to any request. +type Observer struct { + opts Options + store *store + + mu sync.Mutex + labelsRecorded uint64 + sinksObserved uint64 + sinksClean uint64 + panics uint64 + wouldAct map[string]uint64 + ring []Decision + ringStart int +} + +// New builds an Observer, or nil when opts.Enabled is false. +func New(opts Options) *Observer { + if !opts.Enabled { + return nil + } + if opts.MaxSessions <= 0 { + opts.MaxSessions = DefaultMaxSessions + } + if opts.MaxLabelsPerSession <= 0 { + opts.MaxLabelsPerSession = DefaultMaxLabelsPerSession + } + if opts.MaxDecisions <= 0 { + opts.MaxDecisions = DefaultMaxDecisions + } + if opts.Now == nil { + opts.Now = time.Now + } + return &Observer{ + opts: opts, + store: newStore(opts.MaxSessions, opts.MaxLabelsPerSession), + wouldAct: make(map[string]uint64), + } +} + +// RecordLabel notes that the hive observed something in the agent's session. +// An empty agent is an unattributed caller and is not recorded (design: +// failure table). Safe on a nil Observer. +func (o *Observer) RecordLabel(agent string, label Label, origin string, source Source) { + if o == nil { + return + } + defer o.recoverQuiet() + agent = cleanField(agent) + if agent == "" || agent == invalidField { + return + } + if !knownLabel(label) { + return + } + origin = originOrDefault(cleanField(origin)) + if !validOrigin(label, origin) { + origin = invalidField + } + if !knownSource(source) { + source = Source(invalidField) + } + rec := LabelRecord{ + Label: label, + Origin: origin, + Source: source, + FirstSeen: o.opts.Now(), + } + added, dropped := o.store.add(agent, rec) + switch { + case dropped: + // Counted in Stats.LabelsDropped; not logged per attempt, so a + // session at its bound cannot flood the log. + case added: + o.mu.Lock() + o.labelsRecorded++ + o.mu.Unlock() + o.logInfo("session taint label set (observe only)", + "agent", agent, "label", string(rec.Label), "origin", rec.Origin, "source", string(rec.Source)) + o.audit(agent, AuditLabelSet, fmt.Sprintf("label=%s, origin=%s, source=%s, mode=%s", rec.Label, rec.Origin, rec.Source, modeObserve)) + } +} + +// ObserveSink evaluates one outbound action against the agent's labels and +// records any would-act findings. audienceOf resolves the destination's +// audience and is called only when the session holds at least one label, so a +// clean session costs a map lookup and no network call. A panic in audienceOf +// is absorbed and counted. Nothing is returned: the action proceeds exactly as +// it would have with no observer. +func (o *Observer) ObserveSink(agent string, kind SinkKind, repo string, audienceOf func(repo string) Audience) { + if o == nil { + return + } + defer o.recoverQuiet() + agent = cleanField(agent) + if agent == "" || agent == invalidField { + return + } + repo = cleanField(repo) + labels := o.store.labelsOf(agent) + o.mu.Lock() + o.sinksObserved++ + if len(labels) == 0 { + o.sinksClean++ + o.mu.Unlock() + return + } + o.mu.Unlock() + + aud := AudiencePublic + if audienceOf != nil { + aud = o.lookupAudience(audienceOf, repo) + } + findings := Evaluate(labels, Sink{Kind: kind, Repo: repo, Audience: aud}) + for _, f := range findings { + o.recordFinding(agent, kind, repo, f) + } +} + +// lookupAudience runs the host's audience lookup, treating a panic as +// "public" (the conservative answer for a destination). +func (o *Observer) lookupAudience(audienceOf func(string) Audience, repo string) (aud Audience) { + aud = AudiencePublic + defer func() { + if r := recover(); r != nil { + o.mu.Lock() + o.panics++ + o.mu.Unlock() + aud = AudiencePublic + } + }() + return audienceOf(repo) +} + +func (o *Observer) recordFinding(agent string, kind SinkKind, repo string, f Finding) { + d := Decision{ + At: o.opts.Now(), Agent: agent, Rule: f.Rule, Verdict: f.Verdict, + Sink: kind, DestRepo: repo, Label: f.Label, Origin: f.Origin, + } + o.mu.Lock() + o.wouldAct[f.Rule]++ + o.mu.Unlock() + key := f.Rule + "|" + string(kind) + "|" + strings.ToLower(repo) + if !o.store.firstDecision(agent, key) { + return + } + o.mu.Lock() + if len(o.ring) < o.opts.MaxDecisions { + o.ring = append(o.ring, d) + } else { + o.ring[o.ringStart] = d + o.ringStart = (o.ringStart + 1) % o.opts.MaxDecisions + } + o.mu.Unlock() + o.logInfo("session taint would act (observe only, nothing blocked)", + "agent", agent, "rule", d.Rule, "verdict", string(d.Verdict), "sink", string(kind), + "dest", repo, "label", string(d.Label), "origin", d.Origin) + o.audit(agent, AuditWouldAct, fmt.Sprintf("rule=%s, verdict=%s, sink=%s, dest=%s, label=%s, origin=%s, mode=%s", + d.Rule, d.Verdict, kind, repo, d.Label, d.Origin, modeObserve)) +} + +// Stats returns a copy of the counters and the recent decisions. Safe on a nil +// Observer, which reports the zero Stats. +func (o *Observer) Stats() Stats { + if o == nil { + return Stats{} + } + c := o.store.counts() + o.mu.Lock() + defer o.mu.Unlock() + st := Stats{ + Mode: modeObserve, + Sessions: c.sessions, + Labels: c.labels, + SessionsEvicted: c.evicted, + LabelsRecorded: o.labelsRecorded, + LabelsDropped: c.labelsDropped, + SinksObserved: o.sinksObserved, + SinksClean: o.sinksClean, + Panics: o.panics, + WouldAct: make(map[string]uint64, len(o.wouldAct)), + } + for k, v := range o.wouldAct { + st.WouldAct[k] = v + } + st.Recent = append(st.Recent, o.ring[o.ringStart:]...) + st.Recent = append(st.Recent, o.ring[:o.ringStart]...) + return st +} + +// Labels returns a copy of one agent's labels, nil when it has none. Safe on a +// nil Observer. +func (o *Observer) Labels(agent string) []LabelRecord { + if o == nil { + return nil + } + return o.store.labelsOf(cleanField(agent)) +} + +// recoverQuiet absorbs a panic so an observation can never break the relay or +// handler it is called from. +func (o *Observer) recoverQuiet() { + if r := recover(); r != nil { + o.mu.Lock() + o.panics++ + o.mu.Unlock() + } +} + +func (o *Observer) logInfo(msg string, args ...any) { + if o.opts.Logger != nil { + o.opts.Logger.Info(msg, args...) + } +} + +func (o *Observer) audit(agent, action, detail string) { + if o.opts.Audit != nil { + o.opts.Audit(agent, action, detail) + } +} + +func knownLabel(l Label) bool { + switch l { + case LabelSecret, LabelPrivateRepo, LabelCredentialedResponse, LabelUnknown: + return true + } + return false +} + +// validOrigin reports whether origin has the shape its label allows, so a +// credential value or free text can never be kept as an origin: +// - secret and unknown: a category or reason slug of lower-case letters and +// hyphens ("github-token", "state-lost"), at most maxCategoryLen long. A +// credential carries digits, upper case or underscores and is longer; +// - private-repo: an owner/repo id; +// - credentialed-response: a host name. +// +// The placeholder invalidField is always allowed, and is how a refused origin +// is stored. +func validOrigin(l Label, origin string) bool { + if origin == invalidField || origin == unspecifiedOrigin { + return true + } + switch l { + case LabelSecret, LabelUnknown: + return isCategorySlug(origin) + case LabelPrivateRepo: + return isRepoID(origin) + case LabelCredentialedResponse: + return isHost(origin) + } + return false +} + +// isCategorySlug reports whether s is 1 to maxCategoryLen lower-case letters +// and hyphens. +func isCategorySlug(s string) bool { + if s == "" || len(s) > maxCategoryLen { + return false + } + for _, r := range s { + if (r < 'a' || r > 'z') && r != '-' { + return false + } + } + return true +} + +// isRepoID reports whether s is exactly owner/repo, both parts non-empty and +// limited to letters, digits, '.', '_' and '-'. +func isRepoID(s string) bool { + owner, repo, ok := strings.Cut(s, "/") + if !ok || owner == "" || repo == "" || strings.Contains(repo, "/") { + return false + } + return onlyIdentRunes(owner, "._-") && onlyIdentRunes(repo, "._-") +} + +// isHost reports whether s is a host name, with an optional :port. +func isHost(s string) bool { + return s != "" && onlyIdentRunes(s, ".-:") +} + +func onlyIdentRunes(s, extra string) bool { + for _, r := range s { + switch { + case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9': + case strings.ContainsRune(extra, r): + default: + return false + } + } + return true +} + +func knownSource(s Source) bool { + switch s { + case SourceCanaryHit: + return true + } + return false +} + +func originOrDefault(s string) string { + if s == "" { + return unspecifiedOrigin + } + return s +} + +// cleanField reduces an identifier to a short, log-safe form: trimmed, at most +// maxFieldLen bytes, and only letters, digits and . _ - : / @ +. Anything else +// (whitespace, quotes, newlines, free text) becomes invalidField. An empty +// input stays empty. +func cleanField(s string) string { + s = strings.TrimSpace(s) + if s == "" { + return "" + } + if len(s) > maxFieldLen { + return invalidField + } + for _, r := range s { + switch { + case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9': + case strings.ContainsRune("._-:/@+", r): + default: + return invalidField + } + } + return s +} diff --git a/src/crux/sessiontaint/observer_test.go b/src/crux/sessiontaint/observer_test.go new file mode 100644 index 0000000000..422666d43c --- /dev/null +++ b/src/crux/sessiontaint/observer_test.go @@ -0,0 +1,398 @@ +package sessiontaint + +import ( + "bytes" + "fmt" + "log/slog" + "reflect" + "strings" + "sync" + "testing" + "time" +) + +type auditSink struct { + mu sync.Mutex + entries []string +} + +func (a *auditSink) add(agent, action, detail string) { + a.mu.Lock() + defer a.mu.Unlock() + a.entries = append(a.entries, agent+"|"+action+"|"+detail) +} + +func (a *auditSink) count() int { + a.mu.Lock() + defer a.mu.Unlock() + return len(a.entries) +} + +func publicAudience(string) Audience { return AudiencePublic } +func privateAudience(string) Audience { return AudiencePrivate } + +func newTestObserver(t *testing.T, mutate func(*Options)) (*Observer, *auditSink, *bytes.Buffer) { + t.Helper() + au := &auditSink{} + var logs bytes.Buffer + opts := Options{ + Enabled: true, + Logger: slog.New(slog.NewTextHandler(&logs, nil)), + Audit: au.add, + Now: func() time.Time { return time.Unix(1_700_000_000, 0) }, + } + if mutate != nil { + mutate(&opts) + } + o := New(opts) + if o == nil { + t.Fatal("New returned nil for an enabled observer") + } + return o, au, &logs +} + +// Observe-only guarantee: the observer's entry points return nothing, so no +// caller can branch on a verdict, and no verdict type can express a deny. +func TestObserverEntryPointsReturnNothing(t *testing.T) { + typ := reflect.TypeOf(&Observer{}) + for _, name := range []string{"RecordLabel", "ObserveSink"} { + m, ok := typ.MethodByName(name) + if !ok { + t.Fatalf("missing method %s", name) + } + if m.Type.NumOut() != 0 { + t.Errorf("%s returns %d values; an observe-only entry point must return none", name, m.Type.NumOut()) + } + } + if string(VerdictHold) != "hold" || string(VerdictAllow) != "allow" { + t.Fatalf("unexpected verdict vocabulary") + } +} + +func TestNothingIsDeniedWhateverTheSessionHolds(t *testing.T) { + o, _, _ := newTestObserver(t, nil) + for _, l := range []Label{LabelSecret, LabelPrivateRepo, LabelCredentialedResponse, LabelUnknown} { + o.RecordLabel("agent-a", l, "hive-canary", SourceCanaryHit) + } + for _, k := range []SinkKind{SinkRelayIssue, SinkRelayComment, SinkRelayPR, SinkRelayReview} { + o.ObserveSink("agent-a", k, "o/pub", publicAudience) + o.ObserveSink("agent-a", k, "o/priv", privateAudience) + } + st := o.Stats() + if len(st.Recent) == 0 { + t.Fatal("expected would-act decisions to be recorded") + } + for _, d := range st.Recent { + if d.Verdict != VerdictHold { + t.Errorf("decision %+v has verdict %q; only would-hold is possible", d, d.Verdict) + } + } + if st.Mode != "observe" { + t.Errorf("mode = %q, want observe", st.Mode) + } +} + +func TestDisabledRecordsNothing(t *testing.T) { + au := &auditSink{} + var logs bytes.Buffer + o := New(Options{Enabled: false, Logger: slog.New(slog.NewTextHandler(&logs, nil)), Audit: au.add}) + if o != nil { + t.Fatal("a disabled observer must be nil") + } + // Every entry point is a safe no-op on nil. + o.RecordLabel("agent-a", LabelSecret, "hive-canary", SourceCanaryHit) + looked := false + o.ObserveSink("agent-a", SinkRelayIssue, "o/a", func(string) Audience { looked = true; return AudiencePublic }) + if looked { + t.Error("audience lookup ran with the feature off") + } + if got := o.Labels("agent-a"); got != nil { + t.Errorf("labels = %v, want none", got) + } + if st := o.Stats(); !reflect.DeepEqual(st, Stats{}) { + t.Errorf("stats = %+v, want zero", st) + } + if au.count() != 0 || logs.Len() != 0 { + t.Errorf("a disabled observer wrote audit=%d log=%q", au.count(), logs.String()) + } +} + +func TestCleanSessionCostsNoLookupAndRecordsNothing(t *testing.T) { + o, au, logs := newTestObserver(t, nil) + looked := false + o.ObserveSink("agent-a", SinkRelayIssue, "o/a", func(string) Audience { looked = true; return AudiencePublic }) + if looked { + t.Error("audience lookup ran for a session with no labels") + } + st := o.Stats() + if st.Sessions != 0 || st.SinksClean != 1 || len(st.Recent) != 0 || len(st.WouldAct) != 0 { + t.Errorf("clean sink observation changed state: %+v", st) + } + if au.count() != 0 || logs.Len() != 0 { + t.Errorf("clean session wrote audit=%d log=%q", au.count(), logs.String()) + } +} + +func TestLabelThenSinkRecordsWouldHold(t *testing.T) { + o, au, logs := newTestObserver(t, nil) + o.RecordLabel("agent-a", LabelSecret, "hive-canary", SourceCanaryHit) + o.ObserveSink("agent-a", SinkRelayComment, "o/pub", publicAudience) + // Another agent that never read anything is not held. + o.ObserveSink("agent-b", SinkRelayComment, "o/pub", publicAudience) + + st := o.Stats() + if st.WouldAct[RuleSecretPublicWrite] != 1 { + t.Fatalf("would-act counters = %v", st.WouldAct) + } + if len(st.Recent) != 1 || st.Recent[0].Agent != "agent-a" || st.Recent[0].Rule != RuleSecretPublicWrite { + t.Fatalf("recent = %+v", st.Recent) + } + if au.count() != 2 { // one label entry, one would-act entry + t.Fatalf("audit entries = %v", au.entries) + } + if !strings.Contains(logs.String(), "observe only") { + t.Errorf("log does not say observe only: %s", logs.String()) + } +} + +func TestRepeatedDecisionsAreCountedButLoggedOnce(t *testing.T) { + o, au, _ := newTestObserver(t, nil) + o.RecordLabel("agent-a", LabelSecret, "hive-canary", SourceCanaryHit) + const requests = 500 + for i := 0; i < requests; i++ { + o.ObserveSink("agent-a", SinkRelayComment, "o/pub", publicAudience) + } + st := o.Stats() + if st.WouldAct[RuleSecretPublicWrite] != requests { + t.Errorf("counter = %d, want %d", st.WouldAct[RuleSecretPublicWrite], requests) + } + if len(st.Recent) != 1 || au.count() != 2 { + t.Errorf("recent=%d audit=%d, want one decision and two audit entries total", len(st.Recent), au.count()) + } +} + +func TestLabelsAreAUnionAndOnlyGrow(t *testing.T) { + o, au, _ := newTestObserver(t, nil) + o.RecordLabel("agent-a", LabelSecret, "jwt", SourceCanaryHit) + o.RecordLabel("agent-a", LabelSecret, "jwt", SourceCanaryHit) // repeat + o.RecordLabel("agent-a", LabelPrivateRepo, "o/priv", SourceCanaryHit) + if got := len(o.Labels("agent-a")); got != 2 { + t.Fatalf("labels = %d, want 2", got) + } + if st := o.Stats(); st.LabelsRecorded != 2 || au.count() != 2 { + t.Errorf("recorded=%d audit=%d, want 2 and 2", st.LabelsRecorded, au.count()) + } +} + +func TestStoreIsBounded(t *testing.T) { + const maxSessions, maxLabels, maxDecisions = 3, 2, 4 + o, au, _ := newTestObserver(t, func(op *Options) { + op.MaxSessions, op.MaxLabelsPerSession, op.MaxDecisions = maxSessions, maxLabels, maxDecisions + }) + const agents = 20 + for i := 0; i < agents; i++ { + o.RecordLabel(fmt.Sprintf("agent-%d", i), LabelSecret, "jwt", SourceCanaryHit) + } + st := o.Stats() + if st.Sessions != maxSessions || st.SessionsEvicted != agents-maxSessions { + t.Errorf("sessions=%d evicted=%d, want %d and %d", st.Sessions, st.SessionsEvicted, maxSessions, agents-maxSessions) + } + // The most recent sessions survive, the oldest are gone. + if len(o.Labels("agent-0")) != 0 || len(o.Labels(fmt.Sprintf("agent-%d", agents-1))) != 1 { + t.Errorf("eviction did not keep the most recent sessions") + } + + // Per-session label bound: distinct origins past the bound are dropped and counted. + for i := 0; i < 10; i++ { + o.RecordLabel("agent-x", LabelPrivateRepo, fmt.Sprintf("o/r%d", i), SourceCanaryHit) + } + if got := len(o.Labels("agent-x")); got != maxLabels { + t.Errorf("labels = %d, want bound %d", got, maxLabels) + } + if o.Stats().LabelsDropped == 0 { + t.Errorf("dropped labels were not counted") + } + + // Decision ring bound: many distinct would-act decisions keep only the latest. + o.RecordLabel("agent-y", LabelSecret, "jwt", SourceCanaryHit) + before := au.count() + for i := 0; i < 50; i++ { + o.ObserveSink("agent-y", SinkRelayComment, fmt.Sprintf("o/d%d", i), publicAudience) + } + st = o.Stats() + if len(st.Recent) != maxDecisions { + t.Errorf("recent = %d, want ring bound %d", len(st.Recent), maxDecisions) + } + if st.Recent[len(st.Recent)-1].DestRepo != "o/d49" { + t.Errorf("ring is not oldest-first: last = %s", st.Recent[len(st.Recent)-1].DestRepo) + } + if au.count() <= before { + t.Errorf("expected audit entries for distinct decisions") + } + // The audit trail for one session is bounded even with unbounded distinct decisions. + for i := 0; i < 10*maxDecisionKeysPerSession; i++ { + o.ObserveSink("agent-y", SinkRelayIssue, fmt.Sprintf("o/e%d", i), publicAudience) + } + if grown := au.count() - before; grown > maxDecisionKeysPerSession+1 { + t.Errorf("audit grew by %d, want at most %d per session", grown, maxDecisionKeysPerSession+1) + } +} + +// Restart behaviour in this phase: the store is memory only, so a restart is a +// fresh epoch. The new observer holds nothing, records nothing for a sink, and +// does not invent an unknown label (that is an enforcement-phase failure mode). +func TestRestartStartsCleanAndInventsNothing(t *testing.T) { + first, _, _ := newTestObserver(t, nil) + first.RecordLabel("agent-a", LabelSecret, "hive-canary", SourceCanaryHit) + if len(first.Labels("agent-a")) != 1 { + t.Fatal("setup: label not recorded") + } + + second, au, logs := newTestObserver(t, nil) // the "restarted" process + if got := second.Labels("agent-a"); len(got) != 0 { + t.Fatalf("labels survived a restart: %v", got) + } + second.ObserveSink("agent-a", SinkRelayIssue, "o/pub", publicAudience) + st := second.Stats() + if st.Sessions != 0 || len(st.Recent) != 0 || len(st.WouldAct) != 0 || st.SinksClean != 1 { + t.Errorf("restarted observer state = %+v", st) + } + if au.count() != 0 || logs.Len() != 0 { + t.Errorf("restarted observer wrote audit=%d log=%q", au.count(), logs.String()) + } +} + +// No content is stored: free-form or credential-shaped input is replaced by a +// fixed placeholder, never kept, logged or audited. +func TestNoContentOrCredentialValuesAreStored(t *testing.T) { + o, au, logs := newTestObserver(t, nil) + // Synthetic credential-shaped and free-form strings. + synthetic := []string{ + "ghp_" + strings.Repeat("A1", 18), + "line one\nline two with spaces", + strings.Repeat("x", 500), + "eyJhbGciOi.synthetic.payload", + } + for _, s := range synthetic { + o.RecordLabel("agent-a", LabelSecret, s, Source(s)) + } + o.RecordLabel("agent-a", LabelPrivateRepo, "contains spaces and\nnewline", SourceCanaryHit) + for _, rec := range o.Labels("agent-a") { + for _, field := range []string{rec.Origin, string(rec.Source)} { + for _, s := range synthetic { + if strings.Contains(field, s) || strings.Contains(field, "ghp_") { + t.Errorf("stored field %q echoes input", field) + } + } + if strings.ContainsAny(field, " \n") { + t.Errorf("stored field %q contains whitespace", field) + } + } + } + // An unattributed or malformed agent is not recorded at all. + o.RecordLabel("", LabelSecret, "jwt", SourceCanaryHit) + o.RecordLabel("bad agent\nname", LabelSecret, "jwt", SourceCanaryHit) + if st := o.Stats(); st.Sessions != 1 { + t.Errorf("sessions = %d, want only the attributed agent", st.Sessions) + } + // An unknown label kind is ignored. + o.RecordLabel("agent-a", Label("made-up"), "jwt", SourceCanaryHit) + for _, rec := range o.Labels("agent-a") { + if !knownLabel(rec.Label) { + t.Errorf("unknown label stored: %s", rec.Label) + } + } + // Nothing in the log or audit echoes the synthetic strings. + all := logs.String() + strings.Join(au.entries, "\n") + for _, s := range synthetic { + if strings.Contains(all, s) { + t.Errorf("log or audit contains synthetic input %q", s) + } + } +} + +func TestLookupPanicIsAbsorbedAndTreatedAsPublic(t *testing.T) { + o, _, _ := newTestObserver(t, nil) + o.RecordLabel("agent-a", LabelSecret, "hive-canary", SourceCanaryHit) + o.ObserveSink("agent-a", SinkRelayIssue, "o/a", func(string) Audience { panic("lookup failed") }) + st := o.Stats() + if st.Panics != 1 { + t.Errorf("panics = %d, want 1", st.Panics) + } + if st.WouldAct[RuleSecretPublicWrite] != 1 { + t.Errorf("a failed destination lookup must be treated as public: %v", st.WouldAct) + } +} + +func TestConcurrentUseIsSafe(t *testing.T) { + o, _, _ := newTestObserver(t, func(op *Options) { op.MaxSessions = 4 }) + var wg sync.WaitGroup + for g := 0; g < 8; g++ { + wg.Add(1) + go func(g int) { + defer wg.Done() + agent := fmt.Sprintf("agent-%d", g) + for i := 0; i < 200; i++ { + o.RecordLabel(agent, LabelSecret, "jwt", SourceCanaryHit) + o.ObserveSink(agent, SinkRelayComment, "o/pub", publicAudience) + _ = o.Stats() + } + }(g) + } + wg.Wait() +} + +func TestNewAppliesDefaultsForNonPositiveBounds(t *testing.T) { + o := New(Options{Enabled: true, MaxSessions: -1, MaxLabelsPerSession: 0, MaxDecisions: -5}) + if o.store.maxSessions != DefaultMaxSessions || o.store.maxLabels != DefaultMaxLabelsPerSession || o.opts.MaxDecisions != DefaultMaxDecisions { + t.Errorf("bounds = %d %d %d, want the defaults", o.store.maxSessions, o.store.maxLabels, o.opts.MaxDecisions) + } + if o.opts.Now == nil { + t.Error("a nil clock must default") + } + one := New(Options{Enabled: true, MaxSessions: 1, MaxLabelsPerSession: 1, MaxDecisions: 1}) + if one.store.maxSessions != 1 || one.store.maxLabels != 1 || one.opts.MaxDecisions != 1 { + t.Errorf("a bound of 1 must be kept") + } +} + +func TestFieldShapeBoundaries(t *testing.T) { + long := strings.Repeat("a", maxFieldLen) + if cleanField(long) != long { + t.Errorf("a field of exactly %d bytes must be kept", maxFieldLen) + } + if cleanField(long+"a") != invalidField { + t.Errorf("a field over %d bytes must be refused", maxFieldLen) + } + if cleanField(" ") != "" || cleanField(" ok ") != "ok" { + t.Errorf("trim behaviour changed") + } + slug := strings.Repeat("a", maxCategoryLen) + if !isCategorySlug(slug) || isCategorySlug(slug+"a") || isCategorySlug("") { + t.Errorf("category slug length boundary wrong") + } + if !isCategorySlug("a-z") || isCategorySlug("A") || isCategorySlug("a1") || isCategorySlug("a_b") || !isCategorySlug("-") { + t.Errorf("category slug alphabet wrong") + } + for repo, want := range map[string]bool{ + "o/r": true, "My-Org/my.repo_2": true, "o/": false, "/r": false, "o": false, + "o/r/x": false, "o r/x": false, "o/r x": false, "o/r@x": false, "": false, + } { + if got := isRepoID(repo); got != want { + t.Errorf("isRepoID(%q) = %v, want %v", repo, got, want) + } + } + for host, want := range map[string]bool{ + "api.example.com": true, "host:8080": true, "": false, "a b": false, "a/b": false, "a_b": false, + } { + if got := isHost(host); got != want { + t.Errorf("isHost(%q) = %v, want %v", host, got, want) + } + } + if !validOrigin(LabelSecret, invalidField) || !validOrigin(LabelPrivateRepo, unspecifiedOrigin) { + t.Errorf("the placeholders must always be allowed") + } + if validOrigin(Label("made-up"), "x") { + t.Errorf("an unknown label has no valid origin") + } +} diff --git a/src/crux/sessiontaint/store.go b/src/crux/sessiontaint/store.go new file mode 100644 index 0000000000..d9483c7634 --- /dev/null +++ b/src/crux/sessiontaint/store.go @@ -0,0 +1,150 @@ +package sessiontaint + +import ( + "container/list" + "sync" +) + +// Default bounds. Each is a named constant, overridable through Options, so a +// busy hive cannot grow the store without limit (design: Cost, Storage). +const ( + // DefaultMaxSessions bounds how many agent sessions the store holds. At + // the bound the least recently touched session is evicted. + DefaultMaxSessions = 256 + // DefaultMaxLabelsPerSession bounds the labels one session holds. The + // label kinds are a closed set, so the bound is on distinct origins. + DefaultMaxLabelsPerSession = 32 + // DefaultMaxDecisions bounds the recent would-act ring. + DefaultMaxDecisions = 128 + // maxDecisionKeysPerSession bounds how many distinct would-act decisions + // per session are logged and audited; later ones are only counted. + maxDecisionKeysPerSession = 64 +) + +// session is one agent's taint state for the life of the process. A process +// restart is the epoch boundary in this phase: the store is in memory only. +type session struct { + agent string + labels []LabelRecord + seen map[string]struct{} // label+origin keys, for the union + logged map[string]struct{} // would-act decisions already logged + elem *list.Element +} + +// store is the bounded in-memory session map with least-recently-used +// eviction. All methods are safe for concurrent use. +type store struct { + mu sync.Mutex + maxSessions int + maxLabels int + sessions map[string]*session + lru *list.List // front = most recently touched, values are agent names + + evicted uint64 + labelsDropped uint64 +} + +func newStore(maxSessions, maxLabels int) *store { + return &store{ + maxSessions: maxSessions, + maxLabels: maxLabels, + sessions: make(map[string]*session), + lru: list.New(), + } +} + +// touch returns the agent's session, creating it (and evicting the least +// recently used one at the bound) when absent. The caller holds s.mu. +func (s *store) touch(agent string) *session { + if sess, ok := s.sessions[agent]; ok { + s.lru.MoveToFront(sess.elem) + return sess + } + for len(s.sessions) >= s.maxSessions { + oldest := s.lru.Back() + if oldest == nil { + break + } + name, ok := oldest.Value.(string) + s.lru.Remove(oldest) + if ok { + delete(s.sessions, name) + s.evicted++ + } + } + sess := &session{ + agent: agent, + seen: make(map[string]struct{}), + logged: make(map[string]struct{}), + } + sess.elem = s.lru.PushFront(agent) + s.sessions[agent] = sess + return sess +} + +// add joins one label into the agent's session (set union: a repeat is a +// no-op). It reports whether the label is new and whether it was dropped +// because the session is at its label bound. +func (s *store) add(agent string, rec LabelRecord) (added, dropped bool) { + s.mu.Lock() + defer s.mu.Unlock() + sess := s.touch(agent) + key := string(rec.Label) + "\x00" + rec.Origin + if _, dup := sess.seen[key]; dup { + return false, false + } + if len(sess.labels) >= s.maxLabels { + s.labelsDropped++ + return false, true + } + sess.seen[key] = struct{}{} + sess.labels = append(sess.labels, rec) + return true, false +} + +// labelsOf returns a copy of the agent's labels without creating or touching a +// session: a read must not make a clean agent look like it has state. +func (s *store) labelsOf(agent string) []LabelRecord { + s.mu.Lock() + defer s.mu.Unlock() + sess, ok := s.sessions[agent] + if !ok { + return nil + } + return append([]LabelRecord(nil), sess.labels...) +} + +// firstDecision reports whether this is the first time the session logs the +// given decision key, and remembers it. Past the per-session bound it reports +// false, so a long session cannot flood the log or the audit trail. +func (s *store) firstDecision(agent, key string) bool { + s.mu.Lock() + defer s.mu.Unlock() + sess, ok := s.sessions[agent] + if !ok { + return false + } + if _, dup := sess.logged[key]; dup { + return false + } + if len(sess.logged) >= maxDecisionKeysPerSession { + return false + } + sess.logged[key] = struct{}{} + return true +} + +type storeCounts struct { + sessions, labels int + evicted, labelsDropped uint64 +} + +func (s *store) counts() storeCounts { + s.mu.Lock() + defer s.mu.Unlock() + c := storeCounts{sessions: len(s.sessions), evicted: s.evicted, labelsDropped: s.labelsDropped} + for _, sess := range s.sessions { + c.labels += len(sess.labels) + } + return c +} diff --git a/src/crux/sessiontaint/taint.go b/src/crux/sessiontaint/taint.go new file mode 100644 index 0000000000..3d9b11f7eb --- /dev/null +++ b/src/crux/sessiontaint/taint.go @@ -0,0 +1,167 @@ +// Package sessiontaint is the observe-only core of session taint +// (hivecommons/hive#18987, src/docs/design/session-taint.md, phase 0). +// +// It remembers, per agent session, which coarse labels the hive has observed +// ("this session has seen a secret-shaped marker", "this session has read a +// private repository") and evaluates a small fixed rule table against later +// outbound actions. In this phase the result is only ever RECORDED: the +// evaluator returns a would-be verdict, the observer logs it and counts it, +// and nothing in this package can allow, hold, deny, restrict or change a +// request or an action. The observer methods return no value on purpose, so a +// caller has nothing to branch on. +// +// Nothing here stores a credential or any content: a label is a closed kind, +// an origin that is a category name or an owner/repo id, a source name and a +// timestamp. Free-form input is reduced to a short identifier alphabet or +// replaced by a fixed placeholder before it is stored or logged. +// +// The package is stdlib only so the Crux ring (proxy, push broker) can take +// the same observer through a setter in a later phase. +package sessiontaint + +import ( + "strings" + "time" +) + +// Label is the closed set of taint labels (design: Labels). +type Label string + +const ( + // LabelSecret: a credential-shaped value or a canary was seen. The origin + // is a category name, never the value. + LabelSecret Label = "secret" + // LabelPrivateRepo: content from, or the working target of, a private + // repository. The origin is owner/repo. + LabelPrivateRepo Label = "private-repo" + // LabelCredentialedResponse: a response fetched with a brokered + // credential from a host the operator lists as sensitive. The origin is + // the host. + LabelCredentialedResponse Label = "credentialed-response" + // LabelUnknown: state could not be established. Only fail-closed rules + // use it, so it matters from the enforcement phases on. + LabelUnknown Label = "unknown" +) + +// Source names which observation set a label (design: Sources). +type Source string + +const ( + // SourceCanaryHit is S3: the existing canary leak handler saw a planted + // token. + SourceCanaryHit Source = "canary-hit" +) + +// SinkKind names a place Hive already mediates an outbound action. +type SinkKind string + +const ( + // SinkRelayIssue is a hive-open-issue relay request. + SinkRelayIssue SinkKind = "relay-issue" + // SinkRelayComment is a hive-comment relay request. + SinkRelayComment SinkKind = "relay-comment" + // SinkRelayPR is a hive-open-pr relay request. + SinkRelayPR SinkKind = "relay-pr" + // SinkRelayReview is a hive-review relay request. + SinkRelayReview SinkKind = "relay-review" +) + +// Audience is who can read a sink's destination. The zero value is public, so +// an unresolved destination restricts more, never less (design: Visibility +// lookups). +type Audience int + +const ( + // AudiencePublic means readers beyond the repository's collaborators, or + // that the audience could not be established. + AudiencePublic Audience = iota + // AudiencePrivate means the destination is a private repository. + AudiencePrivate +) + +// Verdict is what a rule would do were it enforced. Phase 0 has no deny and no +// enforcement: the first enforced verdict is Hold (design: decision 4), and +// Deny arrives with the enforcement phases, so it does not exist yet. +type Verdict string + +const ( + // VerdictAllow means no rule fired. + VerdictAllow Verdict = "allow" + // VerdictHold means the rule would put the action in front of an operator + // if it were enforced. It is recorded, never acted on. + VerdictHold Verdict = "hold" +) + +// Rule ids (design: Rule shape v1). The ids are the stable names that appear +// in the log, the audit detail and the counters. +const ( + RuleSecretPublicWrite = "taint.secret.public-write" + RulePrivateAudience = "taint.private.audience" + RuleCredPublicWrite = "taint.cred.public-write" + RuleUnknownAnyWrite = "taint.unknown.any-write" +) + +// LabelRecord is one label a session holds. Labels only grow inside a session. +type LabelRecord struct { + Label Label + Origin string + Source Source + FirstSeen time.Time +} + +// Sink describes one outbound action for evaluation: its kind, the destination +// repository (owner/repo) and the destination's audience. +type Sink struct { + Kind SinkKind + Repo string + Audience Audience +} + +// Finding is one rule that would act: the rule id, the verdict, and the label +// and origin that triggered it. +type Finding struct { + Rule string + Verdict Verdict + Label Label + Origin string +} + +// Evaluate is the pure rule table: from a session's labels and one sink to the +// findings, at most one per rule, in rule order. It never mutates its inputs, +// never consults a clock or any state, and can only return VerdictHold +// findings: a session with no matching label yields none. Taint adds a verdict +// to an action every earlier gate allowed; it cannot grant anything. +func Evaluate(labels []LabelRecord, sink Sink) []Finding { + var out []Finding + add := func(rule string, l LabelRecord) { + out = append(out, Finding{Rule: rule, Verdict: VerdictHold, Label: l.Label, Origin: l.Origin}) + } + if l, ok := firstLabel(labels, func(l LabelRecord) bool { + return l.Label == LabelSecret && sink.Audience == AudiencePublic + }); ok { + add(RuleSecretPublicWrite, l) + } + if l, ok := firstLabel(labels, func(l LabelRecord) bool { + return l.Label == LabelPrivateRepo && !strings.EqualFold(l.Origin, sink.Repo) + }); ok { + add(RulePrivateAudience, l) + } + if l, ok := firstLabel(labels, func(l LabelRecord) bool { + return l.Label == LabelCredentialedResponse && sink.Audience == AudiencePublic + }); ok { + add(RuleCredPublicWrite, l) + } + if l, ok := firstLabel(labels, func(l LabelRecord) bool { return l.Label == LabelUnknown }); ok { + add(RuleUnknownAnyWrite, l) + } + return out +} + +func firstLabel(labels []LabelRecord, match func(LabelRecord) bool) (LabelRecord, bool) { + for _, l := range labels { + if match(l) { + return l, true + } + } + return LabelRecord{}, false +} diff --git a/src/crux/sessiontaint/taint_test.go b/src/crux/sessiontaint/taint_test.go new file mode 100644 index 0000000000..4c4ad24501 --- /dev/null +++ b/src/crux/sessiontaint/taint_test.go @@ -0,0 +1,82 @@ +package sessiontaint + +import ( + "reflect" + "testing" + "time" +) + +func lab(l Label, origin string) LabelRecord { + return LabelRecord{Label: l, Origin: origin, Source: SourceCanaryHit, FirstSeen: time.Unix(1, 0)} +} + +func TestEvaluateRuleTable(t *testing.T) { + cases := []struct { + name string + labels []LabelRecord + sink Sink + want []string + }{ + {"no labels", nil, Sink{Kind: SinkRelayComment, Repo: "o/a", Audience: AudiencePublic}, nil}, + {"secret to public", []LabelRecord{lab(LabelSecret, "hive-canary")}, Sink{Kind: SinkRelayIssue, Repo: "o/a", Audience: AudiencePublic}, []string{RuleSecretPublicWrite}}, + {"secret to private", []LabelRecord{lab(LabelSecret, "hive-canary")}, Sink{Kind: SinkRelayIssue, Repo: "o/a", Audience: AudiencePrivate}, nil}, + {"unresolved audience is public", []LabelRecord{lab(LabelSecret, "hive-canary")}, Sink{Kind: SinkRelayPR, Repo: "o/a"}, []string{RuleSecretPublicWrite}}, + {"private repo elsewhere", []LabelRecord{lab(LabelPrivateRepo, "o/secret")}, Sink{Kind: SinkRelayComment, Repo: "o/a", Audience: AudiencePrivate}, []string{RulePrivateAudience}}, + {"private repo same repo", []LabelRecord{lab(LabelPrivateRepo, "o/secret")}, Sink{Kind: SinkRelayComment, Repo: "o/secret", Audience: AudiencePrivate}, nil}, + {"private repo same repo other case", []LabelRecord{lab(LabelPrivateRepo, "O/Secret")}, Sink{Kind: SinkRelayComment, Repo: "o/secret", Audience: AudiencePrivate}, nil}, + {"credentialed to public", []LabelRecord{lab(LabelCredentialedResponse, "host.example")}, Sink{Kind: SinkRelayReview, Repo: "o/a", Audience: AudiencePublic}, []string{RuleCredPublicWrite}}, + {"credentialed to private", []LabelRecord{lab(LabelCredentialedResponse, "host.example")}, Sink{Kind: SinkRelayReview, Repo: "o/a", Audience: AudiencePrivate}, nil}, + {"unknown any write", []LabelRecord{lab(LabelUnknown, "state-lost")}, Sink{Kind: SinkRelayComment, Repo: "o/a", Audience: AudiencePrivate}, []string{RuleUnknownAnyWrite}}, + {"several labels several rules", []LabelRecord{lab(LabelSecret, "jwt"), lab(LabelPrivateRepo, "o/x")}, Sink{Kind: SinkRelayIssue, Repo: "o/a", Audience: AudiencePublic}, []string{RuleSecretPublicWrite, RulePrivateAudience}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + var got []string + for _, f := range Evaluate(tc.labels, tc.sink) { + got = append(got, f.Rule) + if f.Verdict != VerdictHold { + t.Errorf("rule %s verdict = %q, want hold", f.Rule, f.Verdict) + } + } + if !reflect.DeepEqual(got, tc.want) { + t.Fatalf("rules = %v, want %v", got, tc.want) + } + }) + } +} + +// The observe-only invariant at the evaluator: across every label kind, every +// sink kind and both audiences, a verdict is only ever hold, and a session +// with no label never produces one. There is no deny verdict in this phase. +func TestEvaluateNeverDeniesAndCleanSessionNeverFires(t *testing.T) { + kinds := []Label{LabelSecret, LabelPrivateRepo, LabelCredentialedResponse, LabelUnknown} + sinks := []SinkKind{SinkRelayIssue, SinkRelayComment, SinkRelayPR, SinkRelayReview} + for _, l := range kinds { + for _, k := range sinks { + for _, a := range []Audience{AudiencePublic, AudiencePrivate} { + for _, f := range Evaluate([]LabelRecord{lab(l, "o/x")}, Sink{Kind: k, Repo: "o/a", Audience: a}) { + if f.Verdict != VerdictHold { + t.Fatalf("label %s sink %s audience %d: verdict %q, want hold only", l, k, a, f.Verdict) + } + } + if got := Evaluate(nil, Sink{Kind: k, Repo: "o/a", Audience: a}); len(got) != 0 { + t.Fatalf("clean session fired %v", got) + } + } + } + } +} + +func TestEvaluateIsPure(t *testing.T) { + in := []LabelRecord{lab(LabelSecret, "jwt"), lab(LabelPrivateRepo, "o/x")} + snapshot := append([]LabelRecord(nil), in...) + sink := Sink{Kind: SinkRelayIssue, Repo: "o/a", Audience: AudiencePublic} + first := Evaluate(in, sink) + second := Evaluate(in, sink) + if !reflect.DeepEqual(first, second) { + t.Fatalf("not deterministic: %v vs %v", first, second) + } + if !reflect.DeepEqual(in, snapshot) { + t.Fatalf("input labels mutated") + } +} diff --git a/src/docs/design/session-taint.md b/src/docs/design/session-taint.md index 8fc26b4ff3..519c51862b 100644 --- a/src/docs/design/session-taint.md +++ b/src/docs/design/session-taint.md @@ -1,10 +1,12 @@ # Session taint: remembering what an agent has read (#18987) -Status: **Proposed (design only).** Spec for RFC -[#18987](https://github.com/hivecommons/hive/issues/18987). No code or -behaviour changes with this record. Every phase below is off by default and -ships behind its own issue; the RFC stays open for discussion after this page -merges. The parent defence pages are [ioscan](../ioscan.md), +Status: **Proposed, with the observe-only recorder built (phase 0 slice, see +[Phase status](#phase-status)).** Spec for RFC +[#18987](https://github.com/hivecommons/hive/issues/18987). The recorder is off +by default and never blocks, holds, restricts or changes any request or +action; no enforcement exists yet. Every phase below is off by default and +ships behind its own issue; the RFC stays open for discussion, and until it +decides the enforcement phases nothing here changes what an agent may do. The parent defence pages are [ioscan](../ioscan.md), [the security model](../security-model.md) and [the tool policy](crux-tool-policy.md). @@ -337,23 +339,71 @@ Every phase is independently shippable, default off, and ends with a decision point. Config is a single `session_taint` block; absent means off, which is byte-for-byte today's behaviour. -| Phase | Change | Behaviour change | Exit | -|---|---|---|---| -| 0 | This record merges; RFC decides labels, scope, sink list, budget | none | RFC acceptance criteria met | -| 1 | Taint store, audit entry type, read-only API and `hivectl` view, no sources | none | Store passes its tests | -| 2a | S0 and S3 sources, observe | audit only | Labels appear for real kicks | -| 2b | S1 source, observe, off the request path | audit only | Latency and miss rate measured | -| 2c | S2 source with visibility cache and response status hook, observe | audit only | Visibility lookup rate and failure rate known | -| 3a | Rules on relays and the sandbox PR step, `would-act` logging | audit and counters | Per-rule data against the exit criteria above | -| 3b | Same on proxy writes and the push broker | audit and counters | Same | -| 4 | Enforce one rule at a time as `hold`, with release and clear | holds appear | Hold review shows the false hold budget met | -| 5 | Persistence across restart, long-lived scoping, in-memory dynamic canary, desk integration, optional egress rule, cross-agent | varies | Each split into its own issue | +| Phase | Change | Behaviour change | Exit | Status | +|---|---|---|---|---| +| 0 | This record merges; RFC decides labels, scope, sink list, budget | none | RFC acceptance criteria met | Record merged; decisions proposed in the recorder PR, RFC open | +| 1 | Taint store, audit entry type, read-only API and `hivectl` view, no sources | none | Store passes its tests | Store and audit entries built (in memory, bounded); read-only API and `hivectl` view not yet | +| 2a | S0 and S3 sources, observe | audit only | Labels appear for real kicks | S3 (canary hit) built; S0 (kick target) not yet | +| 2b | S1 source, observe, off the request path | audit only | Latency and miss rate measured | Not started | +| 2c | S2 source with visibility cache and response status hook, observe | audit only | Visibility lookup rate and failure rate known | Not started | +| 3a | Rules on relays and the sandbox PR step, `would-act` logging | audit and counters | Per-rule data against the exit criteria above | Rules and would-act logging built for the issue, comment, PR and review relays; sandbox PR step not yet | +| 3b | Same on proxy writes and the push broker | audit and counters | Same | Not started (waits for the proxy changes in flight to land) | +| 4 | Enforce one rule at a time as `hold`, with release and clear | holds appear | Hold review shows the false hold budget met | Not started; nothing in the tree can hold or deny | +| 5 | Persistence across restart, long-lived scoping, in-memory dynamic canary, desk integration, optional egress rule, cross-agent | varies | Each split into its own issue | Not started | Phases 2a to 2c are separate so the cheapest, highest-coverage source (S0) does not wait for the harder ones. Phase 3 splits by sink class because the relays are host-side and easy, and the proxy and broker carry the attribution and latency risk. +## Phase status + +What the observe-only recorder does today, and what it deliberately does not. + +- **Off by default.** `session_taint.enabled` is absent or false: the observer + is never built, no lookup is made, nothing is recorded or logged, and + behaviour is byte-for-byte what it was. A change needs a restart. +- **Package.** `crux/sessiontaint`, stdlib only, so the Crux ring can take the + same observer later. The evaluator (`Evaluate`) is a pure function of + `(labels, sink)`; the observer wraps it with a bounded store. +- **What it records.** Labels (`secret` today; the others exist in the type and + the rule table but have no source yet) and would-be verdicts. A label is a + kind, an origin that is a category name or an owner/repo id, a source name and + a timestamp. No credential, token, body, title or file content is stored, + logged or audited, and free text given as an origin is replaced by the + placeholder `invalid`. +- **Where labels come from.** S3 only: the existing canary leak handler sets a + `secret` label, origin `hive-canary`, on the session of the agent whose token + was seen. An unattributed caller is not recorded. +- **Where it looks.** The issue, comment, PR and review relays, once per relay + write that completed: after every existing gate, retry and dedupe step, so the + data never describes an action the hive refused or retried, and a reused issue, + comment or PR is skipped. Observe-only has nothing to gate, so it runs after the + write; the enforcement phases must move the check before it. A session with + no label costs a map lookup. A session with a label triggers one destination + visibility lookup (the hive's own credential, cached for an hour; a failed + lookup counts as public and is not cached). +- **What it does with a finding.** One log line and one audit entry per + distinct would-act decision per session, a counter per rule for every + request, and a bounded ring of recent decisions. The only verdict that + exists is `hold`, and it is only ever recorded. The observer entry points + return nothing, so no caller can branch on them, and a panic inside them is + absorbed. +- **Bounds.** Sessions (least recently used evicted), labels per session, + decisions in the ring and distinct logged decisions per session are all + capped by named constants; the `session_taint` keys `max_sessions`, + `max_labels_per_session` and `max_decisions` override the first three. +- **Eviction.** The least recently used session is evicted at the session + bound, which would drop a tainted session's labels. That is harmless while + nothing is enforced; before enforcement, eviction must resolve to `unknown` + rather than clean (see the failure table). +- **Restart.** The store is memory only. A restart starts every session clean + and invents no `unknown` label; that failure mode belongs to enforcement + (see [Failure and fail-closed semantics](#failure-and-fail-closed-semantics)). +- **Not built.** S0, S1 and S2 sources, the proxy and push-broker sinks, the + sandbox PR step, the read-only API and `hivectl` view, operator release and + clear, persistence, and any `hold` or `deny` behaviour. + ## Test strategy - **Evaluator.** Table-driven tests over `(labels, descriptor)` for every rule, diff --git a/src/docs/security-model.md b/src/docs/security-model.md index 28b750dea6..76974e5448 100644 --- a/src/docs/security-model.md +++ b/src/docs/security-model.md @@ -532,6 +532,19 @@ compares each agent's assigned intent with the last 120 lines of its rendered terminal transcript and pauses the agent on divergence. It fails open if the reviewer is unavailable. +**Session taint (observe only, off by default).** `session_taint.enabled` +turns on a recorder that remembers which coarse labels an agent session has +accrued (today: a canary hit sets `secret`) and, when that session later asks +the issue, comment, PR or review relay to write, records which rule would have +held the write. It writes a log line and an audit entry (`session_taint_label`, +`session_taint_would_act`) and keeps bounded in-memory counters; it never +blocks, holds, restricts or alters a request or an action, and it stores +labels, counts and ids only, never a credential or any content. A restart +starts every session clean. It is a measurement step toward the design in +[design/session-taint.md](design/session-taint.md); no enforcement exists, so +it adds no protection yet and must not be read as a control. Reads Hive cannot +see (local files, shell output, direct provider traffic) produce no label. + **Audit trails.** The dashboard audit log records every dashboard and API mutation, merge decision, sentinel finding and watchdog action to `/data/audit.jsonl`, rotated at 5 MB with three backups and a 90-day @@ -930,6 +943,11 @@ until code-owner review is required in branch protection. ## 11. What Hive does not do yet * **Rootless containers cannot enforce the egress gate.** +* **Nothing remembers what a session has read.** Pattern scanning checks each + outgoing message on its own, so a reworded copy of something an agent read + earlier passes. Session taint is designed for this + ([design/session-taint.md](design/session-taint.md)); only its observe-only + recorder exists, and it does not block anything. * **The proxy inspects GitHub API traffic only.** Other destinations are tunnelled. Use Kubernetes NetworkPolicies for full egress control. * **The L5 `hold` label is applied by agent policy.** The hard guarantee at diff --git a/src/hive.yaml.example b/src/hive.yaml.example index 16fa81694e..409f501051 100644 --- a/src/hive.yaml.example +++ b/src/hive.yaml.example @@ -108,6 +108,17 @@ project: # sentinel: # trusted_authors_block: false # set true to block trusted authors too +# Optional observe-only session taint recorder (docs/design/session-taint.md). +# Default: off, and nothing is recorded. When enabled it keeps a bounded, +# in-memory record of coarse labels per agent session and logs and audits which +# rule WOULD have held a later relay write. It never blocks, holds or changes +# anything and stores labels, counts and ids only. Takes effect at restart. +# session_taint: +# enabled: false +# max_sessions: 256 +# max_labels_per_session: 32 +# max_decisions: 128 + # Hive-curated `good first issue` advertising (default ON; `enabled: false` # opts out). A periodic sweep scores open, unclaimed issues; the few that qualify get # GitHub's canonical `good first issue` + `help wanted` labels and ONE welcome diff --git a/src/pkg/config/config.go b/src/pkg/config/config.go index 1ac738ece0..fc4979e45e 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -157,6 +157,10 @@ type Config struct { // escalation or codebase damage, from any author. Default on; see // SentinelConfig. Sentinel SentinelConfig `yaml:"sentinel,omitempty" json:"sentinel,omitempty"` + + // SessionTaint is the observe-only session taint recorder (#18987). Off by + // default; see SessionTaintConfig. + SessionTaint SessionTaintConfig `yaml:"session_taint,omitempty" json:"session_taint,omitempty"` // Security holds the hive-wide security knobs that are not one agent's // or one sweep's; see SecurityConfig. Security SecurityConfig `yaml:"security,omitempty" json:"security,omitempty"` diff --git a/src/pkg/config/session_taint.go b/src/pkg/config/session_taint.go new file mode 100644 index 0000000000..b269c26504 --- /dev/null +++ b/src/pkg/config/session_taint.go @@ -0,0 +1,60 @@ +package config + +// SessionTaintConfig gates session taint (hivecommons/hive#18987, +// docs/design/session-taint.md, phase 0). Absent or `enabled: false` means the +// feature is not built at all: nothing is recorded, no lookup is made and every +// request and action behaves exactly as before. +// +// Phase 0 is OBSERVE-ONLY. With `enabled: true` the hive keeps a bounded, +// in-memory record of which coarse labels each agent session has accrued and +// which would-be verdicts a small fixed rule table gives to the agent's later +// relay writes. It writes those to the log and the audit log and never blocks, +// holds, restricts or alters anything. No credential or content value is ever +// stored: labels, counts and ids only. A change takes effect at the next +// restart, and a restart begins every session clean. +type SessionTaintConfig struct { + // Enabled turns the observer on. The default (false) is off. + Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"` + // MaxSessions bounds how many agent sessions are tracked at once; the + // least recently touched is evicted past it. Zero means + // DefaultSessionTaintMaxSessions. + MaxSessions int `yaml:"max_sessions,omitempty" json:"max_sessions,omitempty"` + // MaxLabelsPerSession bounds the labels one session holds. Zero means + // DefaultSessionTaintMaxLabelsPerSession. + MaxLabelsPerSession int `yaml:"max_labels_per_session,omitempty" json:"max_labels_per_session,omitempty"` + // MaxDecisions bounds the ring of recent would-act decisions kept in + // memory. Zero means DefaultSessionTaintMaxDecisions. + MaxDecisions int `yaml:"max_decisions,omitempty" json:"max_decisions,omitempty"` +} + +// The defaults mirror the observer's own bounds (crux/sessiontaint) so a hive +// that sets only `enabled: true` gets the documented limits. +const ( + DefaultSessionTaintMaxSessions = 256 + DefaultSessionTaintMaxLabelsPerSession = 32 + DefaultSessionTaintMaxDecisions = 128 +) + +// MaxSessionsOrDefault resolves MaxSessions; a non-positive value means the default. +func (c SessionTaintConfig) MaxSessionsOrDefault() int { + if c.MaxSessions <= 0 { + return DefaultSessionTaintMaxSessions + } + return c.MaxSessions +} + +// MaxLabelsPerSessionOrDefault resolves MaxLabelsPerSession. +func (c SessionTaintConfig) MaxLabelsPerSessionOrDefault() int { + if c.MaxLabelsPerSession <= 0 { + return DefaultSessionTaintMaxLabelsPerSession + } + return c.MaxLabelsPerSession +} + +// MaxDecisionsOrDefault resolves MaxDecisions. +func (c SessionTaintConfig) MaxDecisionsOrDefault() int { + if c.MaxDecisions <= 0 { + return DefaultSessionTaintMaxDecisions + } + return c.MaxDecisions +} diff --git a/src/pkg/config/session_taint_test.go b/src/pkg/config/session_taint_test.go new file mode 100644 index 0000000000..8d9fdecf4f --- /dev/null +++ b/src/pkg/config/session_taint_test.go @@ -0,0 +1,19 @@ +package config + +import "testing" + +func TestSessionTaintConfigDefaults(t *testing.T) { + var c SessionTaintConfig + if c.Enabled { + t.Error("default must be off") + } + if c.MaxSessionsOrDefault() != DefaultSessionTaintMaxSessions || + c.MaxLabelsPerSessionOrDefault() != DefaultSessionTaintMaxLabelsPerSession || + c.MaxDecisionsOrDefault() != DefaultSessionTaintMaxDecisions { + t.Error("zero values must resolve to the defaults") + } + c = SessionTaintConfig{MaxSessions: -1, MaxLabelsPerSession: 5, MaxDecisions: 7} + if c.MaxSessionsOrDefault() != DefaultSessionTaintMaxSessions || c.MaxLabelsPerSessionOrDefault() != 5 || c.MaxDecisionsOrDefault() != 7 { + t.Error("explicit positive values must be kept, non-positive ones defaulted") + } +} diff --git a/src/pkg/config/testdata/agent_runtime_golden.json b/src/pkg/config/testdata/agent_runtime_golden.json index 345f04714f..4bea69b2cc 100644 --- a/src/pkg/config/testdata/agent_runtime_golden.json +++ b/src/pkg/config/testdata/agent_runtime_golden.json @@ -716,6 +716,7 @@ "quality": {}, "intent": {}, "sentinel": {}, + "session_taint": {}, "security": {}, "evidence": { "complexity": {} diff --git a/src/pkg/dashboard/settings_parity_allowlist.txt b/src/pkg/dashboard/settings_parity_allowlist.txt index fac2e7641c..7e32c2f547 100644 --- a/src/pkg/dashboard/settings_parity_allowlist.txt +++ b/src/pkg/dashboard/settings_parity_allowlist.txt @@ -692,6 +692,10 @@ security.sensitive_paths[] # TODO #15640 self_experiments.scheduler.enabled # TODO #11854 self_experiments.scheduler.interval_s # TODO #11854 self_experiments.scheduler.mode # TODO #11854 +session_taint.enabled # observe-only recorder, yaml-only until its read-only view lands (#18987) +session_taint.max_decisions # bound on the in-memory decision ring; yaml-only (#18987) +session_taint.max_labels_per_session # bound on labels per session; yaml-only (#18987) +session_taint.max_sessions # bound on tracked sessions; yaml-only (#18987) shared_ci_rerun.enabled # TODO #11854 swarm.themes..call_to_arms # TODO #11854 swarm.themes..event_name # TODO #11854 diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index 7b65b65cf1..8865a8ad2e 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -20,6 +20,7 @@ import ( gh "github.com/google/go-github/v72/github" "github.com/hivecommons/hive/crux/logscrub" + "github.com/hivecommons/hive/crux/sessiontaint" "github.com/hivecommons/hive/pkg/attention" "github.com/hivecommons/hive/pkg/authorkind" "github.com/hivecommons/hive/pkg/config" @@ -198,6 +199,8 @@ type Client struct { canaryFailClosed bool canaryRegistry *ioscan.CanaryRegistry canaryLeakFunc func(ioscan.CanaryLeak) + sessionTaint *sessiontaint.Observer // nil unless session_taint.enabled; observe-only (#18987) + taintAudience taintAudienceCache appBotLogin string // "[bot]" when the client authenticates as a GitHub App appBotUserMu sync.Mutex appBotUserID int64 // cached GitHub user id of appBotLogin; see AppBotUserID diff --git a/src/pkg/github/issue_request_watcher.go b/src/pkg/github/issue_request_watcher.go index 5e1718f5d5..50140bfffd 100644 --- a/src/pkg/github/issue_request_watcher.go +++ b/src/pkg/github/issue_request_watcher.go @@ -17,6 +17,7 @@ import ( gh "github.com/google/go-github/v72/github" "github.com/hivecommons/hive/crux/logscrub" + "github.com/hivecommons/hive/crux/sessiontaint" "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/decisionpolicy" "github.com/hivecommons/hive/pkg/effects" @@ -1028,6 +1029,20 @@ func (c *Client) handleOneIssueRequestFrom(ctx context.Context, path string, src c.notifyAgentStart(req.Agent, req.Repo, req.Number, startSignal) } + // Session taint (#18987), observe only. Recorded once per relay write + // that completed, after every refusal, retry and dedupe gate, so the + // would-act data never describes an action the hive then refused or + // retried. A reused issue or comment published nothing new and is + // skipped. The enforcement phases move this check before the write. + if !resp.AlreadyExisted { + switch kind { + case "issue": + c.observeSessionTaint(ctx, req.Agent, sessiontaint.SinkRelayIssue, req.Repo) + case "comment": + c.observeSessionTaint(ctx, req.Agent, sessiontaint.SinkRelayComment, req.Repo) + } + } + action := AuditActionAgentIssueCreated switch kind { case "comment": diff --git a/src/pkg/github/pr_request_watcher.go b/src/pkg/github/pr_request_watcher.go index 9ec4a55f73..ee039edeff 100644 --- a/src/pkg/github/pr_request_watcher.go +++ b/src/pkg/github/pr_request_watcher.go @@ -11,6 +11,8 @@ import ( "strconv" "strings" "time" + + "github.com/hivecommons/hive/crux/sessiontaint" ) // PRRequestDir is where agents drop PR-open requests. An agent pushes its branch @@ -576,6 +578,12 @@ func (c *Client) handleOnePRRequest(ctx context.Context, path string, nowFn func c.failPRRequest(path, req, err, nowFn) return } + // Session taint (#18987), observe only. Recorded once per PR this request + // opened, after every gate; a reused or duplicate PR is not a new write. + // The enforcement phases move this check before the write. + if !res.AlreadyExisted && !res.IsDuplicate() { + c.observeSessionTaint(ctx, req.Agent, sessiontaint.SinkRelayPR, req.Repo) + } resp.OK = true resp.Number = res.Number resp.URL = res.URL diff --git a/src/pkg/github/review_request_watcher.go b/src/pkg/github/review_request_watcher.go index ba13890aa7..6590c45c74 100644 --- a/src/pkg/github/review_request_watcher.go +++ b/src/pkg/github/review_request_watcher.go @@ -13,6 +13,7 @@ import ( "time" gh "github.com/google/go-github/v72/github" + "github.com/hivecommons/hive/crux/sessiontaint" "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/effects" "github.com/hivecommons/hive/pkg/factcheck" @@ -709,6 +710,10 @@ func (c *Client) handleOneReviewRequest(ctx context.Context, path string, src re slog.String("repo", req.Repo), slog.Int("number", req.Number), slog.String("error", err.Error())) return } + // Session taint (#18987), observe only. Recorded once per review the hive + // completed, after every gate and retry. The enforcement phases move this + // check before the write. + c.observeSessionTaint(ctx, req.Agent, sessiontaint.SinkRelayReview, req.Repo) resp.OK = true resp.Number = req.Number resp.State = state diff --git a/src/pkg/github/session_taint.go b/src/pkg/github/session_taint.go new file mode 100644 index 0000000000..06fcccbaa0 --- /dev/null +++ b/src/pkg/github/session_taint.go @@ -0,0 +1,112 @@ +package github + +import ( + "context" + "strings" + "sync" + "time" + + "github.com/hivecommons/hive/crux/sessiontaint" +) + +// Session taint, phase 0 (hivecommons/hive#18987, docs/design/session-taint.md). +// +// The relay watchers call observeSessionTaint once a request has passed every +// existing gate, immediately before the hive acts on it. The call is +// observe-only: it returns nothing, runs after the authorizer, the write gate, +// the pause and the repository scope, and cannot change what the relay does +// next. With no observer installed (the shipped default) it is a nil check. + +const ( + // taintAudienceTTL bounds how long a destination's public/private answer + // is reused. A visibility change is noticed within this window. + taintAudienceTTL = time.Hour + // taintAudienceLookupTimeout bounds one repository lookup so a slow API + // cannot hold up a relay beyond it. + taintAudienceLookupTimeout = 5 * time.Second + // taintAudienceCacheMax bounds the cache; past it the cache is reset. + taintAudienceCacheMax = 512 +) + +type taintAudienceEntry struct { + audience sessiontaint.Audience + at time.Time +} + +// taintAudienceCache caches destination audiences. The zero value is ready. +// Failed lookups are never cached. +type taintAudienceCache struct { + mu sync.Mutex + entries map[string]taintAudienceEntry +} + +func (t *taintAudienceCache) get(repo string, now time.Time) (sessiontaint.Audience, bool) { + t.mu.Lock() + defer t.mu.Unlock() + e, ok := t.entries[repo] + if !ok || now.Sub(e.at) >= taintAudienceTTL { + return sessiontaint.AudiencePublic, false + } + return e.audience, true +} + +func (t *taintAudienceCache) put(repo string, a sessiontaint.Audience, now time.Time) { + t.mu.Lock() + defer t.mu.Unlock() + if t.entries == nil || len(t.entries) >= taintAudienceCacheMax { + t.entries = make(map[string]taintAudienceEntry) + } + t.entries[repo] = taintAudienceEntry{audience: a, at: now} +} + +// SetSessionTaint installs the observe-only session taint observer. A nil +// observer (the default) means the feature is off and nothing is recorded. +func (c *Client) SetSessionTaint(o *sessiontaint.Observer) { + if c == nil { + return + } + c.sessionTaint = o +} + +// observeSessionTaint reports one outbound relay action to the observer. It +// never fails, blocks or alters the request. +func (c *Client) observeSessionTaint(ctx context.Context, agent string, kind sessiontaint.SinkKind, repo string) { + if c == nil || c.sessionTaint == nil { + return + } + owner, name := c.splitRepo(repo) + dest := strings.TrimSpace(owner) + "/" + strings.TrimSpace(name) + c.sessionTaint.ObserveSink(agent, kind, dest, func(r string) sessiontaint.Audience { + return c.taintDestinationAudience(ctx, r) + }) +} + +// taintDestinationAudience resolves a destination repository's audience with +// the hive's own credential. A failed or incomplete lookup is public, the +// conservative answer for a destination (design: Visibility lookups), and is +// not cached. +func (c *Client) taintDestinationAudience(ctx context.Context, repo string) sessiontaint.Audience { + now := time.Now() + if a, ok := c.taintAudience.get(repo, now); ok { + return a + } + if c.client == nil { + return sessiontaint.AudiencePublic + } + owner, name, ok := strings.Cut(repo, "/") + if !ok || owner == "" || name == "" { + return sessiontaint.AudiencePublic + } + lctx, cancel := context.WithTimeout(ctx, taintAudienceLookupTimeout) + defer cancel() + r, _, err := c.client.Repositories.Get(lctx, owner, name) + if err != nil || r == nil || r.Private == nil { + return sessiontaint.AudiencePublic + } + aud := sessiontaint.AudiencePublic + if r.GetPrivate() { + aud = sessiontaint.AudiencePrivate + } + c.taintAudience.put(repo, aud, now) + return aud +} diff --git a/src/pkg/github/session_taint_test.go b/src/pkg/github/session_taint_test.go new file mode 100644 index 0000000000..755047a92f --- /dev/null +++ b/src/pkg/github/session_taint_test.go @@ -0,0 +1,97 @@ +package github + +import ( + "context" + "testing" + "time" + + "github.com/hivecommons/hive/crux/sessiontaint" +) + +func newTaintTestClient(t *testing.T, enabled bool) (*Client, *sessiontaint.Observer) { + t.Helper() + obs := sessiontaint.New(sessiontaint.Options{Enabled: enabled}) + c := &Client{} + c.SetSessionTaint(obs) + return c, obs +} + +// With no observer installed (the shipped default) the relay hook records +// nothing and is a safe no-op, including on a nil client. +func TestObserveSessionTaintOffRecordsNothing(t *testing.T) { + c, obs := newTaintTestClient(t, false) + if obs != nil { + t.Fatal("a disabled observer must be nil") + } + c.observeSessionTaint(context.Background(), "agent-a", sessiontaint.SinkRelayIssue, "o/r") + var nilClient *Client + nilClient.observeSessionTaint(context.Background(), "agent-a", sessiontaint.SinkRelayIssue, "o/r") + nilClient.SetSessionTaint(nil) + if st := obs.Stats(); st.SinksObserved != 0 || len(st.Recent) != 0 { + t.Errorf("stats = %+v, want zero", st) + } +} + +// A relay write by a session that holds a label is recorded as a would-hold +// and nothing else: the hook returns nothing, so the relay proceeds as before. +func TestObserveSessionTaintRecordsWouldHoldOnly(t *testing.T) { + c, obs := newTaintTestClient(t, true) + obs.RecordLabel("agent-a", sessiontaint.LabelSecret, "hive-canary", sessiontaint.SourceCanaryHit) + + // No GitHub client is attached, so the destination audience is + // unresolved and treated as public. + for _, kind := range []sessiontaint.SinkKind{ + sessiontaint.SinkRelayIssue, sessiontaint.SinkRelayComment, + sessiontaint.SinkRelayPR, sessiontaint.SinkRelayReview, + } { + c.observeSessionTaint(context.Background(), "agent-a", kind, "o/r") + } + // A session that read nothing is not recorded. + c.observeSessionTaint(context.Background(), "agent-b", sessiontaint.SinkRelayIssue, "o/r") + + st := obs.Stats() + if got := st.WouldAct[sessiontaint.RuleSecretPublicWrite]; got != 4 { + t.Errorf("would-act count = %d, want 4", got) + } + for _, d := range st.Recent { + if d.Agent != "agent-a" || d.Verdict != sessiontaint.VerdictHold || d.DestRepo != "o/r" { + t.Errorf("unexpected decision %+v", d) + } + } + if st.SinksClean != 1 { + t.Errorf("clean sinks = %d, want 1", st.SinksClean) + } +} + +func TestTaintAudienceCacheExpiresAndIsBounded(t *testing.T) { + var cache taintAudienceCache + now := time.Unix(1_700_000_000, 0) + if _, ok := cache.get("o/r", now); ok { + t.Fatal("empty cache returned a hit") + } + cache.put("o/r", sessiontaint.AudiencePrivate, now) + if a, ok := cache.get("o/r", now.Add(taintAudienceTTL-time.Second)); !ok || a != sessiontaint.AudiencePrivate { + t.Errorf("fresh entry = %v, %v", a, ok) + } + if _, ok := cache.get("o/r", now.Add(taintAudienceTTL)); ok { + t.Errorf("expired entry still served") + } + for i := 0; i < 3*taintAudienceCacheMax; i++ { + cache.put(string(rune('a'+i%26))+"/"+time.Duration(i).String(), sessiontaint.AudiencePublic, now) + } + if n := len(cache.entries); n > taintAudienceCacheMax { + t.Errorf("cache grew to %d, want at most %d", n, taintAudienceCacheMax) + } +} + +// A failed destination lookup is public and is never cached, so a transient +// error cannot pin a private repository as public for an hour. +func TestTaintDestinationAudienceUnresolvedIsPublicAndUncached(t *testing.T) { + c := &Client{} // no API client + if got := c.taintDestinationAudience(context.Background(), "o/r"); got != sessiontaint.AudiencePublic { + t.Errorf("audience = %v, want public", got) + } + if n := len(c.taintAudience.entries); n != 0 { + t.Errorf("failed lookup was cached (%d entries)", n) + } +}