Kive

Deploy

To deploy the operator from the official docker repository, first make sure you have cert-manager installed:

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

Then simply run:

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

Then read the USAGE document to learn how to use the operator. If you want to build the operator yourself please read the DEVELOPMENT document for instructions.

Overview

You can specify a path to monitor and in which containers by creating an 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
      container-name: ".*"
      matchLabels:
        security-level: high
    metadata:
      severity: 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": {
    "severity": "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.

You can find more examples in config/samples.

Learn More

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.

Contributing

We are happy to receive any contribution. The project is hosted on GitHub and it is licensed under under GPLv2. Check out the issues