Rules¶

Rules are part of the Tracee Policy, rules let you define which events to trace.

rules have 2 sections:

events: let you define which events you want to trace.
filters: enable you to refine the policy's scope.

Tracee supports many kinds of events to trace. You can find which events you can trace in the Events section.

NOTE: It is possible to define multiple events within each policy.

Below is an example showcasing a policy:

apiVersion: tracee.aquasec.com/v1beta1
kind: Policy
metadata:
  name: sample-scope-filter
  annotations:
    description: sample scope filter
spec:
  scope:
    - global
  rules:
    - event: openat
      filters:
        - uid=1000

Events¶

Type of Events¶

The value of an event is the event name from the supported events.

For example: syscall event would be the syscall event name.

The events section provides further information on the type of events that Tracee can trace.

Threat-Based Detector Selection¶

Instead of specifying individual detector event names, you can select multiple detectors based on their threat metadata properties. This is especially useful for:

Enabling all high-severity detectors without knowing their names
Selecting detectors by MITRE ATT&CK framework categories
Filtering by threat characteristics

Selecting by Severity¶

Select detectors based on their severity level (info, low, medium, high, critical):

apiVersion: tracee.aquasec.com/v1beta1
kind: Policy
metadata:
  name: critical-threats-only
  annotations:
    description: Enable all critical severity detectors
spec:
  scope:
    - global
  rules:
    - event: threat.severity=critical

You can also use comparison operators:

rules:
  - event: threat.severity>=high  # Enable high and critical threats

Selecting by MITRE ATT&CK¶

Select detectors by MITRE ATT&CK technique or tactic:

apiVersion: tracee.aquasec.com/v1beta1
kind: Policy
metadata:
  name: process-injection-detectors
  annotations:
    description: Enable all process injection detectors
spec:
  scope:
    - global
  rules:
    - event: threat.mitre.technique=T1055

Or by tactic:

rules:
  - event: threat.mitre.tactic=Defense Evasion

Selecting by Threat Name¶

Select detectors by exact threat name:

rules:
  - event: threat.name=process_injection

Selecting by Detector Tags¶

Detectors can be categorized with tags. Select all detectors with a specific tag:

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:

apiVersion: tracee.aquasec.com/v1beta1
kind: Policy
metadata:
  name: mixed-events
  annotations:
    description: Trace specific events and all critical threats
spec:
  scope:
    - global
  rules:
    - event: security_file_open
      filters:
        - data.pathname=/etc/*
    - event: threat.severity=critical

Available Threat Properties¶

Property	Description	Example Values	Operators
`threat.severity`	Severity level	info, low, medium, high, critical (or 0-4)	=, !=, <, >, <=, >=
`threat.mitre.technique`	MITRE technique ID	T1055, T1071	=, !=
`threat.mitre.tactic`	MITRE tactic name	Defense Evasion, Execution	=, !=
`threat.name`	Threat identifier	process_injection	=, !=

Note: Detector selection based on threat properties is performed once when Tracee starts. Matching detectors are enabled; non-matching detectors are never loaded. Multiple rules in a policy are combined with OR logic.

Filters¶

Filters enable you to refine the policy's scope by specifying conditions for particular events. This allows you to narrow down the criteria to precisely target the events you're interested in, ensuring that the policy applies only under specific circumstances.

Every event that is specified within the rules section supports three types of filters: scope, data and return value.

Scope filters¶

Further refinement of the policy's scope is achievable through the application of scope filters:

apiVersion: tracee.aquasec.com/v1beta1
kind: Policy
metadata:
  name: sample-scope-filter
  annotations:
    description: sample scope filter
spec:
  scope:
    - global
  rules:
    - event: sched_process_exec
      filters:
        - pid=1000

The scope filters supported are:

p, pid, processId¶

event: sched_process_exec
filters:
    - pid=1000

tid, threadId¶

event: sched_process_exec
filters:
    - tid=13819

ppid, parentProcessId¶

event: sched_process_exec
filters:
    - ppid=1000

hostTid, hostThreadId¶

event: sched_process_exec
filters:
    - hostTid=1000

hostPid¶

event: sched_process_exec
filters:
    - hostPid=1000

hostParentProcessId¶

event: sched_process_exec
filters:
    - hostParentProcessId=1

uid, userId¶

event: sched_process_exec
filters:
    - uid=0

mntns, mountNamespace¶

event: sched_process_exec
filters:
    - mntns=4026531840

pidns, pidNamespace¶

event: sched_process_exec
filters:
    - pidns=4026531836

comm, processName¶

event: sched_process_exec
filters:
    - comm=uname

hostName¶

event: sched_process_exec
filters:
    - hostName=hostname

cgroupId¶

event: sched_process_exec
filters:
    - cgroupId=5247

container¶

event: sched_process_exec
filters:
    - container=66c2778945e29dfd36532d63c38c2ce4ed1

containerId¶

event: sched_process_exec
filters:
    - containerId=66c2778945e29dfd36532d63c38c2ce4ed1

containerImage¶

event: sched_process_exec
filters:
    - containerImage=ubuntu:latest

containerName¶

event: sched_process_exec
filters:
    - containerName=test

podName¶

event: sched_process_exec
filters:
    - podName=daemonset/test

podNamespace¶

event: sched_process_exec
filters:
    - podNamespace=production

podUid¶

event: sched_process_exec
filters:
    - podUid=66c2778945e29dfd36532d63c38c2ce4ed16a002c44cb254b8e

Data filter¶

Events contain data that can be filtered.

apiVersion: tracee.aquasec.com/v1beta1
kind: Policy
metadata:
  name: sample-data-filter
  annotations:
    description: sample data filter
spec:
  scope:
    - global
  rules:
    - event: security_file_open
      filters:
        - data.pathname=/tmp*

Data fields can be found on the respective event definition, in this case security_file_open - be aware of possible changes to the definition linked above, so always check the main branch.

Or the user can test the event output in CLI before defining a policy, e.g:

tracee -e security_file_open --output json

{"timestamp":1680182976364916505,"threadStartTime":1680179107675006774,"processorId":0,"processId":676,"cgroupId":5247,"threadId":676,"parentProcessId":1,"hostProcessId":676,"hostThreadId":676,"hostParentProcessId":1,"userId":131,"mountNamespace":4026532574,"pidNamespace":4026531836,"processName":"systemd-oomd","hostName":"josedonizetti-x","container":{},"kubernetes":{},"eventId":"730","eventName":"security_file_open","matchedPolicies":[""],"argsNum":6,"returnValue":0,"syscall":"openat","stackAddresses":null,"contextFlags":{"containerStarted":false,"isCompat":false},"args":[{"name":"pathname","type":"const char*","value":"/proc/meminfo"},{"name":"flags","type":"string","value":"O_RDONLY|O_LARGEFILE"},{"name":"dev","type":"dev_t","value":45},{"name":"inode","type":"unsigned long","value":4026532041},{"name":"ctime","type":"unsigned long","value":1680179108391999988},{"name":"syscall_pathname","type":"const char*","value":"/proc/meminfo"}]}

Return value filter¶

Return values can also be filtered.

apiVersion: tracee.aquasec.com/v1beta1
kind: Policy
metadata:
  name: sample-return-value
  annotations:
    description: sample return value
spec:
  scope:
    - global
  rules:
    - event: close
      filters:
        - retval!=0