feat(cmd/flags)!: split filter flag

This commit splits the '--filter' flag into two new flags: '--scope' and '--event'. The '--scope' flag is used to specify the scope of the events to be captured like 'comm', 'binary', 'pid', 'uid', 'mntns', 'pidns', 'uts', 'tree', 'follow' and 'container', while the '--event' flag is used to specify the events and their userland filters like 'args', 'retval' and 'context'. This also relocates unit tests from flags_test.go to respective new correlated files, making it easier to maintain and extend. BREAKING CHANGE: '--filter' flag is now replaced by '--scope' and '--event' flags. Co-authored-by: Yaniv Agman <yanivagman@gmail.com>
aquasecurity · Jun 29, 2023 · cb2201e · cb2201e
1 parent 00f71ab
commit cb2201e
Show file tree

Hide file tree

Showing 58 changed files with 4,000 additions and 2,646 deletions.
diff --git a/cmd/tracee-ebpf/main.go b/cmd/tracee-ebpf/main.go
@@ -57,10 +57,15 @@ func main() {
 				Usage:   "list traceable events",
 			},
 			&cli.StringSliceFlag{
-				Name:    "filter",
-				Aliases: []string{"f"},
+				Name:    "scope",
+				Aliases: []string{"s"},
 				Value:   nil,
-				Usage:   "select events to trace by defining filter expressions. run '--filter help' for more info.",
+				Usage:   "select workloads to trace by defining filter expressions. run '--scope help' for more info.",
+			},
+			&cli.StringSliceFlag{
+				Name:    "event",
+				Aliases: []string{"e"},
+				Usage:   "select events to trace and filter events. run '--event help' for more info.",
 			},
 			&cli.StringSliceFlag{
 				Name:    "capture",

diff --git a/cmd/tracee/cmd/analyze.go b/cmd/tracee/cmd/analyze.go
@@ -96,8 +96,8 @@ var analyze = &cobra.Command{
 Tracee can be used to collect events and store it in a file. This file can be used as input to analyze.
 
 eg:
-tracee --filter event=ptrace --output=json:events.json
-tracee analyze --event=anti_debugging events.json`,
+tracee --event ptrace --output=json:events.json
+tracee analyze --event anti_debugging events.json`,
 	Run: func(cmd *cobra.Command, args []string) {
 		inputFile, err := os.Open(args[0])
 		if err != nil {

diff --git a/cmd/tracee/cmd/root.go b/cmd/tracee/cmd/root.go
@@ -75,14 +75,22 @@ func initCmd() error {
 		hfFallback(cmd, args)
 	})
 
-	// Filter/Policy flags
+	// Scope/Event/Policy flags
 
-	// filter is not bound to viper
+	// scope is not bound to viper
 	rootCmd.Flags().StringArrayP(
-		"filter",
-		"f",
+		"scope",
+		"s",
 		[]string{},
-		"Select events to trace by defining filter expressions",
+		"Select workloads to trace by defining filter expressions",
+	)
+
+	// event is not bound to viper
+	rootCmd.Flags().StringArrayP(
+		"event",
+		"e",
+		[]string{},
+		"Select events to trace and event filters",
 	)
 
 	// policy is not bound to viper

diff --git a/docs/contributing/building/environment.md b/docs/contributing/building/environment.md
@@ -33,8 +33,8 @@
         make tracee
         sudo ./dist/tracee \
             -o option:parse-arguments \
-            --filter comm=bash \
-            --filter follow
+            --scope comm=bash \
+            --scope follow
         ```
 
     Now, in your host's bash shell, execute a command. You will see all events
@@ -55,8 +55,8 @@
         sudo ./dist/tracee \
             -o format:json \
             -o option:parse-arguments \
-            --filter comm=bash \
-            --filter follow 
+            --scope comm=bash \
+            --scope follow 
         ```
 
     Now, in your host's bash shell, execute: `sudo strace /bin/ls` and observe
@@ -134,8 +134,8 @@ And, after the compilation, run the commands directly in your host:
 ```console
 sudo ./dist/tracee \
     -o option:parse-arguments \
-    --filter comm=bash \
-    --filter follow
+    --scope comm=bash \
+    --scope follow
 ```
 
 > **Note**: the generated binary must be compatible to your host (depending on

diff --git a/docs/docs/config/overview.md b/docs/docs/config/overview.md
@@ -38,7 +38,8 @@ There are a few flags that are reserved for the CLI and cannot be set through th
 - `--config`: This flag is used to specify the configuration file, so it cannot be set through the configuration file itself.
 - `--capture`: This flag is used to specify which events should be captured by Tracee, so it cannot be set through the configuration file.
 - `--policy`: This flag is used to specify a policy file for Tracee, so it cannot be set through the configuration file.
-- `--filter `: This flag is used to specify an event filter for Tracee via CLI and via policy file loading mechanism (the --policy flag), so it cannot be set through the configuration file.
+- `--scope `: This flag is used to specify an scope (workload) filter for Tracee via CLI and via policy file loading mechanism (the --policy flag), so it cannot be set through the configuration file.
+- `--event`: This flag is used to specify a event filter for Tracee via CLI and via policy file loading mechanism (the --policy flag), so it cannot be set through the configuration file.
 
 ## Example Configuration Files
 

diff --git a/docs/docs/events/builtin/extra/bpf_attach.md b/docs/docs/events/builtin/extra/bpf_attach.md
@@ -58,7 +58,10 @@ kprobe
 get information about which helper functions are used by the BPF program
 
 ## Example Use Case
-./tracee -f e=bpf_attach
+
+```console
+./tracee -e bpf_attach
+```
 
 ## Issues
 

diff --git a/docs/docs/events/builtin/extra/file_modification.md b/docs/docs/events/builtin/extra/file_modification.md
@@ -39,7 +39,10 @@ kprobe + kretprobe
 Catch the file ctime change and submit the event if marked to be submitted
 
 ## Example Use Case
-./tracee -f e=file_modification
+
+```console
+./tracee -e file_modification
+```
 
 ## Note
 Only the first event of file modification is submitted between the open and the close of a file by a process. 

diff --git a/docs/docs/events/builtin/extra/hidden_kernel_module.md b/docs/docs/events/builtin/extra/hidden_kernel_module.md
@@ -16,7 +16,10 @@ It periodically checks for a hidden module.
 Self-triggered hook by uprobing itself.
 
 ## Example Use Case
-./tracee -f e=hidden_kernel_module
+
+```console
+./tracee -e hidden_kernel_module
+```
 
 ## Issues
 

diff --git a/docs/docs/events/builtin/extra/hooked_syscalls.md b/docs/docs/events/builtin/extra/hooked_syscalls.md
@@ -60,7 +60,9 @@ Detection of syscall hooking.
 The `hooked_syscalls` event could be used as part of a broader system integrity monitoring solution. For example, a security engineer could use it to raise alerts or run further investigations if unexpected syscall hooking activities are detected. This could aid in the early detection and mitigation of malware or rootkit infections.
 Example:
 
-`tracee -f e=hooked_syscalls -f hooked_syscalls.args.check_syscalls=<syscall>,<syscall>,...`
+```console
+tracee -e hooked_syscalls -e hooked_syscalls.args.check_syscalls=<syscall>,<syscall>,...`
+```
 
 ## Issues
 The `check_syscalls` argument is used as a parameter to specify the syscalls to be checked. This will change in the future to be an event parameter.

diff --git a/docs/docs/events/builtin/extra/kallsyms_lookup_name.md b/docs/docs/events/builtin/extra/kallsyms_lookup_name.md
@@ -21,4 +21,7 @@ kprobe + kretprobe
 tracing the kallsyms_lookup_name event
 
 ## Example Use Case
-`./dist/tracee -f e=kallsyms_lookup_name`
+
+```console
+./dist/tracee -e kallsyms_lookup_name
+```
diff --git a/docs/docs/events/builtin/extra/process_execute_failed.md b/docs/docs/events/builtin/extra/process_execute_failed.md
@@ -37,7 +37,10 @@ kretprobe
 Fetch the return value of exec_binprm
 
 ## Example Use Case
-./tracee -f e=process_execution_failed
+
+```console
+./tracee -e process_execution_failed
+```
 
 ## Issues
 Currently, only covers failed executions that are happening within exec_binprm. Other failures may occur at an earlier stage.

diff --git a/docs/docs/events/builtin/extra/security_bpf_prog.md b/docs/docs/events/builtin/extra/security_bpf_prog.md
@@ -42,7 +42,10 @@ kprobe
 get information about which helper functions are used by the BPF program
 
 ## Example Use Case
-./tracee -f e=security_bpf_prog
+
+```console
+./tracee -e security_bpf_prog
+```
 
 ## Issues
 

diff --git a/docs/docs/events/builtin/extra/symbols_collision.md b/docs/docs/events/builtin/extra/symbols_collision.md
@@ -34,7 +34,7 @@ Also, used to maintain the cache used by the event for performance improvement.
 Could be used for example to catch collision between a shared object and `libc.so`, overwriting libc symbols:
 
 ```console
-./dist/tracee -f e=symbols_collision -f symbols_collision.args.loaded_path=/usr/lib/libc.so.6
+./dist/tracee -e symbols_collision -e symbols_collision.args.loaded_path=/usr/lib/libc.so.6
 ```
 
 Running this line will give a lot of spam symbols collision, for example collisions of `libc` with `libm`:
@@ -48,13 +48,13 @@ To reduce the spam collisions, we can configure the event to not print the colli
 1. Whitelist the collided symbols:
 
 ```console
-./dist/tracee -f e=symbols_collision -f symbols_collision.args.loaded_path=/usr/lib/libc.so.6 -f symbols_collision.args.symbols!=finitel,__signbitf,finite,frexpl,frexp,scalbn,__finite,copysignl,scalbnf,__signbitl,scalbnl,copysign,copysignf,ldexpf,modff,modf,ldexp,ldexpl,finitef,frexpf,__finitel,modfl,__finitef,__signbit
+./dist/tracee -e symbols_collision -e symbols_collision.args.loaded_path=/usr/lib/libc.so.6 -e symbols_collision.args.symbols!=finitel,__signbitf,finite,frexpl,frexp,scalbn,__finite,copysignl,scalbnf,__signbitl,scalbnl,copysign,copysignf,ldexpf,modff,modf,ldexp,ldexpl,finitef,frexpf,__finitel,modfl,__finitef,__signbit
 ```
 
 2. Whitelist the library `libm`:
 
 ```console
-./dist/tracee -f e=symbols_collision -f symbols_collision.args.loaded_path=/usr/lib/libc.so.6 -f symbols_collision.args.collision_path!=/usr/lib/libm.so.6
+./dist/tracee -e symbols_collision -e symbols_collision.args.loaded_path=/usr/lib/libc.so.6 -e symbols_collision.args.collision_path!=/usr/lib/libm.so.6
 ```
 
 The first approach is recommended when dealing with common symbols like 'setup_', 'finish_' etc. because it will reduce

diff --git a/docs/docs/events/builtin/extra/symbols_loaded.md b/docs/docs/events/builtin/extra/symbols_loaded.md
@@ -39,7 +39,9 @@ Used by tracee to maintain mount NS cache, used in this event to get to processe
 To catch SO which tries to override the `fopen` function of `libc`, we can use the event in
 the following way:
 
-`./dist/tracee -f e=symbols_loaded -f symbols_loaded.args.symbols=fopen symbols_loaded.args.library_path!=libc`
+```console
+./dist/tracee -e symbols_loaded -e symbols_loaded.args.symbols=fopen -e symbols_loaded.args.library_path!=libc
+```
 
 ## Issues
 Because the event is implemented in user-mode, it needs to open and read files.

diff --git a/docs/docs/events/builtin/network.md b/docs/docs/events/builtin/network.md
@@ -175,7 +175,7 @@ Tracee offers a set of network events that makes it easy to trace network activi
 Trace all TCP packets sent to port 80 anywhere, from any process:
 
 ```console
-tracee --output json --filter event=net_packet_tcp --filter net_packet_tcp.args.dst_port=80
+tracee --output json --event net_packet_tcp --event net_packet_tcp.args.dst_port=80
 ```
 
 ```json
@@ -187,7 +187,7 @@ tracee --output json --filter event=net_packet_tcp --filter net_packet_tcp.args.
 Trace all DNS packets received ONLY from Google DNS server '8.8.8.8':
 
 ```console
-tracee --output json --filter event=net_packet_dns --filter net_packet_dns.args.src=8.8.8.8
+tracee --output json --event net_packet_dns --event net_packet_dns.args.src=8.8.8.8
 ```
 
 (only **systemd-resolved**, since all the other processes are resolving using local systemd-resolved server `127.0.1.1:53`):

diff --git a/docs/docs/events/custom/golang.md b/docs/docs/events/custom/golang.md
@@ -117,7 +117,7 @@ There are 2 ways you can get your own golang signatures working with tracee.
     ```console
     sudo ./dist/tracee \
         --output json \
-        --filter event=mine
+        --event mine
     ```
 
     ```json

diff --git a/docs/docs/events/custom/rego.md b/docs/docs/events/custom/rego.md
@@ -74,7 +74,7 @@ what you want:
 sudo ./dist/tracee \
     --output json
     --signatures-dir signatures/rego \
-    --filter event=mine
+    --event mine
 ```
 
 ```json

diff --git a/docs/docs/events/overview.md b/docs/docs/events/overview.md
@@ -10,8 +10,8 @@ eg:
 
 Tracing `execve` events with [filters]:
 
-```
-tracee --filter event=execve
+```console
+tracee --event execve
 ```
 
 Tracing `execve` events with [policies]:
@@ -116,13 +116,13 @@ net_packet_http_response | [default network_events] |
 Events can be part of a set, for example on the table above we can see a few sets like `default`, `network_events`, `syscalls`. 
 We can ask tracee to trace a full set, or sets, instead of passing event by event, for example:
 
-```
-tracee --filter set=syscalls
+```console
+tracee --event syscalls
 ```
 or 
 
-```
-tracee --filter set=syscalls,network_events
+```console
+tracee --event syscalls,network_events
 ```