Tutorial: Correlate additional metadata with events

[christian-2]

Is there an existing issue for this?

• [X] I have searched the existing issues

Is your feature request related to a problem?

From a practical perspective it would be helpful if Tetragon events could bear human-friendly usernames in addition to uid and auid . However, it seems ill-advised to place the gathering of such usernames in Tetragon itself (including tetra). #2015 includes arguments to that effect. What could be helpful instead is a tutorial that sketches alternative approaches for achieving this practical goal.

Describe the feature you would like

A new tutorials by the title Correlate additional metadata with events. It (its initial version) would lay out two ways of adding human-friendly usernames to Tetragon's events:

1. A simpler approach with more overhead "pipes" Tetragon's JSON events into a script that suitably combines jq and id for achieving the correlation.
2. A second approach with less overhead employs a custom binary program, which reads Tetragon events from a JSON file or acts as gRPC client opposite Tetragon, links against libc (from where it can "pull" usernames), and writes correlated events to a new JSON file.

usage: usernames [ --import-filename file | --server-address address ] [ --uid | --auid ]
  --export-filename file 

--export-filename write correlated events to JSON file
--import-filename read Tetragon events from JSON file
--server-address  receive Tetragon over gRPC 
--uid             derive usernames from uids
--aud             derive usernames from auids

The title of the new tutorial is inspired by a sentence from the O'Reilly report Security Observability with eBPF that addresses roughly similar concerns:

eBPF programs enable Kubernetes support by bundling API “watcher” programs that pull identity metadata from the Kubernetes API server and correlate that with container events in the kernel.

Describe your proposed solution

We can implement this feature by:

• a tutorial in docs/content/en/docs/tutorials/correlate-metadata.md
• implementation of the custom program in contrib/usernames/ (optional; perhaps in C)

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[christian-2]

@mtardy what is the next step for enhancement proposals such as this one; for instance, is a further review required? I'd be willing to work on an implementation (at as self-determined pace).

[mtardy]

You can work on this and propose a PR I think this can be valuable.

As of this:

implementation of the custom program in contrib/usernames/ (optional; perhaps in C)

I would suggest using existing utilities like id if you can.

[christian-2]

@mtardy thanks for your quick response and for assigning the issue. Regarding id, are you suggesting to reuse code from utilities like id for the second list item, or to place more effort on the first list item? I'm assuming it's the latter.

[mtardy]

I was mainly suggesting that well-known well-tested binaries might already exist that do what you want to do instead of needing to rewrite one.

[christian-2]

@mtardy so yes, that's what I meant in the first list item above. From today's perspective, I should have some markdown to that effect ready soon.