diff --git a/docs/docs/integrating/go-templates.md b/docs/docs/integrating/go-templates.md deleted file mode 100644 index be0930cbef2d..000000000000 --- a/docs/docs/integrating/go-templates.md +++ /dev/null @@ -1,68 +0,0 @@ -# Detections: Output Format - -## Configuring - -When a detection is made by any of the loaded signatures, it will always be -printed to stdout. You can customize this output format using a [go template]. - -```bash -$ ./dist/tracee-rules --output-template /path/to/my.tmpl -``` - -[go template]: https://golang.org/pkg/text/template - -!!! Go-templates Note - - The following Go templates are included in the Tracee container image and are - available for use under the `/tracee/templates/` directory in the container: - - | File name | Description | Content-Type | Source | - |--------------------|----------------------------------------|--------------------|-------------------------------------------------------------------------------------------------------------------| - | rawjson.tmpl | Dumps the Finding object as raw JSON | `application/json` | [source](https://github.com/aquasecurity/tracee/blob/{{ git.tag }}/cmd/tracee-rules/templates/rawjson.tmpl) | - -1. Basic Example: **Raw JSON** stdout - - The following example configures Tracee to output detections to stdout as raw JSON: - - ```text - $ docker run \ - --name tracee --rm -it \ - --pid=host --cgroupns=host --privileged \ - -v /etc/os-release:/etc/os-release-host:ro \ - -e LIBBPFGO_OSRELEASE_FILE=/etc/os-release-host \ - aquasec/tracee:{{ git.tag[1:] }} \ - --output-template /tracee/templates/rawjson.tmpl - ``` - - !!! Postee Tip - Tracee default delivery mechanism, using Helm, is through [Postee] and uses - the `rawjson.tmpl` go template. - -[Postee]: ./postee.md - -2. [Deliver using a Webhook](./webhook.md) - -3. [Deliver using Postee](./postee.md) - -## Authoring - -When authoring a Go template for either stdout or webhook, you have Tracee's -`types.Finding` struct as the data source: - -```go -// Finding is the main output of a signature. It represents a match result for -// the signature business logic. - -type Finding struct { - SigMetadata SignatureMetadata // information about the signature that made the detection - Context Event // the raw event that triggered the detection - Data map[string]interface{} // detection specific information -} -``` - -The Go template can utilize helper functions from [Sprig]. - -For example templates, see [tracee/cmd/tracee-rules/templates]. - -[Sprig]: http://masterminds.github.io/sprig/ -[tracee/cmd/tracee-rules/templates]: https://github.com/aquasecurity/tracee/tree/{{ git.tag }}/cmd/tracee-rules/templates diff --git a/docs/docs/integrating/postee.md b/docs/docs/integrating/postee.md deleted file mode 100644 index f352e713d37d..000000000000 --- a/docs/docs/integrating/postee.md +++ /dev/null @@ -1,8 +0,0 @@ -# Detections: Deliver using Postee - -**Postee** integration is the default experience when using **[helm deployment]**. - -[helm deployment]: ../../getting-started/installing/kubernetes.md - -!!! Also Important - 1. [Deliver using a Webhook](./webhook.md) diff --git a/docs/docs/integrating/webhook.md b/docs/docs/integrating/webhook.md deleted file mode 100644 index 79336ae89d46..000000000000 --- a/docs/docs/integrating/webhook.md +++ /dev/null @@ -1,13 +0,0 @@ -# Detections: Deliver using a Webhook - -In addition, Tracee can notify a web service when a detection is made using a -custom webhook: - -```bash -tracee-rules --webhook http://my.webhook/endpoint \ - --webhook-template /path/to/my.tmpl \ - --webhook-content-type application/json -``` - -!!! Also Important - 1. [Deliver using Postee](./postee.md) diff --git a/docs/docs/outputs/output-formats.md b/docs/docs/outputs/output-formats.md index ce581f0827ba..32e9f62a5deb 100644 --- a/docs/docs/outputs/output-formats.md +++ b/docs/docs/outputs/output-formats.md @@ -1,27 +1,34 @@ # Tracing Output Formats -In order to check latest output options you may execute: +The `--output` flag controls where and how Tracee will output events, by specifying `--output :`. You can use the `--output` flag multiple times to output events in multiple ways. To see all output options you can run `tracee --output help`. -```text -$ sudo ./dist/tracee --output help -``` +The following output formats are supported: -Tracee supports different output formats for detected events: +- `table[:/path/to/file]` - output events in table format (default). The default path to file is stdout. +- `table-verbose[:/path/to/file]` - output events in table format with extra fields per event. The default path to file is stdout. +- `json[:/path/to/file]` - output events in json format. The default path to file is stdout. +- `gob[:/path/to/file]` - output events in gob format. The default path to file is stdout. +- `gotemplate=/path/to/template[:/path/to/file]` - output events formatted using a given gotemplate file. The default path to file is stdout. +- `forward:http://url/fluent` - send events in json format using the Forward protocol to a Fluent receiver +- `webhook:http://url/webhook` - send events in json format to the webhook url +- `none` - ignore stream of events output, usually used with --capture -1. **Table** +## Examples - ```text - $ sudo ./dist/tracee --output table --filter comm=bash --filter follow --filter event=openat - TIME UID COMM PID TID RET EVENT ARGS - 11:21:51:254199 1000 exa 1639459 1639459 3 openat dirfd: -100, pathname: /etc/ld.so.cache, flags: O_RDONLY|O_CLOEXEC, mode: 0 - 11:21:51:254285 1000 exa 1639459 1639459 3 openat dirfd: -100, pathname: /lib/x86_64-linux-gnu/libgcc_s.so.1, flags: O_RDONLY|O_CLOEXEC, mode: 0 - 11:21:51:254418 1000 exa 1639459 1639459 3 openat dirfd: -100, pathname: /lib/x86_64-linux-gnu/libm.so.6, flags: O_RDONLY|O_CLOEXEC, mode: 0 - - End of events stream - Stats: {EventCount:3 EventsFiltered:0 NetCapCount:0 BPFLogsCount:0 ErrorCount:0 LostEvCount:0 LostWrCount:0 LostNtCapCount:0 LostBPFLogsCount:0} - ``` +### Table + +```text +$ sudo ./dist/tracee --output table --filter comm=bash --filter follow --filter event=openat +TIME UID COMM PID TID RET EVENT ARGS +11:21:51:254199 1000 exa 1639459 1639459 3 openat dirfd: -100, pathname: /etc/ld.so.cache, flags: O_RDONLY|O_CLOEXEC, mode: 0 +11:21:51:254285 1000 exa 1639459 1639459 3 openat dirfd: -100, pathname: /lib/x86_64-linux-gnu/libgcc_s.so.1, flags: O_RDONLY|O_CLOEXEC, mode: 0 +11:21:51:254418 1000 exa 1639459 1639459 3 openat dirfd: -100, pathname: /lib/x86_64-linux-gnu/libm.so.6, flags: O_RDONLY|O_CLOEXEC, mode: 0 + +End of events stream +Stats: {EventCount:3 EventsFiltered:0 NetCapCount:0 BPFLogsCount:0 ErrorCount:0 LostEvCount:0 LostWrCount:0 LostNtCapCount:0 LostBPFLogsCount:0} +``` -2. **Table (Verbose)** +### Table (Verbose) ```text $ sudo ./dist/tracee --output table-verbose --filter comm=bash --filter follow --filter event=openat @@ -34,61 +41,44 @@ Tracee supports different output formats for detected events: Stats: {EventCount:3 EventsFiltered:0 NetCapCount:0 BPFLogsCount:0 ErrorCount:0 LostEvCount:0 LostWrCount:0 LostNtCapCount:0 LostBPFLogsCount:0} ``` -3. **JSON** - - ```text - $ sudo ./dist/tracee --output json --filter comm=bash --filter follow --filter event=openat - ``` - - ```json - {"timestamp":1657290245020855990,"threadStartTime":615325807626168,"processorId":22,"processId":1664936,"cgroupId":1,"threadId":1664936,"parentProcessId":3795408,"hostProcessId":1664936,"hostThreadId":1664936,"hostParentProcessId":3795408,"userId":1000,"mountNamespace":4026531840,"pidNamespace":4026531836,"processName":"exa","hostName":"fujitsu","containerId":"","containerImage":"","containerName":"","podName":"","podNamespace":"","podUID":"","eventId":"257","eventName":"openat","argsNum":4,"returnValue":3,"stackAddresses":null,"syscall":"openat","contextFlags":{"containerStarted":false,"isCompat":false},"args":[{"name":"dirfd","type":"int","value":-100},{"name":"pathname","type":"const char*","value":"/etc/ld.so.cache"},{"name":"flags","type":"int","value":524288},{"name":"mode","type":"mode_t","value":0}]} - {"timestamp":1657290245020940791,"threadStartTime":615325807626168,"processorId":22,"processId":1664936,"cgroupId":1,"threadId":1664936,"parentProcessId":3795408,"hostProcessId":1664936,"hostThreadId":1664936,"hostParentProcessId":3795408,"userId":1000,"mountNamespace":4026531840,"pidNamespace":4026531836,"processName":"exa","hostName":"fujitsu","containerId":"","containerImage":"","containerName":"","podName":"","podNamespace":"","podUID":"","eventId":"257","eventName":"openat","argsNum":4,"returnValue":3,"stackAddresses":null,"syscall":"openat","contextFlags":{"containerStarted":false,"isCompat":false},"args":[{"name":"dirfd","type":"int","value":-100},{"name":"pathname","type":"const char*","value":"/lib/x86_64-linux-gnu/libgcc_s.so.1"},{"name":"flags","type":"int","value":524288},{"name":"mode","type":"mode_t","value":0}]} - ``` - - !!! Tip - A good tip is to pipe **tracee** json output to [jq]() tool, this way - you can select fields, rename them, filter values, and many other things: - > ```text - > sudo ./dist/tracee -o json -o option:parse-arguments - > -trace comm=ping | jq -c '. | {eventId, hostName, processName, - > hostProcessId,UserId}' - > ``` - -4. **GOB** +### JSON - ```text - $ sudo ./dist/tracee --output json --filter comm=bash --filter follow --filter event=openat - ``` +```text +$ sudo ./dist/tracee --output json --filter comm=bash --filter follow --filter event=openat +``` -5. **GOTEMPLATE** +```json +{"timestamp":1657290245020855990,"threadStartTime":615325807626168,"processorId":22,"processId":1664936,"cgroupId":1,"threadId":1664936,"parentProcessId":3795408,"hostProcessId":1664936,"hostThreadId":1664936,"hostParentProcessId":3795408,"userId":1000,"mountNamespace":4026531840,"pidNamespace":4026531836,"processName":"exa","hostName":"fujitsu","containerId":"","containerImage":"","containerName":"","podName":"","podNamespace":"","podUID":"","eventId":"257","eventName":"openat","argsNum":4,"returnValue":3,"stackAddresses":null,"syscall":"openat","contextFlags":{"containerStarted":false,"isCompat":false},"args":[{"name":"dirfd","type":"int","value":-100},{"name":"pathname","type":"const char*","value":"/etc/ld.so.cache"},{"name":"flags","type":"int","value":524288},{"name":"mode","type":"mode_t","value":0}]} +{"timestamp":1657290245020940791,"threadStartTime":615325807626168,"processorId":22,"processId":1664936,"cgroupId":1,"threadId":1664936,"parentProcessId":3795408,"hostProcessId":1664936,"hostThreadId":1664936,"hostParentProcessId":3795408,"userId":1000,"mountNamespace":4026531840,"pidNamespace":4026531836,"processName":"exa","hostName":"fujitsu","containerId":"","containerImage":"","containerName":"","podName":"","podNamespace":"","podUID":"","eventId":"257","eventName":"openat","argsNum":4,"returnValue":3,"stackAddresses":null,"syscall":"openat","contextFlags":{"containerStarted":false,"isCompat":false},"args":[{"name":"dirfd","type":"int","value":-100},{"name":"pathname","type":"const char*","value":"/lib/x86_64-linux-gnu/libgcc_s.so.1"},{"name":"flags","type":"int","value":524288},{"name":"mode","type":"mode_t","value":0}]} +``` - Check [integrations page](../integrating/go-templates.md) for more info. +!!! Tip + A good tip is to pipe **tracee** json output to [jq]() tool, this way + you can select fields, rename them, filter values, and many other things: + > ```text + > sudo ./dist/tracee -o json -o option:parse-arguments + > -trace comm=ping | jq -c '. | {eventId, hostName, processName, + > hostProcessId,UserId}' + > ``` -## Output Files +### GOB -Tracee gives user the option to select which files they want to use as standard -output and standard error: +```text +$ sudo ./dist/tracee --output json --filter comm=bash --filter follow --filter event=openat +``` -1. Output file +### GOTEMPLATE - !!! tip - User might use different output formats combined with output file option +When authoring a Go template the data source is Tracee's `trace.Event` struct, which is defined in `https://github.com/aquasecurity/tracee/blob/main/types/trace/trace.go#L15`. - ```text - $ sudo ./dist/tracee --filter comm=bash --filter follow --filter event=openat --output json:/tmp/tracee.log - - $ cat /tmp/tracee.log | jq -c - ``` +Go template can utilize helper functions from [Sprig](http://masterminds.github.io/sprig/). - ```json - {"timestamp":1657291487418386000,"threadStartTime":616568205378363,"processorId":11,"processId":1893369,"cgroupId":1,"threadId":1893369,"parentProcessId":3795408,"hostProcessId":1893369,"hostThreadId":1893369,"hostParentProcessId":3795408,"userId":1000,"mountNamespace":4026531840,"pidNamespace":4026531836,"processName":"exa","hostName":"fujitsu","containerId":"","containerImage":"","containerName":"","podName":"","podNamespace":"","podUID":"","eventId":"257","eventName":"openat","argsNum":4,"returnValue":3,"stackAddresses":null,"syscall":"openat","contextFlags":{"containerStarted":false,"isCompat":false},"args":[{"name":"dirfd","type":"int","value":-100},{"name":"pathname","type":"const char*","value":"/etc/ld.so.cache"},{"name":"flags","type":"int","value":524288},{"name":"mode","type":"mode_t","value":0}]} - {"timestamp":1657291487418510000,"threadStartTime":616568205378363,"processorId":11,"processId":1893369,"cgroupId":1,"threadId":1893369,"parentProcessId":3795408,"hostProcessId":1893369,"hostThreadId":1893369,"hostParentProcessId":3795408,"userId":1000,"mountNamespace":4026531840,"pidNamespace":4026531836,"processName":"exa","hostName":"fujitsu","containerId":"","containerImage":"","containerName":"","podName":"","podNamespace":"","podUID":"","eventId":"257","eventName":"openat","argsNum":4,"returnValue":3,"stackAddresses":null,"syscall":"openat","contextFlags":{"containerStarted":false,"isCompat":false},"args":[{"name":"dirfd","type":"int","value":-100},{"name":"pathname","type":"const char*","value":"/lib/x86_64-linux-gnu/libgcc_s.so.1"},{"name":"flags","type":"int","value":524288},{"name":"mode","type":"mode_t","value":0}]} - ``` +For example templates, see [tracee/cmd/tracee-rules/templates](https://github.com/aquasecurity/tracee/tree/main/cmd/tracee-rules/templates). -2. Error file +## Logging - Redirect logs to a file if needed: +Redirect logs to a file if needed: - ```text - $ sudo TRACEE_BPF_FILE=do-not-exist ./dist/tracee --filter comm=bash --filter follow --filter event=openat --output json:/tmp/tracee.events --output log-file:/tmp/tracee.log - ``` +```text +$ sudo TRACEE_BPF_FILE=do-not-exist ./dist/tracee --filter comm=bash --filter follow --filter event=openat --output json:/tmp/tracee.events --output log-file:/tmp/tracee.log +``` diff --git a/docs/docs/outputs/output-options.md b/docs/docs/outputs/output-options.md index ee3b147a8027..54c32e3770dd 100644 --- a/docs/docs/outputs/output-options.md +++ b/docs/docs/outputs/output-options.md @@ -1,13 +1,8 @@ # Tracing Output Options -In order to check latest output options you may execute: +Tracee supports different output options for customizing the way events are printed. For a complete list of available options, run `tracee --output help`. -```text -$ sudo ./dist/tracee --output help -$ sudo ./dist/tracee --output option:xxx -``` - -Tracee supports different output options for detected events: +Available options: 1. **option:stack-addresses** diff --git a/mkdocs.yml b/mkdocs.yml index bc7f9a11da59..c7a9c11d6c60 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -506,11 +506,6 @@ nav: - Getting Started: docs/forensics/index.md - Integrations: - Container Engines: docs/integrating/container-engines.md - - Detected Events: - - Go-template: docs/integrating/go-templates.md - - Deliver: - - Webhook: docs/integrating/webhook.md - - Postee: docs/integrating/postee.md - Prometheus: docs/integrating/prometheus.md - Healthz: docs/integrating/healthz.md - Deep Dive: