{"id":13824887,"url":"https://github.com/genuinetools/bpfd","last_synced_at":"2025-05-16T07:05:23.927Z","repository":{"id":45674017,"uuid":"147996448","full_name":"genuinetools/bpfd","owner":"genuinetools","description":"Framework for running BPF programs with rules on Linux as a daemon. Container aware.","archived":false,"fork":false,"pushed_at":"2021-05-07T16:14:59.000Z","size":3747,"stargazers_count":478,"open_issues_count":5,"forks_count":39,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-08T16:09:14.311Z","etag":null,"topics":["bpf","cli","containers","docker","ebpf","kernel","linux","security","tracing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/genuinetools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-09T05:39:08.000Z","updated_at":"2025-03-10T13:41:00.000Z","dependencies_parsed_at":"2022-09-26T17:41:20.536Z","dependency_job_id":null,"html_url":"https://github.com/genuinetools/bpfd","commit_stats":null,"previous_names":["jessfraz/bpfd"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genuinetools%2Fbpfd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genuinetools%2Fbpfd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genuinetools%2Fbpfd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genuinetools%2Fbpfd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/genuinetools","download_url":"https://codeload.github.com/genuinetools/bpfd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254485057,"owners_count":22078767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bpf","cli","containers","docker","ebpf","kernel","linux","security","tracing"],"created_at":"2024-08-04T09:01:11.168Z","updated_at":"2025-05-16T07:05:18.918Z","avatar_url":"https://github.com/genuinetools.png","language":"Go","readme":"# bpfd\n\n[![Travis CI](https://img.shields.io/travis/genuinetools/bpfd.svg?style=for-the-badge)](https://travis-ci.org/genuinetools/bpfd)\n[![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=for-the-badge)](https://godoc.org/github.com/genuinetools/bpfd)\n[![Github All Releases](https://img.shields.io/github/downloads/genuinetools/bpfd/total.svg?style=for-the-badge)](https://github.com/genuinetools/bpfd/releases)\n\nFramework for running BPF tracers with rules on Linux as a daemon. Container aware.\n\nThis is not just \"yet another tool to trace\"...\n\nSince it uses BPF and allows for any implementation of the `Tracer` interface you\ncan use it to do all sorts of things from modifying a file everytime a call to `open` is\ncalled on it, to hot patching an internal kernel function to prevent a known vulnerability\nwithout the need to upgrade your kernel.\n\nMore use cases with examples coming soon... for now see [how it works](#how-it-works).\n\n**Table of Contents**\n\n\u003c!-- toc --\u003e\n\n- [How it Works](#how-it-works)\n  * [Tracers](#tracers)\n  * [Rules](#rules)\n  * [Actions](#actions)\n- [Installation](#installation)\n    + [Binaries](#binaries)\n    + [Via Go](#via-go)\n    + [Via Docker](#via-docker)\n- [Usage](#usage)\n  * [Run the daemon](#run-the-daemon)\n  * [Create rules dynamically](#create-rules-dynamically)\n  * [Remove rules dynamically](#remove-rules-dynamically)\n  * [List active rules](#list-active-rules)\n  * [Live tracing events](#live-tracing-events)\n\n\u003c!-- tocstop --\u003e\n\n## How it Works\n\n[**Tracers**](#tracers) retrieve the data...\n[**Rules**](#rules) filter the data...\n[**Actions**](#actions) perform actions on the data.\n\nThe tracers are in the [tracer/ folder](tracer).\nThe idea is that you can add any tracers you would like\nand then create [rules](examples) for the data retrieved from the tracers.\nAny events with data that passes the filters will be passed on to the specified\naction.\n\n### Tracers\n\nThe tracers that exist today are based off a few\n[bcc-tools](https://github.com/iovisor/bcc) tracers.\n\nYou could always add your own tracers in a fork if you worry people will\nreverse engineer the data you are collecting and alerting on.\n\nThe current compiled in tracers are:\n\n- [dockeropenbreakout](tracer/dockeropenbreakout): trace when files that are not\n    inside the container rootfs are being accessed\n- [bashreadline](tracer/bashreadline): trace commands being entered into\n    the bash command line\n- [exec](tracer/exec): trace calls to exec binaries\n- [open](tracer/open): trace calls to open files\n\nThese must implement the `Tracer` interface:\n\n```go\n// Tracer defines the basic capabilities of a tracer.\ntype Tracer interface {\n    // Load creates the bpf module and starts collecting the data for the tracer.\n    Load() error\n    // Unload closes the bpf module and all the probes that all attached to it.\n    Unload()\n    // WatchEvent defines the function to watch the events for the tracer.\n    WatchEvent() (*grpc.Event, error)\n    // Start starts the map for the tracer.\n    Start()\n    // String returns a string representation of this tracer.\n    String() string\n}\n```\n\nAs you can see from above you could _technically_ implement this interface with\nsomething other than BPF ;)\n\nThe `Event` type defines the data returned from the tracer. As you can see\nbelow, the `Data` is of type `map[string]string` meaning any key value pair can\nbe returned for the data. The rules then filter using those key value pairs.\n\n```go\n// Event defines the data struct for holding event data.\ntype Event struct {\n    PID              uint32            // Process ID.\n    TGID             uint32            // Task group ID.\n    UID              uint32            // User ID.\n    GID              uint32            // User group ID.\n    Command          string            // The command for the process.\n    ReturnValue      int32             // The return value for the function.\n    Data             map[string]string\n    ContainerRuntime string            // Filled in after the tracer is run so you don't need to.\n    ContainerID      string            // Filled in after the tracer is run so you don't need to.\n    Tracer           string            // Filled in after the tracer is run so you don't need to.\n}\n```\n\n### Rules\n\nThese are toml files that hold some logic for what you would like to trace.\nYou can search for anything returned by a `Tracer` in its `map[string]string`\ndata struct.\n\nYou can also filter based off the container runtime you would like to alert on.\nThe container runtime must be one of the strings defined\n[here](https://github.com/genuinetools/bpfd/blob/master/proc/proc.go#L24).\n\nIf you provide no rules for a tracer, then _all_ the events will be passed to\nactions.\n\nThe example below describes a rule file to filter the data returned from the\n`exec` tracer. Events from `exec` will only be returned if the `command` matches\none of those values AND the container runtime is `docker` or `kube`.\n\n```toml\ntracer = \"exec\"\n\nactions = [\"stdout\"]\n\n[filterEvents]\n  [filterEvents.command]\n  values = [\"sshd\", \"dbus-daemon-lau\", \"ping\", \"ping6\", \"critical-stack-\", \"pmmcli\", \"filemng\", \"PassengerAgent\", \"bwrap\", \"osdetect\", \"nginxmng\", \"sw-engine-fpm\", \"start-stop-daem\"]\n\ncontainerRuntimes = [\"docker\",\"kube\"]\n```\n\nIf you are wondering where the `command` key comes from, it's defined in the\n`exec` tracer [here](https://github.com/genuinetools/bpfd/blob/master/tracer/exec/exec.go#L200).\n\nRules can be dynamically controlled via bpfd's [gRPC](https://grpc.io/) interface.\nThe cli tool can also be used for creating rules dynamically, see \n[`create` usage](#create-rules-dynamically).\n\nThe protobuf protocol definition is defined in [api/grpc/api.proto](https://github.com/genuinetools/bpfd/blob/master/api/grpc/api.proto)\n\nTo interact with the gRPC api you can use the [`--gpc-addr` flag](#usage)\nor the default is a sock at `/run/bpfd/bpfd.sock`.\n\n### Actions\n\nActions do \"something\" on an event. This way you can send filtered events to\nSlack, email, or even run arbitrary code. You could\nkill a container, pause a container, or checkpoint a container to restore it\nelsewhere without even having to login to a computer.\n\nThe current compiled in actions are:\n\n- [stdout](action/stdout): print to stdout\n- [kill](action/kill): kill the process\n- [interrupt](action/interrupt): interrupt the process\n\nActions implement the `Actions` interface:\n\n```go\n// Action performs an action on an event.\ntype Action interface {\n    // Do runs the action on an event.\n    Do(event *grpc.Event) error\n    // String returns a string representation of this tracer.\n    String() string\n}\n```\n\n## Installation\n\nTo build, you need to have `libbcc` installed [SEE INSTRUCTIONS HERE](https://github.com/iovisor/bcc/blob/master/INSTALL.md)\n\n\n#### Binaries\n\nFor installation instructions from binaries please visit the [Releases Page](https://github.com/genuinetools/bpfd/releases).\n\n#### Via Go\n\n```console\n$ go get github.com/genuinetools/bpfd\n```\n\n#### Via Docker\n\n```console\n$ docker run --rm -it \\\n    --name bpfd \\\n    -v /lib/modules:/lib/modules:ro \\\n    -v /usr/src:/usr/src:ro \\\n    --privileged \\\n    r.j3ss.co/bpfd daemon\n```\n\n## Usage\n\n```console\n$ bpfd -h\nbpfd -  Framework for running BPF tracers with rules on Linux as a daemon.\n\nUsage: bpfd \u003ccommand\u003e\n\nFlags:\n\n  -d, --debug  enable debug logging (default: false)\n  --grpc-addr  Address for gRPC api communication (default: /run/bpfd/bpfd.sock)\n\nCommands:\n\n  create   Create one or more rules.\n  daemon   Start the daemon.\n  ls       List rules.\n  rm       Remove one or more rules.\n  trace    Live trace the events returned after filtering.\n  version  Show the version information.\n```\n\n### Run the daemon\n\nYou can preload rules by passing `--rules-dir` to the command or placing\nrules in the default directory: `/etc/bpfd/rules`.\n\n```console\n$ bpfd daemon -h\nUsage: bpfd daemon [OPTIONS]\n\nStart the daemon.\n\nFlags:\n\n  -d, --debug  enable debug logging (default: false)\n  --grpc-addr  Address for gRPC api communication (default: /run/bpfd/bpfd.sock)\n  --rules-dir  Directory that stores the rules files (default: /etc/bpfd/rules)\n```\n\n### Create rules dynamically\n\nYou can create rules on the fly with the `create` command. You can pass more\nthan one file at a time.\n\n```console\nUsage: bpfd create [OPTIONS] RULE_FILE [RULE_FILE...]\n\nCreate one or more rules.\n\nFlags:\n\n  -d, --debug  enable debug logging (default: false)\n  --grpc-addr  Address for gRPC api communication (default: /run/bpfd/bpfd.sock)\n```\n\n### Remove rules dynamically\n\nYou can delete rules with the `rm` command. You can pass more than one\nrule name at a time.\n\n```console\n$ bpfd rm -h\nUsage: bpfd rm [OPTIONS] RULE_NAME [RULE_NAME...]\n\nRemove one or more rules.\n\nFlags:\n\n  -d, --debug  enable debug logging (default: false)\n  --grpc-addr  Address for gRPC api communication (default: /run/bpfd/bpfd.sock)\n```\n\n### List active rules\n\nYou can list the rules that the daemon is filtering with by using the `ls`\ncommand.\n\n```console\n$ bpfd ls\nNAME                TRACER\nbashreadline        bashreadline\npassword_files      open\nsetuid_binaries     exec\n```\n\n### Live tracing events\n\nYou can live trace the events returned after filtering with the `trace`\ncommand.\n\nThis does not include past events. Consider it like a tail.\n\n```console\n$ bpfd trace\nINFO[0000] map[string]string{\"filename\":\"/etc/shadow\", \"command\":\"sudo\", \"returnval\":\"4\"}  container_id= container_runtime=not-found pid=12893 tracer=open tgid=0\nINFO[0000] map[string]string{\"command\":\"sudo\", \"returnval\":\"4\", \"filename\":\"/etc/sudoers.d/README\"}  container_id= container_runtime=not-found pid=12893 tracer=open tgid=0\nINFO[0000] map[string]string{\"command\":\"sudo\", \"returnval\":\"4\", \"filename\":\"/etc/sudoers.d\"}  container_id= container_runtime=not-found pid=12893 tracer=open tgid=0\nINFO[0000] map[string]string{\"filename\":\"/etc/sudoers\", \"command\":\"sudo\", \"returnval\":\"3\"}  container_id= container_runtime=not-found pid=12893 tracer=open tgid=0\nINFO[0000] map[string]string{\"command\":\"sudo bpfd trace\"}  container_id= container_runtime=not-found pid=23751 tracer=bashreadline tgid=0\nINFO[0000] map[string]string{\"command\":\"vim README.md\"}  container_id= container_runtime=not-found pid=23751 tracer=bashreadline tgid=0\nINFO[0000] map[string]string{\"filename\":\"/etc/shadow\", \"command\":\"sudo\", \"returnval\":\"4\"}  container_id= container_runtime=not-found pid=12786 tracer=open tgid=0\nINFO[0000] map[string]string{\"command\":\"sudo\", \"returnval\":\"4\", \"filename\":\"/etc/sudoers.d/README\"}  container_id= container_runtime=not-found pid=12786 tracer=open tgid=0\nINFO[0000] map[string]string{\"filename\":\"/etc/sudoers.d\", \"command\":\"sudo\", \"returnval\":\"4\"}  container_id= container_runtime=not-found pid=12786 tracer=open tgid=0\nINFO[0000] map[string]string{\"filename\":\"/etc/sudoers\", \"command\":\"sudo\", \"returnval\":\"3\"}  container_id= container_runtime=not-found pid=12786 tracer=open tgid=0\n```","funding_links":[],"categories":["Projects Related to eBPF","Go","eBPF 相关项目"],"sub_categories":["Tools","工具"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenuinetools%2Fbpfd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgenuinetools%2Fbpfd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenuinetools%2Fbpfd/lists"}