Rename !container and binary scope filters

docs/docs/filters/filtering.md

@@ -130,7 +130,7 @@ expected.
 
     ```text
     1) --scope container # all container events
-    2) --scope '!container' # events from the host only
+    2) --scope not-container # events from the host only
     3) --scope container=new # containers created after tracee-ebf execution
     4) --scope container=3f93da58be3c --events openat
     5) --scope container=new --events openat.args.pathname=/etc/shadow
@@ -150,12 +150,12 @@ expected.
         Do not use given command prefix for these examples as they're filtering
         by command name as well.
 
-1. **Binary Path** `(Operators: =, !=)`
+1. **Executable Path** `(Operators: =, !=)`
 
     ```text
-    1) --scope binary=/usr/bin/ls
-    2) --scope binary=host:/usr/bin/ls
-    3) --scope binary=4026532448:/usr/bin/ls
+    1) --scope executable=/usr/bin/ls
+    2) --scope executable=host:/usr/bin/ls
+    3) --scope executable=4026532448:/usr/bin/ls
     ```
 
     !!! Note

docs/docs/flags/scope.md

@@ -5,7 +5,7 @@ tracee **--scope** - Select the scope for tracing events
 
 ## SYNOPSIS
 
-tracee **--scope** [\<[uid|pid][=|!=|\<|\>|\<=|\>=]value1(,value2...)\> | \<[mntns|pidns|tree][=|!=]value1(,value2...)\> | \<[uts|comm|container|binary][=|!=]value1(,value2...)\>] | \<[!]container\> | \<container[=|!=]value\> | \<[container|pid]=new\> | \<follow\>]  ...
+tracee **--scope** [\<[uid|pid][=|!=|\<|\>|\<=|\>=]value1(,value2...)\> | \<[mntns|pidns|tree][=|!=]value1(,value2...)\> | \<[uts|comm|container|[executable|exec|binary|bin]][=|!=]value1(,value2...)\>] | \<not-container\> | \<container[=|!=]value\> | \<[container|pid]=new\> | \<follow\>]  ...
 
 ## DESCRIPTION
 
@@ -41,7 +41,7 @@ Available for the following string fields:
 - uts: Select events based on UTS (Unix Timesharing System) names.
 - comm: Select events based on process command names.
 - container: Select events from specific container IDs.
-- binary: Select events based on the binary path.
+- executable: Select events based on the executable path.
 
 Strings can be compared as a prefix if ending with '\*', or as a suffix if starting with '\*'.
 
@@ -109,7 +109,7 @@ The following special filters can be used within the scope filter expressions:
 - To trace only events from the host, use the following flag:
 
   ```console
-  --scope '!container'
+  --scope not-container
   ```
 
 - To trace only events from uid 0, use the following flag:
@@ -178,22 +178,26 @@ The following special filters can be used within the scope filter expressions:
   --scope comm=ls
   ```
 
-- To trace only events from the '/usr/bin/ls' binary, use the following flag:
+- To trace only events from the '/usr/bin/ls' executable, use the executable flag (or the binary alias):
+
+  ```console
+  --scope executable=/usr/bin/ls
+  ```
 
   ```console
   --scope binary=/usr/bin/ls
   ```
 
-- To trace only events from the '/usr/bin/ls' binary in the host mount namespace, use the following flag:
+- To trace only events from the '/usr/bin/ls' executable in the host mount namespace, use the following flag:
 
   ```console
-  --scope binary=host:/usr/bin/ls
+  --scope executable=host:/usr/bin/ls
   ```
 
-- To trace only events from the '/usr/bin/ls' binary in the 4026532448 mount namespace, use the following flag:
+- To trace only events from the '/usr/bin/ls' executable in the 4026532448 mount namespace, use the following flag:
 
   ```console
-  --scope binary=4026532448:/usr/bin/ls
+  --scope executable=4026532448:/usr/bin/ls
   ```
 
 - To trace all events that originated from 'bash' or from one of the processes spawned by 'bash', use the following flag:

docs/docs/policies/scopes.md

