Skip to content

Commit 32789ed

Browse files
josedonizettijosedonizetti
committed
flag(enrich)!: new format flag
BREAKING CHANGE: add --enrichment flag to replace --containers
1 parent ef9e944 commit 32789ed

27 files changed

Lines changed: 1264 additions & 574 deletions

‎cmd/tracee/cmd/man.go‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,14 +55,13 @@ func init() {
5555
capabilitiesCmd,
5656
captureCmd,
5757
configCmd,
58-
containersCmd,
58+
enrichmentCmd,
5959
eventCmd,
6060
eventsCmd,
6161
loggingCmd,
6262
outputCmd,
6363
scopeCmd,
6464
serverCmd,
65-
eventCmd,
6665
storesCmd,
6766
)
6867
}
@@ -117,12 +116,12 @@ var configCmd = &cobra.Command{
117116
},
118117
}
119118

120-
var containersCmd = &cobra.Command{
121-
Use: "containers",
119+
var enrichmentCmd = &cobra.Command{
120+
Use: "enrichment",
122121
Aliases: []string{},
123-
Short: "Show manual page for the --containers flag",
122+
Short: "Show manual page for the --enrichment flag",
124123
RunE: func(cmd *cobra.Command, args []string) error {
125-
return runManForFlag("containers")
124+
return runManForFlag("enrichment")
126125
},
127126
}
128127

‎cmd/tracee/cmd/root.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -161,11 +161,11 @@ func initCmd() error {
161161
// Container flags
162162

163163
rootCmd.Flags().StringArray(
164-
flags.ContainersFlag,
164+
flags.EnrichmentFlag,
165165
[]string{},
166-
"Configure container enrichment and runtime sockets for container events enrichment (see documentation)",
166+
"[container|resolve-fd...]\t\tConfigure enrichment for container events and other enrichment features",
167167
)
168-
err = viper.BindPFlag(flags.ContainersFlag, rootCmd.Flags().Lookup(flags.ContainersFlag))
168+
err = viper.BindPFlag(flags.EnrichmentFlag, rootCmd.Flags().Lookup(flags.EnrichmentFlag))
169169
if err != nil {
170170
return errfmt.WrapError(err)
171171
}

‎docs/docs/flags/containers.1.md‎

Lines changed: 0 additions & 77 deletions
This file was deleted.

‎docs/docs/flags/enrichment.1.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: TRACEE-ENRICHMENT
3+
section: 1
4+
header: Tracee Enrichment Flag Manual
5+
date: 2025/12
6+
...
7+
8+
## NAME
9+
10+
tracee **\-\-enrichment** - Configure enrichment for container events and other enrichment options
11+
12+
## SYNOPSIS
13+
14+
tracee **\-\-enrichment** [container|container.cgroupfs.path=*path*|container.cgroupfs.force|container.docker.socket=*socket_path*|container.containerd.socket=*socket_path*|container.crio.socket=*socket_path*|container.podman.socket=*socket_path*|resolve-fd|exec-hash|exec-hash.mode=*mode*|user-stack-trace] [**\-\-enrichment** ...]
15+
16+
## DESCRIPTION
17+
18+
The `--enrichment` flag allows you to configure enrichment options for container events and other enrichment features.
19+
20+
### Flags
21+
22+
- **container**: Enable container enrichment with default settings. When enabled, Tracee will enrich container events with container information.
23+
24+
- **container.cgroupfs.path**=*path*: Enable container enrichment and configure the path to the cgroupfs where container cgroups are created. This is used as a hint for auto-detection. **Note**: Using this option automatically enables container, so you don't need to also specify `--enrichment container`.
25+
Example:
26+
```console
27+
--enrichment container.cgroupfs.path=/sys/fs/cgroup
28+
```
29+
30+
- **container.cgroupfs.force**: Force the usage of the provided mountpoint path, skipping auto-detection. **Note**: This option requires `container.cgroupfs.path` to be set. It cannot be used alone.
31+
Example:
32+
```console
33+
--enrichment container.cgroupfs.path=/sys/fs/cgroup container.cgroupfs.force
34+
```
35+
36+
- **container.docker.socket**=*socket_path*: Enable container enrichment and configure container runtime sockets for enrichment. Configure the path to the Docker socket. **Note**: Using this option automatically enables container, so you don't need to also specify `--enrichment container`.
37+
Example:
38+
```console
39+
--enrichment container.docker.socket=/var/run/docker.sock
40+
```
41+
42+
- **container.containerd.socket**=*socket_path*: Enable container enrichment and configure container runtime sockets for enrichment. Configure the path to the Containerd socket. **Note**: Using this option automatically enables container, so you don't need to also specify `--enrichment container`.
43+
Example:
44+
```console
45+
--enrichment container.containerd.socket=/var/run/containerd/containerd.sock
46+
```
47+
48+
- **container.crio.socket**=*socket_path*: Enable container enrichment and configure container runtime sockets for enrichment. Configure the path to the CRI-O socket. **Note**: Using this option automatically enables container, so you don't need to also specify `--enrichment container`.
49+
Example:
50+
```console
51+
--enrichment container.crio.socket=/var/run/crio/crio.sock
52+
```
53+
54+
- **container.podman.socket**=*socket_path*: Enable container enrichment and configure container runtime sockets for enrichment. Configure the path to the Podman socket. **Note**: Using this option automatically enables container, so you don't need to also specify `--enrichment container`.
55+
Example:
56+
```console
57+
--enrichment container.podman.socket=/var/run/podman/podman.sock
58+
```
59+
60+
Supported container runtimes for socket configuration:
61+
- CRI-O (`crio`, `cri-o`)
62+
- Containerd (`containerd`)
63+
- Docker (`docker`)
64+
- Podman (`podman`)
65+
66+
- **resolve-fd**
67+
Enable resolve-fd. Presence of the flag enables it, absence disables it.
68+
Example:
69+
```console
70+
--enrichment resolve-fd
71+
```
72+
73+
- **exec-hash**: Enable exec-hash with default settings. When enabled, Tracee will compute hash values for executed binaries.
74+
75+
- **exec-hash.mode**=*mode*: Enable exec-hash and configure the mode for exec-hash. **Note**: Using this option automatically enables exec-hash, so you don't need to also specify `--enrichment exec-hash`.
76+
Example:
77+
```console
78+
--enrichment exec-hash.mode=sha256
79+
```
80+
81+
- **user-stack-trace**
82+
Enable user-stack-trace. Presence of the flag enables it, absence disables it.
83+
Example:
84+
```console
85+
--enrichment user-stack-trace
86+
```
87+
88+
## EXAMPLES
89+
90+
1. Enable container enrichment:
91+
```console
92+
--enrichment container
93+
```
94+
95+
2. Configure Docker socket:
96+
```console
97+
--enrichment container.docker.socket=/var/run/docker.sock
98+
```
99+
Note: `container.docker.socket` automatically enables container, so `--enrichment container` is not needed.
100+
101+
3. Set the cgroupfs path:
102+
```console
103+
--enrichment container.cgroupfs.path=/sys/fs/cgroup
104+
```
105+
Note: `container.cgroupfs.path` automatically enables container, so `--enrichment container` is not needed.
106+
107+
4. Combine multiple flags:
108+
```console
109+
--enrichment container.docker.socket=/var/run/docker.sock container.cgroupfs.path=/sys/fs/cgroup
110+
```
111+
Note: Since `container.docker.socket` and `container.cgroupfs.path` automatically enable container, you don't need `--enrichment container`.
112+
113+
5. Enable resolve-fd and exec-hash:
114+
```console
115+
--enrichment resolve-fd exec-hash
116+
```
117+
118+
6. Enable exec-hash with custom mode:
119+
```console
120+
--enrichment exec-hash.mode=sha256
121+
```
122+
Note: `exec-hash.mode` automatically enables exec-hash, so `--enrichment exec-hash` is not needed.
123+
124+
Please refer to the [documentation](../install/container-engines.md) for more information on container events enrichment.
125+

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

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -101,24 +101,36 @@ filters, destination file and others.
101101

102102
### Containers
103103

104-
- To disable container enrichment use: **`--containers enrich=false`**.
104+
- To enable container enrichment, include the flag: **`--enrichment container`**. To disable it, simply omit the flag. Note: Setting any container sub-option (e.g., `container.docker.socket=/path`) automatically enables container, so `--enrichment container` is not needed.
105105

106106
YAML:
107107
```yaml
108-
containers:
109-
enrich: false
108+
enrichment:
109+
container:
110+
enabled: true
110111
```
111112

112-
__NOTE__: You can view more in the [containers section](../../flags/containers.1.md).
113+
__NOTE__: You can view more in the [enrichment section](../../flags/enrichment.1.md).
113114

114-
- **`--containers`**: Configures container enrichment and runtime sockets. For example, to configure runtime sockets:
115+
- **`--enrichment`**: Configures enrichment options including container enrichment and runtime sockets. For example, to configure runtime sockets:
115116

116117
YAML:
117118
```yaml
118-
containers:
119-
sockets:
120-
- runtime: docker
121-
socket: /var/run/docker.sock
119+
enrichment:
120+
container:
121+
enabled: true
122+
cgroupfs:
123+
path: /host/sys/fs/cgroup
124+
force: false
125+
docker-socket: /var/run/docker.sock
126+
containerd-socket: /var/run/containerd/containerd.sock
127+
crio-socket: /var/run/crio/crio.sock
128+
podman-socket: /var/run/podman/podman.sock
129+
resolve-fd: true
130+
exec-hash:
131+
enabled: true
132+
mode: sha256
133+
user-stack-trace: true
122134
```
123135

124136
### Capabilities

0 commit comments

Comments
 (0)