How exein-io/pulsar works
Project Type and Purpose
• Pulsar is a modular Linux security monitoring tool built in Rust.
• It uses eBPF probes in the kernel to collect runtime events (process, file I/O, network) and sends them to a userspace daemon (pulsard).
• A rule engine inspects events against YAML-defined policies; matches become threat events, which are logged or forwarded by notifier modules.
High-Level Architecture Components
a. Kernel Space
• eBPF Probes (built by crates/bpf-builder, bpf-feature-autodetect, bpf-filtering).
• eBPF Maps & Ring Buffers to transfer raw events to userspace.
b. Userspace Daemon (pulsard)
• Core Library (crates/pulsar-core):
• Bus & Event definitions
• PDK (Plugin Development Kit) for module lifecycle and IPC.
• Rule Engine (crates/modules/rules-engine, crates/validatron):
• DSL parser/compiler
• Validator and matching logic.
• Modules (multiple crates/modules/*):
• File-system monitor, network monitor, process monitor, SMTP notifier, threat logger, desktop notifier, etc.
• Each module loaded via PDK, receives events, applies filtering/notifying logic.
• CLI Frontend (src/cli, src/main.rs):
• pulsar command for ad-hoc runs.
• pulsard daemon launcher.
c. Engine API (crates/engine-api)
• Optional server/client RPC interface for external integrations.
d. Supporting Tooling
• xtask: cross-compile and dev scripts.
• test-suite: integration testing harness.
• examples/: sample module usage and embedding.
e. Deployment & CI
• Dockerfiles and Vagrant setups for various architectures (.cross, .github/docker, vagrant).
• GitHub Actions workflows for build, test, release.
Relationships & Data Flow
1. At load time, pulsard installs eBPF probes into the kernel via libbpf (bpf-common).
2. Kernel probes emit events through ring buffers/maps.
3. pulsard reads events, wraps them in Event structs (pulsar-core).
4. Events are published on the internal Bus, consumed by:
• Rule Engine → identifies threats.
• Modules → may filter, enrich, or forward events.
5. Threat events propagate to notifier modules (e.g., threat-logger prints to console, SMTP-notifier sends email, desktop-notifier pushes OS notification).
6. External clients can connect via engine-api RPC.
Architectural Patterns & Principles
• Modular plugin architecture via PDK: modules conform to a common interface, loaded dynamically.
• Event-driven bus pattern within userspace.
• Separation of concerns:
• Kernel instrumentation separated from userspace logic.
• Rule definition (YAML) decoupled from code.
• Cross-compilation support for multi-arch builds.