Skip to content

Commit 5d26dba

Browse files
josedonizettijosedonizetti
committed
flag(stores): new flag format
1 parent 1fa65a8 commit 5d26dba

File tree

23 files changed

+1203
-457
lines changed

23 files changed

+1203
-457
lines changed

‎cmd/tracee/cmd/man.go‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ func init() {
6161
scopeCmd,
6262
serverCmd,
6363
eventCmd,
64+
storesCmd,
6465
)
6566
}
6667

@@ -177,6 +178,15 @@ var eventCmd = &cobra.Command{
177178
},
178179
}
179180

181+
var storesCmd = &cobra.Command{
182+
Use: "stores",
183+
Aliases: []string{},
184+
Short: "Show manual page for the --stores flag",
185+
RunE: func(cmd *cobra.Command, args []string) error {
186+
return runManForFlag("stores")
187+
},
188+
}
189+
180190
// runManForFlag runs man for the specified flag name
181191
func runManForFlag(flagName string) error {
182192
// Read the embedded manual page

‎cmd/tracee/cmd/root.go‎

Lines changed: 5 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -218,27 +218,14 @@ func initCmd() error {
218218
return errfmt.WrapError(err)
219219
}
220220

221-
// Process Tree flags
222-
223-
rootCmd.Flags().StringArrayP(
224-
"proctree",
225-
"t",
226-
[]string{"source=none"},
227-
"[source=[events|signals|both]...]\tControl process tree options",
228-
)
229-
err = viper.BindPFlag("proctree", rootCmd.Flags().Lookup("proctree"))
230-
if err != nil {
231-
return errfmt.WrapError(err)
232-
}
233-
234-
// DNS Cache flags
221+
// Stores flags
235222

236223
rootCmd.Flags().StringArray(
237-
"dnscache",
238-
[]string{"none"},
239-
"\t\t\t\t\tEnable DNS Cache",
224+
flags.StoresFlag,
225+
[]string{},
226+
"\t\t\t\t\tStores configurations",
240227
)
241-
err = viper.BindPFlag("dnscache", rootCmd.Flags().Lookup("dnscache"))
228+
err = viper.BindPFlag(flags.StoresFlag, rootCmd.Flags().Lookup(flags.StoresFlag))
242229
if err != nil {
243230
return errfmt.WrapError(err)
244231
}

‎deploy/helm/tracee/templates/tracee-config.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,4 +52,34 @@ data:
5252
{{- if .Values.config.blobPerfBufferSize }}
5353
blob-perf-buffer-size: {{ .Values.config.blobPerfBufferSize}}
5454
{{- end }}
55+
{{- if or .Values.config.stores.dns.enabled .Values.config.stores.dns.maxEntries .Values.config.stores.process.enabled .Values.config.stores.process.maxProcesses .Values.config.stores.process.maxThreads .Values.config.stores.process.source .Values.config.stores.process.useProcfs }}
56+
stores:
57+
{{- if or .Values.config.stores.dns.enabled .Values.config.stores.dns.maxEntries }}
58+
dns:
59+
{{- if .Values.config.stores.dns.enabled }}
60+
enabled: {{ .Values.config.stores.dns.enabled }}
61+
{{- end }}
62+
{{- if .Values.config.stores.dns.maxEntries }}
63+
max-entries: {{ .Values.config.stores.dns.maxEntries }}
64+
{{- end }}
65+
{{- end }}
66+
{{- if or .Values.config.stores.process.enabled .Values.config.stores.process.maxProcesses .Values.config.stores.process.maxThreads .Values.config.stores.process.source .Values.config.stores.process.useProcfs }}
67+
process:
68+
{{- if .Values.config.stores.process.enabled }}
69+
enabled: {{ .Values.config.stores.process.enabled }}
70+
{{- end }}
71+
{{- if .Values.config.stores.process.maxProcesses }}
72+
max-processes: {{ .Values.config.stores.process.maxProcesses }}
73+
{{- end }}
74+
{{- if .Values.config.stores.process.maxThreads }}
75+
max-threads: {{ .Values.config.stores.process.maxThreads }}
76+
{{- end }}
77+
{{- if .Values.config.stores.process.source }}
78+
source: {{ .Values.config.stores.process.source }}
79+
{{- end }}
80+
{{- if .Values.config.stores.process.useProcfs }}
81+
use-procfs: {{ .Values.config.stores.process.useProcfs }}
82+
{{- end }}
83+
{{- end }}
84+
{{- end }}
5585
{{- end }}

‎deploy/helm/tracee/values.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,16 @@ config:
108108
# port: "8080"
109109
# protocol: http
110110
# timeout: 3s
111+
stores:
112+
dns:
113+
enabled: ""
114+
maxEntries: ""
115+
process:
116+
enabled: ""
117+
maxProcesses: ""
118+
maxThreads: ""
119+
source: ""
120+
useProcfs: ""
111121

112122
defaultPolicy: true
113123

‎docs/docs/advanced/data-sources/builtin/dns.md‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,20 @@ These relations can be queried in signatures through a data source.
88
To switch on the `DNS Cache` feature, run the command:
99

1010
```bash
11-
sudo tracee --output option:sort-events --output json --output option:parse-arguments --dnscache enable --events <event_type>
11+
sudo tracee --output option:sort-events --output json --output option:parse-arguments --stores dns.enabled --events <event_type>
1212
```
1313

1414
The underlying structure is populated using the core [net_packet_dns](../../../events/builtin/man/network/net_packet_dns.md) event and its payload.
1515

1616
## Command Line Option
1717

1818
```bash
19-
$ tracee --dnscache help
20-
Select different options for the DNS cache.
21-
2219
Example:
23-
--dnscache enable | enable with default values (see below).
24-
--dnscache size=X | will cache up to X dns query trees - further queries may be cached regardless (default: 5000).
20+
--stores dns.enabled | enable the DNS cache.
21+
--stores dns.max-entries=X | will cache up to X dns query trees - further queries may be cached regardless (default: 5000).
2522

26-
Use comma OR use the flag multiple times to choose multiple options:
27-
--dnscache size=A
28-
--dnscache enable
23+
Use the flag multiple times to choose multiple options:
24+
--stores dns.enabled --stores dns.max-entries=5000
2925
```
3026

3127
Consider for your usecase, how many query trees would you like to store? If you will frequently check only a few addresses, consider lowering the size.

‎docs/docs/advanced/data-sources/builtin/process-tree.md‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ The `Process Tree` feature offers a structured view of processes and threads act
77
To switch on the `Process Tree` feature, run the command:
88

99
```bash
10-
sudo tracee --output option:sort-events --output json --output option:parse-arguments --proctree source=both --events <event_type>
10+
sudo tracee --output option:sort-events --output json --output option:parse-arguments --stores process.enabled --stores process.source=both --events <event_type>
1111
```
1212

1313
The underlying structure is populated using the core `sched_process_fork`, `sched_process_exec`, and `sched_process_exit` events and their data. There's also an option to bootstrap the process tree through a secondary route using internal signal events.
@@ -27,19 +27,18 @@ The process tree query the procfs upon initialization and during runtime to fill
2727

2828
```bash
2929
Example:
30-
--proctree source=[none|events|signals|both]
31-
none | process tree is disabled (default).
30+
--stores process.enabled | enable the process tree.
31+
--stores process.source=[none|events|signals|both]
32+
none | process tree source is disabled (default).
3233
events | process tree is built from events.
3334
signals | process tree is built from signals.
3435
both | process tree is built from both events and signals.
35-
--proctree process-cache=8192 | will cache up to 8192 processes in the tree (LRU cache).
36-
--proctree thread-cache=16384 | will cache up to 16384 threads in the tree (LRU cache).
37-
--proctree disable-procfs | will disable procfs entirely.
38-
--proctree disable-procfs-query | will disable procfs quering during runtime.
39-
40-
Use comma OR use the flag multiple times to choose multiple options:
41-
--proctree source=A,process-cache=B,thread-cache=C
42-
--proctree process-cache=X --proctree thread-cache=Y
36+
--stores process.max-processes=8192 | will cache up to 8192 processes in the tree (LRU cache).
37+
--stores process.max-threads=16384 | will cache up to 16384 threads in the tree (LRU cache).
38+
--stores process.use-procfs | will enable procfs initialization and querying.
39+
40+
Use the flag multiple times to choose multiple options:
41+
--stores process.enabled --stores process.source=both --stores process.max-processes=8192
4342
```
4443

4544
## Internal Data Organization

‎docs/docs/flags/stores.1.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: TRACEE-STORES
3+
section: 1
4+
header: Tracee Stores Flag Manual
5+
date: 2025/11
6+
...
7+
8+
## NAME
9+
10+
tracee **\-\-stores** - Configure data stores for DNS cache and process tree
11+
12+
## SYNOPSIS
13+
14+
tracee **\-\-stores** [dns.enabled|dns.max-entries=*size*|process.enabled|process.max-processes=*size*|process.max-threads=*size*|process.source=*source*|process.use-procfs] [**\-\-stores** ...]
15+
16+
## DESCRIPTION
17+
18+
The **\-\-stores** flag allows you to configure data stores for DNS cache and process tree functionality.
19+
20+
### DNS Store Options
21+
22+
- **dns.enabled**: Enable the DNS cache store. When enabled, Tracee will cache DNS query information for enrichment of network events.
23+
24+
- **dns.max-entries**=*size*: Set the maximum number of DNS query trees to cache. Default is 5000. Further queries may be cached regardless once the limit is reached.
25+
26+
### Process Store Options
27+
28+
- **process.enabled**: Enable the process tree store. When enabled, Tracee will maintain a tree of processes and threads for enrichment of events.
29+
30+
- **process.max-processes**=*size*: Set the maximum number of processes to cache in the process tree. Default is 10928. This is an LRU cache that will evict least recently accessed entries when full.
31+
32+
- **process.max-threads**=*size*: Set the maximum number of threads to cache in the process tree. Default is 21856. This is an LRU cache that will evict least recently accessed entries when full.
33+
34+
- **process.source**=*source*: Set the source for process tree enrichment. Valid values are:
35+
- **none**: Process tree source is disabled (default).
36+
- **events**: Process tree is built from events.
37+
- **signals**: Process tree is built from signals.
38+
- **both**: Process tree is built from both events and signals.
39+
40+
- **process.use-procfs**: Enable procfs initialization and querying. When enabled, Tracee will:
41+
- Scan procfs during initialization to fill all existing processes and threads.
42+
- Query specific processes at runtime in case of missing information caused by missing events.
43+
44+
Note: The procfs query might increase the feature toll on CPU and memory. The runtime query might have a snowball effect on lost events, as it will reduce the system resources in the processes of filling missing information.
45+
46+
## EXAMPLES
47+
48+
1. Enable DNS cache:
49+
```console
50+
--stores dns.enabled
51+
```
52+
53+
2. Enable DNS cache with custom size:
54+
```console
55+
--stores dns.enabled --stores dns.max-entries=10000
56+
```
57+
58+
3. Enable process tree:
59+
```console
60+
--stores process.enabled
61+
```
62+
63+
4. Enable process tree with custom cache sizes:
64+
```console
65+
--stores process.enabled --stores process.max-processes=8192 --stores process.max-threads=16384
66+
```
67+
68+
5. Enable process tree with events source:
69+
```console
70+
--stores process.enabled --stores process.source=events
71+
```
72+
73+
6. Enable process tree with both events and signals sources:
74+
```console
75+
--stores process.enabled --stores process.source=both
76+
```
77+
78+
7. Enable process tree with procfs support:
79+
```console
80+
--stores process.enabled --stores process.use-procfs
81+
```
82+
83+
8. Combine DNS and process stores:
84+
```console
85+
--stores dns.enabled --stores dns.max-entries=5000 --stores process.enabled --stores process.source=both --stores process.max-processes=8192
86+
```
87+
88+
9. Complete configuration example:
89+
```console
90+
--stores dns.enabled --stores dns.max-entries=5000 --stores process.enabled --stores process.max-processes=8192 --stores process.max-threads=16384 --stores process.source=both --stores process.use-procfs
91+
```
92+
93+
Please refer to the [DNS data source documentation](../advanced/data-sources/builtin/dns.md) and [Process Tree data source documentation](../advanced/data-sources/builtin/process-tree.md) for more information.
94+

‎docs/docs/install/config/index.md‎

Lines changed: 9 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -50,17 +50,21 @@ A complete config file with all available options can be found [here](https://gi
5050
pyroscope: true
5151
```
5252

53-
### Process Tree
53+
### Stores (Process Tree and DNS Cache)
5454

55-
- **`--proctree` (`-t`)**: Controls process tree options.
55+
- **`--stores`**: Controls process tree and DNS cache options.
5656

5757

58-
__NOTE__: You can view more in the [Process Tree section](../../advanced/data-sources/builtin/process-tree.md).
58+
__NOTE__: You can view more in the [Process Tree section](../../advanced/data-sources/builtin/process-tree.md) and [DNS Cache section](../../advanced/data-sources/builtin/dns.md).
5959

6060
YAML:
6161
```yaml
62-
proctree:
63-
- process
62+
stores:
63+
process:
64+
enabled: true
65+
source: both
66+
dns:
67+
enabled: true
6468
```
6569

6670
### Install Path
@@ -109,17 +113,6 @@ A complete config file with all available options can be found [here](https://gi
109113
socket: /var/run/docker.sock
110114
```
111115

112-
### DNS Cache
113-
114-
- **`--dnscache`**: Enables DNS caching in Tracee.
115-
116-
__NOTE__: You can view more in the [DNS Cache section](../../advanced/data-sources/builtin/dns.md).
117-
118-
YAML:
119-
```yaml
120-
dnscache: enable
121-
```
122-
123116
### Capabilities
124117

125118
- **`--capabilities` (`-C`)**: Define specific capabilities for Tracee to run with. This allows you to either bypass, add, or drop certain capabilities based on your security and operational needs.

‎docs/docs/policies/usage/cli.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -67,11 +67,14 @@ signatures-dir: ""
6767

6868
capabilities:
6969
bypass: false
70-
proctree:
71-
source: both
72-
cache:
73-
process: 8192
74-
thread: 8192
70+
stores:
71+
process:
72+
enabled: true
73+
source: both
74+
max-processes: 8192
75+
max-threads: 8192
76+
dns:
77+
enabled: false
7578

7679
# logging
7780

0 commit comments

Comments
 (0)