Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

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.go
index 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.go
index 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.go
index 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.go
index a5e0a1ef..b611e594 100644
--- a/pkg/asymptoteobserve/threatrules/scan.go
+++ b/pkg/asymptoteobserve/threatrules/scan.go
@@ -3,15 +3,18 @@ package threatrules
import (
"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.anyAction
diff --git a/pkg/asymptoteobserve/threatrules/scan_bench_test.go b/pkg/asymptoteobserve/threatrules/scan_bench_test.go
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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)
+ }
+ }
+ })
+ }
+}