k8saudit

Kubernetes Audit Events Plugin

Introduction

This plugin extends Falco to support Kubernetes Audit Events as a new data source. Audit events are logged by the API server when almost every cluster management task is performed. By monitoring the audit logs, this plugins provides high visibility over the activity in your cluster allows detecting malicious behavior.

Support for Kubernetes Audit Events was previously introduced in Falco v0.13 as a parallel independent stream of events that was read separately from system calls, and was matched separately against its own sets of rules. This legacy implementation resided in the Falco codebase and hooked into many points of libsinsp. This plugin is a direct porting of that feature by leveraging the Falco Plugin System introduced in Falco 0.31. The plugin implementation is a 1-1 porting of the legacy implementation supported by Falco, with few breaking changes introduced to solve few cases of ambiguous behavior and to comply to the constraints of libsinsp and the plugin system.

Functionality

This plugin supports consuming Kubernetes Audit Events coming from the Webhook backend or from file. For webhooks, the plugin embeds a webserver that listens on a configurable port and accepts POST requests. The posted JSON object comprises one or more events. The webserver of the plugin can be configuted as part of the plugin's init configuration and open parameters. For files, the plugins expects content to be in JSONL format, where each line represents a JSON object, containing one or more audit events.

The expected way of using the plugin is through Webhook. The file reading support is mostly designed for testing purposes and for development, but does not represent a concrete deployment use case.

Capabilities

The k8saudit plugin implements both the event sourcing and the field extraction capabilities of the Falco Plugin System.

Event Source

The event source for Kubernetes Audit Events is k8s_audit.

Supported Fields

Usage

Requirements

The Kubernetes cluster must have the audit logs enabled and configured to send the audit logs to the plugin. We provide the audit-policy.yaml which is tailored for the k8saudit plugin. The 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 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:

plugins:
  - name: k8saudit
    library_path: libk8saudit.so
    init_config:
      sslCertificate: /etc/falco/falco.pem
    open_params: "http://:9765/k8s-audit"
  - name: json
    library_path: libjson.so
    init_config: ""

load_plugins: [k8saudit, json]

Initialization Config:

• sslCertificate: The SSL Certificate to be used with the HTTPS Webhook endpoint (Default: /etc/falco/falco.pem)
• maxEventSize: Maximum size of single audit event (Default: 262144)
• webhookMaxBatchSize: Maximum size of incoming webhook POST request bodies (Default: 12582912)
• useAsync: If true then async extraction optimization is enabled (Default: true)

Open Parameters:

• http://<host>:<port>/<endpoint>: Opens an event stream by listening on a HTTP webserver
• https://<host>:<port>/<endpoint>: Opens an event stream by listening on a HTTPS webserver
• 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). The official ruleset depends on the json plugin, which motivates its presence in the falco.yaml sample showed above.

Running

This plugin requires Falco with version >= 0.32.0.

falco -c falco.yaml -r k8s_audit_rules.yaml

14:09:12.581541000: Warning Pod started with privileged container (user=system:serviceaccount:kube-system:replicaset-controller pod=nginx-deployment-5cdcc99dbf-rgw6z ns=default image=nginx)
Driver Events:0
Driver Drops:0
Elapsed time: 0.004, Captured Events: 1, 224.62 eps
Events detected: 1
Rule counts by severity:
   WARNING: 1
Triggered rules by rule name:
   Create Privileged Pod: 1
Syscall event drop monitoring:
   - event drop detected: 0 occurrences
   - num times actions taken: 0