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

Note: This dependency is currently required but it should be dropped in a future release. Additionally, as a temporary solution cert-manager configures a self-signing issuer: this is not meant to be used on EKS or other providers, please use Minikube or Kind to test the operator.

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: "regex:nginx-.*"
      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.

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

Kive

Kive is an eBPF-powered file access monitoring Kubernetes operator.

Deploy

Overview

Learn More

Contributing