diff --git a/docs/content/en/docs/benchmarks/_index.md b/docs/content/en/docs/benchmarks/_index.md new file mode 100644 index 00000000000..22ec2f5ff98 --- /dev/null +++ b/docs/content/en/docs/benchmarks/_index.md @@ -0,0 +1,10 @@ +--- +title: "Benchmarks" +icon: "resources" +weight: 4 +description: > + This section presents benchmarks used to test Tetragon. +--- + +Tetragon benchmarks are run per release to ensure overhead created by Tetragon +is within expectations. diff --git a/docs/content/en/docs/concepts/enforcement/_index.md b/docs/content/en/docs/concepts/enforcement/_index.md new file mode 100644 index 00000000000..2a739e9149d --- /dev/null +++ b/docs/content/en/docs/concepts/enforcement/_index.md @@ -0,0 +1,10 @@ +--- +title: "Enforcement" +icon: "overview" +weight: 4 +description: "Documentation for Tetragon enforcement system" +--- + +Tetragon allows enforcing events in the kernel inline with the operation itself. +This describes the types of enforcmenet provided by Tetragon and concerns +policy implementors must be aware of. diff --git a/docs/content/en/docs/concepts/events/_index.md b/docs/content/en/docs/concepts/events/_index.md new file mode 100644 index 00000000000..f7e4d536363 --- /dev/null +++ b/docs/content/en/docs/concepts/events/_index.md @@ -0,0 +1,9 @@ +--- +title: "Events" +icon: "overview" +weight: 1 +description: "Documentation for Tetragon event system" +--- + +Tetragon's events are exposed to the system through either the gRPC +endpoint or JSON logs. diff --git a/docs/content/en/docs/concepts/events/grpc-events.md b/docs/content/en/docs/concepts/events/grpc-events.md new file mode 100644 index 00000000000..836e0c67aea --- /dev/null +++ b/docs/content/en/docs/concepts/events/grpc-events.md @@ -0,0 +1,8 @@ +--- +title: "gRPC Events" +weight: 3 +icon: "reference" +description: "Tetragon gRPC events" +--- + +A gRPC endpoint is exposed by the agent and is configurable. diff --git a/docs/content/en/docs/getting-started/explore-security-observability-events.md b/docs/content/en/docs/concepts/events/json-events.md similarity index 94% rename from docs/content/en/docs/getting-started/explore-security-observability-events.md rename to docs/content/en/docs/concepts/events/json-events.md index c91500e6611..cbb36127ef7 100644 --- a/docs/content/en/docs/getting-started/explore-security-observability-events.md +++ b/docs/content/en/docs/concepts/events/json-events.md @@ -1,8 +1,8 @@ --- -title: "Explore security observability events" +title: "JSON events" weight: 3 icon: "reference" -description: "Learn how to start exploring the Tetragon events" +description: "Tetragon JSON events" --- After Tetragon and the [demo application is up and diff --git a/docs/content/en/docs/tutorials/tetragon-metrics.md b/docs/content/en/docs/concepts/metrics.md similarity index 80% rename from docs/content/en/docs/tutorials/tetragon-metrics.md rename to docs/content/en/docs/concepts/metrics.md index 9918a429548..34838765b88 100644 --- a/docs/content/en/docs/tutorials/tetragon-metrics.md +++ b/docs/content/en/docs/concepts/metrics.md @@ -1,17 +1,18 @@ --- -title: "Tetragon Metrics" -weight: 1 +title: "Metrics" icon: "overview" -description: "Fetching and understanding Tetragon metrics" +weight: 2 +description: "Documentation for Tetragon metrics" --- +Tetragon's metrics are exposed to the system through an HTTP endpoint. These +are used to expose event summaries and information about the state of the +Tetragon agent. + ## Kubernetes -When installed with Helm as described in -[Deploying on Kubernetes]({{< ref -"/docs/getting-started/deployment/kubernetes" >}}), Tetragon pods expose a -metrics endpoint by default. The chart also creates a service named `tetragon` -that exposes metrics on the specified port. +Tetragon pods exposes a metrics endpoint by default. The chart also creates a +service named `tetragon` that exposes metrics on the specified port. ### Getting metrics port @@ -28,8 +29,8 @@ tetragon ClusterIP 10.96.54.218 2112/TCP 3m ``` {{< note >}} -In the previous output it shows, 2112 is the port on which the service is -listening. It is also the port on which the Tetragon metrics server listens +In the previous output it shows, 2112 is the port on which the service is +listening. It is also the port on which the Tetragon metrics server listens with the default Helm values. {{< /note >}} @@ -43,13 +44,11 @@ kubectl -n kube-system port-forward service/tetragon 2112:2112 ## Package -Tetragon, when installed via release packages as mentioned in -[Package Deployment]({{< ref "/docs/getting-started/deployment/package" >}}). -By default, metrics are disabled, which can be enabled using `--metrics-server` +By default, metrics are disabled, which can be enabled using `--metrics-server` flag, by specifying the address. Alternatively, the [examples/configuration/tetragon.yaml](https://github.com/cilium/tetragon/blob/main/examples/configuration/tetragon.yaml) -file contains example entries showing the defaults for the address of +file contains example entries showing the defaults for the address of metrics-server. Local overrides can be created by editing and copying this file into `/etc/tetragon/tetragon.yaml`, or by editing and copying "drop-ins" from the [examples/configuration/tetragon.conf.d](https://github.com/cilium/tetragon/tree/main/examples/configuration/tetragon.conf.d) @@ -67,25 +66,25 @@ sudo tetragon --metrics-server localhost:2112 The output should be similar to this: ``` -time="2023-09-21T13:17:08+05:30" level=info msg="Starting tetragon" +time="2023-09-21T13:17:08+05:30" level=info msg="Starting tetragon" version=v0.11.0 -time="2023-09-21T13:17:08+05:30" level=info msg="config settings" +time="2023-09-21T13:17:08+05:30" level=info msg="config settings" config="mapeased -time="2023-09-22T23:16:24+05:30" level=info msg="Starting metrics server" -addr="localhost:2112" +time="2023-09-22T23:16:24+05:30" level=info msg="Starting metrics server" +addr="localhost:2112" [...] time="2023-09-21T13:17:08+05:30" level=info msg="Listening for events..." ``` -Alternatively, a file named `server-address` can be created in `etc/tetragon/tetragon.conf.d/metrics-server` with content specifying -a port like this `localhost:2112`, or any port of your choice as mentioned +Alternatively, a file named `server-address` can be created in `etc/tetragon/tetragon.conf.d/metrics-server` with content specifying +a port like this `localhost:2112`, or any port of your choice as mentioned above. ## Fetch the Metrics -After the metrics are exposed, either by port forwarding in case of -Kubernetes installation or by setting metrics address in case of Package -installation, the metrics can be fetched using +After the metrics are exposed, either by port forwarding in case of +Kubernetes installation or by setting metrics address in case of Package +installation, the metrics can be fetched using `curl` on `localhost:2112/metrics`: ```shell-session diff --git a/docs/content/en/docs/concepts/tracing-policy/example.md b/docs/content/en/docs/concepts/tracing-policy/example.md index e97892fa328..07c6e1a2eef 100644 --- a/docs/content/en/docs/concepts/tracing-policy/example.md +++ b/docs/content/en/docs/concepts/tracing-policy/example.md @@ -115,8 +115,8 @@ echo eBPF! > /tmp/tetragon Starting Tetragon with the above `TracingPolicy`, for example putting the policy in the `example.yaml` file, compiling the project locally and starting Tetragon with (you can do similar things with container image releases, see the -docker run command in the [Try Tetragon on Linux guide]({{< ref -"/docs/getting-started/try-tetragon-linux#observability-with-tracingpolicy" >}}): +docker run command in the [Try Tetragon on Linux guide] + ```shell-session sudo ./tetragon --bpf-lib bpf/objs --tracing-policy example.yaml ``` diff --git a/docs/content/en/docs/concepts/k8s-filtering.md b/docs/content/en/docs/concepts/tracing-policy/k8s-filtering.md similarity index 100% rename from docs/content/en/docs/concepts/k8s-filtering.md rename to docs/content/en/docs/concepts/tracing-policy/k8s-filtering.md diff --git a/docs/content/en/docs/contribution-guide/_index.md b/docs/content/en/docs/contribution-guide/_index.md index 8652197fb42..af22604dc4a 100644 --- a/docs/content/en/docs/contribution-guide/_index.md +++ b/docs/content/en/docs/contribution-guide/_index.md @@ -1,7 +1,7 @@ --- title: "Contribution Guide" linkTitle: "Contribution Guide" -weight: 7 +weight: 6 icon: "contribution" description: > How to contribute to the project diff --git a/docs/content/en/docs/contribution-guide/development-setup.md b/docs/content/en/docs/contribution-guide/development-setup.md index 8ad53a42ecf..a1d1d07838a 100644 --- a/docs/content/en/docs/contribution-guide/development-setup.md +++ b/docs/content/en/docs/contribution-guide/development-setup.md @@ -111,10 +111,6 @@ To build Tetragon tarball: make tarball ``` -The produced tarball will be inside directory `./build/`, then follow the -[package deployment guide]({{< ref "/docs/getting-started/deployment/package" >}}) to -install it as a systemd service. - ### Running Tetragon in kind The scripts in contrib/localdev will help you run Tetragon locally in a kind diff --git a/docs/content/en/docs/faq/_index.md b/docs/content/en/docs/faq/_index.md index 66940a9e1da..80761cb33c9 100644 --- a/docs/content/en/docs/faq/_index.md +++ b/docs/content/en/docs/faq/_index.md @@ -107,9 +107,7 @@ to [can I run Tetragon on Mac computers](#can-i-run-tetragon-on-mac-computers). ### Can I install and use Tetragon in standalone mode (outside of k8s)? -Yes! Check the [Container deployment](/docs/getting-started/deployment/container/) or -[Package deployment](/docs/getting-started/deployment/package/) guides -for alternative install methods. +Yes! TBD docs Otherwise you can build Tetragon from source by running `make` to generate standalone binaries. diff --git a/docs/content/en/docs/getting-started/deployment/_index.md b/docs/content/en/docs/getting-started/deployment/_index.md deleted file mode 100644 index 6496b748711..00000000000 --- a/docs/content/en/docs/getting-started/deployment/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Deployment" -weight: 4 -icon: "observability" -description: "Learn different ways to deploy and manage Tetragon" ---- diff --git a/docs/content/en/docs/getting-started/enforcement.md b/docs/content/en/docs/getting-started/enforcement.md new file mode 100644 index 00000000000..bfc23664888 --- /dev/null +++ b/docs/content/en/docs/getting-started/enforcement.md @@ -0,0 +1,201 @@ +--- +title: "Policy Enforcement" +weight: 6 +description: "Policy Enforcement" +--- + +This adds a network and file policy enforcement on top of execution, file tracing +and networking policy already deployed in the quick start. In this use case we use +a namespace filter to limit the scope of the enforcement policy to just the `darkstar` +cluster we installed the demo application in from the +[Quick Kubernetes Install]({{< ref "docs/getting-started/install-k8s" >}}). + +This highlights two important concepts of Tetragon. First in kernel filtering +provides a key performance improvement by limiting events from kernel to user +space. But, also allows for enforcing policies in the kernel. By issueing a +`SIGKILL` to the process at this point the application will be stopped from +continuing to run. If the operation is triggered through a syscall this means +the application will not return from the syscall and will be terminated. + +Second, by including kubernetes filters, such as namespace and labels we can +segment a policy to apply to targeted namespaces and pods. This is critical +for effective policy segmentation. + +For implementation details see the [Enforcement]({{< ref "/docs/concepts/enforcement" >}}) +concept section. + +## Kubernetes Enforcement + +The following section is layed out with the following: +- A guide to promote the network observation policy that observer all network + traffic egressing the cluster to enforce this policy. +- A guide to promote the file access monitoring policy to block write and read + operations to sensitive files. + +### Block TCP Connect outside Cluster + +First we will deploy the [Network Monitoring]({{< ref "docs/getting-started/network" >}}) +policy with enforcement on. For this case the policy is written to only apply +against the `empire` namespace. This limits the scope of the policy for the +getting started guide. + +Ensure we have the proper Pod CIDRs + +```shell-session +export PODCIDR=`kubectl get nodes -o jsonpath='{.items[*].spec.podCIDR}'` +``` + + and Service CIDRs configured. + +{{< tabpane lang=shell-session >}} +{{< tab GKE >}} +export SERVICECIDR=$(gcloud container clusters describe ${NAME} --zone ${ZONE} --project ${PROJECT} | awk '/servicesIpv4CidrBlock/ { print $2; }') +{{< /tab >}} + +{{< tab Kind >}} +export SERVICECIDR=$(kubectl describe pod -n kube-system kube-apiserver-kind-control-plane | awk -F= '/--service-cluster-ip-range/ {print $2; }') +{{< /tab >}} +{{< /tabpane >}} + +Then we can apply the egress cluster enforcement policy + +```shell-session +wget http://github.com/cilium/tetragon/examples/quickstart/network_egress_cluster_enforce.yaml +envsubst < network_egress_cluster_enforce.yaml | kubectl apply -n default -f - +``` + +With the enforcement policy applied we can attach tetra to observe events again: + +```shell-session +kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing +``` + +And once again execute a curl command in the xwing: + +```shell-session +kubectl exec -ti xwing -- bash -c 'curl https://ebpf.io/applications/#tetragon' +``` + +The command returns an error code because the egress TCP connects are blocked shown here. +``` +command terminated with exit code 137 +``` + +Connect inside the cluster will work as expected, + +```shell-session +kubectl exec -ti xwing -- bash -c 'curl -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing' +``` + +The Tetra CLI will print the curl and annotate that the process that was issued +a Sigkill. The successful internal connect is filtered and will not be shown. + +``` +πŸš€ process default/xwing /bin/bash -c "curl https://ebpf.io/applications/#tetragon" +πŸš€ process default/xwing /usr/bin/curl https://ebpf.io/applications/#tetragon +πŸ”Œ connect default/xwing /usr/bin/curl tcp 10.32.0.28:45200 -> 104.198.14.52:443 +πŸ’₯ exit default/xwing /usr/bin/curl https://ebpf.io/applications/#tetragon SIGKILL +πŸš€ process default/xwing /bin/bash -c "curl -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing" +πŸš€ process default/xwing /usr/bin/curl -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing +``` + +The enforces TCP connects see [Enforce Sandbox]({{< ref "#enforce-common-security-policy" >}}) +below to further restrict possible workaround such as writing through /dev +devices and raw sockets application may attempt. + +### Enforce File Access Monitoring + +The following extends the example from [File Access Monitoring]({{< ref "docs/getting-started/file-events" >}}) +with enforcement to ensure sensitive files are not read. The policy used is the +[`file-monitoring-enforce.yaml`](https://github.com/cilium/tetragon/blob/main/examples/quickstart/file-monitoring-enforce.yaml) +it can be reviewed and extended as needed. The only difference between the +observation policy and the enforce policy is the addition of an action block +to sigkill the application and return an error on the op. + +To apply the policy: + +{{< tabpane lang=shell-session >}} + +{{< tab Kubernetes >}} +kubectl delete -f http://github.com/cilium/tetragon/examples/quickstart/file_monitoring.yaml +kubectl apply -f http://github.com/cilium/tetragon/examples/quickstart/file_monitoring_enforce.yaml +{{< /tab >}} +{{< tab Docker >}} +wget http://github.com/cilium/tetragon/examples/quickstart/file-monitoring.yaml +docker stop tetragon-container +docker run --name tetragon-container --rm --pull always \ + --pid=host --cgroupns=host --privileged \ + -v ${PWD}/file_monitoring.yaml:/etc/tetragon/tetragon.tp.d/file_monitoring_enforce.yaml \ + -v /sys/kernel/btf/vmlinux:/var/lib/tetragon/btf \ + quay.io/cilium/tetragon-ci:latest +{{< /tab >}} +{{< /tabpane >}} + +With the file applied we can attach tetra to observe events again, + +{{< tabpane lang=shell-session >}} +{{< tab Kubernetes >}} +kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing +{{< /tab >}} +{{< tab Docker >}} +docker exec tetragon-container tetra getevents -o compact +{{< /tab >}} +{{< /tabpane >}} + +Then reading a sensitive file, + +{{< tabpane lang=shell-session >}} +{{< tab Kubernetes >}} +kubectl exec -ti xwing -- bash -c 'cat /etc/shadow' +{{< /tab >}} +{{< tab Docker >}} +cat /etc/shadow +{{< /tab >}} +{{< /tabpane >}} + +The command will fail with an error code because this is one of our sensitive files, +```shell-session +kubectl exec -ti xwing -- bash -c 'cat /etc/shadow' +``` + +The output should be similar to: + +``` +command terminated with exit code 137 +``` + +This will generate a read event (Docker events will omit Kubernetes metadata), + +``` +πŸš€ process default/xwing /bin/bash -c "cat /etc/shadow" +πŸš€ process default/xwing /bin/cat /etc/shadow +πŸ“š read default/xwing /bin/cat /etc/shadow +πŸ“š read default/xwing /bin/cat /etc/shadow +πŸ“š read default/xwing /bin/cat /etc/shadow +πŸ’₯ exit default/xwing /bin/cat /etc/shadow SIGKILL +``` + +Writes and reads to files not part of the enforced file policy will not be +impacted. + +``` +πŸš€ process default/xwing /bin/bash -c "echo foo >> bar; cat bar" +πŸš€ process default/xwing /bin/cat bar +πŸ’₯ exit default/xwing /bin/cat bar 0 +πŸ’₯ exit default/xwing /bin/bash -c "echo foo >> bar; cat bar" 0 +``` + +## What's next + +The completes the quick start guides. At this point we should be able to +observe execution traces in a Kubernetes cluster and extend the base deployment +of Tetragon with policies to observe and enforce different aspects of a +Kubernetes system. + +The rest of the docs provide further documentation about installation and +using policies. Some useful links: + +To explore details of writing and implementing policies the [Concepts]({{< ref "/docs/concepts" >}}) is a good jumping off point. +For installation into production environments we recommend reviewing [Advanced Installations]({{< ref "docs/installation" >}}). +For a more in depth discussion on Tetragon overhead and how we measure system load try [Benchmarks]({{< ref "docs/benchmarks" >}}). +Finally [Use Cases]({{< ref "docs/use-cases" >}}) and [Tutorials]({{< ref "docs/tutorials" >}}) cover different uses and deployment concerns related to Tetragon. diff --git a/docs/content/en/docs/getting-started/execution.md b/docs/content/en/docs/getting-started/execution.md new file mode 100644 index 00000000000..6cbae6c4e1b --- /dev/null +++ b/docs/content/en/docs/getting-started/execution.md @@ -0,0 +1,155 @@ +--- +title: "Execution Monitoring" +weight: 3 +description: "Execution traces with Tetragon" +--- + +At the core of Tetragon is the tracking of all executions in a kubernetes cluster, +virtual machines, and baremetal systems. This creates the foundation that allows +Tetragon to attribute all system behavior back to a specific binary and its +associated metadata (container, Pod, Node, and cluster). + +## Observe Tetragon Execution Events + +Tetragon exposes the execution trace over JSON logs and GRPC stream. The user +can then observe all executions in the system. + +The following command can be used to observe exec events. + +{{< tabpane lang=shell-session >}} +{{< tab Kubernetes >}} +kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing +{{< /tab >}} +{{< tab Docker >}} +docker exec tetragon-container tetra getevents -o compact +{{< /tab >}} +{{< /tabpane >}} + +This will print a compact form of the exec logs. For an example we do the following +with the demo application. + + +{{< tabpane lang=shell-session >}} +{{< tab Kubernetes >}} +kubectl exec -ti xwing -- bash -c 'curl https://ebpf.io/applications/#tetragon' +{{< /tab >}} +{{< tab Docker >}} +curl https://ebpf.io/applications/#tetragon +{{< /tab >}} +{{< /tabpane >}} + +The CLI will print a compact form of the event to the terminal similar to the +following output. + +``` +πŸš€ process default/xwing /bin/bash -c "curl https://ebpf.io/applications/#tetragon" +πŸš€ process default/xwing /usr/bin/curl https://ebpf.io/applications/#tetragon +πŸ’₯ exit default/xwing /usr/bin/curl https://ebpf.io/applications/#tetragon 60 +``` + +The compact exec event contains the event type, the pod name, the binary and the args. The exit event will include the return code, in the case of curl `60` above. + +For the complete exec event in JSON format remove the compact option. + +{{< tabpane lang=shel-session >}} +{{< tab Kubernetes >}} +kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents +{{< /tab >}} +{{< tab Docker >}} +docker exec tetragon-container tetra getevents +{{< /tab >}} +{{< /tabpane >}} + +This will include a lot more details related the binary and event. A full example of the above curl is hown here, +In a Kubernetes environment this will include the Kubernetes metadata include the Pod, Container, Namespaces, and +Labels among other useful metadata. + +
Process execution event +

