From 05b0c6d283d21a8687fea70eb8476b78df401488 Mon Sep 17 00:00:00 2001 From: William Findlay Date: Thu, 21 Mar 2024 11:32:00 -0400 Subject: [PATCH] docs: document redaction filters for events Signed-off-by: William Findlay --- docs/content/en/docs/concepts/events.md | 38 +++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/docs/content/en/docs/concepts/events.md b/docs/content/en/docs/concepts/events.md index 649928e6b15..667b0c8573b 100644 --- a/docs/content/en/docs/concepts/events.md +++ b/docs/content/en/docs/concepts/events.md @@ -118,7 +118,41 @@ A default deployment writes the JSON log to `/var/run/cilium/tetragon/tetragon.l be exported through normal log collection tooling, e.g. 'fluentd', logstash, etc.. The file will be rotated and compressed by default. See [Helm Options] for details on how to customize this location. -#### `tetra` CLI +#### Redacting Sensitive Information + +Since Tetragon traces the entire system, event exports might sometimes contain +sensitive information (for example, a secret passed via a command line argument +to a process). To prevent this information from being exfiltrated via Tetragon +JSON export, Tetragon provides a mechanism called Redaction Filters which can be +used to select events and string patterns to redact. These filters are written +in JSON and passed to the Tetragon agent via the `--redaction-filters` command +line flag or the `redactionFilters` Helm value. + +Redaction filters select events using the `match` field, which contains one or +more filters (these filters are defined the same way as export filters). If no +match filter is defined, all events are selected. + +As a concrete example, the following will redact all passwords passed to +processes with the `"--password"` argument: + +```json +{"redact": ["--password(?:\s+|=)(\S*)"]} +``` + +Now, an event which contains the string `"--password=foo"` would have that string +replaced with `"--password=*****"`. + +Suppose we also see some passwords passed via the -p shorthand for a specific binary, foo. +We can also redact these as follows: + +```json +{"match": [{"binary_regex": "(?:^|/)foo$"}], "redact": ["-p(?:\s+|=)(\S*)"]} +``` + +With both of the above redaction filters in place, we are now redacting all +password arguments. + +### `tetra` CLI A second way is to use the [`tetra`](https://github.com/cilium/tetragon/tree/main/cmd/tetra) CLI. This has the advantage that it can also be used to filter and pretty print the output. The tool @@ -166,4 +200,4 @@ An example gRPC endpoint is the Tetra CLI when its not piped JSON output directl ```shell kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact -``` +``` \ No newline at end of file