feat: enable detector selection by tags

Register detector ProducedEvent.Tags as event sets, allowing users to select
detectors using --events <tag>. Includes unit and integration tests.

Author: yanivagman

docs/docs/flags/events.1.md

@@ -1,4 +1,4 @@
----
+--
 title: TRACEE-EVENTS
 section: 1
 header: Tracee Events Flag Manual
@@ -113,6 +113,24 @@ Threat selection can be combined with regular events. Multiple `--events` flags
 
 **Note:** Detector selection based on threat properties is performed once at startup. Matching detectors are enabled; non-matching detectors are never loaded.
 
+## DETECTOR TAG SELECTION
+
+Detectors can be categorized with tags. You can select all detectors with a specific tag:
+
+```console
+--events containers       # All detectors tagged with "containers"
+--events malware          # All detectors tagged with "malware"
+--events detectors        # All detectors (existing behavior)
+```
+
+Tags can be combined with other selection methods:
+
+```console
+--events containers,execve                # Detectors with "containers" tag + execve syscall
+--events 'threat.severity=critical'       # Critical threats (any tag)
+--events malware,'threat.severity>=high'  # Detectors with "malware" tag OR high+ severity threats
+```
+
 ## EXAMPLES
 
 - To trace only 'execve' and 'open' events, use the following flag:

docs/docs/policies/rules.md