@@ -69,14 +69,12 @@ scope:
     - container
 ```
 
-### !container
+### not-container
 Events are collected from everything but containers:
 
-NOTE: YAML requires that values containing special characters, in this case `!`, be enclosed in quotes!
-
 ```yaml
 scope:
-    - "!container"
+    - not-container
 ```
 
 ### tree
@@ -87,12 +85,12 @@ scope:
     - tree=1000
 ```
 
-### binary, bin
-Events are collected from binary:
+### executable, exec
+Events are collected from executable:
 
 ```yaml
 scope:
-    - binary=/usr/bin/dig
+    - executable=/usr/bin/dig
 ```
 
 ### follow

examples/policies/dig.yaml

@@ -3,10 +3,10 @@ kind: TraceePolicy
 metadata:
   name: dig
   annotations:
-    description: traces dns events from the dig binary
+    description: traces dns events from the dig executable
 spec:
-  scope: 
-    - binary=/usr/bin/dig
+  scope:
+    - executable=/usr/bin/dig
   rules:
-    - event: net_packet_dns_request        
+    - event: net_packet_dns_request
     - event: net_packet_dns_response

examples/policies/not_containers.yaml

@@ -5,7 +5,7 @@ metadata:
   annotations:
     description: traces anti_debugging in the host
 spec:
-  scope: 
-    - "!container"
+  scope:
+    - not-container
   rules:
     - event: anti_debugging

pkg/cmd/flags/filter.go

@@ -16,7 +16,7 @@ Available numerical expressions: uid, pid, mntns, pidns.
 NOTE: Expressions containing '<' or '>' token must be escaped! This is also shown in the examples below.
 
 String expressions which compares text and allow the following operators: '=', '!='.
-Available string expressions: uts, comm, container, binary.
+Available string expressions: uts, comm, container, executable.
 
 Boolean expressions that check if a boolean is true and allow the following operator: '!'.
 Available boolean expressions: container.
@@ -54,7 +54,7 @@ Scope examples:
   --scope container=ab356bc4dd554                              | only trace events from container id ab356bc4dd554
   --scope container                                            | only trace events from containers
   --scope c                                                    | only trace events from containers (same as above)
-  --scope '!container'                                         | only trace events from the host
+  --scope not-container                                        | only trace events from the host
   --scope uid=0                                                | only trace events from uid 0
   --scope mntns=4026531840                                     | only trace events from mntns id 4026531840
   --scope pidns!=4026531836                                    | only trace events from pidns id not equal to 4026531840
@@ -66,9 +66,9 @@ Scope examples:
   --scope 'u>0' --scope u!=1000                                | only trace events from uids greater than 0 but not 1000
   --scope uts!=ab356bc4dd554                                   | don't trace events from uts name ab356bc4dd554
   --scope comm=ls                                              | only trace events from ls command
-  --scope binary=/usr/bin/ls                                   | only trace events from /usr/bin/ls binary
-  --scope binary=host:/usr/bin/ls                              | only trace events from /usr/bin/ls binary in the host mount namespace
-  --scope binary=4026532448:/usr/bin/ls                        | only trace events from /usr/bin/ls binary in 4026532448 mount namespace
+  --scope executable=/usr/bin/ls                               | only trace events from /usr/bin/ls executable
+  --scope executable=host:/usr/bin/ls                          | only trace events from /usr/bin/ls executable in the host mount namespace
+  --scope executable=4026532448:/usr/bin/ls                    | only trace events from /usr/bin/ls executable in 4026532448 mount namespace
   --scope comm=bash --scope follow                             | trace all events that originated from bash or from one of the processes spawned by bash
 
 Event examples:

pkg/cmd/flags/policy.go

@@ -128,7 +128,9 @@ func CreatePolicies(policyScopeMap PolicyScopeMap, policyEventsMap PolicyEventMa
 				continue
 			}
 