+ +```json +{ + "process_exec": { + "process": { + "exec_id": "Z2tlLWpvaG4tNjMyLWRlZmF1bHQtcG9vbC03MDQxY2FjMC05czk1OjEzNTQ4Njc0MzIxMzczOjUyNjk5", + "pid": 52699, + "uid": 0, + "cwd": "/", + "binary": "/usr/bin/curl", + "arguments": "https://ebpf.io/applications/#tetragon", + "flags": "execve rootcwd", + "start_time": "2023-10-06T22:03:57.700327580Z", + "auid": 4294967295, + "pod": { + "namespace": "default", + "name": "xwing", + "container": { + "id": "containerd://551e161c47d8ff0eb665438a7bcd5b4e3ef5a297282b40a92b7c77d6bd168eb3", + "name": "spaceship", + "image": { + "id": "docker.io/tgraf/netperf@sha256:8e86f744bfea165fd4ce68caa05abc96500f40130b857773186401926af7e9e6", + "name": "docker.io/tgraf/netperf:latest" + }, + "start_time": "2023-10-06T21:52:41Z", + "pid": 49 + }, + "pod_labels": { + "app.kubernetes.io/name": "xwing", + "class": "xwing", + "org": "alliance" + }, + "workload": "xwing" + }, + "docker": "551e161c47d8ff0eb665438a7bcd5b4", + "parent_exec_id": "Z2tlLWpvaG4tNjMyLWRlZmF1bHQtcG9vbC03MDQxY2FjMC05czk1OjEzNTQ4NjcwODgzMjk5OjUyNjk5", + "tid": 52699 + }, + "parent": { + "exec_id": "Z2tlLWpvaG4tNjMyLWRlZmF1bHQtcG9vbC03MDQxY2FjMC05czk1OjEzNTQ4NjcwODgzMjk5OjUyNjk5", + "pid": 52699, + "uid": 0, + "cwd": "/", + "binary": "/bin/bash", + "arguments": "-c \"curl https://ebpf.io/applications/#tetragon\"", + "flags": "execve rootcwd clone", + "start_time": "2023-10-06T22:03:57.696889812Z", + "auid": 4294967295, + "pod": { + "namespace": "default", + "name": "xwing", + "container": { + "id": "containerd://551e161c47d8ff0eb665438a7bcd5b4e3ef5a297282b40a92b7c77d6bd168eb3", + "name": "spaceship", + "image": { + "id": "docker.io/tgraf/netperf@sha256:8e86f744bfea165fd4ce68caa05abc96500f40130b857773186401926af7e9e6", + "name": "docker.io/tgraf/netperf:latest" + }, + "start_time": "2023-10-06T21:52:41Z", + "pid": 49 + }, + "pod_labels": { + "app.kubernetes.io/name": "xwing", + "class": "xwing", + "org": "alliance" + }, + "workload": "xwing" + }, + "docker": "551e161c47d8ff0eb665438a7bcd5b4", + "parent_exec_id": "Z2tlLWpvaG4tNjMyLWRlZmF1bHQtcG9vbC03MDQxY2FjMC05czk1OjEzNTQ4NjQ1MjQ1ODM5OjUyNjg5", + "tid": 52699 + } + }, + "node_name": "gke-john-632-default-pool-7041cac0-9s95", + "time": "2023-10-06T22:03:57.700326678Z" +} + +``` +

