Organise Tracing Policies - #5268
Conversation
Signed-off-by: Paul Arah <paularah.self@gmail.com>
Signed-off-by: Paul Arah <paularah.self@gmail.com>
Signed-off-by: Paul Arah <paularah.self@gmail.com>
✅ Deploy Preview for tetragon ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
some initial work here, still WIP. I choose to organise the policies around usecases. Then, i'll slightly change how we put policies in the docs. You write the policy, put it in the correct usecase directory, and then reference the path. LMK what you think. |
mtardy
left a comment
mtardy
left a comment
There was a problem hiding this comment.
I think there are many changes to apply before this is ready. I would also check why the CI is complaining and add many more details to each commit logs explaining the why of each of your changes.
If you want you could split your PR into two:
- reorganize and move around the "official policies" (maybe some (all?) of them should go to the OSS repo also), and update all the existing references.
- introduce the new page on the documentation for displaying them.
On the second point, I think it would be nice to generate some kind of generated reference based on the policies folder. I think it should be doable to use it as a data source and generate HTML based on it, but might be some amount of work!
There was a problem hiding this comment.
where do all these new policies come from? If they come from examples, should we git mv them so that we have git history following them and replace all the references to them properly?
| Policies in this directory cover use cases related to monitoring network activity, | ||
| including socket operations, packet transmission, network interfaces, | ||
| and protocol-specific events. No newline at end of file |
There was a problem hiding this comment.
nit: you have weird indent in most of the readmes
| {{- if not $file -}} | ||
| {{- errorf "policy-example: policies/%s not found (%s)" $path .Position -}} | ||
| {{- else -}} | ||
| {{ highlight $file.Content "yaml" "" }} | ||
| <p><a href="https://github.com/cilium/tetragon/blob/main/policies/{{ replace $path " " "%20" }}">View {{ path.Base $path }} on GitHub</a></p> |
There was a problem hiding this comment.
so the build should fail thanks to this errorf (since this is not merged yet) but it doesn't seems to
| # Adding an explicit mount below requires listing Hugo's implicit default | ||
| # mounts too, otherwise they stop applying (see | ||
| # https://gohugo.io/hugo-modules/configuration/#module-configuration-mounts). | ||
| [[module.mounts]] | ||
| source = "content/en" | ||
| target = "content" | ||
| [[module.mounts]] | ||
| source = "data" | ||
| target = "data" | ||
| [[module.mounts]] | ||
| source = "layouts" | ||
| target = "layouts" | ||
| [[module.mounts]] | ||
| source = "i18n" | ||
| target = "i18n" | ||
| [[module.mounts]] | ||
| source = "archetypes" | ||
| target = "archetypes" | ||
| [[module.mounts]] | ||
| source = "assets" | ||
| target = "assets" | ||
| [[module.mounts]] | ||
| source = "static" | ||
| target = "static" |
There was a problem hiding this comment.
could you explain all these changes?
| After deploying Tetragon, use the {{< policy-ref "system-integrity/monitor-signed-kernel-modules.yaml" >}} tracing policy which generates [ProcessKprobe]({{< ref "/docs/reference/grpc-api#processkprobe" >}}) events | ||
| to identify if kernel modules are signed or not. | ||
|
|
||
| Apply the [monitor-signed-kernel-modules](https://raw.githubusercontent.com/cilium/tetragon/main/examples/tracingpolicy/host-changes/monitor-signed-kernel-modules.yaml) tracing policy: | ||
| Apply the {{< policy-ref "system-integrity/monitor-signed-kernel-modules.yaml" >}} tracing policy: | ||
| ```shell | ||
| kubectl apply -f https://raw.githubusercontent.com/cilium/tetragon/main/examples/tracingpolicy/host-changes/monitor-signed-kernel-modules.yaml | ||
| kubectl apply -f {{< policy-raw-url "system-integrity/monitor-signed-kernel-modules.yaml" >}} |
There was a problem hiding this comment.
I would maybe first introduce the shortcode and then add commit using it
2 participants
Description
Summary
The Tetragon project currently lacks a centralized, well-organized collection of tracing policies. As a result, there is no single place where users can discover high-quality tracing policy examples or learn how to write their own.
This PR addresses that by organizing the existing tracing policies referenced throughout the documentation into a dedicated
/policiesdirectory, grouped by use case. This makes it significantly easier for users to discover relevant policies, understand how they work, and use them as references when authoring new tracing policies.In addition, this PR introduces three new Hugo shortcodes for referencing tracing policies from the documentation. These shortcodes provide several benefits:
Documentation describing how to use these shortcodes has been added to the documentation contribution guide.
As an example, the Kernel Modules section under the Host System use case has been updated to use the new shortcodes. Converting the remaining documentation to use these shortcodes will be done in a separate follow-up PR.
Changelog