tetragon: docs, copy Cilium style k8s install

docs/content/en/docs/advanced-config/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Advanced Configuration"
+weight: 4
+icon: "observability"
+description: "Tetragon deployment configuration options"
+---

docs/content/en/docs/getting-started/deployment/container.md → docs/content/en/docs/advanced-config/container.md

@@ -91,5 +91,5 @@ See [Tetragon daemon configuration](/docs/reference/tetragon-configuration) refe
 
 ## 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 how to see the Tetragon events.

docs/content/en/docs/getting-started/deployment/package.md → docs/content/en/docs/advanced-config/package.md

@@ -174,6 +174,6 @@ Tetragon also ships a gRPC client that can be used to receive events.
 
 ## 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.
 

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.

docs/content/en/docs/concepts/enforcement/_index.md

@@ -0,0 +1,10 @@
+---
+title: "Enforcement"
+icon: "overview"
+weight: 5
+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.

docs/content/en/docs/concepts/metrics/_index.md

@@ -0,0 +1,10 @@
+---
+title: "Tetragon Metrics"
+icon: "overview"
+weight: 3
+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.

docs/content/en/docs/concepts/tetragon-events/_index.md

@@ -0,0 +1,9 @@
+---
+title: "Tetragon Events"
+icon: "overview"
+weight: 3
+description: "Documentation for Tetragon event system"
+---
+
+Tetragon's events are exposed to the system through either the GRPC
+endpoint or JSON logs.

docs/content/en/docs/concepts/tetragon-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.

docs/content/en/docs/getting-started/explore-security-observability-events.md → docs/content/en/docs/concepts/tetragon-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

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
 ```

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

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

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.

docs/content/en/docs/getting-started/enforcement.md

@@ -0,0 +1,200 @@
+---
+title: "Policy Enforcement"
+weight: 2
+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 binary 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" >}})
+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.
+
+### Kubernetes 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 text=true >}}
+{{% tab GKE %}}
+
+```shell-session
+export SERVICECIDR=$(gcloud container clusters describe ${NAME} --zone ${ZONE} --project ${PROJECT} | awk '/servicesIpv4CidrBlock/ { print $2; }')
+```
+{{% /tab %}}
+
+{{% tab Kind %}}
+```shell-session
+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/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
+```shell-session
+$ kubectl exec -ti xwing -- bash -c 'curl https://ebpf.io/applications/#tetragon'
+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.
+
+``` shell
+🚀 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/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/quickstart/file_monitoring.yaml
+kubectl apply -f http://github.com/cilium/tetragon/quickstart/file_monitoring_enforce.yaml
+{{< /tab >}}                                                                                                                                                                                   
+{{< tab Docker >}}          
+wget http://github.com/cilium/tetragon/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,
+```
+$ kubectl exec -ti xwing -- bash -c 'cat /etc/shadow'
+command terminated with exit code 137
+```
+
+This will generate a read event (Docker events will omit Kubernetes metadata),
+
+```shell-session
+🚀 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.
+
+```shell-session
+🚀 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.