observe

Documentation

Overview

Package observe holds the THREE pure observable force-escalate predicates the cascade's structural-confidence gate scores, plus every helper / threshold / map they read — extracted VERBATIM from core/eval/scenario_tools.go so that the eval scenarioToolRunner AND the production core/toolrun.Runner call ONE shared implementation and get BYTE-IDENTICAL booleans + details.

THE DIVERGENCE THIS CLOSES (the veracity flag): before this package the observable predicates lived only in core/eval. The production cascade reached tools through the SAME agent.ToolRunner seam but had no live runner — and any future prod runner that re-implemented these predicates could drift from the eval's, silently breaking the validated 83.9% / 2-missed-attacks number. With the predicates as FREE functions here, a single change moves both runners together: there is exactly one source of truth.

PURITY / IMPORT DISCIPLINE: every function here is pure over its inputs — (actor string, *baseline.Baseline, []tools.EventView) — exactly what BOTH runners already hold. The package imports ONLY core/tools (for tools.EventView) and pkg/baseline (for baseline.Relationship/Baseline). It MUST NOT import core/agent, core/eval, core/store, core/pipeline, exam, or any orchestration / transport / vendor SDK (see imports_test.go). It opens no store, makes no inference call, and touches no shared mutable state.

EXTRACTION-NOT-REWRITE: the bodies below are the eval bodies moved verbatim — every comparison, threshold, map entry, and edge case preserved so behavior is byte-identical. The only mechanical change is the method receiver (r.actor → the actor parameter, r.baseline → the b parameter); the logic is untouched.

Index

• func ActorRoleGrantFrequency(actor string, b *baseline.Baseline) int
• func BulkExportNoJustification(actor string, events []tools.EventView) (bool, string)
• func RoleGrantByActor(actor string, b *baseline.Baseline, events []tools.EventView) (bool, string)
• func ZeroHistoryAccess(actor string, b *baseline.Baseline, events []tools.EventView) (bool, string)

Functions

func ActorRoleGrantFrequency

func ActorRoleGrantFrequency(actor string, b *baseline.Baseline) int

ActorRoleGrantFrequency returns the finding actor's baseline frequency for role-grant event types, summed across the role-grant type keys. A frequency table key has the shape "<source>:<event_type>:<actor>" or "<source>:<event_type>" (the exam seeds the latter); we sum any key whose event_type segment is a role-grant type AND that references the actor. 0 means "no role-grant precedent".

func BulkExportNoJustification

func BulkExportNoJustification(actor string, events []tools.EventView) (bool, string)

BulkExportNoJustification (FIX 4) reports whether the surfaced events show a HIGH-VOLUME read / PII / secret export performed by the finding actor with NO legitimate-justification companion event. It is a TERMINAL escalate (the discriminator is the ACTION, model-independent): it restores URA-03's floor and catches ND-01 (2am PII export, no ticket) + IT-03 (bulk subscription sweep, no justification). It does NOT fire when a justification companion is present, so the benign high-volume scenarios (CC-01/CC-02/VA-02/VA-05) are excluded.

The justification scan is over ALL surfaced events (not just the bulk event): CC-02's release_started companion carries window_id on a DIFFERENT event than the volume burst, and the doc's "no business justification" test is at the FINDING level — "is there ANY explanation in this finding's events". The bulk-signal scan is restricted to events AUTHORED BY the finding actor (the actor under investigation actually performed the export).

func RoleGrantByActor

func RoleGrantByActor(actor string, b *baseline.Baseline, events []tools.EventView) (bool, string)

RoleGrantByActor (FIX 3b) reports whether the surfaced events show the FINDING ACTOR performing a role-grant / privilege event (event_type role_assignment, or action add_role_assignment) for which it has NO baseline history of granting roles. UT-01 / IT-02: admin-user (the finding actor) grants a role with a role_assignment baseline frequency of 0. ID-01 is NOT caught: there the role grant is authored by admin-user (a KNOWN role-granter with frequency 28), NOT by the finding actor deploy-svc-new — so the finding actor performed no grant.

func ZeroHistoryAccess

func ZeroHistoryAccess(actor string, b *baseline.Baseline, events []tools.EventView) (bool, string)

ZeroHistoryAccess (FIX 3a) reports whether the finding actor, in the surfaced events, accessed a target with which it has ZERO relationship history (no relationship record, or a record with count 0). VA-03: ci-bot reads storage targets absent from its (deploy-only) relationship set. CO-02: deploy-svc bulk-reads a target outside its established relationships. VA-01 is NOT caught: every deploy target is in deploy-svc's relationships with a positive count.

It considers only events AUTHORED BY the finding actor (the actor under investigation actually performed the access) and only events carrying a target (a login/health-check with no resource target is not an "access"). The first zero-history target found is named in the detail for the audit trail.