kivebpf

kivebpf

Kive is a free and open source eBPF-powered file access monitoring Kubernetes operator.

Basic Usage

You can specify a path to monitor and in which containers by creating a KivePolicy. The following is an example policy:

apiVersion: kivebpf.san7o.github.io/v1
kind: KivePolicy
metadata:
  labels:
    app.kubernetes.io/name: kivebpf
  name: kive-sample-policy
  namespace: kivebpf-system
spec:
  alertVersion: v1
  traps:
  - path: /secret.txt
    create: true
    mode: 444
    callback: "http://my-callback.com/alerts"
    matchAny:
    - pod: nginx-pod
      namespace: default
      containerName: "rgex:nginx-.*"
      matchLabels:
        security-level: high
    metadata:
      alert-level: critical

This sets up a trap on the path /secret.txt in the matched containers, creating it with mode permissions if it does not exist. The match groups under the matchAny field will be matched via a logical OR, and each field in a match group is matched with a logical AND. All the match fields are optional, but there must be at least one match group under matchAny.

When a file gets accessed, the operator will generate an KiveAlert and print the information to standard output in json format. The following is an example alert:

{
  "kive-alert-version": "v1",
  "kive-policy-name": "kive-sample-policy",
  "timestamp": "2025-08-02T16:51:19Z",
  "metadata": {
    "path": "/secret.txt",
    "inode": 16256084,
    "mask": 36,
    "kernel-id": "2c147a95-23e5-4f99-a2de-67d5e9fdb502"
  },
  "custom-metadata": {
    "alert-level": "critical"
  },
  "pod": {
    "name": "nginx-pod",
    "namespace": "default",
    "container": {
      "id": "containerd://0c37512624823392d71e99a12011148db30ba7ea2a74fc7ff8bd5f85bc7b499c",
      "name": "nginx"
    }
  },
  "node": {
    "name": "kive-worker"
  },
  "process": {
    "pid": 176928,
    "tgid": 176928,
    "uid": 0,
    "gid": 0,
    "binary": "/usr/bin/cat",
    "cwd": "/",
    "arguments": "/secret.txt -"
  }
}

If you specify a callback in the KivePolicy, then the data will be sent to the URL of the callback through an HTTP POST request.

Please, read the USAGE document to learn how to use the operator in more detail. You can find more examples in config/samples.

Quick deploy

To deploy the operator, first make sure you have cert-manager installed for secure TLS connections (required):

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

Then simply install the operator with from the official docker repository:

kubectl apply -f https://raw.githubusercontent.com/San7o/kivebpf/refs/heads/main/dist/install-remote.yaml

Supported Environments

Development

The DESIGN document contains all the information about the internals of the operator.

Please read the DEVELOPMENT document to build and get started with Kive's development. EBPF-TESTING has instructions to build and test the eBPF program without running the kubernetes operator. To run a local cluster, take a look at k8s-lab or simply use the script registry-cluster.sh.

The status contains information about the current status of development and future work.