README.md

Introduction

Userspace eBPF instrumentation and control framework for deploying control and monitoring functions in a secure manner. It is part of Project Janus and provides probes for eBPF-like functionality outside of the Linux kernel.

Architectural overview

The overall jbpf architecture is shown in the figure above. It consists of the following main components:

• Application: It is a user-provided executable that we want to instrument and control, built so that it is linked with the libjbpf library.
• jbpf library: The library that provides the functionality of deploying and executing codeletes, sending output data (output API) and receiving control data (input API).
• Management framework: This a framework to load/unload codelets (codelet life-cycle management and secure codelet store), collect telemetry and excert control (data collection and control) and build and deploy codelets (codelet management).

jbpf is not prescriptive in how the management framework should be built. It provides several APIs in the form of libraries: libjbpf_lcm (life-cycle management), libjbpf_io (input and output API) and libjbpf_verifier (extended verifier), and a sample implementation of the management framework using the APIs. It expects that each user will use the APIs to integrate jbpf into their own prodution environment.

For a high-level overview of the framework functionality, please read this.

Getting started

To build the library, install the dependencies, and run the following:

source ./setup_jbpf_env.sh
mkdir build
cd build
cmake ..
make -j

Check here to see build options.

Then follow these steps to run a simple example and read here to understand the example better. Other variants of this example can be found here and here.

Doxygen documentation

You can generate the documentation using Doxygen. To do so, run the following:

make doc

The documentation will be generated in the $OUT_DIR/docs/html directory.

Further documentation

To learn further, explore our documentation:

• High-level overview of jbpf instrumentation and control process
• Developing codelets:
  • Writing your first codelet
• Integrating jbpf with your own project:
  • Install dependencies
  • Integrate libjbpf
  • Add new hook
  • Add new helper function
  • Add maps
  • Verification
  • Data collection and control
  • Codelet life-cycle management
  • Best security principles
• Experimental features:
  • Serialization of IO messages
• Contributing to the framework:
  • How to contribute?
  • How to add a test?

For more information, also consider:

• jbpf technical paper: A research paper that describes the motivation behind the framework. The paper is focused on 5G RAN instrumentation, but most concepts extend to arbitrary applications.

Related projects

• jbpf-protobuf: jbpf extension, demonstrating how to utilize protobuf serialization for sending and receiving data from codelets loaded in jbpf applications.

License

The jbpf framework is licensed under the MIT license.