+
+ +## What's next + +Execution events are the most basic event Tetragon can produce. To see how to +use tracing policies to enable file monitoring see the +[File Access Monitoring]({{< ref "/docs/getting-started/file-events" >}}) quickstart. +To see a network policy check the [Networking Monitoring]({{< ref "/docs/getting-started/network" >}}) quickstart. diff --git a/docs/content/en/docs/getting-started/file-events.md b/docs/content/en/docs/getting-started/file-events.md new file mode 100644 index 00000000000..2441f1a38df --- /dev/null +++ b/docs/content/en/docs/getting-started/file-events.md @@ -0,0 +1,83 @@ +--- +title: "File Access Monitoring" +weight: 4 +description: "File access traces with Tetragon" +--- + +Tracing Policies can be added to Tetragon through YAML configuration files +that extend Tetragon's base execution tracing capabilities. These policies +do filtering in kernel to ensure only interesting events are published +to userspace from the BPF programs running in kernel. This ensures overhead +remains low even on busy systems. + +The following extends the example from Execution Tracing with a policy to +monitor sensitive files in Linux. The policy used is the +[`file-monitoring.yaml`](https://github.com/cilium/tetragon/blob/main/examples/quickstart/file-monitoring.yaml) +it can be reviewed and extended as needed. Files monitored here serve as a good +base set of files. + +To apply the policy Kubernetes uses a CRD that can be applied with kubectl. +Uses the same YAML configuration as Kuberenetes, but loaded through a file +on disk. + +{{< tabpane lang=shell-session >}} + +{{< tab Kubernetes >}} +kubectl apply -f http://github.com/cilium/tetragon/examples/quickstart/file-monitoring.yaml +{{< /tab >}} +{{< tab Docker >}} +wget http://github.com/cilium/tetragon/examples/quickstart/file-monitoring.yaml +docker stop tetragon-container +docker run --name tetragon-container --rm --pull always \ + --pid=host --cgroupns=host --privileged \ + -v ${PWD}/file_monitoring.yaml:/etc/tetragon/tetragon.tp.d/file_monitoring.yaml \ + -v /sys/kernel/btf/vmlinux:/var/lib/tetragon/btf \ + quay.io/cilium/tetragon-ci:latest +{{< /tab >}} +{{< /tabpane >}} + +With the file applied we can attach tetra to observe events again: + +{{< tabpane lang=shell-session >}} +{{< tab Kubernetes >}} +kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing +{{< /tab >}} +{{< tab Docker >}} +docker exec tetragon-container tetra getevents -o compact +{{< /tab >}} +{{< /tabpane >}} + +Then reading a sensitive file: + +{{< tabpane lang=shell-session >}} +{{< tab Kubernetes >}} +kubectl exec -ti xwing -- bash -c 'cat /etc/shadow' +{{< /tab >}} +{{< tab Docker >}} +cat /etc/shadow +{{< /tab >}} +{{< /tabpane >}} + +This will generate a read event (Docker events will omit Kubernetes metadata), + +``` +πŸš€ process default/xwing /bin/bash -c "cat /etc/shadow" +πŸš€ process default/xwing /bin/cat /etc/shadow +πŸ“š read default/xwing /bin/cat /etc/shadow +πŸ’₯ exit default/xwing /bin/cat /etc/shadow 0 +``` + +Attempts to write in sensitive directories will similar create an event. For +example attempting to write in `/etc`. + +``` +πŸš€ process default/xwing /bin/bash -c "echo foo >> /etc/bar" +πŸ“ write default/xwing /bin/bash /etc/bar +πŸ“ write default/xwing /bin/bash /etc/bar +πŸ’₯ exit default/xwing /bin/bash -c "echo foo >> /etc/bar +``` + +# What's next + +To explore tracing policies for networking try the [Networking Monitoring]({{< ref "/docs/getting-started/network" >}}) quickstart. +To dive into the details of policies and events please see [Concepts]({{< ref "docs/concepts" >}}) section. diff --git a/docs/content/en/docs/getting-started/install-docker.md b/docs/content/en/docs/getting-started/install-docker.md new file mode 100644 index 00000000000..96b5857229a --- /dev/null +++ b/docs/content/en/docs/getting-started/install-docker.md @@ -0,0 +1,36 @@ +--- +title: "Quick Local Docker Install" +weight: 2 +description: "Discover and experiment with Tetragon on your local Linux host" +--- + +{{< note >}} +This guide has been tested on Ubuntu 22.04 and 22.10 with respectively kernel +`5.15.0` and `5.19.0` on amd64 and arm64 but +[any recent distribution](https://github.com/libbpf/libbpf#bpf-co-re-compile-once--run-everywhere) +shipping with a relatively recent kernel should work. See the FAQ for further details on +the [recommended kernel versions]({{< ref "/docs/faq#what-is-the-minimum-linux-kernel-version-to-run-tetragon" >}}). + +Note that you cannot run Tetragon using Docker Desktop on macOS because of a +limitation of the Docker Desktop Linux virtual machine. Learn more about this issue +and how to run Tetragon on a Mac computer in [this section of the FAQ page](/docs/faq/#can-i-run-tetragon-on-mac-computers). +{{< /note >}} + +## Start Tetragon + +The easiest way to start experimenting with Tetragon is to run it via Docker +using the released container images. + +```shell-session +docker run --name tetragon-container --rm --pull always \ + --pid=host --cgroupns=host --privileged \ + -v /sys/kernel/btf/vmlinux:/var/lib/tetragon/btf \ + quay.io/cilium/tetragon-ci:latest +``` + +This will start Tetragon in a privileged container. Priviliges are required +to load and attach BPF programs. See Installation section for more details. + +## What's Next + +Check for [execution events]({{< ref "/docs/getting-started/execution" >}}). diff --git a/docs/content/en/docs/getting-started/install-k8s.md b/docs/content/en/docs/getting-started/install-k8s.md new file mode 100644 index 00000000000..ff253e11e21 --- /dev/null +++ b/docs/content/en/docs/getting-started/install-k8s.md @@ -0,0 +1,83 @@ +--- +title: "Quick Kubernetes Install" +weight: 1 +description: "Discover and experiment with Tetragon in a kubernetes environment" +--- + +### Create a cluster + +If you don’t have a Kubernetes Cluster yet, you can use the instructions below +to create a Kubernetes cluster locally or using a managed Kubernetes service: + +{{< tabpane text=true >}} +{{% tab GKE %}} + +The following commands create a Kubernetes cluster using [Google +Kubernetes Engine](https://cloud.google.com/kubernetes-engine). See +[Installing Google Cloud SDK](https://cloud.google.com/sdk/install) for +instructions on how to install `gcloud` and prepare your account. + +```shell-session +export NAME="$(whoami)-$RANDOM" +gcloud container clusters create "${NAME}" --zone us-west2-a +gcloud container clusters get-credentials "${NAME}" --zone us-west2-a +``` +{{% /tab %}} + +{{% tab Kind %}} +Run the following command to create the Kubernetes cluster: + +```shell-session +kind create cluster +``` +{{% /tab %}} + +{{< /tabpane >}} + +### Deploy Tetragon + +To install and deploy Tetragon, run the following commands: + +```shell-session +helm repo add cilium https://helm.cilium.io +helm repo update +helm install tetragon cilium/tetragon -n kube-system +kubectl rollout status -n kube-system ds/tetragon -w +``` + +By default, Tetragon will filter kube-system events to reduce noise in the +event logs. See concepts and advanced configuration to configure these +parameters. + +### Deploy demo application + +To explore Tetragon its helpful to have a sample workload. Here wu use the Cilium +HTTP application, but any workload would work equally well. + +To use our [demo +application](https://docs.cilium.io/en/v1.11/gettingstarted/http/#deploy-the-demo-application) + +```shell-session +kubectl create -f https://raw.githubusercontent.com/cilium/cilium/v1.11/examples/minikube/http-sw-app.yaml +``` + +Before going forward, verify that all pods are up and running - it might take +several seconds for some pods until they satisfy all the dependencies: + +```shell-session +kubectl get pods +``` + +The output should be similar to this: + +``` +NAME READY STATUS RESTARTS AGE +deathstar-6c94dcc57b-7pr8c 1/1 Running 0 10s +deathstar-6c94dcc57b-px2vw 1/1 Running 0 10s +tiefighter 1/1 Running 0 10s +xwing 1/1 Running 0 10s +``` + +## What's Next + +Check for [execution events]({{< ref "/docs/getting-started/execution" >}}). diff --git a/docs/content/en/docs/getting-started/kubernetes-quickstart-guide.md b/docs/content/en/docs/getting-started/kubernetes-quickstart-guide.md deleted file mode 100644 index 4614f3c60b0..00000000000 --- a/docs/content/en/docs/getting-started/kubernetes-quickstart-guide.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "Kubernetes quickstart guide" -weight: 2 -icon: "overview" -description: "Deploy Tetragon on a Kubernetes cluster" ---- - -This quickstart guide uses a Kind cluster and a helm-based installation to -provide a simple way to get a hands on experience with Tetragon and -the generated events. These events include monitoring process execution, -network sockets, and file access to see what binaries are executing and making -network connections or writing to sensitive files. - -In this scenario, we are going to install a demo application, - -* observe all process execution happening inside a Kubernetes workload -* detect file access and writes -* observe network connections that a Kubernetes workload is making -* detect privileged processes inside a Kubernetes workload - -While, we use a Kubernetes Kind cluster in this guide, users can also apply -the same concepts in other Kubernetes platforms, bare-metal, or VM environments. - -### Requirements - -The base kernel should support [BTF](#btf-requirement) or the BTF file should -be placed where Tetragon can read it. - -For reference, the examples below use this [Vagrantfile](#btf-requirement) and we -created our [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) cluster using -the defaults options. - -### Create a cluster - -Create a Kubernetes cluster using Kind or GKE. - -#### Kind - -Run the following command to create the Kubernetes cluster: -``` -kind create cluster -``` - -#### GKE - -Run the following command to create a GKE cluster: - -```shell -export NAME="$(whoami)-$RANDOM" -gcloud container clusters create "${NAME}" \ - --zone us-west2-a \ - --num-nodes 1 -``` - -### Deploy Tetragon - -To install and deploy Tetragon, run the following commands: - -```shell -helm repo add cilium https://helm.cilium.io -helm repo update -helm install tetragon cilium/tetragon -n kube-system -kubectl rollout status -n kube-system ds/tetragon -w -``` - -By default, kube-system pods are filtered. For the examples below, we use the demo -deployment from [Cilium](https://docs.cilium.io/en/v1.11/gettingstarted/http/#gs-http) -to generate events. - -### Deploy the demo application - -Once Tetragon is installed, you can use our [demo -application](https://docs.cilium.io/en/v1.11/gettingstarted/http/#deploy-the-demo-application) -to explore the Security Observability Events: - -```shell -kubectl create -f https://raw.githubusercontent.com/cilium/cilium/v1.11/examples/minikube/http-sw-app.yaml -``` - -Before going forward, verify that all pods are up and running - it might take -several seconds for some pods until they satisfy all the dependencies: - -```shell -kubectl get pods -``` - -The output should be similar to: -``` -NAME READY STATUS RESTARTS AGE -deathstar-6c94dcc57b-7pr8c 1/1 Running 0 10s -deathstar-6c94dcc57b-px2vw 1/1 Running 0 10s -tiefighter 1/1 Running 0 10s -xwing 1/1 Running 0 10s -``` - -### What's next - -- Learn how to checks this events in the next section [Explore security -observability events](/docs/getting-started/explore-security-observability-events). diff --git a/docs/content/en/docs/getting-started/network.md b/docs/content/en/docs/getting-started/network.md new file mode 100644 index 00000000000..1c3170f2c30 --- /dev/null +++ b/docs/content/en/docs/getting-started/network.md @@ -0,0 +1,145 @@ +--- +title: "Network Monitoring" +weight: 5 +description: "Network access traces with Tetragon" +--- + +This adds a network policy on top of execution and file tracing already +deployed in the quick start. In this case we monitor all network traffic +outside the Kubernetes pod CIDR and service CIDR. + +## Kubernetes Cluster Network Access Monitoring + +First we must find the pod CIDR and service CIDR in use. The pod +IP CIDR can be found relatively easily in many cases. + +```shell-session +export PODCIDR=`kubectl get nodes -o jsonpath='{.items[*].spec.podCIDR}'` +``` + +The services CIDR can then be fetched depending on environment. We +require environment variables ZONE, PROJECT, and NAME from install steps. + +{{< tabpane lang=shell-session >}} + +{{< tab GKE >}} +export SERVICECIDR=$(gcloud container clusters describe ${NAME} --zone ${ZONE} --project ${PROJECT} | awk '/servicesIpv4CidrBlock/ { print $2; }') +{{< /tab >}} + +{{< tab Kind >}} +export SERVICECIDR=$(kubectl describe pod -n kube-system kube-apiserver-kind-control-plane | awk -F= '/--service-cluster-ip-range/ {print $2; }') +{{< /tab >}} + +{{< /tabpane >}} + +First we apply a policy that includes the `podCIDR` and `serviceIP` list as +filters to avoid filter out cluster local traffic. To apply the policy: + +```shell-session +wget http://github.com/cilium/tetragon/examples/quickstart/network_egress_cluster.yaml +envsubst < network_egress_cluster.yaml | kubectl apply -f - +``` + +With the file applied we can attach tetra to observe events again: + +```shell-session + kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing --processes curl +``` + +Then execute a curl command in the xwing pod to curl one of our favorite +sites. + +```shell-session + kubectl exec -ti xwing -- bash -c 'curl https://ebpf.io/applications/#tetragon' +``` + +A connect will be observed in the tetra shell: + +``` +πŸš€ process default/xwing /usr/bin/curl https://ebpf.io/applications/#tetragon +πŸ”Œ connect default/xwing /usr/bin/curl tcp 10.32.0.19:33978 -> 104.198.14.52:443 +πŸ’₯ exit default/xwing /usr/bin/curl https://ebpf.io/applications/#tetragon 60 +``` + +We can confirm in-kernel BPF filters are not producing events for in cluster +traffic by issuing a curl to one of our services and noting there is no connect +event. + +```shell-session +kubectl exec -ti xwing -- bash -c 'curl -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing' +``` + +The output should be similar to: + +``` +Ship landed +``` + +And as expected no new events: + +``` +πŸš€ process default/xwing /usr/bin/curl https://ebpf.io/applications/#tetragon +πŸ”Œ connect default/xwing /usr/bin/curl tcp 10.32.0.19:33978 -> 104.198.14.52:443 +πŸ’₯ exit default/xwing /usr/bin/curl https://ebpf.io/applications/#tetragon 60 +``` + +## Docker/Baremetal Network Access Monitoring + +This example also works easily for local docker users as well except it is not as +obvious to the quickstart authors what IP address CIDR will be useful. The policy +by default will filter all local IPs `127.0.0.1` from the event log. So we can +demo that here. + +Set env variables to local loopback IP. +```shell-session +export PODCIDR="127.0.0.1/32" +export SERVICECIDR="127.0.0.1/32" +``` + +To create the policy, +```shell-session +wget http://github.com/cilium/tetragon/examples/quickstart/network_egress_cluster.yaml +envsubst < network_egress_cluster.yaml > network_egress_cluster_subst.yaml +``` + +Start Tetragon with the new policy: +```shell-session +docker stop tetragon-container +docker run --name tetragon-container --rm --pull always \ + --pid=host --cgroupns=host --privileged \ + -v ${PWD}/network_egress_cluster_subst.yaml:/etc/tetragon/tetragon.tp.d/network_egress_cluster_subst.yaml \ + -v /sys/kernel/btf/vmlinux:/var/lib/tetragon/btf \ + quay.io/cilium/tetragon-ci:latest +``` + +Attach to the tetragon output +```shell-session +docker exec tetragon-container tetra getevents -o compact +``` + +Now remote TCP connections will be logged and local IPs filters. Executing a curl +to generate a remote TCP connect. +```shell-session +curl https://ebpf.io/applications/#tetragon +``` + +Produces the following output: +``` +πŸš€ process /usr/bin/curl https://ebpf.io/applications/#tetragon +πŸ”Œ connect /usr/bin/curl tcp 192.168.1.190:36124 -> 104.198.14.52:443 +πŸ’₯ exit /usr/bin/curl https://ebpf.io/applications/#tetragon 0 +``` + +# Whats Next + +So far we have installed Tetragon and shown a couple policies to monitor +sensitive files and provide network auditing for connections outside our own +cluster and node. Both these cases highlight the value of in kernel filtering. +Another benefit of in-kernel filtering is we can add +[enforcement]({{< ref "/docs/getting-started/enforcement" >}}) to the policies +to not only alert, but block the operation in kernel and/or kill the +application attempting the operation. + +To learn more about policies and events Tetragon can implement review the +[Concepts]({{< ref "/docs/concepts" >}}) section. + diff --git a/docs/content/en/docs/installation/_index.md b/docs/content/en/docs/installation/_index.md new file mode 100644 index 00000000000..954d1f0a2b2 --- /dev/null +++ b/docs/content/en/docs/installation/_index.md @@ -0,0 +1,5 @@ +--- +title: "Installation" +weight: 2 +description: "Tetragon installation and deployment configuration options" +--- diff --git a/docs/content/en/docs/getting-started/deployment/container.md b/docs/content/en/docs/installation/container.md similarity index 94% rename from docs/content/en/docs/getting-started/deployment/container.md rename to docs/content/en/docs/installation/container.md index 38c027aed58..b0a69266ed3 100644 --- a/docs/content/en/docs/getting-started/deployment/container.md +++ b/docs/content/en/docs/installation/container.md @@ -14,7 +14,7 @@ To run a stable version, please check [Tetragon quay repository](https://quay.io and select which version you want. For example if you want to run the latest version which is `{{< latest-version >}}` currently. -```shell +```shell-session docker run --name tetragon --rm -d \ --pid=host --cgroupns=host --privileged \ -v /sys/kernel/btf/vmlinux:/var/lib/tetragon/btf \ @@ -28,7 +28,7 @@ To run unstable development versions of Tetragon, use the This will run the image that was built from the latest commit available on the Tetragon main branch. -```shell +```shell-session docker run --name tetragon --rm -d \ --pid=host --cgroupns=host --privileged \ -v /sys/kernel/btf/vmlinux:/var/lib/tetragon/btf \ @@ -48,7 +48,7 @@ There are multiple ways to set configuration options: 1. Append Tetragon controlling settings at the end of the command As an example set the file where to export JSON events with `--export-filename` argument: - ```shell + ```shell-session docker run --name tetragon --rm -d \ --pid=host --cgroupns=host --privileged \ -v /sys/kernel:/sys/kernel \ @@ -61,7 +61,7 @@ There are multiple ways to set configuration options: 2. Environment variables - ```shell + ```shell-session docker run --name tetragon --rm -d \ --pid=host --cgroupns=host --privileged \ --env "TETRAGON_EXPORT_FILENAME=/var/log/tetragon/tetragon.log" \ @@ -77,7 +77,7 @@ There are multiple ways to set configuration options: On the host machine set the configuration drop-ins inside `/etc/tetragon/tetragon.conf.d/` directory according to the [configuration examples](/docs/reference/tetragon-configuration/#configuration-examples), then mount it as volume: - ```shell + ```shell-session docker run --name tetragon --rm -d \ --pid=host --cgroupns=host --privileged \ -v /sys/kernel:/sys/kernel \ @@ -89,7 +89,3 @@ There are multiple ways to set configuration options: See [Tetragon daemon configuration](/docs/reference/tetragon-configuration) reference for further details. -## What's next - -- See [Explore security observability events](/docs/getting-started/explore-security-observability-events/) -to learn how to see the Tetragon events. diff --git a/docs/content/en/docs/getting-started/deployment/kubernetes.md b/docs/content/en/docs/installation/kubernetes.md similarity index 95% rename from docs/content/en/docs/getting-started/deployment/kubernetes.md rename to docs/content/en/docs/installation/kubernetes.md index 5e93fcecf14..9269f9787fa 100644 --- a/docs/content/en/docs/getting-started/deployment/kubernetes.md +++ b/docs/content/en/docs/installation/kubernetes.md @@ -22,14 +22,14 @@ in the Tetragon repository. You can use any of the values and override them with `--set KEY1=VALUE1,KEY2=VALUE2`. {{< /note >}} -```shell +```shell-session helm repo add cilium https://helm.cilium.io helm repo update helm install tetragon cilium/tetragon -n kube-system ``` To wait until Tetragon deployment is ready, use the following `kubectl` command: -```shell +```shell-session kubectl rollout status -n kube-system ds/tetragon -w ``` @@ -48,14 +48,14 @@ for details and solutions. You can then make modifications to the Tetragon configuration using `helm upgrade`, see the following example. -```shell +```shell-session helm upgrade tetragon cilium/tetragon -n kube-system --set tetragon.grpc.address=localhost:1337 ``` You can also edit the `tetragon-config` ConfigMap directly and restart the Tetragon daemonset with: -```shell +```shell-session kubectl edit cm tetragon-config -n kube-system kubectl rollout restart ds/tetragon -n kube-system ``` @@ -64,7 +64,7 @@ kubectl rollout restart ds/tetragon -n kube-system Upgrade Tetragon using a new specific version of the helm chart. -```shell +```shell-session helm upgrade tetragon cilium/tetragon -n kube-system --version 0.9.0 ``` @@ -72,6 +72,6 @@ helm upgrade tetragon cilium/tetragon -n kube-system --version 0.9.0 Uninstall Tetragon using the following command. -```shell +```shell-session helm uninstall tetragon -n kube-system ``` diff --git a/docs/content/en/docs/getting-started/deployment/package.md b/docs/content/en/docs/installation/package.md similarity index 93% rename from docs/content/en/docs/getting-started/deployment/package.md rename to docs/content/en/docs/installation/package.md index 20bfc63f517..849a2df3a87 100644 --- a/docs/content/en/docs/getting-started/deployment/package.md +++ b/docs/content/en/docs/installation/package.md @@ -17,14 +17,14 @@ Tetragon as of version 1.0 supports amd64 and arm64 architectures. 1. First download the latest binary tarball, using `curl` for example to download the `amd64` release: - ```shell + ```shell-session curl -LO https://github.com/cilium/tetragon/releases/download/{{< latest-version >}}/tetragon-{{< latest-version >}}-amd64.tar.gz ``` 2. Extract the downloaded archive, and start the install script to install Tetragon. Feel free to inspect the script before starting it. - ```shell + ```shell-session tar -xvf tetragon-{{< latest-version >}}-amd64.tar.gz cd tetragon-{{< latest-version >}}-amd64/ sudo ./install.sh @@ -38,7 +38,7 @@ Tetragon as of version 1.0 supports amd64 and arm64 architectures. 3. Finally, you can check the Tetragon systemd service. - ```shell + ```shell-session sudo systemctl status tetragon ``` @@ -80,19 +80,19 @@ To upgrade Tetragon: 1. Download the new tarball. - ```shell + ```shell-session curl -LO https://github.com/cilium/tetragon/releases/download/{{< latest-version >}}/tetragon-{{< latest-version >}}-amd64.tar.gz ``` 2. Stop the Tetragon service. - ```shell + ```shell-session sudo systemctl stop tetragon ``` 3. Remove the old Tetragon version. - ```shell + ```shell-session sudo rm -fr /usr/lib/systemd/system/tetragon.service sudo rm -fr /usr/local/bin/tetragon sudo rm -fr /usr/local/lib/tetragon/ @@ -100,7 +100,7 @@ To upgrade Tetragon: 4. Install the upgraded Tetragon version. - ```shell + ```shell-session tar -xvf tetragon-{{< latest-version >}}-amd64.tar.gz cd tetragon-{{< latest-version >}}-amd64/ sudo ./install.sh @@ -111,7 +111,7 @@ To upgrade Tetragon: To completely remove Tetragon run the `uninstall.sh` script that is provided inside the tarball. -```shell +```shell-session sudo ./uninstall.sh ``` @@ -129,7 +129,7 @@ sudo rm -fr /usr/local/lib/tetragon/ To just purge custom settings: -```shell +```shell-session sudo rm -fr /etc/tetragon/ ``` @@ -143,7 +143,7 @@ Tetragon tarball by default listens on `unix:///var/run/tetragon/tetragon.sock` To access the gRPC API with `tetra` client, set `--server-address` to point to the corresponding address: - ``` + ```shell-session sudo tetra --server-address unix:///var/run/tetragon/tetragon.sock getevents ``` @@ -156,24 +156,24 @@ Logs are always rotated into the same directory. To read real-time JSON events, tailing the logs file is enough. - ```shell + ```shell-session sudo tail -f /var/log/tetragon/tetragon.log ``` Tetragon also ships a gRPC client that can be used to receive events. 1. To print events in `json` format using `tetra` gRPC client: - ```shell + ```shell-session sudo tetra --server-address "unix:///var/run/tetragon/tetragon.sock" getevents ``` 2. To print events in human compact format: - ```shell + ```shell-session sudo tetra --server-address "unix:///var/run/tetragon/tetragon.sock" getevents -o compact ``` ## What's next -See [Explore security observability events](/docs/getting-started/explore-security-observability-events/) +See [Explore security observability events](/docs/concepts/tetragon-events/) to learn more about how to see the Tetragon events. diff --git a/docs/content/en/docs/getting-started/install-tetra-cli.md b/docs/content/en/docs/installation/tetra-cli.md similarity index 98% rename from docs/content/en/docs/getting-started/install-tetra-cli.md rename to docs/content/en/docs/installation/tetra-cli.md index a74ea9e5f2c..3f0cf9d4ffa 100644 --- a/docs/content/en/docs/getting-started/install-tetra-cli.md +++ b/docs/content/en/docs/installation/tetra-cli.md @@ -1,6 +1,6 @@ --- title: "Install tetra CLI" -weight: 5 +weight: 4 description: "To interact with Tetragon, install the Tetragon client CLI tetra" --- @@ -22,7 +22,7 @@ Linux distribution but you can usually find them respectively under the package `curl` and `coreutils`. {{< /note >}} -```shell +```shell-session GOOS=$(go env GOOS) GOARCH=$(go env GOARCH) curl -L --remote-name-all https://github.com/cilium/tetragon/releases/latest/download/tetra-${GOOS}-${GOARCH}.tar.gz{,.sha256sum} @@ -89,7 +89,7 @@ tar -xz tetra-windows-arm64.tar.gz fetch precompiled binaries. You can also use it to build from sources (using the `--build-from-source` flag) with a Go dependency. -```shell +```shell-session brew install tetra ``` @@ -101,7 +101,7 @@ at the following URL: https://github.com/cilium/tetragon/releases. To download a specific release you can use the following script, replacing the `OS`, `ARCH` and `TAG` values with your desired options. -```shell +```shell-session OS=linux ARCH=amd64 TAG=v0.9.0 diff --git a/docs/content/en/docs/reference/_index.md b/docs/content/en/docs/reference/_index.md index bd9221eccd1..cb13f212ae3 100644 --- a/docs/content/en/docs/reference/_index.md +++ b/docs/content/en/docs/reference/_index.md @@ -1,7 +1,7 @@ --- title: "Reference" linkTitle: "Reference" -weight: 6 +weight: 7 icon: "reference" description: > Low level reference documentation for Tetragon diff --git a/docs/content/en/docs/tutorials/software-bill-of-materials.md b/docs/content/en/docs/tutorials/software-bill-of-materials.md index b10e08547d2..fdc947870e4 100644 --- a/docs/content/en/docs/tutorials/software-bill-of-materials.md +++ b/docs/content/en/docs/tutorials/software-bill-of-materials.md @@ -1,6 +1,6 @@ --- title: "Software bill of materials" -weight: 2 +weight: 4 icon: "reference" description: "Download and verify the signature of the software bill of materials" --- diff --git a/docs/content/en/docs/getting-started/try-tetragon-linux.md b/docs/content/en/docs/tutorials/try-tetragon-linux.md similarity index 96% rename from docs/content/en/docs/getting-started/try-tetragon-linux.md rename to docs/content/en/docs/tutorials/try-tetragon-linux.md index fc8603ec779..21debbaf1a8 100644 --- a/docs/content/en/docs/getting-started/try-tetragon-linux.md +++ b/docs/content/en/docs/tutorials/try-tetragon-linux.md @@ -1,13 +1,13 @@ --- title: "Try Tetragon on Linux" -weight: 1 +weight: 2 description: "Discover and experiment with Tetragon on your local Linux host" --- {{< caution >}} This guide is not a tutorial on how to deploy Tetragon standalone (i.e. without -Kubernetes), you can see the [container deployment]({{< ref "/docs/getting-started/deployment/container" >}}) -and [package deployment]({{< ref "/docs/getting-started/deployment/package" >}}) guides for +Kubernetes), you can see the [container deployment]({{< ref "/docs/installation/container" >}}) +and [package deployment]({{< ref "/docs/installation/package" >}}) guides for that. This is just a walkthrough to try and experiment Tetragon for the first time. {{< /caution >}} @@ -392,8 +392,3 @@ Again, the specific filtering is only given as an example, just reading the file using `cat ./tracing_policy.yaml` will bypass the policies presented here. {{< /caution >}} -## What's next - -- Try Tetragon in [Kubernetes environments]({{< ref "docs/getting-started/kubernetes-quickstart-guide" >}}). -- Learn more about [TracingPolicy]({{< ref "/docs/concepts/tracing-policy" >}}). -- See more use cases for observability in the [Use cases section]({{< ref "docs/use-cases" >}}). diff --git a/docs/content/en/docs/tutorials/verify-tetragon-image-signatures.md b/docs/content/en/docs/tutorials/verify-tetragon-image-signatures.md index 9ce3b7c671c..89672f97ac1 100644 --- a/docs/content/en/docs/tutorials/verify-tetragon-image-signatures.md +++ b/docs/content/en/docs/tutorials/verify-tetragon-image-signatures.md @@ -1,6 +1,6 @@ --- title: "Verify Tetragon image signatures" -weight: 1 +weight: 3 icon: "overview" description: "Learn how to verify Tetragon container images signatures." --- diff --git a/examples/quickstart/file_monitoring.yaml b/examples/quickstart/file_monitoring.yaml new file mode 100644 index 00000000000..f7e749a07a6 --- /dev/null +++ b/examples/quickstart/file_monitoring.yaml @@ -0,0 +1,176 @@ +apiVersion: cilium.io/v1alpha1 +kind: TracingPolicy +metadata: + name: "file-monitoring-filtered" +spec: + kprobes: + - call: "security_file_permission" + syscall: false + return: true + args: + - index: 0 + type: "file" # (struct file *) used for getting the path + - index: 1 + type: "int" # 0x04 is MAY_READ, 0x02 is MAY_WRITE + returnArg: + index: 0 + type: "int" + returnArgAction: "Post" + selectors: + - matchArgs: + - index: 0 + operator: "Prefix" + values: + - "/boot" # Reads to sensitive directories + - "/root/.ssh" # Reads to sensitive files we want to know about + - "/etc/shadow" + - "/etc/profile" + - "/etc/sudoers" + - "/etc/pam.conf" # Reads global shell configs bash/csh supported + - "/etc/bashrc" + - "/etc/csh.cshrc" + - "/etc/csh.login" # Add additional sensitive files here + - index: 1 + operator: "Equal" + values: + - "4" # MAY_READ + - matchArgs: + - index: 0 + operator: "Postfix" + values: + - ".bashrc" # Reads to shell config files bash, csh supported + - ".bash_profile" # add any other shell support here. + - ".bash_login" + - ".bash_logout" + - ".cshrc" + - ".cshdirs" + - ".profile" # Reads to common environments files + - ".login" + - ".logout" + - ".history" # Add additional sensitive files here + - index: 1 + operator: "Equal" + values: + - "4" # MAY_READ + - matchArgs: + - index: 0 + operator: "Prefix" + values: + - "/etc" # Writes to sensitive directories + - "/boot" + - "/lib" + - "/lib64" + - "/bin" + - "/usr/lib" + - "/usr/local/lib" + - "/usr/local/sbin" + - "/usr/local/bin" + - "/usr/bin" + - "/usr/sbin" + - "/var/log" # Writes to logs + - "/dev/log" + - "/root/.ssh" # Writes to sensitive files add here. + - index: 1 + operator: "Equal" + values: + - "2" # MAY_WRITE + - call: "security_mmap_file" + syscall: false + return: true + args: + - index: 0 + type: "file" # (struct file *) used for getting the path + - index: 1 + type: "uint32" # the prot flags PROT_READ(0x01), PROT_WRITE(0x02), PROT_EXEC(0x04) + - index: 2 + type: "uint32" # the mmap flags (i.e. MAP_SHARED, ...) + returnArg: + index: 0 + type: "int" + returnArgAction: "Post" + selectors: + - matchArgs: + - index: 0 + operator: "Prefix" + values: + - "/boot" # Reads to sensitive directories + - "/root/.ssh" # Reads to sensitive files we want to know about + - "/etc/shadow" + - "/etc/sudoers" + - "/etc/pam.conf" # Reads global shell configs bash/csh supported + - "/etc/profile" + - "/etc/bashrc" + - "/etc/csh.cshrc" + - "/etc/csh.login" + - ".bashrc" # Reads to shell config files bash, csh supported + - ".bash_profile" # add any other shell support here. + - ".bash_login" + - ".bash_logout" + - ".cshrc" + - ".cshdirs" + - ".profile" # Reads to common environments files + - ".login" + - ".logout" + - ".history" # Add additional sensitive mmap files here + - index: 1 + operator: "Equal" + values: + - "1" # MAY_READ + - index: 2 + operator: "Mask" + values: + - "1" # MAP_SHARED + - matchArgs: + - index: 0 + operator: "Prefix" + values: + - "/etc" # Writes to sensitive directories + - "/boot" + - "/lib" + - "/lib64" + - "/bin" + - "/usr/lib" + - "/usr/local/lib" + - "/usr/local/sbin" + - "/usr/local/bin" + - "/usr/bin" + - "/usr/sbin" + - "/var/log" # Writes to logs + - "/dev/log" + - "/root/.ssh" # Writes to sensitive files add here. + - index: 1 + operator: "Mask" + values: + - "2" # PROT_WRITE + - index: 2 + operator: "Mask" + values: + - "1" # MAP_SHARED + - call: "security_path_truncate" + syscall: false + return: true + args: + - index: 0 + type: "path" # (struct path *) used for getting the path + returnArg: + index: 0 + type: "int" + returnArgAction: "Post" + selectors: + - matchArgs: + - index: 0 + operator: "Prefix" + values: + - "/etc" # Truncate to sensitive directories + - "/boot" + - "/lib" + - "/lib64" + - "/usr/lib" + - "/usr/local/lib" + - "/usr/local/sbin" + - "/usr/local/bin" + - "/usr/bin" + - "/usr/sbin" + - "/var/log" # Truncate to logs + - "/dev/log" + - "/root/.ssh" # Truncate to sensitive files add here. diff --git a/examples/quickstart/file_monitoring_enforce.yaml b/examples/quickstart/file_monitoring_enforce.yaml new file mode 100644 index 00000000000..03d53c5885d --- /dev/null +++ b/examples/quickstart/file_monitoring_enforce.yaml @@ -0,0 +1,188 @@ +apiVersion: cilium.io/v1alpha1 +kind: TracingPolicyNamespaced +metadata: + name: "file-monitoring-filtered" +spec: + kprobes: + - call: "security_file_permission" + syscall: false + return: true + args: + - index: 0 + type: "file" # (struct file *) used for getting the path + - index: 1 + type: "int" # 0x04 is MAY_READ, 0x02 is MAY_WRITE + returnArg: + index: 0 + type: "int" + returnArgAction: "Post" + selectors: + - matchArgs: + - index: 0 + operator: "Prefix" + values: + - "/boot" # Reads to sensitive directories + - "/root/.ssh" # Reads to sensitive files we want to know about + - "/etc/shadow" + - "/etc/profile" + - "/etc/sudoers" + - "/etc/pam.conf" # Reads global shell configs bash/csh supported + - "/etc/bashrc" + - "/etc/csh.cshrc" + - "/etc/csh.login" # Add additional sensitive files here + - index: 1 + operator: "Equal" + values: + - "4" # MAY_READ + matchActions: + - action: Sigkill + - matchArgs: + - index: 0 + operator: "Postfix" + values: + - ".bashrc" # Reads to shell config files bash, csh supported + - ".bash_profile" # add any other shell support here. + - ".bash_login" + - ".bash_logout" + - ".cshrc" + - ".cshdirs" + - ".profile" # Reads to common environments files + - ".login" + - ".logout" + - ".history" # Add additional sensitive files here + - index: 1 + operator: "Equal" + values: + - "4" # MAY_READ + matchActions: + - action: Sigkill + - matchArgs: + - index: 0 + operator: "Prefix" + values: + - "/etc" # Writes to sensitive directories + - "/boot" + - "/lib" + - "/lib64" + - "/bin" + - "/usr/lib" + - "/usr/local/lib" + - "/usr/local/sbin" + - "/usr/local/bin" + - "/usr/bin" + - "/usr/sbin" + - "/var/log" # Writes to logs + - "/dev/log" + - "/root/.ssh" # Writes to sensitive files add here. + - index: 1 + operator: "Equal" + values: + - "2" # MAY_WRITE + matchActions: + - action: Sigkill + - call: "security_mmap_file" + syscall: false + return: true + args: + - index: 0 + type: "file" # (struct file *) used for getting the path + - index: 1 + type: "uint32" # the prot flags PROT_READ(0x01), PROT_WRITE(0x02), PROT_EXEC(0x04) + - index: 2 + type: "uint32" # the mmap flags (i.e. MAP_SHARED, ...) + returnArg: + index: 0 + type: "int" + returnArgAction: "Post" + selectors: + - matchArgs: + - index: 0 + operator: "Prefix" + values: + - "/boot" # Reads to sensitive directories + - "/root/.ssh" # Reads to sensitive files we want to know about + - "/etc/shadow" + - "/etc/sudoers" + - "/etc/pam.conf" # Reads global shell configs bash/csh supported + - "/etc/profile" + - "/etc/bashrc" + - "/etc/csh.cshrc" + - "/etc/csh.login" + - ".bashrc" # Reads to shell config files bash, csh supported + - ".bash_profile" # add any other shell support here. + - ".bash_login" + - ".bash_logout" + - ".cshrc" + - ".cshdirs" + - ".profile" # Reads to common environments files + - ".login" + - ".logout" + - ".history" # Add additional sensitive mmap files here + - index: 1 + operator: "Equal" + values: + - "1" # MAY_READ + - index: 2 + operator: "Mask" + values: + - "1" # MAP_SHARED + matchActions: + - action: Sigkill + - matchArgs: + - index: 0 + operator: "Prefix" + values: + - "/etc" # Writes to sensitive directories + - "/boot" + - "/lib" + - "/lib64" + - "/bin" + - "/usr/lib" + - "/usr/local/lib" + - "/usr/local/sbin" + - "/usr/local/bin" + - "/usr/bin" + - "/usr/sbin" + - "/var/log" # Writes to logs + - "/dev/log" + - "/root/.ssh" # Writes to sensitive files add here. + - index: 1 + operator: "Mask" + values: + - "2" # PROT_WRITE + - index: 2 + operator: "Mask" + values: + - "1" # MAP_SHARED + matchActions: + - action: Sigkill + - call: "security_path_truncate" + syscall: false + return: true + args: + - index: 0 + type: "path" # (struct path *) used for getting the path + returnArg: + index: 0 + type: "int" + returnArgAction: "Post" + selectors: + - matchArgs: + - index: 0 + operator: "Prefix" + values: + - "/etc" # Truncate to sensitive directories + - "/boot" + - "/lib" + - "/lib64" + - "/usr/lib" + - "/usr/local/lib" + - "/usr/local/sbin" + - "/usr/local/bin" + - "/usr/bin" + - "/usr/sbin" + - "/var/log" # Truncate to logs + - "/dev/log" + - "/root/.ssh" # Truncate to sensitive files add here. + matchActions: + - action: Sigkill diff --git a/examples/quickstart/network_egress_cluster.yaml b/examples/quickstart/network_egress_cluster.yaml new file mode 100644 index 00000000000..2f16a0e98d8 --- /dev/null +++ b/examples/quickstart/network_egress_cluster.yaml @@ -0,0 +1,28 @@ +# output of "gcloud container clusters describe tetragon-benchmarking-oss --zone=us-west2-a | grep -e clusterIpv4Cidr -e servicesIpv4Cidr" +# clusterIpv4Cidr: 10.44.0.0/14 +# clusterIpv4Cidr: 10.44.0.0/14 +# clusterIpv4CidrBlock: 10.44.0.0/14 +# servicesIpv4Cidr: 10.48.0.0/20 +# servicesIpv4CidrBlock: 10.48.0.0/20 +# servicesIpv4Cidr: 10.48.0.0/20 + +# For more information see: https://docs.isovalent.com/user-guide/sec-ops-visibility/workload-identity/index.html#egress-flow-to-suspicious-external-ip +apiVersion: cilium.io/v1alpha1 +kind: TracingPolicy +metadata: + name: "monitor-network-activity-outside-cluster-cidr-range" +spec: + kprobes: + - call: "tcp_connect" + syscall: false + args: + - index: 0 + type: "sock" + selectors: + - matchArgs: + - index: 0 + operator: "NotDAddr" + values: + - 127.0.0.1 + - ${PODCIDR} + - ${SERVICECIDR} diff --git a/examples/quickstart/network_egress_cluster_enforce.yaml b/examples/quickstart/network_egress_cluster_enforce.yaml new file mode 100644 index 00000000000..af2794fbbdc --- /dev/null +++ b/examples/quickstart/network_egress_cluster_enforce.yaml @@ -0,0 +1,21 @@ +apiVersion: cilium.io/v1alpha1 +kind: TracingPolicyNamespaced +metadata: + name: "monitor-network-activity-outside-cluster-cidr-range" +spec: + kprobes: + - call: "tcp_connect" + syscall: false + args: + - index: 0 + type: "sock" + selectors: + - matchArgs: + - index: 0 + operator: "NotDAddr" + values: + - 127.0.0.1 + - ${PODCIDR} + - ${SERVICECIDR} + matchActions: + - action: Sigkill