The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
feat(threat-rules): an event scanner, prepared events and a step matcher for correlation rules (#1243)
kyle-elliott-asymptotebf851f2e21e9
diff --git a/pkg/asymptoteobserve/threatrules/cel.go b/pkg/asymptoteobserve/threatrules/cel.goindex 32a3dadd..6a46ddf7 100644--- a/pkg/asymptoteobserve/threatrules/cel.go+++ b/pkg/asymptoteobserve/threatrules/cel.go@@ -173,8 +173,8 @@ func selectsField(ast *cel.Ast, name string) bool {//// Derived fields (see DerivedFields) are filled on a copy of the event first, so a caller// holding only a program sees the same values a CompiledRule does. CompiledRule skips that-// step for rules that never reference a derived field, and ScanEvents does it once per event-// for all the rules that do.+// step for rules that never reference a derived field, and ScanEvents and EventScanner do it+// once per event for all the rules that do.func EvalMatch(prog cel.Program, event asymptoteobserve.Event) (bool, error) {return evalMatch(prog, newEventActivation(withDerivedFields(event)))}diff --git a/pkg/asymptoteobserve/threatrules/fastpath_test.go b/pkg/asymptoteobserve/threatrules/fastpath_test.goindex dc92a7fc..ac36b4b4 100644--- a/pkg/asymptoteobserve/threatrules/fastpath_test.go+++ b/pkg/asymptoteobserve/threatrules/fastpath_test.go@@ -397,23 +397,65 @@ func agree(t testing.TB, what string, fast, reference []*CompiledRule, events []got, gotErr := ScanEvents(fast, events)want, wantErr := ScanEvents(reference, events)same("as one log", got, want, gotErr, wantErr)- scanner := newEventScanner(singleEventRules(fast))+ scanner, err := NewEventScanner(singleEventRules(fast))+ if err != nil {+ t.Fatal(err)+ }singleReference := singleEventRules(reference)+ steps, err := NewStepMatcher(correlationRules(fast))+ if err != nil {+ t.Fatal(err)+ }+ referenceSteps := correlationRules(reference)for i, e := range events {what := fmt.Sprintf("event %d (%s) alone", i, e.Event.Action)- var got []Finding- gotErr := scanner.scan(&eventInput{event: &e}, func(r int) {- got = append(got, scanner.rules[r].newFinding([]asymptoteobserve.Event{e}))- })- if gotErr != nil {- got = nil- }+ got, gotErr := scanner.ScanEvent(e)want, wantErr := ScanEvents(singleReference, []asymptoteobserve.Event{e})same(what, got, want, gotErr, wantErr)+ // The prepared event is scanned, then its steps matched, on one set of activations.+ p := PrepareEvent(e)+ got, gotErr = scanner.ScanPrepared(p)+ same(what+", prepared", got, want, gotErr, wantErr)+ any, anyErr := steps.AnyStep(p)+ wantAny, wantAnyErr := anyStepReference(referenceSteps, e)+ if any != wantAny || fmt.Sprint(anyErr) != fmt.Sprint(wantAnyErr) {+ t.Fatalf("%s: AnyStep %v, %v; reference %v, %v", what, any, anyErr, wantAny, wantAnyErr)+ }}return findings, errs}+func correlationRules(rules []*CompiledRule) []*CompiledRule {+ var out []*CompiledRule+ for _, r := range rules {+ if r.steps != nil {+ out = append(out, r)+ }+ }+ return out+}++// anyStepReference evaluates every step of every rule on the event as the correlation evaluator+// does (CompiledRule.eval): true when one holds, otherwise the first failure in rule and step order.+func anyStepReference(rules []*CompiledRule, e asymptoteobserve.Event) (bool, error) {+ var first error+ for _, r := range rules {+ for i, st := range r.steps {+ matched, err := r.eval(st, e)+ if err != nil {+ if first == nil {+ first = fmt.Errorf("rule %q step %q: %w", r.rule.ID, r.rule.Correlation.Steps[i].ID, err)+ }+ continue+ }+ if matched {+ return true, nil+ }+ }+ }+ return false, first+}+func findingRuleIDs(fs []Finding) []string {ids := make([]string, len(fs))for i, f := range fs {@@ -715,3 +757,9 @@ func TestFastEnvIsInstalled(t *testing.T) {t.Fatalf("Env adapts values with %T", env.CELTypeAdapter())}}++func TestEventScannerRejectsCorrelationRules(t *testing.T) {+ if _, err := NewEventScanner([]*CompiledRule{readThenEgressRule(t)}); err == nil {+ t.Fatal("NewEventScanner accepted a correlation rule")+ }+}diff --git a/pkg/asymptoteobserve/threatrules/findings.go b/pkg/asymptoteobserve/threatrules/findings.goindex 8eceecfb..4d75e367 100644--- a/pkg/asymptoteobserve/threatrules/findings.go+++ b/pkg/asymptoteobserve/threatrules/findings.go@@ -125,9 +125,9 @@ func (c *CompiledRule) newFinding(evidence []asymptoteobserve.Event) Finding {// ScanEvents runs every compiled rule over the events and returns all findings, in rule// order. It is the aggregator backing the `beacon scan` command.//-// Single-event rules run event by event through an event scanner (scan.go): only the rules that-// can match an event's action are evaluated, and an event's derived fields (a parsed command line,-// a tool result's text) are computed once for every rule that references them, not once per rule,+// Single-event rules run event by event, as an EventScanner runs them: only the rules that can+// match an event's action are evaluated, and an event's derived fields (a parsed command line, a+// tool result's text) are computed once for every rule that references them, not once per rule,// and dropped before the next event. Correlation rules run after, each over the whole sequence.func ScanEvents(rules []*CompiledRule, events []asymptoteobserve.Event) ([]Finding, error) {found := make([][]Finding, len(rules))diff --git a/pkg/asymptoteobserve/threatrules/scan.go b/pkg/asymptoteobserve/threatrules/scan.goindex a5e0a1ef..b611e594 100644--- a/pkg/asymptoteobserve/threatrules/scan.go+++ b/pkg/asymptoteobserve/threatrules/scan.go@@ -3,15 +3,18 @@ package threatrulesimport ("fmt""slices"++ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve")-// eventScanner runs single-event rules against one event at a time. It is built once and is safe-// for concurrent use.+// EventScanner runs single-event rules against one event at a time, for a caller that judges+// events as they arrive rather than scanning a log. It is built once and is safe for concurrent+// use.//// For each event it evaluates only the rules that can match the event's action (see// eventActions), and every rule reads the event through one activation, so the event's derived// fields are worked out once, and only when a rule that reads them is evaluated.-type eventScanner struct {+type EventScanner struct {rules []*CompiledRule// byAction lists, for each action some rule is limited to, the rules that can match an event// with that action, in rule order; anyAction lists them for every other action.@@ -19,8 +22,19 @@ type eventScanner struct {anyAction []int}-func newEventScanner(rules []*CompiledRule) *eventScanner {- s := &eventScanner{rules: rules, byAction: map[string][]int{}}+// NewEventScanner returns a scanner over single-event rules. A correlation rule needs the events+// of a session and is rejected.+func NewEventScanner(rules []*CompiledRule) (*EventScanner, error) {+ for _, r := range rules {+ if r.steps != nil {+ return nil, fmt.Errorf("rule %q is a correlation rule; an event scanner runs single-event rules", r.rule.ID)+ }+ }+ return newEventScanner(rules), nil+}++func newEventScanner(rules []*CompiledRule) *EventScanner {+ s := &EventScanner{rules: rules, byAction: map[string][]int{}}for i, r := range rules {if r.match.actions == nil {s.anyAction = append(s.anyAction, i)@@ -40,9 +54,44 @@ func newEventScanner(rules []*CompiledRule) *eventScanner {return s}-// scan calls hit with the index of every rule that matches the event, in rule order. An-// evaluation error (such as one that exceeded MaxEvalCost) fails the scan and names the rule.-func (s *eventScanner) scan(in *eventInput, hit func(rule int)) error {+// ScanEvent returns a finding for every rule that matches the event, in rule order, with the event+// as evidence: what ScanEvents returns for the same rules and this one event. An evaluation error+// (such as one that exceeded MaxEvalCost) fails the scan and names the rule.+func (s *EventScanner) ScanEvent(event asymptoteobserve.Event) ([]Finding, error) {+ return s.ScanPrepared(PrepareEvent(event))+}++// ScanPrepared is ScanEvent for a prepared event, whose activations, derived fields and size tier+// are then shared with whatever else evaluates it (StepMatcher.AnyStep).+func (s *EventScanner) ScanPrepared(p *PreparedEvent) ([]Finding, error) {+ var findings []Finding+ err := s.scan(&p.in, func(r int) {+ findings = append(findings, s.rules[r].newFinding([]asymptoteobserve.Event{p.event}))+ })+ if err != nil {+ return nil, err+ }+ return findings, nil+}++// PreparedEvent is one event ready for evaluation by an EventScanner and a StepMatcher. What+// evaluating it needs (its binding, its derived fields, the size tier that decides untracked+// evaluation, the canonical text prefilters search) is worked out on first use and shared by every+// rule and step evaluated on it. It is not safe for concurrent use.+type PreparedEvent struct {+ event asymptoteobserve.Event+ in eventInput+}++// PrepareEvent prepares an event for evaluation; nothing is computed until a rule needs it.+func PrepareEvent(event asymptoteobserve.Event) *PreparedEvent {+ p := &PreparedEvent{event: event}+ p.in.event = &p.event+ return p+}++// scan calls hit with the index of every rule that matches the event, in rule order.+func (s *EventScanner) scan(in *eventInput, hit func(rule int)) error {candidates, ok := s.byAction[in.event.Event.Action]if !ok {candidates = s.anyActiondiff --git a/pkg/asymptoteobserve/threatrules/scan_bench_test.go b/pkg/asymptoteobserve/threatrules/scan_bench_test.goindex 8aa62fb4..0c14eae9 100644--- a/pkg/asymptoteobserve/threatrules/scan_bench_test.go+++ b/pkg/asymptoteobserve/threatrules/scan_bench_test.go@@ -47,17 +47,15 @@ func BenchmarkScanEvent(b *testing.B) {}single = append(single, c)}- scanner := newEventScanner(single)+ scanner, err := NewEventScanner(single)+ if err != nil {+ b.Fatal(err)+ }for _, bc := range scanBenchEvents(b) {b.Run(bc.name, func(b *testing.B) {b.ReportAllocs()for b.Loop() {- var findings []Finding- e := bc.event- err := scanner.scan(&eventInput{event: &e}, func(r int) {- findings = append(findings, single[r].newFinding([]asymptoteobserve.Event{e}))- })- if err != nil {+ if _, err := scanner.ScanEvent(bc.event); err != nil {b.Fatal(err)}}diff --git a/pkg/asymptoteobserve/threatrules/stepmatch.go b/pkg/asymptoteobserve/threatrules/stepmatch.gonew file mode 100644index 00000000..63eb4ae4--- /dev/null+++ b/pkg/asymptoteobserve/threatrules/stepmatch.go@@ -0,0 +1,86 @@+package threatrules++import (+ "fmt"+ "slices"+)++// StepMatcher reports whether an event matches any step of a set of correlation rules: whether a+// caller that keeps events for those rules needs to keep this one. Steps with the same expression,+// read on the same form of the event, are evaluated once. It is built once and is safe for+// concurrent use.+type StepMatcher struct {+ steps []step+ byAction map[string][]int // as EventScanner's, over steps+ anyAction []int+}++type step struct {+ match matcher+ derived bool // the step's rule reads derived fields, so the step reads the derived event+ name string+}++// NewStepMatcher returns a matcher over the steps of correlation rules, in rule and step order.+// A single-event rule has no steps and is rejected.+func NewStepMatcher(rules []*CompiledRule) (*StepMatcher, error) {+ m := &StepMatcher{byAction: map[string][]int{}}+ seen := map[[2]any]bool{}+ for _, r := range rules {+ if r.steps == nil {+ return nil, fmt.Errorf("rule %q is a single-event rule; a step matcher runs correlation steps", r.rule.ID)+ }+ for i, st := range r.rule.Correlation.Steps {+ key := [2]any{st.Match, r.derived}+ if seen[key] {+ continue+ }+ seen[key] = true+ m.steps = append(m.steps, step{match: r.steps[i], derived: r.derived, name: fmt.Sprintf("rule %q step %q", r.rule.ID, st.ID)})+ }+ }+ for i, st := range m.steps {+ if st.match.actions == nil {+ m.anyAction = append(m.anyAction, i)+ }+ }+ for i, st := range m.steps {+ for action := range st.match.actions {+ if _, ok := m.byAction[action]; !ok {+ m.byAction[action] = slices.Clone(m.anyAction)+ }+ m.byAction[action] = append(m.byAction[action], i)+ }+ }+ for _, ss := range m.byAction {+ slices.Sort(ss)+ }+ return m, nil+}++// AnyStep reports whether some step's match holds for the event, stopping at the first that does.+// A step whose evaluation fails does not hide a later one that matches: the result is true when any+// step evaluates to true, as each rule's own evaluation would find it. Only when none does is the+// first failure returned, naming its rule and step.+func (m *StepMatcher) AnyStep(p *PreparedEvent) (bool, error) {+ candidates, ok := m.byAction[p.event.Event.Action]+ if !ok {+ candidates = m.anyAction+ }+ var first error+ for _, i := range candidates {+ st := &m.steps[i]+ act := p.in.activation(st.derived)+ matched, err := evalObserved(st.match.program(act), act)+ if err != nil {+ if first == nil {+ first = fmt.Errorf("%s: %w", st.name, err)+ }+ continue+ }+ if matched {+ return true, nil+ }+ }+ return false, first+}diff --git a/pkg/asymptoteobserve/threatrules/stepmatch_test.go b/pkg/asymptoteobserve/threatrules/stepmatch_test.gonew file mode 100644index 00000000..3a824e57--- /dev/null+++ b/pkg/asymptoteobserve/threatrules/stepmatch_test.go@@ -0,0 +1,127 @@+package threatrules++import (+ "strings"+ "testing"++ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"+)++// A step that fails does not hide a later step that matches; with none matching, the first failure+// is returned, naming its rule and step. Rules that are not correlations are rejected.+func TestAnyStepErrors(t *testing.T) {+ lowerCostLimit(t)+ compile := func(id string, steps ...CorrelationStep) *CompiledRule {+ c, err := Compile(&Rule{+ ID: id, Spec: SupportedSpec, Version: 1, Title: "x",+ Severity: asymptoteobserve.SeverityHigh, Status: StatusExperimental, Posture: PostureDetect,+ Emit: Emit{Reason: "x"},+ Correlation: &Correlation{Scope: ScopeSession, Window: "60s", Steps: steps},+ Tests: []Fixture{{Name: "x", Verdict: VerdictNoMatch, Events: []FixtureEvent{{Event: corrEvent("", "z", "s", nil)}}}},+ })+ if err != nil {+ t.Fatal(err)+ }+ return c+ }+ runaway := compile("runaway", CorrelationStep{ID: "slow", Match: nestedAll(7)}, CorrelationStep{ID: "b", Match: `e.event.action == "b"`})+ later := compile("later", CorrelationStep{ID: "a", Match: `e.event.action == "a"`}, CorrelationStep{ID: "c", Match: `e.event.action == "c"`})+ m, err := NewStepMatcher([]*CompiledRule{runaway, later})+ if err != nil {+ t.Fatal(err)+ }+ if ok, err := m.AnyStep(PrepareEvent(corrEvent("", "a", "s", nil))); !ok || err != nil {+ t.Fatalf("AnyStep = %v, %v; want the later step's match", ok, err)+ }+ // "y" makes the nested all() run every iteration (it stops early on action "x").+ ok, err := m.AnyStep(PrepareEvent(corrEvent("", "y", "s", nil)))+ if ok || err == nil || !strings.Contains(err.Error(), `rule "runaway" step "slow"`) || !strings.Contains(err.Error(), "cost limit exceeded") {+ t.Fatalf("AnyStep = %v, %v; want the runaway step's error", ok, err)+ }+ single, err := Compile(validSingleEventRule())+ if err != nil {+ t.Fatal(err)+ }+ if _, err := NewStepMatcher([]*CompiledRule{single}); err == nil {+ t.Fatal("NewStepMatcher accepted a single-event rule")+ }+}++// BenchmarkPreparedSteps judges one event with the single-event rules and asks whether it matches a+// step of a correlation rule, three ways: the single-event rules alone (ScanEvent); those, then+// every distinct step evaluated on its own (ScanEvent+steps, each step binding and deriving the+// event again); and one prepared event for both, stopping at the first step that holds+// (Prepared+AnyStep).+func BenchmarkPreparedSteps(b *testing.B) {+ var single, corr []*CompiledRule+ for _, r := range corpusRules(b) {+ c, err := Compile(r)+ if err != nil {+ b.Fatalf("%s: %v", r.ID, err)+ }+ if c.steps == nil {+ single = append(single, c)+ } else {+ corr = append(corr, c)+ }+ }+ scanner, err := NewEventScanner(single)+ if err != nil {+ b.Fatal(err)+ }+ steps, err := NewStepMatcher(corr)+ if err != nil {+ b.Fatal(err)+ }+ type distinct struct {+ rule *CompiledRule+ step matcher+ }+ var each []distinct+ seen := map[string]bool{}+ for _, c := range corr {+ for i, st := range c.rule.Correlation.Steps {+ if !seen[st.Match] {+ seen[st.Match] = true+ each = append(each, distinct{c, c.steps[i]})+ }+ }+ }+ events := scanBenchEvents(b)+ events = append(events, namedEvent{"file.read_call", decodeBenchEvent(b, `{"timestamp":"2023-11-14T22:13:20.000000000Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","severity":"info","harness":{"name":"claude_code","version":"2.1.306"},"session":{"id":"a0"},"event":{"kind":"agent_runtime","action":"file.read","category":"file","fidelity":"inferred"},"tool":{"name":"Read","path":"/home/dev/project/internal/cache/lru.go"},"file":{"path":"/home/dev/project/internal/cache/lru.go","operation":"read"},"gen_ai":{"conversation":{"id":"a0"},"tool":{"name":"Read","call":{"id":"toolu_7c20e02dae62425abf1f477f","arguments":"{\"file_path\":\"/home/dev/project/internal/cache/lru.go\",\"limit\":200}"}}},"model":"claude-sonnet-4-5-20250929"}`)})+ for _, bc := range events {+ b.Run(bc.name+"/ScanEvent", func(b *testing.B) {+ b.ReportAllocs()+ for b.Loop() {+ if _, err := scanner.ScanEvent(bc.event); err != nil {+ b.Fatal(err)+ }+ }+ })+ b.Run(bc.name+"/ScanEvent+steps", func(b *testing.B) {+ b.ReportAllocs()+ for b.Loop() {+ if _, err := scanner.ScanEvent(bc.event); err != nil {+ b.Fatal(err)+ }+ for _, d := range each {+ if _, err := d.rule.eval(d.step, bc.event); err != nil {+ b.Fatal(err)+ }+ }+ }+ })+ b.Run(bc.name+"/Prepared+AnyStep", func(b *testing.B) {+ b.ReportAllocs()+ for b.Loop() {+ p := PrepareEvent(bc.event)+ if _, err := scanner.ScanPrepared(p); err != nil {+ b.Fatal(err)+ }+ if _, err := steps.AnyStep(p); err != nil {+ b.Fatal(err)+ }+ }+ })+ }+}