Skip to content

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

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.go
index 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, 0
for _, 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index fa2a3f85..e2788f7c 100644
--- a/cli/beacon/internal/endpoint/detect/detect.go
+++ b/cli/beacon/internal/endpoint/detect/detect.go
@@ -9,6 +9,8 @@
package detect
import (
+ "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.mdx
index 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.mdx
index 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 goals
The standard is designed to be:
diff --git a/docs/detections/yaml-schema.mdx b/docs/detections/yaml-schema.mdx
index 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.1
correlation:
scope: session
window: 120s
diff --git a/pkg/asymptoteobserve/rulestore/baseline/secret-read-then-egress.rule.yaml b/pkg/asymptoteobserve/rulestore/baseline/secret-read-then-egress.rule.yaml
index 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.order
version: 2
title: Secret-file read and network egress in one session
description: >
diff --git a/pkg/asymptoteobserve/rulestore/rulestore.go b/pkg/asymptoteobserve/rulestore/rulestore.go
index 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.go
index 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.go
index 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.go
index cbc060f9..27412383 100644
--- a/pkg/asymptoteobserve/threatrules/loader.go
+++ b/pkg/asymptoteobserve/threatrules/loader.go
@@ -2,6 +2,7 @@ package threatrules
import (
"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 -> path
for _, 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] = path
rules = 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.go
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.yaml
index 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.order
version: 1
title: Secret-file read and recursive delete in one session
description: >
diff --git a/rules/context-exfiltration/secret-read-then-egress.rule.yaml b/rules/context-exfiltration/secret-read-then-egress.rule.yaml
index 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.order
version: 2
title: Secret-file read and network egress in one session
description: >
diff --git a/spec/threat-rules/SPEC.md b/spec/threat-rules/SPEC.md
index 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 Beacon
endpoint 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 op
evaluation engine that consumes them may be separate (and closed). Any engine that
produces 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.
```yaml
id: secret-read-then-egress
-version: 1
+spec: threat-rules/v1.1 # needed only because this rule uses correlation.order
+version: 2
title: Secret-file read followed by network egress
description: >
Flags a session that reads a credential file and then issues an outbound
@@ -38,6 +39,7 @@ taxonomy:
correlation:
scope: session
window: 120s
+ order: any
steps:
- id: read_secret
match: >
@@ -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 seque
Conformance is defined entirely in these terms: for each fixture, an engine MUST produce
the 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/VERSION
index 84c334e3..3779923a 100644
--- a/spec/threat-rules/VERSION
+++ b/spec/threat-rules/VERSION
@@ -1 +1 @@
-threat-rules/v1
+threat-rules/v1.1
diff --git a/spec/threat-rules/schema.json b/spec/threat-rules/schema.json
index 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,