Explain auditing with Falco

Co-authored-by: Lorenzo Fontana <lo@linux.com>
Signed-off-by: Leonardo Di Donato <leodidonato@gmail.com>

content/en/docs/tasks/debug-application-cluster/audit.md

@@ -419,6 +419,97 @@ Note that in addition to file output plugin, logstash has a variety of outputs t
 let users route data where they want. For example, users can emit audit events to elasticsearch
 plugin which supports full-text search and analytics.
 
+## Webhook Collector Examples
+
+### Use Falco to collect audit events
+
+[Falco](falco) is an open source project for intrusion and abnormality detection for Cloud Native platforms.
+In this example, we will see how to send audit events to the Kubernetes Audit endpoint exposed by Falco.
+
+After receiving Audit Events, Falco applies a set of [Audit Rules][#audit-rules], described below, in order to detect suspicious or notable behavior automatically.
+
+#### Install Falco
+
+You can install Falco standalone or as a Kubernetes DaemonSet following the instructions [here](falco-installation).
+You can also install Falco using the official [Helm Chart](falco-helm-chart).
+
+Once Falco is installed you need to make sure it is configured to expose the Audit webhook.
+
+This is the configuration to enable it.
+
+```yaml
+webserver:
+   enabled: true
+   listen_port: 8765
+   k8s_audit_endpoint: /k8s_audit
+   ssl_enabled: false
+   ssl_certificate: /etc/falco/falco.pem
+```
+
+This configuration is usually in `/etc/falco/falco.yaml`. When installed as a Kubernetes DaemonSet you can edit that file changing the `falco-config` ConfigMap.
+
+#### Configure Kubernetes Audit
+
+1. Create a [kubeconfig file](/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig/) for [kube-apiserver][kube-apiserver] webhook audit backend
+
+        cat <<EOF > /etc/kubernetes/audit-webhook-kubeconfig
+        apiVersion: v1
+        kind: Config
+        clusters:
+        - cluster:
+            server: http://<ip_of_falco>:8765/k8s_audit
+          name: falco
+        contexts:
+        - context:
+            cluster: falco
+            user: ""
+          name: default-context
+        current-context: default-context
+        preferences: {}
+        users: []
+        EOF
+
+2. Start [kube-apiserver][kube-apiserver] with the following options:
+
+    ```shell
+    --audit-policy-file=/etc/kubernetes/audit-policy.yaml --audit-webhook-config-file=/etc/kubernetes/audit-webhook-kubeconfig
+    ```
+
+#### Audit Rules
+
+Rules devoted to Kubernetes Audit Events can be found [k8s_audit_rules.yaml][falco-k8s-audit-rules]. When installed as a native package or using the official Docker images, Falco installs this rules file to `/etc/falco/`, so they are available for use.
+
+There are three classes of rules.
+
+The first class of rules looks for suspicious or exceptional activity. This includes things like:
+
+- Any activity by a user outside of a set of allowed users, or by the anonymous user.
+- Creating a pod with an image outside of a set of allowed images.
+- Creating a privileged pod, a pod mounting a sensitive filesystem from the host, or a pod using host networking.
+- Creating a NodePort service.
+- Creating a configmap containing likely private credentials such as passwords, aws keys, etc.
+- Attaching or execing to a running pod.
+- Creating a namespace outside of a set of allowed namespaces.
+- Creating a pod or service account in the kube-system or kube-public namespaces.
+- Trying to modify or delete a system ClusterRole.
+- Creating a ClusterRoleBinding to the cluster-admin role.
+- Creating a ClusterRole with wildcarded verbs or resources (e.g. overly permissive)
+- Creating a ClusterRole with write permissions or a ClusterRole that can exec to pods.
+
+A second class of rules tracks resources being created or destroyed, including:
+
+- Deployments
+- Services
+- ConfigMaps
+- Namespaces
+- Service accounts
+- Role/ClusterRoles
+- Role/ClusterRoleBindings
+
+The final class of rules simply displays any Audit Event received by Falco. This rule is disabled by default, as it can be quite noisy.
+
+For further details refer to the this [Falco documentation page](falco-ka-docs)
+
 [kube-apiserver]: /docs/admin/kube-apiserver
 [auditing-proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/auditing.md
 [auditing-api]: https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/staging/src/k8s.io/apiserver/pkg/apis/audit/v1/types.go
@@ -430,5 +521,10 @@ plugin which supports full-text search and analytics.
 [logstash]: https://www.elastic.co/products/logstash
 [logstash_install_doc]: https://www.elastic.co/guide/en/logstash/current/installing-logstash.html
 [kube-aggregator]: /docs/concepts/api-extension/apiserver-aggregation
+[falco]: https://falco.org
+[falco-k8s-audit-rules]: https://github.com/falcosecurity/falco/blob/master/rules/k8s_audit_rules.yaml
+[falco-ka-docs]: https://falco.org/docs/event-sources/kubernetes-audit
+[falco-installation]: https://falco.org/docs/installation
+[falco-helm-chart]: https://github.com/helm/charts/tree/master/stable/falco
 
 {{% /capture %}}