# exein-io/pulsar architecture

> Architecture diagram of the GitHub repository exein-io/pulsar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/exein-io/pulsar
- Repository: https://github.com/exein-io/pulsar

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Kernel / eBPF Layer
  subgraph "Kernel / eBPF Layer"
    style KernelLayer fill:#0b6623,stroke:#0b6623,color:white
    eBPFBuilder["eBPF Probes\n(crates/bpf-builder)"]:::kernel
    BpfFeature["BPF Feature Detection\n(crates/bpf-feature-autodetect)"]:::kernel
    BpfFiltering["Filtering Helpers\n(crates/bpf-filtering)"]:::kernel
    BpfCommon["Common BPF Utils\n(crates/bpf-common)"]:::kernel
    RingBuffers[(Ring Buffers & Maps)]:::kernel
  end

  %% Userspace Daemon Core
  subgraph "Userspace Daemon"
    style CoreLayer fill:#1f77b4,stroke:#1f77b4,color:white
    DaemonEntrypoint["Daemon Entrypoint\n(src/pulsard/daemon.rs)"]:::core
    ModuleManager["Module Manager\n(src/pulsard/module_manager.rs)"]:::core
    Config["Configuration Loader\n(src/pulsard/config.rs)"]:::core
    PulsarCore["Core Library\n(crates/pulsar-core)"]:::core
    Bus["Event Bus & Definitions"]:::core
  end

  %% Rule Engine & Modules
  subgraph "Rule Engine & Modules"
    style ModulesLayer fill:#ff7f0e,stroke:#ff7f0e,color:white
    RuleEngine["Rule Engine\n(crates/modules/rules-engine)"]:::modules
    Validatron["Rules Validator\n(crates/validatron)"]:::modules
    FSM["File-System Monitor\n(crates/modules/file-system-monitor)"]:::modules
    NetMon["Network Monitor\n(crates/modules/network-monitor)"]:::modules
    ProcMon["Process Monitor\n(crates/modules/process-monitor)"]:::modules
    ThreatLogger["Threat Logger\n(crates/modules/threat-logger)"]:::modules
    SMTPNotifier["SMTP Notifier\n(crates/modules/smtp-notifier)"]:::modules
    DesktopNotifier["Desktop Notifier\n(crates/modules/desktop-notifier)"]:::modules
  end

  %% CLI / API / External
  subgraph "CLI, API & External"
    style ExternalLayer fill:#7f7f7f,stroke:#7f7f7f,color:white
    PulsarCLI["'pulsar' CLI\n(src/cli/pulsar.rs)"]:::external
    PulsardCLI["'pulsard' CLI Launcher\n(src/cli/pulsard.rs)"]:::external
    CLIMod["Shared CLI wiring\n(src/cli/mod.rs, src/main.rs, src/lib.rs)"]:::external
    EngineAPI["Engine API RPC\n(crates/engine-api)"]:::external
    SMTPService[(SMTP Service)]:::external
    DesktopUI[(OS Notification)]:::external
  end

  %% CI / Deployment
  subgraph "CI & Deployment"
    style CILayer fill:#9467bd,stroke:#9467bd,color:white
    Xtask["xtask (Dev Scripts)\n(xtask/src)"]:::ci
    TestSuite["Integration Tests\n(test-suite/src)"]:::ci
    Examples["Sample Examples\n(examples/)"]:::ci
    CrossDocker["Cross-compile Dockerfiles\n(.cross/)"]:::ci
    GHWorkflows["GitHub Actions\n(.github/workflows/)"]:::ci
    GHDocker["Docker Config & INI\n(.github/docker/)"]:::ci
    Vagrant["Vagrant Setups\n(vagrant/)"]:::ci
  end

  %% Connections
  eBPFBuilder -->|builds probes| RingBuffers
  BpfFeature -->|detects features| RingBuffers
  BpfFiltering -->|filters events| RingBuffers
  BpfCommon -->|libbpf integration| RingBuffers

  RingBuffers -->|raw events| DaemonEntrypoint
  DaemonEntrypoint -->|loads PDK| ModuleManager
  DaemonEntrypoint -->|initializes| PulsarCore
  PulsarCore -->|publishes events| Bus

  Bus -->|to rule engine| RuleEngine
  RuleEngine -->|uses DSL| Validatron
  Bus -->|to modules| FSM
  Bus -->|to modules| NetMon
  Bus -->|to modules| ProcMon

  RuleEngine -->|threat events| ThreatLogger
  ThreatLogger -->|logs| DesktopUI
  ThreatLogger -->|alerts| SMTPService
  ThreatLogger -->|alerts| DesktopNotifier
  DesktopNotifier -->|push| DesktopUI
  SMTPNotifier -->|sends| SMTPService

  PulsarCLI -->|CLI entry| DaemonEntrypoint
  PulsardCLI -->|daemon launcher| DaemonEntrypoint
  CLIMod -->|wiring| PulsarCLI
  CLIMod -->|wiring| PulsardCLI

  EngineAPI -->|RPC calls| DaemonEntrypoint

  Xtask -->|build scripts| PulsarCore
  TestSuite -->|integration tests| DaemonEntrypoint
  Examples -->|usage demos| ModuleManager
  CrossDocker -->|build targets| Xtask
  GHWorkflows -->|CI pipelines| CrossDocker
  GHDocker -->|config| GHWorkflows
  Vagrant -->|env for| DaemonEntrypoint

  %% Click Events
  click eBPFBuilder "https://github.com/exein-io/pulsar/tree/main/crates/bpf-builder"
  click BpfFeature "https://github.com/exein-io/pulsar/tree/main/crates/bpf-feature-autodetect"
  click BpfFiltering "https://github.com/exein-io/pulsar/tree/main/crates/bpf-filtering"
  click BpfCommon "https://github.com/exein-io/pulsar/tree/main/crates/bpf-common"
  click PulsarCore "https://github.com/exein-io/pulsar/tree/main/crates/pulsar-core/src"
  click DaemonEntrypoint "https://github.com/exein-io/pulsar/blob/main/src/pulsard/daemon.rs"
  click ModuleManager "https://github.com/exein-io/pulsar/blob/main/src/pulsard/module_manager.rs"
  click Config "https://github.com/exein-io/pulsar/blob/main/src/pulsard/config.rs"
  click RuleEngine "https://github.com/exein-io/pulsar/tree/main/crates/modules/rules-engine/src"
  click Validatron "https://github.com/exein-io/pulsar/tree/main/crates/validatron/src"
  click FSM "https://github.com/exein-io/pulsar/blob/main/crates/modules/file-system-monitor/src/lib.rs"
  click NetMon "https://github.com/exein-io/pulsar/blob/main/crates/modules/network-monitor/src/lib.rs"
  click ProcMon "https://github.com/exein-io/pulsar/blob/main/crates/modules/process-monitor/src/lib.rs"
  click ThreatLogger "https://github.com/exein-io/pulsar/blob/main/crates/modules/threat-logger/src/lib.rs"
  click SMTPNotifier "https://github.com/exein-io/pulsar/blob/main/crates/modules/smtp-notifier/src/lib.rs"
  click DesktopNotifier "https://github.com/exein-io/pulsar/blob/main/crates/modules/desktop-notifier/src/lib.rs"
  click EngineAPI "https://github.com/exein-io/pulsar/tree/main/crates/engine-api/src"
  click Xtask "https://github.com/exein-io/pulsar/tree/main/xtask/src"
  click TestSuite "https://github.com/exein-io/pulsar/tree/main/test-suite/src"
  click Examples "https://github.com/exein-io/pulsar/tree/main/examples/"
  click CrossDocker "https://github.com/exein-io/pulsar/tree/main/.cross/"
  click GHWorkflows "https://github.com/exein-io/pulsar/tree/main/.github/workflows/"
  click GHDocker "https://github.com/exein-io/pulsar/tree/main/.github/docker/"
  click Vagrant "https://github.com/exein-io/pulsar/tree/main/vagrant/"

  %% Styles
  classDef kernel fill:#0b6623,stroke:#0b6623,color:white
  classDef core fill:#1f77b4,stroke:#1f77b4,color:white
  classDef modules fill:#ff7f0e,stroke:#ff7f0e,color:white
  classDef external fill:#7f7f7f,stroke:#7f7f7f,color:white
  classDef ci fill:#9467bd,stroke:#9467bd,color:white
```
