diff --git a/plugins/k8saudit/README.md b/plugins/k8saudit/README.md index ab514642..440ff747 100644 --- a/plugins/k8saudit/README.md +++ b/plugins/k8saudit/README.md @@ -90,6 +90,15 @@ The event source for Kubernetes Audit Events is `k8s_audit`. ## Usage +### Requirements + +The Kubernetes cluster must have the [audit logs](https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/) +enabled and configured to send the audit logs to the plugin. We provide the [audit-policy.yaml](./configs/audit-policy.yaml) which is tailored for the `k8saudit` plugin. +The [audit-policy.yaml](./configs/audit-policy.yaml) is of vital importance, it defines the rules about what events should +be recorded and what data they should include. The rules shipped with the `k8saudit` plugins relies on those events. +The [webhook-config.yaml](./configs/webhook-config.yaml.in) shows how to configure the webhook backend to send events to +an external HTTP API. + ### Configuration Here's an example of configuration of `falco.yaml`: @@ -120,6 +129,9 @@ load_plugins: [k8saudit, json] - `no scheme`: Opens an event stream by reading the events from a file on the local filesystem. The params string is interpreted as a filepath +**NOTE**: There is also a full tutorial on how to run the k8saudit plugin in a Kubernetes cluster using minikube: +https://falco.org/docs/install-operate/third-party/learning/#falco-with-multiple-sources. + ### Rules The `k8saudit` plugin ships with a default set of ruleset (see `rules/` directory). diff --git a/plugins/k8saudit/configs/audit-policy.yaml b/plugins/k8saudit/configs/audit-policy.yaml new file mode 100644 index 00000000..90679200 --- /dev/null +++ b/plugins/k8saudit/configs/audit-policy.yaml @@ -0,0 +1,82 @@ +apiVersion: audit.k8s.io/v1 # This is required. +kind: Policy +# Don't generate audit events for all requests in RequestReceived stage. +omitStages: + - "RequestReceived" +rules: + # Log pod changes at RequestResponse level + - level: RequestResponse + resources: + - group: "" + # Resource "pods" doesn't match requests to any subresource of pods, + # which is consistent with the RBAC policy. + resources: ["pods", "deployments"] + + - level: RequestResponse + resources: + - group: "rbac.authorization.k8s.io" + # Resource "pods" doesn't match requests to any subresource of pods, + # which is consistent with the RBAC policy. + resources: ["clusterroles", "clusterrolebindings"] + + # Log "pods/log", "pods/status" at Metadata level + - level: Metadata + resources: + - group: "" + resources: ["pods/log", "pods/status"] + + # Don't log requests to a configmap called "controller-leader" + - level: None + resources: + - group: "" + resources: ["configmaps"] + resourceNames: ["controller-leader"] + + # Don't log watch requests by the "system:kube-proxy" on endpoints or services + - level: None + users: ["system:kube-proxy"] + verbs: ["watch"] + resources: + - group: "" # core API group + resources: ["endpoints", "services"] + + # Don't log authenticated requests to certain non-resource URL paths. + - level: None + userGroups: ["system:authenticated"] + nonResourceURLs: + - "/api*" # Wildcard matching. + - "/version" + + # Log the request body of configmap changes in kube-system. + - level: Request + resources: + - group: "" # core API group + resources: ["configmaps"] + # This rule only applies to resources in the "kube-system" namespace. + # The empty string "" can be used to select non-namespaced resources. + namespaces: ["kube-system"] + + # Log configmap changes in all other namespaces at the RequestResponse level. + - level: RequestResponse + resources: + - group: "" # core API group + resources: ["configmaps"] + + # Log secret changes in all other namespaces at the Metadata level. + - level: Metadata + resources: + - group: "" # core API group + resources: ["secrets"] + + # Log all other resources in core and extensions at the Request level. + - level: Request + resources: + - group: "" # core API group + - group: "extensions" # Version of group should NOT be included. + + # A catch-all rule to log all other requests at the Metadata level. + - level: Metadata + # Long-running requests like watches that fall under this rule will not + # generate an audit event in RequestReceived. + omitStages: + - "RequestReceived" diff --git a/plugins/k8saudit/configs/webhook-config.yaml.in b/plugins/k8saudit/configs/webhook-config.yaml.in new file mode 100644 index 00000000..54e211e6 --- /dev/null +++ b/plugins/k8saudit/configs/webhook-config.yaml.in @@ -0,0 +1,14 @@ +apiVersion: v1 +kind: Config +clusters: +- name: falco + cluster: + server: http://$FALCO_SERVICE_CLUSTERIP:8765/k8s-audit +contexts: +- context: + cluster: falco + user: "" + name: default-context +current-context: default-context +preferences: {} +users: []