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(rules): threat-rules/v1.1 with a per-rule spec version gate (#701)
Claude718e1a322993
diff --git a/cli/beacon/cmd/rules.go b/cli/beacon/cmd/rules.goindex 1b862941..7aab4a89 100644--- a/cli/beacon/cmd/rules.go+++ b/cli/beacon/cmd/rules.go@@ -49,10 +49,11 @@ var rulesListCmd = &cobra.Command{Short: "List the active threat-detection rules",SilenceUsage: true,RunE: func(cmd *cobra.Command, args []string) error {- loaded, err := detect.LoadActive(rulesUserMode(), "")+ loaded, skipped, err := detect.LoadActiveSkipping(rulesUserMode(), "")if err != nil {return err}+ detect.WarnSkipped(cmd.ErrOrStderr(), skipped)out := cmd.OutOrStdout()if len(loaded) == 0 {fmt.Fprintln(out, "No rules.")@@ -72,10 +73,11 @@ var rulesAddCmd = &cobra.Command{Args: cobra.ExactArgs(1),SilenceUsage: true,RunE: func(cmd *cobra.Command, args []string) error {- installed, err := detect.InstallFiles(rulesUserMode(), args[0], rulesOpts.force)+ installed, skipped, err := detect.InstallFilesSkipping(rulesUserMode(), args[0], rulesOpts.force)if err != nil {return err}+ detect.WarnSkipped(cmd.ErrOrStderr(), skipped)out := cmd.OutOrStdout()for _, in := range installed {fmt.Fprintf(out, "installed %s -> %s\n", in.ID, in.Path)@@ -162,10 +164,11 @@ func runRulesPull(cmd *cobra.Command, args []string) error {return fmt.Errorf("unsupported url: expected a .rule.yaml or .tar.gz/.tgz pack")}- installed, err := detect.InstallFiles(rulesUserMode(), src, rulesOpts.force)+ installed, skipped, err := detect.InstallFilesSkipping(rulesUserMode(), src, rulesOpts.force)if err != nil {return err}+ detect.WarnSkipped(cmd.ErrOrStderr(), skipped)for _, in := range installed {fmt.Fprintf(out, "installed %s -> %s\n", in.ID, in.Path)}@@ -288,30 +291,40 @@ var rulesFieldsCmd = &cobra.Command{},}-func loadRuleFiles(path string) ([]*threatrules.Rule, error) {+// loadRuleFiles loads a rule file or directory for lint. Rules that need a newer spec+// than this binary supports come back in skipped rather than failing the load.+func loadRuleFiles(path string) ([]*threatrules.Rule, []threatrules.SkippedRule, error) {info, err := os.Stat(path)if err != nil {- return nil, err+ return nil, nil, err}if info.IsDir() {- return threatrules.LoadDir(path)+ return threatrules.LoadDirSkipping(path)}rule, err := threatrules.LoadRule(path)+ if unsupported, ok := threatrules.AsUnsupportedSpec(err); ok {+ return nil, []threatrules.SkippedRule{{Path: path, Err: unsupported}}, nil+ }if err != nil {- return nil, err+ return nil, nil, err}- return []*threatrules.Rule{rule}, nil+ return []*threatrules.Rule{rule}, nil, nil}func lintRulesPath(cmd *cobra.Command, path string) error {out := cmd.OutOrStdout()- rules, err := loadRuleFiles(path)+ rules, skipped, err := loadRuleFiles(path)if err != nil {return fmt.Errorf("load rules: %w", err)}- if len(rules) == 0 {+ if len(rules) == 0 && len(skipped) == 0 {return fmt.Errorf("no *.rule.yaml files found under %s", filepath.Clean(path))}+ // Lint cannot vouch for a rule it cannot evaluate, so a skip fails the run, but the+ // rest of the pack is still checked.+ for _, s := range skipped {+ fmt.Fprintf(out, "SKIP %s\n", s)+ }failures, fixtures := 0, 0for _, rule := range rules {@@ -334,9 +347,16 @@ func lintRulesPath(cmd *cobra.Command, path string) error {fmt.Fprintf(out, "ok %s (%d fixtures)\n", rule.ID, len(results))}}- fmt.Fprintf(out, "\n%d rule(s), %d fixture(s), %d failure(s)\n", len(rules), fixtures, failures)- if failures > 0 {+ if len(skipped) > 0 {+ fmt.Fprintf(out, "\n%d rule(s), %d fixture(s), %d failure(s), %d skipped (need a newer Beacon)\n", len(rules), fixtures, failures, len(skipped))+ } else {+ fmt.Fprintf(out, "\n%d rule(s), %d fixture(s), %d failure(s)\n", len(rules), fixtures, failures)+ }+ switch {+ case failures > 0:return fmt.Errorf("%d failure(s)", failures)+ case len(skipped) > 0:+ return fmt.Errorf("%d rule(s) need a newer Beacon (supports up to %s)", len(skipped), threatrules.SupportedSpec)}return nil}diff --git a/cli/beacon/cmd/rules_test.go b/cli/beacon/cmd/rules_test.goindex 36db706b..de762ad7 100644--- a/cli/beacon/cmd/rules_test.go+++ b/cli/beacon/cmd/rules_test.go@@ -77,6 +77,49 @@ func TestRulesLintFailsOnFixtureMismatch(t *testing.T) {}}+// newerSpecRuleYAML declares a spec newer than this binary supports.+var newerSpecRuleYAML = strings.Replace(strings.Replace(validRuleYAML, "id: cli-test-rule\n", "id: cli-future-rule\nspec: threat-rules/v1.9\n", 1),+ "emit:", "future_field: true\nemit:", 1)++const upgradeMessage = `rule "cli-future-rule" requires threat-rules/v1.9, but this Beacon supports up to threat-rules/v1.1; upgrade Beacon to load it`++func TestRulesLintReportsNewerSpecAsSkip(t *testing.T) {+ dir := t.TempDir()+ writeRuleFile(t, dir, "ok.rule.yaml", validRuleYAML)+ writeRuleFile(t, dir, "future.rule.yaml", newerSpecRuleYAML)+ cmd, buf := newCmd()+ err := lintRulesPath(cmd, dir)+ if err == nil || !strings.Contains(err.Error(), "need a newer Beacon") {+ t.Fatalf("want a newer-Beacon lint error, got %v\n%s", err, buf.String())+ }+ out := buf.String()+ if !strings.Contains(out, "ok cli-test-rule") {+ t.Errorf("the rest of the pack should still be linted:\n%s", out)+ }+ if !strings.Contains(out, "SKIP ") || !strings.Contains(out, "future.rule.yaml: "+upgradeMessage) {+ t.Errorf("want a SKIP line with the upgrade message:\n%s", out)+ }+}++func TestRulesAddSkipsNewerSpec(t *testing.T) {+ testenv.SetHome(t, t.TempDir())+ src := t.TempDir()+ writeRuleFile(t, src, "ok.rule.yaml", validRuleYAML)+ writeRuleFile(t, src, "future.rule.yaml", newerSpecRuleYAML)+ cmd, buf := newCmd()+ rulesOpts.userMode, rulesOpts.systemMode, rulesOpts.force = true, false, false+ if err := rulesAddCmd.RunE(cmd, []string{src}); err != nil {+ t.Fatalf("rules add: %v\n%s", err, buf.String())+ }+ out := buf.String()+ if !strings.Contains(out, "installed cli-test-rule") || !strings.Contains(out, "1 rule(s) installed.") {+ t.Errorf("want the current rule installed:\n%s", out)+ }+ if !strings.Contains(out, "warning: skipped ") || !strings.Contains(out, upgradeMessage) {+ t.Errorf("want a skip warning with the upgrade message:\n%s", out)+ }+}+func TestRulesLintEmptyDir(t *testing.T) {cmd, _ := newCmd()if err := lintRulesPath(cmd, t.TempDir()); err == nil {@@ -235,9 +278,9 @@ func TestRulesPullRejectsUnsupportedPath(t *testing.T) {func TestLoadRuleFilesSingleFile(t *testing.T) {dir := t.TempDir()p := writeRuleFile(t, dir, "ok.rule.yaml", validRuleYAML)- rules, err := loadRuleFiles(p)- if err != nil {- t.Fatalf("loadRuleFiles single: %v", err)+ rules, skipped, err := loadRuleFiles(p)+ if err != nil || len(skipped) != 0 {+ t.Fatalf("loadRuleFiles single: %v (skipped %v)", err, skipped)}if len(rules) != 1 || rules[0].ID != "cli-test-rule" {t.Fatalf("unexpected: %+v", rules)diff --git a/cli/beacon/cmd/scan.go b/cli/beacon/cmd/scan.goindex 10efd8c5..3e2fc739 100644--- a/cli/beacon/cmd/scan.go+++ b/cli/beacon/cmd/scan.go@@ -76,10 +76,11 @@ func runScan(cmd *cobra.Command, args []string) error {}// Load and compile the active rule set.- loaded, err := detect.LoadActive(userMode, strings.TrimSpace(scanOpts.rulesDir))+ loaded, skipped, err := detect.LoadActiveSkipping(userMode, strings.TrimSpace(scanOpts.rulesDir))if err != nil {return fmt.Errorf("load rules: %w", err)}+ detect.WarnSkipped(cmd.ErrOrStderr(), skipped)if len(loaded) == 0 {return fmt.Errorf("no rules to run (store is empty and baseline missing)")}diff --git a/cli/beacon/cmd/scan_test.go b/cli/beacon/cmd/scan_test.goindex cda35c12..983f8fe1 100644--- a/cli/beacon/cmd/scan_test.go+++ b/cli/beacon/cmd/scan_test.go@@ -174,3 +174,31 @@ func TestScanMinSeverityFilters(t *testing.T) {t.Fatalf("expected high finding filtered by --min-severity critical, got:\n%s", buf.String())}}++func TestScanSkipsNewerSpecRuleWithWarning(t *testing.T) {+ scanFixture(t, []string{evSecretRead})+ future := strings.Replace(strings.Replace(scanTestRule, "id: scan-test-secret-read\n", "id: scan-future-rule\nspec: threat-rules/v2\n", 1),+ "emit:", "future_field: true\nemit:", 1)+ if err := os.WriteFile(filepath.Join(scanOpts.rulesDir, "future.rule.yaml"), []byte(future), 0o644); err != nil {+ t.Fatal(err)+ }+ scanOpts.jsonOutput = true+ stdout, stderr := &strings.Builder{}, &strings.Builder{}+ cmd, _ := newCmd()+ cmd.SetOut(stdout)+ cmd.SetErr(stderr)+ if err := runScan(cmd, nil); err != nil {+ t.Fatalf("scan: %v", err)+ }+ var findings []threatrules.Finding+ if err := json.Unmarshal([]byte(stdout.String()), &findings); err != nil {+ t.Fatalf("stdout must stay valid JSON: %v\n%s", err, stdout.String())+ }+ if len(findings) != 1 || findings[0].RuleID != "scan-test-secret-read" {+ t.Fatalf("the current rule should still run: %+v", findings)+ }+ want := `rule "scan-future-rule" requires threat-rules/v2, but this Beacon supports up to ` + threatrules.SupportedSpec + `; upgrade Beacon to load it`+ if !strings.Contains(stderr.String(), "warning: skipped ") || !strings.Contains(stderr.String(), want) {+ t.Fatalf("want the skip warning on stderr, got %q", stderr.String())+ }+}diff --git a/cli/beacon/internal/endpoint/dashboard/detections.go b/cli/beacon/internal/endpoint/dashboard/detections.goindex de408680..55e153dd 100644--- a/cli/beacon/internal/endpoint/dashboard/detections.go+++ b/cli/beacon/internal/endpoint/dashboard/detections.go@@ -31,12 +31,14 @@ type DetectionView struct {type DetectionsResponse struct {Rules []DetectionView `json:"rules"`Count int `json:"count"`+ // Skipped lists rule files left out because they need a newer Beacon.+ Skipped []string `json:"skipped,omitempty"`}// BuildDetections lists the active rule set (store when present, else the// embedded baseline — the same set `beacon scan` would run) as detection views.func BuildDetections(userMode bool, rulesDir string) (DetectionsResponse, error) {- loaded, err := detect.LoadActive(userMode, strings.TrimSpace(rulesDir))+ loaded, skipped, err := detect.LoadActiveSkipping(userMode, strings.TrimSpace(rulesDir))if err != nil {return DetectionsResponse{}, err}@@ -61,7 +63,11 @@ func BuildDetections(userMode bool, rulesDir string) (DetectionsResponse, error)Taxonomy: r.Taxonomy,})}- return DetectionsResponse{Rules: rules, Count: len(rules)}, nil+ resp := DetectionsResponse{Rules: rules, Count: len(rules)}+ for _, sk := range skipped {+ resp.Skipped = append(resp.Skipped, sk.String())+ }+ return resp, nil}// FindingsResponse is the /api/findings payload: the hits from running the@@ -89,7 +95,8 @@ func RunScan(userMode bool, logPath, rulesDir, session, minSeverity string) (Fin}}- loaded, err := detect.LoadActive(userMode, strings.TrimSpace(rulesDir))+ // Rules needing a newer Beacon are left out here and listed by BuildDetections.+ loaded, _, err := detect.LoadActiveSkipping(userMode, strings.TrimSpace(rulesDir))if err != nil {return FindingsResponse{}, fmt.Errorf("load rules: %w", err)}diff --git a/cli/beacon/internal/endpoint/detect/detect.go b/cli/beacon/internal/endpoint/detect/detect.goindex fa2a3f85..e2788f7c 100644--- a/cli/beacon/internal/endpoint/detect/detect.go+++ b/cli/beacon/internal/endpoint/detect/detect.go@@ -9,6 +9,8 @@package detectimport (+ "fmt"+ "io""path/filepath"endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"@@ -50,11 +52,31 @@ func LoadActive(userMode bool, rulesDir string) ([]LoadedRule, error) {return rulestore.LoadActive(StoreDir(userMode), rulesDir)}+// LoadActiveSkipping is LoadActive, setting aside rules that need a newer spec than this+// binary supports. See rulestore.LoadActiveSkipping.+func LoadActiveSkipping(userMode bool, rulesDir string) ([]LoadedRule, []threatrules.SkippedRule, error) {+ return rulestore.LoadActiveSkipping(StoreDir(userMode), rulesDir)+}+// InstallFiles validates and installs the *.rule.yaml files at src into the store.func InstallFiles(userMode bool, src string, force bool) ([]Installed, error) {return rulestore.InstallFiles(StoreDir(userMode), src, force)}+// InstallFilesSkipping is InstallFiles, leaving out rules that need a newer spec than+// this binary supports. See rulestore.InstallFilesSkipping.+func InstallFilesSkipping(userMode bool, src string, force bool) ([]Installed, []threatrules.SkippedRule, error) {+ return rulestore.InstallFilesSkipping(StoreDir(userMode), src, force)+}++// WarnSkipped writes one warning line per skipped rule. Commands send it to stderr so+// JSON on stdout stays parseable.+func WarnSkipped(w io.Writer, skipped []threatrules.SkippedRule) {+ for _, s := range skipped {+ fmt.Fprintf(w, "warning: skipped %s\n", s)+ }+}+// Remove deletes a rule by id from the store and returns the removed path.func Remove(userMode bool, id string) (string, error) {return rulestore.Remove(StoreDir(userMode), id)diff --git a/docs/detections/engine.mdx b/docs/detections/engine.mdxindex 766f3f11..5868713e 100644--- a/docs/detections/engine.mdx+++ b/docs/detections/engine.mdx@@ -25,6 +25,7 @@ Rules are checked before any event scanning begins.Beacon:+- reads each rule's `spec` version first, and skips a rule that needs a newer spec than the binary supports, with a warning such as `warning: skipped …/x.rule.yaml: rule "x" requires threat-rules/v1.2, but this Beacon supports up to threat-rules/v1.1; upgrade Beacon to load it`- decodes rule YAML strictly- rejects unknown structural fields- enforces required fields and `match` versus `correlation` exclusivity@@ -77,7 +78,7 @@ correlation:For `threat-rules/v1`, correlation scope is `session`. Beacon groups events by `e.session.id`, then looks for each step in order. A later step must occur at or after the prior matched step, and the final step must occur within the configured `window` from the first matched step.-A correlation that sets `order: any` drops the ordering requirement: Beacon assigns each step a distinct event from the session, in whatever order they occurred, and every matched event must fall within `window` of the earliest one. The evidence events are reported in the order they happened. Either way a rule reports a session at most once.+A correlation that sets `order: any` (a `threat-rules/v1.1` field, so the rule must declare `spec: threat-rules/v1.1`) drops the ordering requirement: Beacon assigns each step a distinct event from the session, in whatever order they occurred, and every matched event must fall within `window` of the earliest one. The evidence events are reported in the order they happened. Either way a rule reports a session at most once.Correlation is useful when no single event is suspicious enough on its own, but the sequence is meaningful.diff --git a/docs/detections/standard.mdx b/docs/detections/standard.mdxindex aaa41fb3..4faa1fb2 100644--- a/docs/detections/standard.mdx+++ b/docs/detections/standard.mdx@@ -1,6 +1,6 @@---title: "Detection Standard"-description: "The threat-rules/v1 standard for portable AI-agent security detections"+description: "The threat-rules/v1.1 standard for portable AI-agent security detections"---## Standard overview@@ -11,10 +11,16 @@ This makes the format portable. Any engine that loads the same rule pack and pro## Version-The current rule format is `threat-rules/v1`.+The current rule format is `threat-rules/v1.1`. It adds `correlation.order` to `threat-rules/v1`; every v1 rule is still a valid v1.1 rule.The version covers the rule document shape, required metadata, CEL contract, correlation model, and fixture semantics. Rule files also include their own integer `version` field, which is the content revision for that individual rule.+A rule that uses a feature added after v1 declares the spec version it needs in its `spec` field, for example `spec: threat-rules/v1.1`. Rules that do not need a newer feature leave `spec` out and stay loadable by older engines. A Beacon build that supports an older version skips a rule declaring a newer one, with a warning that names the rule and tells you to upgrade Beacon, and still runs the rest of the corpus.++<Warning>+Beacon releases from before `threat-rules/v1.1` do not read `spec`. They refuse any rules directory that contains a v1.1 rule and report an unknown `spec` field. Upgrade Beacon before you pull a corpus that contains v1.1 rules.+</Warning>+## Design goalsThe standard is designed to be:diff --git a/docs/detections/yaml-schema.mdx b/docs/detections/yaml-schema.mdxindex 1066934e..86eae74d 100644--- a/docs/detections/yaml-schema.mdx+++ b/docs/detections/yaml-schema.mdx@@ -7,7 +7,7 @@ description: "Human-readable reference for Beacon threat-rule YAML files"Beacon detection rules are YAML documents ending in `.rule.yaml`. Each rule describes one security condition over Beacon endpoint events and includes enough metadata and tests for the rule to be validated before it runs.-The structural schema is the `threat-rules/v1` JSON Schema in the Agent Beacon repository. The runtime engine also compiles CEL expressions and checks rule fixtures, because those checks cannot be fully represented by JSON Schema alone.+The structural schema is the `threat-rules/v1.1` JSON Schema in the Agent Beacon repository. The runtime engine also compiles CEL expressions and checks rule fixtures, because those checks cannot be fully represented by JSON Schema alone.## Minimal rule@@ -45,6 +45,7 @@ tests:| `status` | Yes | One of `experimental`, `stable`, or `deprecated`. || `posture` | Yes | `detect` for observe-only rules or `enforce-capable` for rules designed to support enforcement. || `taxonomy` | No | External references such as OWASP, MITRE ATLAS, or CVEs. |+| `spec` | No | Minimum spec version the rule needs, such as `threat-rules/v1.1`. Omit it unless the rule uses a newer feature. Required for `correlation.order`. || `match` | One of `match` or `correlation` | CEL boolean expression for a single event. || `correlation` | One of `match` or `correlation` | Ordered multi-event sequence definition. || `emit.reason` | Yes | Human-readable finding reason. |@@ -85,9 +86,10 @@ correlation:Use `correlation` when the risk comes from a sequence, such as a secret-bearing file read followed by network egress in the same agent session.-Steps match in the order they are listed unless the correlation sets `order: any`. With `order: any`, each step must be satisfied by a different event, in whatever order those events occurred, and every matched event must fall within `window` of the earliest one. Use it when the combination is the risk regardless of which came first:+Steps match in the order they are listed unless the correlation sets `order: any`, a `threat-rules/v1.1` field. A rule that sets `order` must declare `spec: threat-rules/v1.1`. With `order: any`, each step must be satisfied by a different event, in whatever order those events occurred, and every matched event must fall within `window` of the earliest one. Use it when the combination is the risk regardless of which came first:```yaml title="Order-insensitive correlation"+spec: threat-rules/v1.1correlation:scope: sessionwindow: 120sdiff --git a/pkg/asymptoteobserve/rulestore/baseline/secret-read-then-egress.rule.yaml b/pkg/asymptoteobserve/rulestore/baseline/secret-read-then-egress.rule.yamlindex a1839749..b7bfab0f 100644--- a/pkg/asymptoteobserve/rulestore/baseline/secret-read-then-egress.rule.yaml+++ b/pkg/asymptoteobserve/rulestore/baseline/secret-read-then-egress.rule.yaml@@ -1,4 +1,5 @@id: secret-read-then-egress+spec: threat-rules/v1.1 # needed for correlation.orderversion: 2title: Secret-file read and network egress in one sessiondescription: >diff --git a/pkg/asymptoteobserve/rulestore/rulestore.go b/pkg/asymptoteobserve/rulestore/rulestore.goindex acaf139d..9602e989 100644--- a/pkg/asymptoteobserve/rulestore/rulestore.go+++ b/pkg/asymptoteobserve/rulestore/rulestore.go@@ -106,29 +106,42 @@ func baselineRulePath(name string) string {// - else load from storeDir; if the store is empty (or absent), fall back to the// embedded baseline.//-// Every returned rule has passed validation (via threatrules.LoadDir / Baseline).+// Every returned rule has passed validation (via threatrules.LoadDir / Baseline). A rule+// that needs a newer spec than this engine supports fails the load; LoadActiveSkipping is+// the variant that sets it aside instead.func LoadActive(storeDir, rulesDir string) ([]LoadedRule, error) {- if rulesDir != "" {- rules, err := threatrules.LoadDir(rulesDir)- if err != nil {- return nil, err- }- return tag(rules, SourceStore), nil+ loaded, skipped, err := LoadActiveSkipping(storeDir, rulesDir)+ if err != nil {+ return nil, err}+ if len(skipped) > 0 {+ return nil, fmt.Errorf("%s: %w", skipped[0].Path, skipped[0].Err)+ }+ return loaded, nil+}- if HasRuleFiles(storeDir) {- rules, err := threatrules.LoadDir(storeDir)+// LoadActiveSkipping is LoadActive, except that store or override rules declaring a spec+// newer than threatrules.SupportedSpec are left out and returned in skipped, so the rest+// of the corpus still runs. Callers surface skipped as warnings. The embedded baseline is+// never skipped: it ships with the engine that evaluates it.+func LoadActiveSkipping(storeDir, rulesDir string) ([]LoadedRule, []threatrules.SkippedRule, error) {+ dir := rulesDir+ if dir == "" && HasRuleFiles(storeDir) {+ dir = storeDir+ }+ if dir != "" {+ rules, skipped, err := threatrules.LoadDirSkipping(dir)if err != nil {- return nil, err+ return nil, nil, err}- return tag(rules, SourceStore), nil+ return tag(rules, SourceStore), skipped, nil}base, err := Baseline()if err != nil {- return nil, err+ return nil, nil, err}- return tag(base, SourceBaseline), nil+ return tag(base, SourceBaseline), nil, nil}func tag(rules []*threatrules.Rule, src Source) []LoadedRule {@@ -156,8 +169,29 @@ func HasRuleFiles(dir string) bool {// InstallFiles validates every *.rule.yaml found at src (a file or directory) and// writes the valid ones into storeDir. Each rule is validated before any file is// written; an invalid rule aborts the whole install. A rule whose id already exists-// in the store is rejected unless force is set. Returns the rules installed.+// in the store is rejected unless force is set. Returns the rules installed. A rule that+// needs a newer spec than this engine supports aborts the install like any other invalid+// rule; InstallFilesSkipping is the variant that leaves it out instead.func InstallFiles(storeDir, src string, force bool) ([]Installed, error) {+ return installFiles(storeDir, src, force, nil)+}++// InstallFilesSkipping is InstallFiles, except that a rule declaring a spec newer than+// threatrules.SupportedSpec is not installed and is returned in skipped, while the rest+// of the source installs. The store only ever holds rules this engine validated, so a+// skipped rule is picked up by re-running the install after upgrading Beacon.+func InstallFilesSkipping(storeDir, src string, force bool) ([]Installed, []threatrules.SkippedRule, error) {+ var skipped []threatrules.SkippedRule+ installed, err := installFiles(storeDir, src, force, &skipped)+ if err != nil {+ return nil, nil, err+ }+ return installed, skipped, nil+}++// installFiles implements InstallFiles. When skipped is non-nil, rules needing a newer+// spec are appended to it rather than aborting the install.+func installFiles(storeDir, src string, force bool, skipped *[]threatrules.SkippedRule) ([]Installed, error) {srcPaths, err := ruleFilesAt(src)if err != nil {return nil, err@@ -190,6 +224,10 @@ func InstallFiles(storeDir, src string, force bool) ([]Installed, error) {return nil, err}rule, err := threatrules.DecodeRule(data)+ if unsupported, ok := threatrules.AsUnsupportedSpec(err); ok && skipped != nil {+ *skipped = append(*skipped, threatrules.SkippedRule{Path: p, Err: unsupported})+ continue+ }if err != nil {return nil, fmt.Errorf("%s: %w", p, err)}diff --git a/pkg/asymptoteobserve/rulestore/rulestore_test.go b/pkg/asymptoteobserve/rulestore/rulestore_test.goindex c871cac8..5d769acd 100644--- a/pkg/asymptoteobserve/rulestore/rulestore_test.go+++ b/pkg/asymptoteobserve/rulestore/rulestore_test.go@@ -283,3 +283,79 @@ func srcOf(l []LoadedRule) []Source {}return s}++// futureRule declares a spec newer than this engine supports and carries a field that+// version might add, which a strict decode alone would report as unknown.+const futureRule = `+id: future-rule+spec: threat-rules/v1.9+version: 1+title: T+severity: low+status: experimental+posture: detect+match: 'e.event.action == "file.read"'+future_field: true+emit:+ reason: ok+tests:+ - name: p+ verdict: match+ events:+ - event: { action: file.read }+`++func TestInstallFilesSkippingLeavesNewerSpecOut(t *testing.T) {+ src := t.TempDir()+ if err := os.WriteFile(filepath.Join(src, "a.rule.yaml"), []byte(ruleWithID("current-rule")), 0o644); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(filepath.Join(src, "b.rule.yaml"), []byte(futureRule), 0o644); err != nil {+ t.Fatal(err)+ }+ store := t.TempDir()++ if _, err := InstallFiles(store, src, false); err == nil || !strings.Contains(err.Error(), "upgrade Beacon") {+ t.Fatalf("strict InstallFiles want the unsupported-spec error, got %v", err)+ }+ if HasRuleFiles(store) {+ t.Fatal("strict InstallFiles must not write anything when it fails")+ }++ installed, skipped, err := InstallFilesSkipping(store, src, false)+ if err != nil {+ t.Fatalf("install: %v", err)+ }+ if len(installed) != 1 || installed[0].ID != "current-rule" {+ t.Fatalf("want current-rule installed, got %+v", installed)+ }+ if len(skipped) != 1 || skipped[0].Err.RuleID != "future-rule" {+ t.Fatalf("want future-rule skipped, got %+v", skipped)+ }+ if _, err := os.Stat(filepath.Join(store, "future-rule"+RuleFileSuffix)); !os.IsNotExist(err) {+ t.Fatalf("skipped rule must not land in the store (stat err %v)", err)+ }+}++func TestLoadActiveSkippingRunsTheRestOfTheStore(t *testing.T) {+ store := t.TempDir()+ if err := os.WriteFile(filepath.Join(store, "current-rule.rule.yaml"), []byte(ruleWithID("current-rule")), 0o644); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(filepath.Join(store, "future-rule.rule.yaml"), []byte(futureRule), 0o644); err != nil {+ t.Fatal(err)+ }+ loaded, skipped, err := LoadActiveSkipping(store, "")+ if err != nil {+ t.Fatalf("load: %v", err)+ }+ if len(loaded) != 1 || loaded[0].Rule.ID != "current-rule" || loaded[0].Source != SourceStore {+ t.Fatalf("want only current-rule from the store, got %d rules", len(loaded))+ }+ if len(skipped) != 1 || !strings.Contains(skipped[0].String(), `rule "future-rule" requires threat-rules/v1.9, but this Beacon supports up to `+threatrules.SupportedSpec+`; upgrade Beacon to load it`) {+ t.Fatalf("want future-rule skipped with the upgrade message, got %+v", skipped)+ }+ if _, err := LoadActive(store, ""); err == nil {+ t.Fatal("strict LoadActive want an error for the newer-spec rule")+ }+}diff --git a/pkg/asymptoteobserve/threatrules/correlation_test.go b/pkg/asymptoteobserve/threatrules/correlation_test.goindex ba173b91..6dac29cf 100644--- a/pkg/asymptoteobserve/threatrules/correlation_test.go+++ b/pkg/asymptoteobserve/threatrules/correlation_test.go@@ -31,8 +31,12 @@ func readThenEgressRule(t *testing.T) *CompiledRule {// window, and steps.func compileCorrelation(t *testing.T, order Order, window string, steps ...CorrelationStep) *CompiledRule {t.Helper()+ spec := ""+ if order != "" {+ spec = SupportedSpec+ }rule := &Rule{- ID: "rte", Version: 1, Title: "rte",+ ID: "rte", Spec: spec, Version: 1, Title: "rte",Severity: asymptoteobserve.SeverityHigh, Status: StatusExperimental, Posture: PostureDetect,Emit: Emit{Reason: "x"},Correlation: &Correlation{Scope: ScopeSession, Window: window, Order: order, Steps: steps},@@ -324,7 +328,7 @@ func TestCorrelationAnyOrderOneFindingPerSession(t *testing.T) {func TestCorrelationRejectsUnknownOrder(t *testing.T) {rule := &Rule{- ID: "bad-order", Version: 1, Title: "t",+ ID: "bad-order", Spec: SupportedSpec, Version: 1, Title: "t",Severity: asymptoteobserve.SeverityLow, Status: StatusExperimental, Posture: PostureDetect,Emit: Emit{Reason: "x"},Correlation: &Correlation{Scope: ScopeSession, Window: "60s", Order: "unordered", Steps: []CorrelationStep{diff --git a/pkg/asymptoteobserve/threatrules/loader.go b/pkg/asymptoteobserve/threatrules/loader.goindex cbc060f9..27412383 100644--- a/pkg/asymptoteobserve/threatrules/loader.go+++ b/pkg/asymptoteobserve/threatrules/loader.go@@ -2,6 +2,7 @@ package threatrulesimport ("bytes"+ "errors""fmt""io/fs""os"@@ -18,7 +19,20 @@ const ruleFileSuffix = ".rule.yaml"// DecodeRule strictly decodes a single rule document. Unknown fields are rejected so a// typo in a rule key is a load-time error rather than a silently ignored field. It does// not Validate; callers run Validate (or Compile) separately.+//+// The spec version is checked first, from a lenient read of just id and spec, so a rule+// written for a newer spec returns an *UnsupportedSpecError naming the version it needs+// rather than an unknown-field error about whatever that version added.func DecodeRule(data []byte) (*Rule, error) {+ var head struct {+ ID string `yaml:"id"`+ Spec string `yaml:"spec"`+ }+ if yaml.Unmarshal(data, &head) == nil {+ if err := checkSpecSupported(head.ID, head.Spec); err != nil {+ return nil, err+ }+ }dec := yaml.NewDecoder(bytes.NewReader(data))dec.KnownFields(true)var rule Rule@@ -44,12 +58,37 @@ func LoadRule(path string) (*Rule, error) {return rule, nil}+// SkippedRule is a rule file a loader left out because it needs a newer spec than this+// engine supports.+type SkippedRule struct {+ Path string+ Err *UnsupportedSpecError+}++func (s SkippedRule) String() string { return s.Path + ": " + s.Err.Error() }+// LoadDir discovers every *.rule.yaml under root (recursively), decodes and validates// each, and returns them sorted by id. A duplicate id across files is a hard error, as is-// any decode/validate failure (the offending path is named).+// any decode/validate failure (the offending path is named), including a rule that needs+// a newer spec. LoadDirSkipping is the variant that sets such rules aside instead.func LoadDir(root string) ([]*Rule, error) {+ rules, skipped, err := LoadDirSkipping(root)+ if err != nil {+ return nil, err+ }+ if len(skipped) > 0 {+ return nil, fmt.Errorf("%s: %w", skipped[0].Path, skipped[0].Err)+ }+ return rules, nil+}++// LoadDirSkipping is LoadDir, except that a rule declaring a spec newer than+// SupportedSpec is left out and returned in skipped rather than failing the load, so an+// older engine keeps running the rest of a newer corpus. Every other failure still fails+// the whole load.+func LoadDirSkipping(root string) (rules []*Rule, skipped []SkippedRule, err error) {var paths []string- err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {+ err = filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {if err != nil {return err}@@ -62,24 +101,37 @@ func LoadDir(root string) ([]*Rule, error) {return nil})if err != nil {- return nil, err+ return nil, nil, err}sort.Strings(paths)- rules := make([]*Rule, 0, len(paths))+ rules = make([]*Rule, 0, len(paths))seen := make(map[string]string, len(paths)) // id -> pathfor _, path := range paths {rule, err := LoadRule(path)+ if unsupported, ok := AsUnsupportedSpec(err); ok {+ skipped = append(skipped, SkippedRule{Path: path, Err: unsupported})+ continue+ }if err != nil {- return nil, err+ return nil, nil, err}if prev, dup := seen[rule.ID]; dup {- return nil, fmt.Errorf("duplicate rule id %q in %s and %s", rule.ID, prev, path)+ return nil, nil, fmt.Errorf("duplicate rule id %q in %s and %s", rule.ID, prev, path)}seen[rule.ID] = pathrules = append(rules, rule)}- return rules, nil+ return rules, skipped, nil+}++// AsUnsupportedSpec reports whether err is, or wraps, an *UnsupportedSpecError.+func AsUnsupportedSpec(err error) (*UnsupportedSpecError, bool) {+ var u *UnsupportedSpecError+ if errors.As(err, &u) {+ return u, true+ }+ return nil, false}func isRuleFile(path string) bool {diff --git a/pkg/asymptoteobserve/threatrules/rule.go b/pkg/asymptoteobserve/threatrules/rule.goindex 60d133e9..e22331ec 100644--- a/pkg/asymptoteobserve/threatrules/rule.go+++ b/pkg/asymptoteobserve/threatrules/rule.go@@ -51,7 +51,12 @@ const ScopeSession Scope = "session"// Rule is a single threat-detection rule. Exactly one of Match or Correlation is set.type Rule struct {- ID string `yaml:"id"`+ ID string `yaml:"id"`+ // Spec is the minimum Threat Rules spec version the rule needs, such as+ // "threat-rules/v1.1". Empty means the original v1. A rule that uses a feature added+ // after v1 must declare it, so an engine that predates the feature can tell the rule+ // is too new instead of failing on an unknown field.+ Spec string `yaml:"spec,omitempty"`Version int `yaml:"version"`Title string `yaml:"title"`Description string `yaml:"description,omitempty"`@@ -160,6 +165,9 @@ func (r *Rule) Validate() error {if !idPattern.MatchString(r.ID) {return fmt.Errorf("id %q must match %s", r.ID, idPattern.String())}+ if err := checkSpecSupported(r.ID, r.Spec); err != nil {+ return err+ }if r.Version < 1 {return fmt.Errorf("version must be >= 1, got %d", r.Version)}@@ -240,6 +248,12 @@ func (r *Rule) validateCorrelation() error {default:return fmt.Errorf("correlation.order %q unsupported (%q or %q)", c.Order, OrderSequence, OrderAny)}+ if c.Order != "" {+ // Already known to be parseable and supported (Validate checked it first).+ if v, _ := parseSpec(r.Spec); specV1_1.newerThan(v) {+ return fmt.Errorf("correlation.order requires spec: threat-rules/v1.1 or later (engines before v1.1 reject the field)")+ }+ }if len(c.Steps) < 2 {return fmt.Errorf("correlation requires >= 2 steps, got %d", len(c.Steps))}diff --git a/pkg/asymptoteobserve/threatrules/specversion.go b/pkg/asymptoteobserve/threatrules/specversion.gonew file mode 100644index 00000000..88a8851a--- /dev/null+++ b/pkg/asymptoteobserve/threatrules/specversion.go@@ -0,0 +1,87 @@+package threatrules++import (+ "fmt"+ "regexp"+ "strconv"+)++// SupportedSpec is the newest Threat Rules spec version this engine implements. It must+// equal spec/threat-rules/VERSION (a test pins the two together).+const SupportedSpec = "threat-rules/v1.1"++// specV1_1 is the version that added correlation.order.+var specV1_1 = specVersion{major: 1, minor: 1}++// specPattern is the grammar of a spec version: threat-rules/v<major>[.<minor>].+var specPattern = regexp.MustCompile(`^threat-rules/v([0-9]+)(?:\.([0-9]+))?$`)++// specVersion is a parsed spec version. An omitted minor is 0, so v1 == v1.0.+type specVersion struct{ major, minor int }++func (v specVersion) newerThan(o specVersion) bool {+ if v.major != o.major {+ return v.major > o.major+ }+ return v.minor > o.minor+}++// parseSpec parses a rule's spec field. An empty value is the original spec, v1.+func parseSpec(s string) (specVersion, error) {+ if s == "" {+ return specVersion{major: 1}, nil+ }+ m := specPattern.FindStringSubmatch(s)+ if m == nil {+ return specVersion{}, fmt.Errorf("spec %q must look like %q", s, SupportedSpec)+ }+ major, err := strconv.Atoi(m[1])+ if err != nil {+ return specVersion{}, fmt.Errorf("spec %q: %w", s, err)+ }+ minor := 0+ if m[2] != "" {+ if minor, err = strconv.Atoi(m[2]); err != nil {+ return specVersion{}, fmt.Errorf("spec %q: %w", s, err)+ }+ }+ return specVersion{major: major, minor: minor}, nil+}++var supportedSpec = func() specVersion {+ v, err := parseSpec(SupportedSpec)+ if err != nil {+ panic(err)+ }+ return v+}()++// UnsupportedSpecError reports a rule that declares a spec version newer than this+// engine implements. Loaders that can continue without the rule (LoadDirSkipping,+// rulestore) skip it and surface this error as a warning.+type UnsupportedSpecError struct {+ RuleID string // from a lenient read of the file; may be empty+ Required string // the rule's spec field+}++func (e *UnsupportedSpecError) Error() string {+ id := e.RuleID+ if id == "" {+ id = "(no id)"+ }+ return fmt.Sprintf("rule %q requires %s, but this Beacon supports up to %s; upgrade Beacon to load it",+ id, e.Required, SupportedSpec)+}++// checkSpecSupported returns an *UnsupportedSpecError when spec is newer than+// SupportedSpec, and a plain error when it is malformed.+func checkSpecSupported(id, spec string) error {+ v, err := parseSpec(spec)+ if err != nil {+ return err+ }+ if v.newerThan(supportedSpec) {+ return &UnsupportedSpecError{RuleID: id, Required: spec}+ }+ return nil+}diff --git a/pkg/asymptoteobserve/threatrules/specversion_test.go b/pkg/asymptoteobserve/threatrules/specversion_test.gonew file mode 100644index 00000000..3a6d2d3d--- /dev/null+++ b/pkg/asymptoteobserve/threatrules/specversion_test.go@@ -0,0 +1,142 @@+package threatrules++import (+ "os"+ "path/filepath"+ "strings"+ "testing"+)++// specRule is a minimal valid single-event rule with the given id and spec line.+func specRule(id, specLine, extra string) string {+ return "id: " + id + "\n" + specLine + `+version: 1+title: T+severity: low+status: experimental+posture: detect+match: 'e.event.action == "file.read"'+emit:+ reason: ok+` + extra + `tests:+ - name: p+ verdict: match+ events:+ - event: { action: file.read }+`+}++func TestSupportedSpecMatchesVersionFile(t *testing.T) {+ raw, err := os.ReadFile(filepath.Join(specDir(t), "VERSION"))+ if err != nil {+ t.Fatal(err)+ }+ if got := strings.TrimSpace(string(raw)); got != SupportedSpec {+ t.Fatalf("spec/threat-rules/VERSION is %q but the engine's SupportedSpec is %q", got, SupportedSpec)+ }+}++func TestDecodeRuleAcceptsSupportedSpecs(t *testing.T) {+ for _, line := range []string{"", "spec: threat-rules/v1", "spec: threat-rules/v1.0", "spec: " + SupportedSpec} {+ rule, err := DecodeRule([]byte(specRule("r", line, "")))+ if err != nil {+ t.Errorf("%q: decode: %v", line, err)+ continue+ }+ if err := rule.Validate(); err != nil {+ t.Errorf("%q: validate: %v", line, err)+ }+ }+}++func TestDecodeRuleRejectsNewerSpecClearly(t *testing.T) {+ for _, spec := range []string{"threat-rules/v1.2", "threat-rules/v2"} {+ // A future rule also carries the fields its version added; the spec check must+ // come first so the error names the version rather than the unknown field.+ _, err := DecodeRule([]byte(specRule("future-rule", "spec: "+spec, "future_field: true\n")))+ u, ok := AsUnsupportedSpec(err)+ if !ok {+ t.Fatalf("%s: want *UnsupportedSpecError, got %v", spec, err)+ }+ if u.RuleID != "future-rule" || u.Required != spec {+ t.Errorf("%s: got %+v", spec, u)+ }+ want := `rule "future-rule" requires ` + spec + `, but this Beacon supports up to ` + SupportedSpec + `; upgrade Beacon to load it`+ if err.Error() != want {+ t.Errorf("message:\n got: %s\n want: %s", err.Error(), want)+ }+ }+}++func TestDecodeRuleRejectsMalformedSpec(t *testing.T) {+ for _, spec := range []string{"v1.1", "threat-rules/1.1", "threat-rules/v1.1-beta"} {+ _, err := DecodeRule([]byte(specRule("r", "spec: "+spec, "")))+ if err == nil {+ t.Errorf("%q: want error", spec)+ continue+ }+ if _, ok := AsUnsupportedSpec(err); ok {+ t.Errorf("%q: malformed spec must not read as merely unsupported", spec)+ }+ }+}++func TestOrderRequiresSpecV1_1(t *testing.T) {+ c := compileCorrelation(t, OrderAny, "60s",+ CorrelationStep{ID: "a", Match: `e.event.action == "file.read"`},+ CorrelationStep{ID: "b", Match: `e.event.action == "command.executed"`},+ )+ rule := *c.Rule()+ for _, spec := range []string{"", "threat-rules/v1"} {+ rule.Spec = spec+ err := rule.Validate()+ if err == nil || !strings.Contains(err.Error(), "correlation.order requires spec: threat-rules/v1.1") {+ t.Errorf("spec %q: want the order/spec error, got %v", spec, err)+ }+ }+}++func TestLoadDirSkippingSetsNewerSpecAside(t *testing.T) {+ dir := t.TempDir()+ write := func(name, body string) {+ t.Helper()+ if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o644); err != nil {+ t.Fatal(err)+ }+ }+ write("current.rule.yaml", specRule("current-rule", "spec: "+SupportedSpec, ""))+ write("legacy.rule.yaml", specRule("legacy-rule", "", ""))+ write("future.rule.yaml", specRule("future-rule", "spec: threat-rules/v1.9", "future_field: 1\n"))++ rules, skipped, err := LoadDirSkipping(dir)+ if err != nil {+ t.Fatalf("load: %v", err)+ }+ if len(rules) != 2 || rules[0].ID != "current-rule" || rules[1].ID != "legacy-rule" {+ t.Fatalf("want current-rule and legacy-rule loaded, got %v", ruleIDs(rules))+ }+ if len(skipped) != 1 || skipped[0].Err.RuleID != "future-rule" || filepath.Base(skipped[0].Path) != "future.rule.yaml" {+ t.Fatalf("want future-rule skipped, got %+v", skipped)+ }+ if !strings.Contains(skipped[0].String(), "future.rule.yaml: rule \"future-rule\" requires threat-rules/v1.9") {+ t.Errorf("skip message should name the file, rule, and version: %s", skipped[0])+ }++ // Strict LoadDir refuses instead, naming the same rule.+ if _, err := LoadDir(dir); err == nil || !strings.Contains(err.Error(), "upgrade Beacon") {+ t.Fatalf("LoadDir want the unsupported-spec error, got %v", err)+ }+ // Other failures still fail the whole skipping load.+ write("broken.rule.yaml", specRule("broken-rule", "", "typo_field: 1\n"))+ if _, _, err := LoadDirSkipping(dir); err == nil {+ t.Fatal("an unknown field in a current-spec rule must still fail the load")+ }+}++func ruleIDs(rules []*Rule) []string {+ ids := make([]string, len(rules))+ for i, r := range rules {+ ids[i] = r.ID+ }+ return ids+}diff --git a/rules/context-exfiltration/secret-read-then-destructive.rule.yaml b/rules/context-exfiltration/secret-read-then-destructive.rule.yamlindex 47689858..2e4abf78 100644--- a/rules/context-exfiltration/secret-read-then-destructive.rule.yaml+++ b/rules/context-exfiltration/secret-read-then-destructive.rule.yaml@@ -1,4 +1,5 @@id: secret-read-then-destructive+spec: threat-rules/v1.1 # needed for correlation.orderversion: 1title: Secret-file read and recursive delete in one sessiondescription: >diff --git a/rules/context-exfiltration/secret-read-then-egress.rule.yaml b/rules/context-exfiltration/secret-read-then-egress.rule.yamlindex a1839749..b7bfab0f 100644--- a/rules/context-exfiltration/secret-read-then-egress.rule.yaml+++ b/rules/context-exfiltration/secret-read-then-egress.rule.yaml@@ -1,4 +1,5 @@id: secret-read-then-egress+spec: threat-rules/v1.1 # needed for correlation.orderversion: 2title: Secret-file read and network egress in one sessiondescription: >diff --git a/spec/threat-rules/SPEC.md b/spec/threat-rules/SPEC.mdindex 3be1042c..e24de65a 100644--- a/spec/threat-rules/SPEC.md+++ b/spec/threat-rules/SPEC.md@@ -1,4 +1,4 @@-# Threat Rules — Specification (v1)+# Threat Rules — Specification (v1.1)An open detection-rule format for AI-agent security threats, native to the Beaconendpoint event schema. A rule is a YAML document whose match conditions are@@ -9,7 +9,7 @@ This is the "Sigma for agent telemetry" layer: the rule format and corpus are opevaluation engine that consumes them may be separate (and closed). Any engine thatproduces the same `verdict` for a rule's fixtures conforms to this spec.-- Spec version: `threat-rules/v1` (see `VERSION`).+- Spec version: `threat-rules/v1.1` (see `VERSION` and [Versioning](#versioning)).- Canonical event schema: the Beacon endpoint event(`pkg/asymptoteobserve` `Event`, `schema_version: "1.0"`).- Machine-readable structural schema: `schema.json` (JSON Schema, draft 2020-12).@@ -23,7 +23,8 @@ produces the same `verdict` for a rule's fixtures conforms to this spec.```yamlid: secret-read-then-egress-version: 1+spec: threat-rules/v1.1 # needed only because this rule uses correlation.order+version: 2title: Secret-file read followed by network egressdescription: >Flags a session that reads a credential file and then issues an outbound@@ -38,6 +39,7 @@ taxonomy:correlation:scope: sessionwindow: 120s+ order: anysteps:- id: read_secretmatch: >@@ -77,6 +79,7 @@ Exactly one of `match` or `correlation` must be present. Required:| Field | Required | Type / values | Meaning ||---|---|---|---|| `id` | yes | string `^[a-z0-9][a-z0-9-]*$` | Stable unique identity. Unique across the pack. Flows to `policy.id` on a finding. |+| `spec` | no | `threat-rules/v<major>[.<minor>]` (default `threat-rules/v1`) | Minimum spec version the rule needs. Required (v1.1 or later) when the rule uses a v1.1 feature. See [Versioning](#versioning). || `version` | yes | int ≥ 1 | Rule content revision; bump on logic change. || `title` | yes | string | Human-readable name. Flows to `policy.name`. || `description` | no | string | Documentation only; never evaluated. |@@ -95,7 +98,7 @@ Exactly one of `match` or `correlation` must be present. Required:|---|---|---|---|| `scope` | yes | `session` | Grouping key (`e.session.id`). v1 supports `session` only. || `window` | yes | Go duration (`120s`, `5m`) | Max elapsed time from the earliest matched event to the latest. |-| `order` | no | `sequence` (default) \| `any` | Whether `steps` must occur in listed order. |+| `order` | no | `sequence` (default) \| `any` | Whether `steps` must occur in listed order. Since v1.1; a rule that sets it MUST declare `spec: threat-rules/v1.1` or later. || `steps` | yes | list ≥ 2 | Step conditions; see `order`. || `steps[].id` | yes | string | Step label (diagnostics). Not evaluated. || `steps[].match` | yes | CEL string → bool | Per-event condition, same contract as top-level `match`. |@@ -153,6 +156,32 @@ An engine produces one of two verdicts for a rule against an ordered event sequeConformance is defined entirely in these terms: for each fixture, an engine MUST producethe fixture's declared `verdict`.+## Versioning++A spec version is `threat-rules/v<major>.<minor>`; `v1` is `v1.0`. A minor version only adds+optional fields, so every rule valid under an earlier minor stays valid. A major version may+change meaning.++A rule declares the version it needs in `spec`, not the version current when it was written,+so a corpus mixes versions and a rule moves to a newer `spec` only when it adopts a newer+feature. That keeps the rest of a corpus loadable by an older engine.++An engine MUST read a rule's `spec` before it rejects any unknown field, and MUST NOT evaluate+a rule whose `spec` is newer than the version it implements. It SHOULD set that rule aside with+a diagnostic naming the rule, the version the rule needs, and the version the engine supports,+and continue loading the rest of the corpus. The reference engine skips such rules with a+warning in `beacon scan`, `beacon rules list`, `add`, and `pull`, and reports them as `SKIP`+lines that fail `beacon rules lint`.++Engines released before v1.1 do not read `spec`: they reject a rule that carries it, or any+v1.1 field, as an unknown field, and refuse the directory that contains it.++### Changelog++- **v1.1**: `correlation.order` (`sequence` default, or `any` for order-insensitive steps),+ and the per-rule `spec` field with the engine rules above.+- **v1**: initial version.+## Maturity ladder`status` gates what a rule must prove:diff --git a/spec/threat-rules/VERSION b/spec/threat-rules/VERSIONindex 84c334e3..3779923a 100644--- a/spec/threat-rules/VERSION+++ b/spec/threat-rules/VERSION@@ -1 +1 @@-threat-rules/v1+threat-rules/v1.1diff --git a/spec/threat-rules/schema.json b/spec/threat-rules/schema.jsonindex e7bc434f..848b1025 100644--- a/spec/threat-rules/schema.json+++ b/spec/threat-rules/schema.json@@ -2,7 +2,7 @@"$schema": "https://json-schema.org/draft/2020-12/schema","$id": "https://beacon.dev/spec/threat-rules/v1/schema.json","title": "Beacon Threat Rule",- "description": "Open detection-rule format for AI-agent security threats, native to the Beacon endpoint event schema. Match conditions are CEL expressions; CEL correctness is enforced by an engine, not by this structural schema.",+ "description": "Open detection-rule format for AI-agent security threats (threat-rules/v1.1), native to the Beacon endpoint event schema. Match conditions are CEL expressions; CEL correctness is enforced by an engine, not by this structural schema.","type": "object","additionalProperties": false,"required": ["id", "version", "title", "severity", "status", "posture", "emit", "tests"],@@ -16,6 +16,12 @@"pattern": "^[a-z0-9][a-z0-9-]*$","description": "Stable unique identity; unique across the pack."},+ "spec": {+ "type": "string",+ "pattern": "^threat-rules/v[0-9]+(\\.[0-9]+)?$",+ "default": "threat-rules/v1",+ "description": "Minimum Threat Rules spec version the rule needs. Required (threat-rules/v1.1 or later) when the rule uses correlation.order. Engines skip a rule whose spec is newer than they support."+ },"version": {"type": "integer","minimum": 1,