feat(flags): simplify detectors flag and add short aliases

yanivagman · yanivagman · commit fe54be01601e · 2026-01-20T01:43:58.000+02:00
- Change --detectors to accept paths directly (no yaml-dir= prefix)
- Add -d alias for --detectors, -E alias for --enrichment
- Simplify config file format to flat list under detectors key
- Update --buffers description to 'Set buffers size'
- Add detectors man page and update man index with new aliases
diff --git a/cmd/tracee/cmd/man.go b/cmd/tracee/cmd/man.go
@@ -55,6 +55,7 @@ func init() {
 		capabilitiesCmd,
 		artifactsCmd,
 		configCmd,
+		detectorsCmd,
 		enrichmentCmd,
 		eventCmd,
 		eventsCmd,
@@ -122,9 +123,18 @@ var configCmd = &cobra.Command{
 	},
 }
 
+var detectorsCmd = &cobra.Command{
+	Use:     "detectors",
+	Aliases: []string{"d"},
+	Short:   "Show manual page for the --detectors flag",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		return runManForFlag("detectors")
+	},
+}
+
 var enrichmentCmd = &cobra.Command{
 	Use:     "enrichment",
-	Aliases: []string{},
+	Aliases: []string{"E"},
 	Short:   "Show manual page for the --enrichment flag",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return runManForFlag("enrichment")
diff --git a/cmd/tracee/cmd/root.go b/cmd/tracee/cmd/root.go
@@ -152,8 +152,9 @@ func initCmd() error {
 
 	// Container flags
 
-	rootCmd.Flags().StringArray(
+	rootCmd.Flags().StringArrayP(
 		flags.EnrichmentFlag,
+		"E",
 		[]string{},
 		"[container|resolve-fd...]\t\tConfigure enrichment for container events and other enrichment features",
 	)
@@ -190,10 +191,11 @@ func initCmd() error {
 
 	// Detector flags
 
-	rootCmd.Flags().StringArray(
+	rootCmd.Flags().StringArrayP(
 		flags.DetectorsFlag,
+		"d",
 		[]string{},
-		"[yaml-dir=<dir>]\t\t\tConfigure YAML detector search directories",
+		"[path...]\t\t\t\tConfigure YAML detector search directories",
 	)
 	err = viper.BindPFlag(flags.DetectorsFlag, rootCmd.Flags().Lookup(flags.DetectorsFlag))
 	if err != nil {
@@ -211,7 +213,7 @@ func initCmd() error {
 			fmt.Sprintf("kernel.artifacts=%d", flags.GetDefaultPerfBufferSize()),
 			"pipeline=1000",
 		},
-		"[kernel.events|...]\t\tSize for kernel and user buffers",
+		"[kernel.events|...]\t\tSet buffers size",
 	)
 	err = viper.BindPFlag(flags.BuffersFlag, rootCmd.Flags().Lookup(flags.BuffersFlag))
 	if err != nil {
diff --git a/docs/docs/detectors/yaml-detectors.md b/docs/docs/detectors/yaml-detectors.md
@@ -910,15 +910,14 @@ Specify custom directories using:
 
 **CLI Flag:**
 ```bash
-tracee --detectors yaml-dir=/custom/path
+tracee --detectors /custom/path
 ```
 
 **Config File:**
 ```yaml
 detectors:
-  yaml-dir:
-    - /custom/path1
-    - /custom/path2
+  - /custom/path1
+  - /custom/path2
 ```
 
 ## Validation
diff --git a/docs/docs/flags/buffers.1.md b/docs/docs/flags/buffers.1.md
@@ -7,7 +7,7 @@ date: 2025/12
 
 ## NAME
 
-tracee **\-\-buffers** - Configure the buffers sizes for kernel and user buffers
+tracee **\-\-buffers** - Set kernel/user buffers size
 
 ## SYNOPSIS
 
diff --git a/docs/docs/flags/detectors.1.md b/docs/docs/flags/detectors.1.md
@@ -0,0 +1,49 @@
+---
+title: TRACEE-DETECTORS
+section: 1
+header: Tracee Detectors Flag Manual
+date: 2026/01
+...
+
+## NAME
+
+tracee **\-\-detectors** - Configure YAML detector search directories
+
+## SYNOPSIS
+
+tracee **\-\-detectors** [path...] [**\-\-detectors** path...]
+
+## DESCRIPTION
+
+The **\-\-detectors** flag lets you add directories or files to search for YAML detectors and shared lists.
+
+Each path can be a directory or a YAML file. If not specified, Tracee uses the default search path `/etc/tracee/detectors`.
+
+## EXAMPLES
+
+1. Use the default search path:
+   ```console
+   tracee
+   ```
+
+2. Add a custom directory:
+   ```console
+   --detectors /custom/detectors
+   ```
+
+3. Add multiple directories:
+   ```console
+   --detectors /dir1 --detectors /dir2
+   ```
+
+4. Add a specific YAML detector file:
+   ```console
+   --detectors ./detectors/suspicious_exec.yaml
+   ```
+
+5. Config file format:
+   ```yaml
+   detectors:
+     - /custom/path1
+     - /custom/path2
+   ```
diff --git a/docs/docs/flags/man.1.md b/docs/docs/flags/man.1.md
@@ -25,7 +25,8 @@ The **man** command accepts subcommands that correspond to tracee flags:
 - **buffers** - Show manual page for the --buffers flag
 - **capabilities**, **C** - Show manual page for the --capabilities flag
 - **config**, **c** - Show manual page for the --config flag
-- **enrichment** - Show manual page for the --enrichment flag
+- **detectors**, **d** - Show manual page for the --detectors flag
+- **enrichment**, **E** - Show manual page for the --enrichment flag
 - **events**, **e** - Show manual page for the --events flag
 - **list** - Show manual page for the list command
 - **list-events** - Show manual page for the list events subcommand
diff --git a/docs/man/buffers.1 b/docs/man/buffers.1
@@ -2,11 +2,11 @@
 .\"
 .TH "TRACEE\-BUFFERS" "1" "2025/12" "" "Tracee Buffers Flag Manual"
 .SS NAME
-tracee \f[B]\-\-buffers\f[R] \- Configure the buffers sizes for kernel
-and user buffers
+tracee \f[B]\-\-buffers\f[R] \- Set kernel/user buffers size
 .SS SYNOPSIS
-tracee \f[B]\-\-buffers\f[R] [kernel.events=<size> | kernel.artifacts=<size>
-| kernel.control\-plane=<size> | pipeline=<size>] \&...
+tracee \f[B]\-\-buffers\f[R] [kernel.events=<size> |
+kernel.artifacts=<size> | kernel.control\-plane=<size> |
+pipeline=<size>] \&...
 [\f[B]\-\-buffers\f[R] [kernel.events=<size> | kernel.artifacts=<size> |
 kernel.control\-plane=<size> | pipeline=<size>] \&...]
 .SS DESCRIPTION
@@ -24,8 +24,8 @@ Possible buffer options:
 \f[B]kernel.events=<size>\f[R]: Sets the size, in pages, of the internal
 perf ring buffer used to submit events from the kernel.
 .IP \[bu] 2
-\f[B]kernel.artifacts=<size>\f[R]: Sets the size, in pages, of the internal
-perf ring buffer used to send artifacts from the kernel.
+\f[B]kernel.artifacts=<size>\f[R]: Sets the size, in pages, of the
+internal perf ring buffer used to send artifacts from the kernel.
 .IP \[bu] 2
 \f[B]kernel.control\-plane=<size>\f[R]: Sets the size, in pages, of the
 internal perf ring buffer used to submit events from the control plane.
diff --git a/docs/man/detectors.1 b/docs/man/detectors.1
@@ -0,0 +1,59 @@
+.\" Automatically generated by Pandoc 3.2
+.\"
+.TH "TRACEE\-DETECTORS" "1" "2026/01" "" "Tracee Detectors Flag Manual"
+.SS NAME
+tracee \f[B]\-\-detectors\f[R] \- Configure YAML detector search
+directories
+.SS SYNOPSIS
+tracee \f[B]\-\-detectors\f[R] [path\&...]
+[\f[B]\-\-detectors\f[R] path\&...]
+.SS DESCRIPTION
+The \f[B]\-\-detectors\f[R] flag lets you add directories or files to
+search for YAML detectors and shared lists.
+.PP
+Each path can be a directory or a YAML file.
+If not specified, Tracee uses the default search path
+\f[CR]/etc/tracee/detectors\f[R].
+.SS EXAMPLES
+.IP "1." 3
+Use the default search path:
+.RS 4
+.IP
+.EX
+tracee
+.EE
+.RE
+.IP "2." 3
+Add a custom directory:
+.RS 4
+.IP
+.EX
+\-\-detectors /custom/detectors
+.EE
+.RE
+.IP "3." 3
+Add multiple directories:
+.RS 4
+.IP
+.EX
+\-\-detectors /dir1 \-\-detectors /dir2
+.EE
+.RE
+.IP "4." 3
+Add a specific YAML detector file:
+.RS 4
+.IP
+.EX
+\-\-detectors ./detectors/suspicious_exec.yaml
+.EE
+.RE
+.IP "5." 3
+Config file format:
+.RS 4
+.IP
+.EX
+detectors\f[B]:\f[R]
+  \f[B]\-\f[R] /custom/path1
+  \f[B]\-\f[R] /custom/path2
+.EE
+.RE
diff --git a/docs/man/man.1 b/docs/man/man.1
@@ -28,7 +28,11 @@ flags:
 \f[B]config\f[R], \f[B]c\f[R] \- Show manual page for the \[en]config
 flag
 .IP \[bu] 2
-\f[B]enrichment\f[R] \- Show manual page for the \[en]enrichment flag
+\f[B]detectors\f[R], \f[B]d\f[R] \- Show manual page for the
+\[en]detectors flag
+.IP \[bu] 2
+\f[B]enrichment\f[R], \f[B]E\f[R] \- Show manual page for the
+\[en]enrichment flag
 .IP \[bu] 2
 \f[B]events\f[R], \f[B]e\f[R] \- Show manual page for the \[en]events
 flag
diff --git a/examples/config/global_config.yaml b/examples/config/global_config.yaml
@@ -107,10 +107,10 @@ artifacts:
     #     path: /tmp/tracee
     #     clear: false
 
-# Detectors configuration
+# Detectors configuration - list of paths to search for YAML detectors
 detectors:
-    # yaml-dir:
-    #     - /path/to/detector/dir
+    # - /path/to/detector/dir
+    # - /another/detector/path
 
 # Logging configuration
 logging:
diff --git a/examples/detectors/yaml/CHAIN_TEST.md b/examples/detectors/yaml/CHAIN_TEST.md
@@ -12,7 +12,7 @@ Simple 3-level chain for local testing (no K8s required).
 
 ### Terminal 1: Start Tracee
 ```bash
-sudo tracee --detectors yaml-dir=./examples/detectors/yaml --output json \
+sudo tracee --detectors ./examples/detectors/yaml --output json \
   --enrichment container \
   --events netcat_privileged_alert
 ```
diff --git a/pkg/cmd/cobra/cobra.go b/pkg/cmd/cobra/cobra.go
@@ -103,11 +103,7 @@ func GetTraceeRunner(c *cobra.Command, version string) (cmd.Runner, error) {
 
 	// Get YAML detector search directories from config or CLI
 	var yamlDetectorDirs []string
-	if viper.IsSet(flags.YAMLDirFlag) {
-		// Config file format: detectors.yaml-dir
-		yamlDetectorDirs = viper.GetStringSlice(flags.YAMLDirFlag)
-	} else if viper.IsSet(flags.DetectorsFlag) {
-		// CLI format: --detectors yaml-dir=/path/to/dir
+	if viper.IsSet(flags.DetectorsFlag) {
 		detectorsFlags, err := flags.GetFlagsFromViper(flags.DetectorsFlag)
 		if err != nil {
 			return runner, err
@@ -116,7 +112,7 @@ func GetTraceeRunner(c *cobra.Command, version string) (cmd.Runner, error) {
 		if err != nil {
 			return runner, err
 		}
-		yamlDetectorDirs = detectorsConfig.YAMLDirs
+		yamlDetectorDirs = detectorsConfig.Paths
 	}
 
 	// Pre-register detector events in events.Core before policy initialization
diff --git a/pkg/cmd/flags/detectors.go b/pkg/cmd/flags/detectors.go
@@ -10,52 +10,31 @@ import (
 const (
 	DetectorsFlag = "detectors"
 
-	// yamlDirFlag is the CLI flag name for YAML detector directories (--detectors yaml-dir=/path)
-	yamlDirFlag = "yaml-dir"
-
-	// YAMLDirFlag is the config file key for YAML detector directories (detectors.yaml-dir)
-	YAMLDirFlag = "detectors.yaml-dir"
-
 	invalidDetectorsFlagError = "invalid detectors flag: '%s', use 'tracee man detectors' for more info"
 )
 
 // DetectorsConfig is the configuration for detectors
 type DetectorsConfig struct {
-	YAMLDirs []string `mapstructure:"yaml-dir"`
+	Paths []string `mapstructure:",remain"`
 }
 
 // flags returns the flags for the detectors config
 func (c *DetectorsConfig) flags() []string {
-	flags := make([]string, 0, len(c.YAMLDirs))
-
-	for _, dir := range c.YAMLDirs {
-		flags = append(flags, fmt.Sprintf("%s=%s", yamlDirFlag, dir))
-	}
-
-	return flags
+	return c.Paths
 }
 
 // PrepareDetectors prepares the detectors configuration from a list of flags
 func PrepareDetectors(flags []string) (DetectorsConfig, error) {
 	config := DetectorsConfig{
-		YAMLDirs: make([]string, 0),
+		Paths: make([]string, 0),
 	}
 
 	for _, flag := range flags {
-		parts := strings.Split(flag, "=")
-		if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+		if flag == "" || strings.Contains(flag, "=") {
 			return DetectorsConfig{}, errfmt.Errorf(invalidDetectorsFlagError, flag)
 		}
 
-		flagName := parts[0]
-		flagValue := parts[1]
-
-		switch flagName {
-		case yamlDirFlag:
-			config.YAMLDirs = append(config.YAMLDirs, flagValue)
-		default:
-			return DetectorsConfig{}, errfmt.Errorf(invalidDetectorsFlagError, flagName)
-		}
+		config.Paths = append(config.Paths, flag)
 	}
 
 	return config, nil
diff --git a/pkg/cmd/flags/detectors_test.go b/pkg/cmd/flags/detectors_test.go
