feat(secl): add a capture field to the set action (#54165)

### What does this PR do?

Extends the SECL `set` action with a new `capture` field: a regular expression with a
single capture group, applied to the value of `field`, whose first group becomes the
variable value.

```yaml
- id: ssm_command_tracking
  expression: open.file.path =~ "/var/lib/amazon/ssm/*/document/orchestration/**"
  silent: true
  actions:
    - set:
        name: ssm_command_id
        scope: process
        inherited: true
        field: open.file.path
        capture: "/orchestration/([^/]+)/"
```

- `eval.CaptureStringMatcher` joins the existing `StringMatcher` family in
  `secl/compiler/eval/strings.go`. `Compile` rejects patterns that don't compile and
  patterns with no capture group; `Capture` uses `FindStringSubmatchIndex` to avoid
  allocating a slice of strings for every group.
- The compiled pattern lives on the `*Action` (next to `ScopeFieldEvaluator`), compiled
  once at policy load by `CompileCaptureMatcher`. It deliberately does **not** live in
  `RuleSet.fieldEvaluators`, which is keyed by field name and shared across rules — two
  rules capturing different patterns out of the same field would otherwise collide.
- Validation is all at load time: `capture` requires `field` (which transitively makes it
  exclusive with `value` and `expression`), and is rejected on non-string and array
  fields. At runtime the only branch is match / no match.
- A value that doesn't match is a silent no-op leaving the variable at its previous
  value. Capture rules can be attached to high frequency events, so a miss must not log
  or clear anything.
- `policy.schema.json` is regenerated. Because it declares `additionalProperties: false`,
  skipping this would make every policy using `capture` fail schema validation.

Only fields holding a single string are supported. Array fields would need per-element
extraction, which is out of scope here.

### Motivation

Workload Protection events are rich at the kernel layer but disconnected from
cloud-layer activity. The identifiers needed to join them frequently already exist
inside WP event fields — an SSM `CommandId` inside a filesystem path, an IAM role inside
an IMDS url — but a rule could match those fields without being able to decompose them.

Storing the whole field value doesn't help: CloudTrail has the bare `a1b2…`, so the
strings aren't equal and there is nothing to join on. Capturing the id and attaching it
to the process with `inherited: true` puts the join key on every descendant event, so the
backend join becomes an exact equality instead of command-line parsing inside a time
window.

Implements the approved RFC "Capturing Correlation Artifact: Structured Join Keys from
SECL Set Actions".

### Describe how you validated your changes

Unit tests (`secl/compiler/eval`, `secl/rules`) cover extraction, the first-group-only
rule, non-participating optional groups, load-time rejection of malformed patterns and
of non-string/array fields, and the two-rules-same-field case that guards the per-action
matcher.

Functional test `TestActionCaptureInherited` on a real kernel covers the end-to-end
scenario: a silent rule captures a UUID-shaped SSM command id out of an orchestration
path, and a **grandchild** shell two levels down fires a rule asserting
`${process.ssm_command_id}` equals the bare id. It also asserts the artifact reaches the
serialized event intact at `$.process.variables.ssm_command_id` — variable values pass
through `scrubber.ScrubString`, so this confirms the scrubber doesn't mangle the join key
— and that no event is sent for the extraction rule itself.

Benchmark added for the set action, since the review raised the cost of evaluating the
pattern on frequently matched rules (linux/arm64):

| Case | ns/op | B/op | allocs/op |
|---|---|---|---|
| set without capture | 106 | 48 | 3 |
| set with capture, match | 335 | 104 | 6 |
| set with capture, no match | 122 | 48 | 3 |

Matching costs ~+230ns over a plain set action; a miss costs ~+16ns and no extra
allocations. Go's `regexp` is RE2, so a pattern is linear in the input length and cannot
backtrack catastrophically regardless of how it is written.

### Additional Notes

Captured values are cloned rather than sliced out of the field value: a Go substring
shares its backing array, so a 36-byte id would otherwise keep the whole path alive for
as long as the variable lived — and these variables are inherited across process trees
and can carry a TTL. That is the `+1 alloc` in the table above.

Note for reviewers: `secl/rules/policy_test.go` and `ruleset_test.go` are `//go:build
linux`, so the package reports 52 passing tests on darwin against 190 on linux. Changes
here need a linux run to be meaningfully verified.

Follow-ups, both out of scope:
- Capture on array fields, which is what env var artifacts (`GITHUB_RUN_ID`,
  `ECS_TASK_ARN`) would need; `exec.envp` currently fails at load.
- The ECS task id example from the RFC, which depends on `process.cgroup.id` exposing the
  relative cgroup path rather than just the leaf container id on the EC2 launch type.
  That still needs to be checked on a real ECS host.

Co-authored-by: lorenzo.susini <lorenzo.susini@datadoghq.com>

Author: loresuso

pkg/security/rules/monitor/policy_monitor.go

@@ -231,6 +231,7 @@ type RuleSetAction struct {
 	Value        interface{} `json:"value,omitempty"`
 	DefaultValue interface{} `json:"default_value,omitempty"`
 	Field        string      `json:"field,omitempty"`
+	Capture      string      `json:"capture,omitempty"`
 	Expression   string      `json:"expression,omitempty"`
 	Append       bool        `json:"append,omitempty"`
 	Scope        string      `json:"scope,omitempty"`
@@ -347,6 +348,7 @@ func RuleStateFromRule(rule *rules.PolicyRule, policy *rules.PolicyInfo, status
 				Value:        action.Def.Set.Value,
 				DefaultValue: action.Def.Set.DefaultValue,
 				Field:        action.Def.Set.Field,
+				Capture:      action.Def.Set.Capture,
 				Expression:   action.Def.Set.Expression,
 				Append:       action.Def.Set.Append,
 				Scope:        string(action.Def.Set.Scope),

pkg/security/rules/monitor/policy_monitor_easyjson.go

@@ -79,6 +79,63 @@ func TestPolicyMonitorPolicyState(t *testing.T) {
 				},
 			},
 		},
+		{
+			// the capture pattern is what distinguishes an action storing part of a
+			// field from one storing the whole of it, so it has to be reported
+			name: "rule with a capture set action",
+			policies: []*testPolicy{
+				{
+					info: rules.PolicyInfo{
+						Name:   "Policy A",
+						Source: "test",
+					},
+					def: rules.PolicyDef{
+						Rules: []*rules.RuleDefinition{
+							{
+								ID:         "rule_a",
+								Expression: `exec.file.path == "/etc/foo/bar"`,
+								Actions: []*rules.ActionDefinition{
+									{
+										Set: &rules.SetDefinition{
+											Name:    "artifact",
+											Field:   "process.file.path", // use field available for both Linux and Windows
+											Capture: "/orchestration/([^/]+)/",
+											Scope:   "process",
+										},
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+			expectedPolicyStates: []*PolicyState{
+				{
+					PolicyMetadata: PolicyMetadata{
+						Name:   "Policy A",
+						Source: "test",
+					},
+					Status: PolicyStatusLoaded,
+					Rules: []*RuleState{
+						{
+							ID:         "rule_a",
+							Expression: `exec.file.path == "/etc/foo/bar"`,
+							Status:     "loaded",
+							Actions: []RuleAction{
+								{
+									Set: &RuleSetAction{
+										Name:    "artifact",
+										Field:   "process.file.path",
+										Capture: "/orchestration/([^/]+)/",
+										Scope:   "process",
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+		},
 		{
 			name: "rule with no expression",
 			policies: []*testPolicy{

pkg/security/rules/monitor/policy_monitor_test.go

@@ -268,6 +268,56 @@ func (s *ScalarStringMatcher) Matches(value string) bool {
 	return s.value == value
 }
 
+// CaptureStringMatcher extracts a single capture group out of a value. Unlike the
+// StringMatcher implementations it is not used to match values, but to pull a
+// substring out of them, and is therefore compiled from a regexp with at least one
+// capture group.
+type CaptureStringMatcher struct {
+	pattern string
+	re      *regexp.Regexp
+}
+
+// Compile a capture pattern. The pattern must be a valid regular expression holding
+// at least one capture group, as only the first one is ever extracted.
+func (c *CaptureStringMatcher) Compile(pattern string) error {
+	re, err := regexp.Compile(pattern)
+	if err != nil {
+		return err
+	}
+
+	if re.NumSubexp() < 1 {
+		return errors.New("no capture group")
+	}
+
+	c.pattern = pattern
+	c.re = re
+
+	return nil
+}
+
+// String implements the stringer interface
+func (c *CaptureStringMatcher) String() string {
+	return c.pattern
+}
+
+// Capture returns the content of the first capture group, and whether the pattern
+// matched the value at all. A value that doesn't match, or that matches without the
+// first group participating, returns false.
+func (c *CaptureStringMatcher) Capture(value string) (string, bool) {
+	// FindStringSubmatchIndex is used over FindStringSubmatch to avoid allocating a
+	// slice of strings for every group of the pattern
+	indexes := c.re.FindStringSubmatchIndex(value)
+	if indexes == nil || indexes[2] < 0 {
+		return "", false
+	}
+
+	// slicing would share the backing array of the whole field value, keeping it alive
+	// for as long as the captured value is stored. Captures end up in variables that
+	// can be inherited across a process tree and outlive the event by a long time, so
+	// a small artifact must not pin the path it was extracted from.
+	return strings.Clone(value[indexes[2]:indexes[3]]), true
+}
+
 // NewStringMatcher returns a new string matcher
 func NewStringMatcher(kind FieldValueType, pattern string, opts StringCmpOpts) (StringMatcher, error) {
 	if opts.Sanitize != nil {

pkg/security/secl/compiler/eval/strings.go

@@ -259,6 +259,118 @@ func TestRegexp(t *testing.T) {
 	})
 }
 
+func TestCaptureStringMatcher(t *testing.T) {
+	t.Run("ssm-command-id", func(t *testing.T) {
+		var matcher CaptureStringMatcher
+		if err := matcher.Compile("/orchestration/([^/]+)/"); err != nil {
+			t.Fatal(err)
+		}
+
+		value, found := matcher.Capture("/var/lib/amazon/ssm/i-0abc/document/orchestration/a1b2c3d4/awsrunShellScript")
+		if !found {
+			t.Fatal("should have captured")
+		}
+
+		if value != "a1b2c3d4" {
+			t.Errorf("should have captured the command id, got `%s`", value)
+		}
+	})
+
+	t.Run("imds-role", func(t *testing.T) {
+		var matcher CaptureStringMatcher
+		if err := matcher.Compile("/security-credentials/([^/?]+)"); err != nil {
+			t.Fatal(err)
+		}
+
+		value, found := matcher.Capture("/latest/meta-data/iam/security-credentials/my-role?x=1")
+		if !found {
+			t.Fatal("should have captured")
+		}
+
+		if value != "my-role" {
+			t.Errorf("should have captured the role name, got `%s`", value)
+		}
+	})
+
+	t.Run("no-match", func(t *testing.T) {
+		var matcher CaptureStringMatcher
+		if err := matcher.Compile("/orchestration/([^/]+)/"); err != nil {
+			t.Fatal(err)
+		}
+
+		if value, found := matcher.Capture("/etc/passwd"); found {
+			t.Errorf("shouldn't have captured, got `%s`", value)
+		}
+	})
+
+	t.Run("no-capture-group", func(t *testing.T) {
+		var matcher CaptureStringMatcher
+		if err := matcher.Compile("/orchestration/[^/]+/"); err == nil {
+			t.Error("should have failed to compile a pattern without a capture group")
+		}
+	})
+
+	t.Run("non-capturing-group-only", func(t *testing.T) {
+		var matcher CaptureStringMatcher
+		if err := matcher.Compile("/orchestration/(?:[^/]+)/"); err == nil {
+			t.Error("should have failed to compile a pattern with only a non-capturing group")
+		}
+	})
+
+	t.Run("malformed-pattern", func(t *testing.T) {
+		var matcher CaptureStringMatcher
+		if err := matcher.Compile("/orchestration/([^/]+"); err == nil {
+			t.Error("should have failed to compile a malformed pattern")
+		}
+	})
+
+	t.Run("non-participating-group", func(t *testing.T) {
+		var matcher CaptureStringMatcher
+		if err := matcher.Compile("abc(x)?"); err != nil {
+			t.Fatal(err)
+		}
+
+		// the pattern matches, but the optional first group took no part in it
+		if value, found := matcher.Capture("abc"); found {
+			t.Errorf("shouldn't have captured, got `%s`", value)
+		}
+	})
+
+	t.Run("first-group-only", func(t *testing.T) {
+		var matcher CaptureStringMatcher
+		if err := matcher.Compile("/ecs/([0-9a-f-]+)/([0-9a-f-]+)"); err != nil {
+			t.Fatal(err)
+		}
+
+		value, found := matcher.Capture("/ecs/a1b2c3d4-1111/e5f6a7b8-2222")
+		if !found {
+			t.Fatal("should have captured")
+		}
+
+		if value != "a1b2c3d4-1111" {
+			t.Errorf("should have captured the first group only, got `%s`", value)
+		}
+	})
+
+	t.Run("big-or-pattern", func(t *testing.T) {
+		// RegexpStringMatcher takes a fast path for this shape and leaves its compiled
+		// regexp nil, which is why capture cannot reuse it. Make sure we still extract.
+		var matcher CaptureStringMatcher
+		if err := matcher.Compile(".*(restore|recovery|ransom).*"); err != nil {
+			t.Fatal(err)
+		}
+
+		value, found := matcher.Capture("123ransom456.txt")
+		if !found {
+			t.Fatal("should have captured")
+		}
+
+		if value != "ransom" {
+			t.Errorf("should have captured the alternation, got `%s`", value)
+		}
+	})
+}
+
 func BenchmarkRegexpEvaluator(b *testing.B) {
 	b.Run("with stars", func(b *testing.B) {
 		pattern := ".*(restore|recovery|readme|instruction|how_to|ransom).*"

pkg/security/secl/compiler/eval/strings_test.go

@@ -18,6 +18,7 @@ type Action struct {
 	InternalCallback    *InternalCallbackDefinition
 	FilterEvaluator     *eval.RuleEvaluator
 	ScopeFieldEvaluator eval.Evaluator
+	CaptureMatcher      *eval.CaptureStringMatcher
 }
 
 // CompileFilter compiles the filter expression
@@ -57,6 +58,21 @@ func (a *Action) CompileScopeField(model eval.Model) error {
 	return nil
 }
 
+// CompileCaptureMatcher compiles the capture pattern
+func (a *Action) CompileCaptureMatcher() error {
+	if a.Def.Set == nil || len(a.Def.Set.Capture) == 0 {
+		return nil
+	}
+
+	var matcher eval.CaptureStringMatcher
+	if err := matcher.Compile(a.Def.Set.Capture); err != nil {
+		return &ErrCapture{Pattern: a.Def.Set.Capture, Err: err}
+	}
+
+	a.CaptureMatcher = &matcher
+	return nil
+}
+
 // IsAccepted returns whether a filter is accepted and has to be executed
 func (a *Action) IsAccepted(ctx *eval.Context) bool {
 	return a.FilterEvaluator == nil || a.FilterEvaluator.Eval(ctx)

pkg/security/secl/rules/actions.go

@@ -184,6 +184,20 @@ func (e *ErrScopeField) Unwrap() error {
 	return e.Err
 }
 
+// ErrCapture is returned on capture definition error
+type ErrCapture struct {
+	Pattern string
+	Err     error
+}
+
+func (e *ErrCapture) Error() string {
+	return fmt.Sprintf("capture `%s` error: %s", e.Pattern, e.Err)
+}
+
+func (e *ErrCapture) Unwrap() error {
+	return e.Err
+}
+
 // ErrFieldNotAvailable is returned when a field is not available
 type ErrFieldNotAvailable struct {
 	Field        eval.Field

pkg/security/secl/rules/errors.go

@@ -226,6 +226,7 @@ type SetDefinition struct {
 	Value                   interface{}            `yaml:"value,omitempty" json:"value,omitempty" jsonschema:"oneof_required=SetWithValue,oneof_type=string;integer;boolean;array"`
 	DefaultValue            interface{}            `yaml:"default_value,omitempty" json:"default_value,omitempty" jsonschema:"oneof_type=string;integer;boolean;array"`
 	Field                   string                 `yaml:"field,omitempty" json:"field,omitempty" jsonschema:"oneof_required=SetWithField"`
+	Capture                 string                 `yaml:"capture,omitempty" json:"capture,omitempty" jsonschema:"description=A regular expression with a single capture group applied to 'field' to extract the value to store"`
 	Expression              string                 `yaml:"expression,omitempty" json:"expression,omitempty" jsonschema:"oneof_required=SetWithExpression"`
 	Append                  bool                   `yaml:"append,omitempty" json:"append,omitempty"`
 	Scope                   Scope                  `yaml:"scope,omitempty" json:"scope,omitempty" jsonschema:"enum=process,enum=container,enum=cgroup"`
@@ -259,6 +260,13 @@ func (s *SetDefinition) PreCheck(_ PolicyLoaderOpts) error {
 		return fmt.Errorf("failed to infer type for variable '%s', please set 'default_value'", s.Name)
 	}
 
+	// 'capture' extracts a substring out of the value of 'field', so it is meaningless
+	// without it. Combined with the check above, this also makes 'capture' mutually
+	// exclusive with 'value' and 'expression'.
+	if s.Capture != "" && s.Field == "" {
+		return errors.New("'capture' can only be used along with 'field'")
+	}
+
 	if s.Inherited && s.Scope != ScopeProcess {
 		return errors.New("only variables scoped to process can be marked as inherited")
 	}