@@ -103,6 +103,16 @@ rules:
   - event: threat.name=process_injection
 ```
 
+#### Selecting by Detector Tags
+
+Detectors can be categorized with tags. Select all detectors with a specific tag:
+
+```yaml
+rules:
+  - event: containers        # All detectors with "containers" tag
+  - event: malware          # All detectors with "malware" tag
+```
+
 #### Combining with Regular Events
 
 Threat-based selection can be combined with regular event selection:

docs/man/events.1

@@ -1,6 +1,9 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "TRACEE\-EVENTS" "1" "2024/12" "" "Tracee Events Flag Manual"
+.TH "" "" "" "" ""
+.PP
+\[en] title: TRACEE\-EVENTS section: 1 header: Tracee Events Flag Manual
+date: 2024/12 \&...
 .SS NAME
 tracee \f[B]\-\-events\f[R] \- Select which events to trace
 .SS SYNOPSIS
@@ -127,12 +130,34 @@ Supports: =, !=
 \-\-events threat.name=process_injection
 .EE
 .PP
-Threat selection can be combined with regular events and is performed at
-policy initialization (static, not runtime filtering):
+Threat selection can be combined with regular events.
+Multiple \f[CR]\-\-events\f[R] flags are combined additively (OR logic):
+.IP
+.EX
+\-\-events threat.severity=critical \-\-events write    # Critical threats OR write events
+\-\-events fs \-\-events \[aq]threat.severity>=high\[aq]        # Filesystem events OR high+ threats
+.EE
+.PP
+\f[B]Note:\f[R] Detector selection based on threat properties is
+performed once at startup.
+Matching detectors are enabled; non\-matching detectors are never
+loaded.
+.SS DETECTOR TAG SELECTION
+Detectors can be categorized with tags.
+You can select all detectors with a specific tag:
+.IP
+.EX
+\-\-events containers       # All detectors tagged with \[dq]containers\[dq]
+\-\-events malware          # All detectors tagged with \[dq]malware\[dq]
+\-\-events detectors        # All detectors (existing behavior)
+.EE
+.PP
+Tags can be combined with other selection methods:
 .IP
 .EX
-\-\-events threat.severity=critical \-\-events write
-\-\-events fs \-\-events \[aq]threat.severity>=high\[aq]
+\-\-events containers,execve                # Detectors with \[dq]containers\[dq] tag + execve syscall
+\-\-events \[aq]threat.severity=critical\[aq]       # Critical threats (any tag)
+\-\-events malware,\[aq]threat.severity>=high\[aq]  # Detectors with \[dq]malware\[dq] tag OR high+ severity threats
 .EE
 .SS EXAMPLES
 .IP \[bu] 2

pkg/cmd/flags/policy_test.go

@@ -1,13 +1,17 @@
 package flags
 
 import (
+	"context"
 	"fmt"
 	"math"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	pb "github.com/aquasecurity/tracee/api/v1beta1"
+	"github.com/aquasecurity/tracee/api/v1beta1/detection"
+	"github.com/aquasecurity/tracee/pkg/detectors"
 	"github.com/aquasecurity/tracee/pkg/events"
 	"github.com/aquasecurity/tracee/pkg/filters"
 	k8s "github.com/aquasecurity/tracee/pkg/k8s/apis/tracee.aquasec.com/v1beta1"
@@ -2488,3 +2492,148 @@ func TestParseEventFilters(t *testing.T) {
 		})
 	}
 }
+
+func TestParseEventFiltersDetectorTags(t *testing.T) {
+	// NOTE: Not using t.Parallel() because this test modifies global events.Core state
+
+	// Save and restore events.Core
+	originalCore := events.Core
+	defer func() { events.Core = originalCore }()
+
+	// Create fresh DefinitionGroup with core events
+	events.Core = events.NewDefinitionGroup()
+	err := events.Core.AddBatch(events.CoreEvents)
+	require.NoError(t, err)
+
+	// Create mock detectors with tags and register their events
+	mockDetectors := []detection.EventDetector{
+		createMockDetectorForTagTest("det1", "detector_event1", []string{"test_tag_a"}),
+		createMockDetectorForTagTest("det2", "detector_event2", []string{"test_tag_b"}),
+		createMockDetectorForTagTest("det3", "detector_event3", []string{"test_tag_a", "test_tag_c"}),
+	}
+
+	// Register detector events in events.Core (simulating what happens at startup)
+	eventNameToID, err := detectors.CreateEventsFromDetectors(events.StartDetectorID, mockDetectors)
+	require.NoError(t, err)
+
+	testCases := []struct {
+		name       string
+		eventFlags []eventFlag
+		validate   func(*testing.T, *policy.Policy, map[string]events.ID)
+	}{
+		{
+			name: "detector tag selection - test_tag_a",
+			eventFlags: []eventFlag{{
+				full:      "test_tag_a",
+				eventName: "test_tag_a",
+			}},
+			validate: func(t *testing.T, p *policy.Policy, eMap map[string]events.ID) {
+				// Should have detector_event1 and detector_event3 (both have "test_tag_a" tag)
+				assert.Contains(t, p.Rules, eMap["detector_event1"])
+				assert.Contains(t, p.Rules, eMap["detector_event3"])
+				assert.NotContains(t, p.Rules, eMap["detector_event2"])
+				assert.Equal(t, 2, len(p.Rules), "Should have exactly 2 events selected")
+			},
+		},
+		{
+			name: "detector tag selection - test_tag_b",
+			eventFlags: []eventFlag{{
+				full:      "test_tag_b",
+				eventName: "test_tag_b",
+			}},
+			validate: func(t *testing.T, p *policy.Policy, eMap map[string]events.ID) {
+				// Should have only detector_event2
+				assert.Contains(t, p.Rules, eMap["detector_event2"])
+				assert.NotContains(t, p.Rules, eMap["detector_event1"])
+				assert.NotContains(t, p.Rules, eMap["detector_event3"])
+				assert.Equal(t, 1, len(p.Rules), "Should have exactly 1 event selected")
+			},
+		},
+		{
+			name: "detector tag with regular event",
+			eventFlags: []eventFlag{
+				{
+					full:      "test_tag_a",
+					eventName: "test_tag_a",
+				},
+				{
+					full:      "write",
+					eventName: "write",
+				},
+			},
+			validate: func(t *testing.T, p *policy.Policy, eMap map[string]events.ID) {
+				// Should have test_tag_a detectors + write syscall
+				assert.Contains(t, p.Rules, eMap["detector_event1"])
+				assert.Contains(t, p.Rules, eMap["detector_event3"])
+				assert.Contains(t, p.Rules, events.Write)
+				assert.Equal(t, 3, len(p.Rules), "Should have 3 events selected")
+			},
+		},
+		{
+			name: "all detectors set",
+			eventFlags: []eventFlag{{
+				full:      "detectors",
+				eventName: "detectors",
+			}},
+			validate: func(t *testing.T, p *policy.Policy, eMap map[string]events.ID) {
+				// Should have all detector events (including built-in detectors, so check for ours)
+				assert.Contains(t, p.Rules, eMap["detector_event1"])
+				assert.Contains(t, p.Rules, eMap["detector_event2"])
+				assert.Contains(t, p.Rules, eMap["detector_event3"])
+				// Note: may have more than 3 if there are built-in detectors
+				assert.GreaterOrEqual(t, len(p.Rules), 3, "Should have at least our 3 detector events")
+			},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			// Don't use t.Parallel() here because we need the events.Core state from parent test
+			// Create fresh policy for each test case
+			p := policy.NewPolicy()
+
+			err := parseEventFilters(p, tc.eventFlags, mockDetectors)
+			require.NoError(t, err)
+
+			if tc.validate != nil {
+				tc.validate(t, p, eventNameToID)
+			}
+		})
+	}
+}
+
+// createMockDetectorForTagTest creates a mock detector for tag testing
+func createMockDetectorForTagTest(id, eventName string, tags []string) detection.EventDetector {
+	return &mockDetectorForPolicyTest{
+		id:        id,
+		eventName: eventName,
+		tags:      tags,
+	}
+}
+
+// mockDetectorForPolicyTest implements detection.EventDetector for policy testing
+type mockDetectorForPolicyTest struct {
+	id        string
+	eventName string
+	tags      []string
+}
+
+func (m *mockDetectorForPolicyTest) GetDefinition() detection.DetectorDefinition {
+	return detection.DetectorDefinition{
+		ID: m.id,
+		ProducedEvent: pb.EventDefinition{
+			Name:        m.eventName,
+			Description: "Mock detector for policy test",
+			Tags:        m.tags,
+		},
+		Requirements: detection.DetectorRequirements{},
+	}
+}
+
+func (m *mockDetectorForPolicyTest) Init(params detection.DetectorParams) error {
+	return nil
+}
+
+func (m *mockDetectorForPolicyTest) OnEvent(ctx context.Context, event *pb.Event) ([]detection.DetectorOutput, error) {
+	return nil, nil
+}

pkg/detectors/events.go

@@ -99,10 +99,10 @@ func CreateEventsFromDetectors(startID events.ID, detectors []detection.EventDet
 			def.ProducedEvent.Description,             // description
 			false,                                     // internal
 			false,                                     // syscall
-			[]string{"detectors", "default"},          // sets
-			events.NewDependencyStrategy(dependencies),          // deps
-			convertFieldsToDataFields(def.ProducedEvent.Fields), // fields
-			map[string]interface{}{"detectorID": def.ID},        // properties
+			append([]string{"detectors", "default"}, def.ProducedEvent.Tags...), // sets - include detector tags
+			events.NewDependencyStrategy(dependencies),                          // deps
+			convertFieldsToDataFields(def.ProducedEvent.Fields),                 // fields
+			map[string]interface{}{"detectorID": def.ID},                        // properties
 		)
 
 		// Add to events.Core