From e3d8f7c35b4e600d7f693b3ba96714be088110d2 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Thu, 6 Mar 2025 10:12:42 +0200 Subject: [PATCH] flags(log): new flag format --- cmd/tracee-ebpf/main.go | 2 +- cmd/tracee/cmd/analyze.go | 12 +- cmd/tracee/cmd/root.go | 6 +- .../helm/tracee/templates/tracee-config.yaml | 85 +++ deploy/helm/tracee/values.yaml | 33 ++ docs/docs/advanced/os-info.md | 10 +- docs/docs/flags/log.1.md | 37 +- docs/docs/outputs/logging.md | 51 +- docs/docs/policies/usage/cli.md | 2 +- docs/docs/troubleshooting.md | 4 +- docs/man/log.1 | 56 +- examples/config/global_config.yaml | 54 +- pkg/cmd/cobra/config.go | 61 +-- pkg/cmd/cobra/config_test.go | 177 ++++--- pkg/cmd/flags/logger.go | 379 +++++++------- pkg/cmd/flags/logger_test.go | 492 ++++++++++++++---- scripts/tracee_start.sh | 4 +- tests/e2e-inst-test.sh | 4 +- tests/e2e-kernel-test.sh | 2 +- tests/e2e-net-test.sh | 2 +- 20 files changed, 978 insertions(+), 495 deletions(-) diff --git a/cmd/tracee-ebpf/main.go b/cmd/tracee-ebpf/main.go index 3649d0be841c..06aa9a1cc22b 100644 --- a/cmd/tracee-ebpf/main.go +++ b/cmd/tracee-ebpf/main.go @@ -129,7 +129,7 @@ func main() { &cli.StringSliceFlag{ Name: "log", Usage: "logger option. run '--log help' for more info.", - Value: cli.NewStringSlice("info"), + Value: cli.NewStringSlice("level=info"), }, }, } diff --git a/cmd/tracee/cmd/analyze.go b/cmd/tracee/cmd/analyze.go index 3026e4640256..abff43183aac 100644 --- a/cmd/tracee/cmd/analyze.go +++ b/cmd/tracee/cmd/analyze.go @@ -49,10 +49,10 @@ func init() { ) analyzeCmd.Flags().StringArrayP( - "log", - "l", - []string{"info"}, - "Logger options [debug|info|warn...]", + flags.LogFlag, + flags.LogFlagShort, + []string{flags.DefaultLogLevelFlag}, + "Logger options", ) } @@ -71,7 +71,7 @@ tracee analyze --events anti_debugging --source events.json`, bindViperFlag(cmd, "events") bindViperFlag(cmd, "source") bindViperFlag(cmd, "output") - bindViperFlag(cmd, "log") + bindViperFlag(cmd, flags.LogFlag) bindViperFlag(cmd, "signatures-dir") }, Run: command, @@ -79,7 +79,7 @@ tracee analyze --events anti_debugging --source events.json`, } func command(cmd *cobra.Command, args []string) { - logFlags := viper.GetStringSlice("log") + logFlags := viper.GetStringSlice(flags.LogFlag) logCfg, err := flags.PrepareLogger(logFlags, true) if err != nil { diff --git a/cmd/tracee/cmd/root.go b/cmd/tracee/cmd/root.go index 109d34609677..af8d11f186b8 100644 --- a/cmd/tracee/cmd/root.go +++ b/cmd/tracee/cmd/root.go @@ -279,9 +279,9 @@ func initCmd() error { } rootCmd.Flags().StringArrayP( - "log", - "l", - []string{"info"}, + flags.LogFlag, + flags.LogFlagShort, + []string{flags.DefaultLogLevelFlag}, "[debug|info|warn...]\t\tLogger options", ) err = viper.BindPFlag("log", rootCmd.Flags().Lookup("log")) diff --git a/deploy/helm/tracee/templates/tracee-config.yaml b/deploy/helm/tracee/templates/tracee-config.yaml index 83941f061286..9749ec481847 100644 --- a/deploy/helm/tracee/templates/tracee-config.yaml +++ b/deploy/helm/tracee/templates/tracee-config.yaml @@ -25,6 +25,91 @@ data: {{- end }} log: level: {{ .Values.config.log.level }} + {{- if .Values.config.log.file }} + file: {{ .Values.config.log.file }} + {{- end }} + {{- if .Values.config.log.aggregate }} + aggregate: + enabled: {{ .Values.config.log.aggregate.enabled | default false }} + {{- if .Values.config.log.aggregate.flushInterval }} + flush-interval: {{ .Values.config.log.aggregate.flushInterval }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters }} + filters: + {{- if .Values.config.log.filters.libbpf }} + libbpf: {{ .Values.config.log.filters.libbpf }} + {{- end }} + {{- if .Values.config.log.filters.include }} + include: + {{- if .Values.config.log.filters.include.msg }} + msg: + {{- range .Values.config.log.filters.include.msg }} + - {{ . }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters.include.pkg }} + pkg: + {{- range .Values.config.log.filters.include.pkg }} + - {{ . }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters.include.file }} + file: + {{- range .Values.config.log.filters.include.file }} + - {{ . }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters.include.level }} + level: + {{- range .Values.config.log.filters.include.level }} + - {{ . }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters.include.regex }} + regex: + {{- range .Values.config.log.filters.include.regex }} + - {{ . }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters.include.libbpf }} + libbpf: {{ .Values.config.log.filters.include.libbpf }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters.exclude }} + exclude: + {{- if .Values.config.log.filters.exclude.msg }} + msg: + {{- range .Values.config.log.filters.exclude.msg }} + - {{ . }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters.exclude.pkg }} + pkg: + {{- range .Values.config.log.filters.exclude.pkg }} + - {{ . }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters.exclude.file }} + file: + {{- range .Values.config.log.filters.exclude.file }} + - {{ . }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters.exclude.level }} + level: + {{- range .Values.config.log.filters.exclude.level }} + - {{ . }} + {{- end }} + {{- end }} + {{- if .Values.config.log.filters.exclude.regex }} + regex: + {{- range .Values.config.log.filters.exclude.regex }} + - {{ . }} + {{- end }} + {{- end }} + {{- end }} + {{- end }} output: {{ .Values.config.output.format }}: files: diff --git a/deploy/helm/tracee/values.yaml b/deploy/helm/tracee/values.yaml index a2760b45a752..a90e7c809d9e 100644 --- a/deploy/helm/tracee/values.yaml +++ b/deploy/helm/tracee/values.yaml @@ -90,6 +90,39 @@ config: signaturesDir: "" log: level: info + # file: "/var/log/tracee.log" + # aggregate: + # enabled: true + # flush-interval: "5s" + # filters: + # include: + # libbpf: false + # msg: + # - SampleMessage1 + # - SampleMessage2 + # pkg: + # - package1 + # - package2 + # file: + # - file1.go + # - file2.go + # level: + # - warn + # - error + # regex: + # - ^pattern1 + # - ^pattern2 + # exclude: + # msg: + # - ExcludedMessage1 + # pkg: + # - excludedPackage + # file: + # - excludedFile.go + # level: + # - debug + # regex: + # - ^excludedPattern output: format: json options: diff --git a/docs/docs/advanced/os-info.md b/docs/docs/advanced/os-info.md index 763b92551cc1..eda143f2329a 100644 --- a/docs/docs/advanced/os-info.md +++ b/docs/docs/advanced/os-info.md @@ -12,10 +12,10 @@ at helpers/kernel_config). ## OS-RELEASE Tracee will show you collected information about the running Linux OS with the -`--log debug` argument: +`--log level=debug` argument: ```console -sudo ./dist/tracee --log debug --scope uid=1000 --scope pid=new --events execve +sudo ./dist/tracee --log level=debug --scope uid=1000 --scope pid=new --events execve ``` ```text @@ -39,7 +39,7 @@ because you're running inside a container that does not support it, you may face the following error: ```console -sudo ./dist/tracee --log debug --scope uid=1000 --scope pid=new --events execve +sudo ./dist/tracee --log level=debug --scope uid=1000 --scope pid=new --events execve ``` ```text @@ -81,7 +81,7 @@ Tracee needs access to kconfig file (/proc/config.gz OR /boot/config-$(uname -r) - **missing kconfig file** ```console - sudo ./dist/tracee --log debug --scope uid=1000 --scope pid=new --events execve + sudo ./dist/tracee --log level=debug --scope uid=1000 --scope pid=new --events execve ``` ```json @@ -110,7 +110,7 @@ Tracee needs access to kconfig file (/proc/config.gz OR /boot/config-$(uname -r) variable: ```console -sudo LIBBPFGO_KCONFIG_FILE=/boot/config-other -E ./dist/tracee --log debug --scope uid=1000 --scope pid=new --events execve +sudo LIBBPFGO_KCONFIG_FILE=/boot/config-other -E ./dist/tracee --log level=debug --scope uid=1000 --scope pid=new --events execve ``` ```text diff --git a/docs/docs/flags/log.1.md b/docs/docs/flags/log.1.md index d5ba20f790df..c8dadbd83edf 100644 --- a/docs/docs/flags/log.1.md +++ b/docs/docs/flags/log.1.md @@ -2,7 +2,7 @@ title: TRACEE-LOG section: 1 header: Tracee Log Flag Manual -date: 2024/06 +date: 2025/03 ... ## NAME @@ -11,7 +11,8 @@ tracee **\-\-log** - Control logger options - aggregation and level priority ## SYNOPSIS -tracee **\-\-log** aggregate[:flush-interval] | | file:/path/to/file | filter:[msg=;regex=;pkg=;file=;lvl=;libbpf] | filter-out:[msg=;regex=;pkg=;file=;lvl=;libbpf] +tracee **\-\-log** aggregate.flush-interval=| aggregate.enable= | level= | file=/path/to/file | filters.include.[msg=] | filters.include.[regex=] | filters.include.[pkg=] | filters.include.[file=] | filters.include.[level=] | filters.include.[libbpf] | filters.exclude.[msg=] | filters.exclude.[regex=] | filters.exclude.[pkg=] | filters.exclude.[file=] | filters.exclude.[level=] | filters.exclude.[libbpf] + ## DESCRIPTION @@ -19,15 +20,15 @@ The **\-\-log** flag allows you to control logger options for the tool. Possible log options: -- **aggregate[:flush-interval]**: Turns log aggregation on, delaying output with an optional interval (default: 3s). The flush-interval can be specified in seconds (s) or minutes (m). +- **aggregate.flush-interval=[time] | aggregate.enable=[true|false]**: Turns log aggregation on, delaying output with an optional interval (default: 3s). The flush-interval can be specified in seconds (s) or minutes (m). -- ****: Sets the log level. The default log level is 'info'. +- **level=**: Sets the log level. The default log level is 'info'. -- **file:/path/to/file**: Writes the logs to the specified file. If the file exists, it will be created or trimmed. +- **file=/path/to/file**: Writes the logs to the specified file. If the file exists, it will be created or trimmed. -- **filter:**: Filters in logs that match the specified option values. Multiple filter options can be provided, separated by semicolons. +- **filters.include.**: Filters in logs that match the specified option values. Multiple filter options can be provided, separated by semicolons. -- **filter-out:**: Filters out logs that match the specified option values. Multiple filter options can be provided, separated by semicolons. +- **filters.exclude.**: Filters out logs that match the specified option values. Multiple filter options can be provided, separated by semicolons. Filter options: @@ -39,7 +40,7 @@ Filter options: - **file=**: Filters logs that originate from the specified file. -- **lvl=**: Filters logs that are of the specified level. +- **level=**: Filters logs that are of the specified level. - **libbpf**: Filters logs that originate from libbpf. @@ -48,59 +49,59 @@ Filter options: - To output debug level logs, use the following flag: ```console - --log debug + --log level=debug ``` - To output aggregated debug level logs every 3 seconds (default), use the following flag: ```console - --log debug --log aggregate + --log level=debug --log aggregate.enable=true ``` - To output aggregated logs every 5 seconds, use the following flag: ```console - --log aggregate:5s + --log aggregate.flush-interval=5s ``` - To output debug level logs to `/tmp/tracee.log`, use the following flag: ```console - --log debug --log file:/tmp/tracee.log + --log level=debug --log file=/tmp/tracee.log ``` - To filter in logs that have either 'foo' or 'bar' in the message, are from the 'core' package, and are of 'error' level, use the following flag: ```console - --log filter:'msg=foo,bar;pkg=core;lvl=error' + --log filters.include.msg=foo,bar --log filters.include.pkg=core --log filters.include.level=error ``` - To filter out logs that have either 'foo' or 'bar' in the message, are from the 'core' package, and are of 'error' level, use the following flag: ```console - --log filter-out:'msg=foo,bar;pkg=core;lvl=error' + --log filters.exclude.msg=foo,bar --log filters.exclude.pkg=core --log filters.exclude.level=error ``` - To filter in logs that have either 'foo' or 'bar' in the message and, based on that result, filter out logs that are from the 'core' package, use the following flag: ```console - --log filter:msg=foo,bar --log filter-out:pkg=core + --log filters.include.msg=foo,bar --log filters.exclude.pkg=core ``` - To filter out logs that originate from the '/pkg/cmd/flags/logger.go' file, use the following flag: ```console - --log filter-out:file=/pkg/cmd/flags/logger.go + --log filters.exclude.file=/pkg/cmd/flags/logger.go ``` - To filter in logs that have messages matching the regex '^foo', use the following flag: ```console - --log filter:regex='^foo' + --log filters.include.regex='^foo' ``` - To filter in logs that originate from libbpf, use the following flag: ```console - --log filter:libbpf + --log filters.include.libbpf ``` diff --git a/docs/docs/outputs/logging.md b/docs/docs/outputs/logging.md index b8b7c378af0d..7e48d291ce70 100644 --- a/docs/docs/outputs/logging.md +++ b/docs/docs/outputs/logging.md @@ -37,65 +37,72 @@ The flush-interval defines how often the Tracee logs will be forwarded. ```console log: - filters: - msg: - - foo - - bar + filters: + include: + msg: + - foo + - bar ``` **Filter logs using regular expressions against messages:** ```console log: - filters: - regex: - - ^pattern-one + filters: + include: + regex: + - ^pattern-one ``` **Filter logs originating from a specific package:** ```console log: - filters: - pkg: - - core + filters: + include: + pkg: + - core ``` **Filter logs originating from a specific file:** ```console log: - filter: - file: - - /pkg/cmd/flags/logger.go + filters: + include: + file: + - /pkg/cmd/flags/logger.go ``` **Filter logs based on their severity level:** ```console log: - filters: - level: - - error + filters: + include: + level: + - error ``` **Filter logs originating from libbpf**: ```console log: - filters: - libbpf: true + filters: + include: + libbpf: true ``` ## Additional Configuration -All `filters` options can also be used with `filter-out` to achieve the opposite behavior. +All `filters` options can also be used with `exclude` to achieve the opposite behavior. For instance, the following configuration would exclude all logs with the severity level `error`: ```console log: - filter-out: - level: - - error + filters: + exclude: + level: + - error ``` diff --git a/docs/docs/policies/usage/cli.md b/docs/docs/policies/usage/cli.md index 96400856d7cf..8381d6f90307 100644 --- a/docs/docs/policies/usage/cli.md +++ b/docs/docs/policies/usage/cli.md @@ -82,7 +82,7 @@ log: # enabled: true # flush-interval: 5s filters: - out: + exclude: pkg: - capabilities # output diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md index 5d2baf23609e..b27ff24cfe71 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/troubleshooting.md @@ -171,7 +171,7 @@ WARN events dropped due to buffer overflow 2. **Check for mixed output**: ```bash # Separate logs from events - tracee --output json --log file:/var/log/tracee.log + tracee --output json --log file=/var/log/tracee.log ``` ### Missing Event Fields @@ -192,7 +192,7 @@ WARN events dropped due to buffer overflow ```bash # Enable debug logs -tracee --log debug +tracee --log level=debug # Or via environment TRACEE_LOG_LEVEL=debug tracee diff --git a/docs/man/log.1 b/docs/man/log.1 index 1c8809a585ea..f7ad14ed7ecf 100644 --- a/docs/man/log.1 +++ b/docs/man/log.1 @@ -1,37 +1,45 @@ .\" Automatically generated by Pandoc 3.2 .\" -.TH "TRACEE\-LOG" "1" "2024/06" "" "Tracee Log Flag Manual" +.TH "TRACEE\-LOG" "1" "2025/03" "" "Tracee Log Flag Manual" .SS NAME tracee \f[B]\-\-log\f[R] \- Control logger options \- aggregation and level priority .SS SYNOPSIS -tracee \f[B]\-\-log\f[R] aggregate[:flush\-interval] | - | file:/path/to/file | -filter:[msg=;regex=;pkg=;file=;lvl=;libbpf] -| -filter\-out:[msg=;regex=;pkg=;file=;lvl=;libbpf] +tracee \f[B]\-\-log\f[R] aggregate.flush\-interval=