dmitris/pulsar

A highly modular and blazing fast eBPF-based runtime security agent framework for the IoT.

Quickstart

The following are a set of steps to quickly get started with Pulsar on a Debian-based distribution running kernel version 5.5 or higher with BPF and BTF enabled (requirements).

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install Clang (needed for eBPF compilation)
sudo apt install clang

# Get and build Pulsar
git clone https://github.com/Exein-io/pulsar.git
cd pulsar
cargo test
cargo build --release

# Install files
sudo cp scripts/pulsar scripts/pulsard target/release/pulsar-exec /usr/bin/
sudo chmod +x /usr/bin/pulsar /usr/bin/pulsard

# Run it
sudo pulsard

Architecture

Pulsar is powered by the pulsard daemon — responsible for managing the state of modules that come with Pulsar.

Functionality is enabled through the use of Pulsar modules. Modules are sub- programs that perform specific operations (e.g. monitoring filesystem access) that are loaded into Pulsar at runtime and enable the use of eBPF to power most modules.

Internally every module has access to the shared message bus and can either produce or consume events. It's a broadcast MPMC channel (multi-producer, multi consumer) where every subscriber will receive every message. This allows to build modular code with a clear separation of concerns.

The probe tutorial highlights how to build an eBPF probe and integrate it into Pulsar via the module system.

Minimum Kernel Requirements

Currently Pulsar requires at least kernel version 5.5 with BPF and BTF enabled.

We're requiring 5.5 because we use BPF_CORE_READ, which under the hood uses bpf_probe_read_kernel. To support older kernel versions we may use the older and generic bpf_probe_read.

See https://github.com/iovisor/bcc/blob/master/docs/kernel-versions.md

Advanced

Running without installing

Warning: pulsar requires root privileges to load eBPF programs. To make it easier for development, we run cargo artifacts with sudo.

cargo run -- pulsard

Integration tests

In order to make sure your system is fully surpported, run the test suite.

cargo test

Single probe runner

Probes can be run in isolation by running the following.

cargo run --example probe -- file-created

Contributing

If you're interested in contributing to Pulsar — thank you!

We have a contributing guide which will help you getting involved in the project.

Community

Join the Pulsar Discord server to chat with developers, maintainers, and the whole community. You can also drop any question about Pulsar on the official GitHub discussions or use the GitHub issues for feature requests and bug reports.

License

Pulsar is licensed under two licenses — Pulsar userspace code is licensed under APACHE-2.0. Pulsar eBPF probes are licensed under GPL-2.0.

dmitris / pulsar