-			if scopeFlag.scopeName == "binary" || scopeFlag.scopeName == "bin" {
+			if scopeFlag.scopeName == "exec" || scopeFlag.scopeName == "executable" ||
+				scopeFlag.scopeName == "bin" || scopeFlag.scopeName == "binary" {
+				// TODO: Rename BinaryFilter to ExecutableFilter
 				err := p.BinaryFilter.Parse(scopeFlag.operatorAndValues)
 				if err != nil {
 					return nil, err
@@ -137,8 +139,8 @@ func CreatePolicies(policyScopeMap PolicyScopeMap, policyEventsMap PolicyEventMa
 			}
 
 			if scopeFlag.scopeName == "container" {
-				if scopeFlag.operator == "!" {
-					err := p.ContFilter.Parse(scopeFlag.full) // !container
+				if scopeFlag.operator == "not" {
+					err := p.ContFilter.Parse(scopeFlag.full)
 					if err != nil {
 						return nil, err
 					}

pkg/cmd/flags/policy_test.go

@@ -357,13 +357,13 @@ func TestPrepareFilterMapsFromPolicies(t *testing.T) {
 			},
 		},
 		{
-			testName: "!container",
+			testName: "not-container",
 			policy: v1beta1.PolicyFile{
 				Metadata: v1beta1.Metadata{
-					Name: "!container-scope",
+					Name: "not-container-scope",
 				},
 				Spec: v1beta1.PolicySpec{
-					Scope:          []string{"!container"},
+					Scope:          []string{"not-container"},
 					DefaultActions: []string{"log"},
 					Rules: []v1beta1.Rule{
 						{Event: "write"},
@@ -372,12 +372,12 @@ func TestPrepareFilterMapsFromPolicies(t *testing.T) {
 			},
 			expPolicyScopeMap: PolicyScopeMap{
 				0: {
-					policyName: "!container-scope",
+					policyName: "not-container-scope",
 					scopeFlags: []scopeFlag{
 						{
-							full:              "!container",
+							full:              "not-container",
 							scopeName:         "container",
-							operator:          "!",
+							operator:          "not",
 							values:            "",
 							operatorAndValues: "",
 						},
@@ -386,7 +386,7 @@ func TestPrepareFilterMapsFromPolicies(t *testing.T) {
 			},
 			expPolicyEventMap: PolicyEventMap{
 				0: {
-					policyName: "!container-scope",
+					policyName: "not-container-scope",
 					eventFlags: []eventFlag{
 						writeEvtFlag,
 					},
@@ -505,13 +505,13 @@ func TestPrepareFilterMapsFromPolicies(t *testing.T) {
 			},
 		},
 		{
-			testName: "binary=host:/usr/bin/ls",
+			testName: "executable=host:/usr/bin/ls",
 			policy: v1beta1.PolicyFile{
 				Metadata: v1beta1.Metadata{
-					Name: "binary-scope",
+					Name: "executable-scope",
 				},
 				Spec: v1beta1.PolicySpec{
-					Scope:          []string{"binary=host:/usr/bin/ls"},
+					Scope:          []string{"executable=host:/usr/bin/ls"},
 					DefaultActions: []string{"log"},
 					Rules: []v1beta1.Rule{
 						{Event: "write"},
@@ -520,11 +520,11 @@ func TestPrepareFilterMapsFromPolicies(t *testing.T) {
 			},
 			expPolicyScopeMap: PolicyScopeMap{
 				0: {
-					policyName: "binary-scope",
+					policyName: "executable-scope",
 					scopeFlags: []scopeFlag{
 						{
-							full:              "binary=host:/usr/bin/ls",
-							scopeName:         "binary",
+							full:              "executable=host:/usr/bin/ls",
+							scopeName:         "executable",
 							operator:          "=",
 							values:            "host:/usr/bin/ls",
 							operatorAndValues: "=host:/usr/bin/ls",
@@ -534,19 +534,56 @@ func TestPrepareFilterMapsFromPolicies(t *testing.T) {
 			},
 			expPolicyEventMap: PolicyEventMap{
 				0: {
-					policyName: "binary-scope",
+					policyName: "executable-scope",
 					eventFlags: []eventFlag{
 						writeEvtFlag,
 					},
 				},
 			},
 			skipPolicyCreation: true, // needs root privileges
 		},
+		{
+			testName: "exec=4026532448:/usr/bin/ls",
+			policy: v1beta1.PolicyFile{
+				Metadata: v1beta1.Metadata{
+					Name: "exec-scope",
+				},
+				Spec: v1beta1.PolicySpec{
+					Scope:          []string{"exec=4026532448:/usr/bin/ls"},
+					DefaultActions: []string{"log"},
+					Rules: []v1beta1.Rule{
+						{Event: "write"},
+					},
+				},
+			},
+			expPolicyScopeMap: PolicyScopeMap{
+				0: {
+					policyName: "exec-scope",
+					scopeFlags: []scopeFlag{
+						{
+							full:              "exec=4026532448:/usr/bin/ls",
+							scopeName:         "exec",
+							operator:          "=",
+							values:            "4026532448:/usr/bin/ls",
+							operatorAndValues: "=4026532448:/usr/bin/ls",
+						},
+					},
+				},
+			},
+			expPolicyEventMap: PolicyEventMap{
+				0: {
+					policyName: "exec-scope",
+					eventFlags: []eventFlag{
+						writeEvtFlag,
+					},
+				},
+			},
+		},
 		{
 			testName: "bin=4026532448:/usr/bin/ls",
 			policy: v1beta1.PolicyFile{
 				Metadata: v1beta1.Metadata{
-					Name: "bin-scope",
+					Name: "exec-scope (bin alias)",
 				},
 				Spec: v1beta1.PolicySpec{
 					Scope:          []string{"bin=4026532448:/usr/bin/ls"},
@@ -558,7 +595,7 @@ func TestPrepareFilterMapsFromPolicies(t *testing.T) {
 			},
 			expPolicyScopeMap: PolicyScopeMap{
 				0: {
-					policyName: "bin-scope",
+					policyName: "exec-scope (bin alias)",
 					scopeFlags: []scopeFlag{
 						{
 							full:              "bin=4026532448:/usr/bin/ls",
@@ -572,7 +609,7 @@ func TestPrepareFilterMapsFromPolicies(t *testing.T) {
 			},
 			expPolicyEventMap: PolicyEventMap{
 				0: {
-					policyName: "bin-scope",
+					policyName: "exec-scope (bin alias)",
 					eventFlags: []eventFlag{
 						writeEvtFlag,
 					},
@@ -623,7 +660,7 @@ func TestPrepareFilterMapsFromPolicies(t *testing.T) {
 					Name: "multiple-scope",
 				},
 				Spec: v1beta1.PolicySpec{
-					Scope:          []string{"comm=bash", "follow", "!container", "uid=1000"},
+					Scope:          []string{"comm=bash", "follow", "not-container", "uid=1000"},
 					DefaultActions: []string{"log"},
 					Rules: []v1beta1.Rule{
 						{Event: "write"},
@@ -649,9 +686,9 @@ func TestPrepareFilterMapsFromPolicies(t *testing.T) {
 							operatorAndValues: "",
 						},
 						{
-							full:              "!container",
+							full:              "not-container",
 							scopeName:         "container",
-							operator:          "!",
+							operator:          "not",
 							values:            "",
 							operatorAndValues: "",
 						},
@@ -1907,12 +1944,12 @@ func TestCreatePolicies(t *testing.T) {
 		},
 		// requires root privileges
 		// {
-		// 	testName:   "success - binary=host:/usr/bin/ls",
-		// 	scopeFlags: []string{"binary=host:/usr/bin/ls"},
+		// 	testName:   "success - executable=host:/usr/bin/ls",
+		// 	scopeFlags: []string{"executable=host:/usr/bin/ls"},
 		// },
 		{
-			testName:   "success - binary=/usr/bin/ls",
-			scopeFlags: []string{"binary=/usr/bin/ls"},
+			testName:   "success - executable=/usr/bin/ls",
+			scopeFlags: []string{"executable=/usr/bin/ls"},
 		},
 		{
 			testName:   "success - uts!=deadbeaf",