# rithvik1124/edrlite-linuxtelemetryagent architecture

> Architecture diagram of the GitHub repository rithvik1124/edrlite-linuxtelemetryagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rithvik1124/edrlite-linuxtelemetryagent
- Repository: https://github.com/rithvik1124/edrlite-linuxtelemetryagent

## Overview

#### Purpose and topology
This repository is a Linux security telemetry and detection prototype. A root Rust/BPF component captures kernel-level events, while a separate Rust server receives, persists, and evaluates telemetry against Sigma/YARA-oriented detection rules.

#### Runtime entry points
- Endpoint/collector executable: `src/main.rs`
- Server executable: `server/src/main.rs`
- eBPF program source and generated bindings/object: `bpf/trial.bpf.c`, `src/trial.skel.rs`, `trial.bpf.o`
- Build integration for BPF artifacts: `build.rs`, `build.sh`

The project is Rust/Cargo-based at both the root and `server/`, with Linux/eBPF kernel dependencies implied by `vmlinux.h` and the BPF sources.

#### Endpoint telemetry collection
The collector couples userspace Rust with an eBPF probe:
- Kernel-side instrumentation is defined in `bpf/trial.bpf.c`, with a secondary Rust BPF-related source at `bpf/some.rs`.
- `vmlinux.h` supplies kernel type definitions for BPF compilation.
- `src/trial.skel.rs` is the generated skeleton/binding boundary used by userspace.
- Telemetry handling is organized under `src/telemetry/new.rs` and likely invoked from `src/main.rs`.

Control flow is expected to be: load BPF object → attach probes → read emitted events in userspace → serialize/send or locally evaluate events.

#### Detection layer
Detection code exists independently in both collector and server:
- Collector detection module: `src/detect/mod.rs`, `src/detect/edr_detect_rules.rs`
- Server detection module: `server/src/detect/mod.rs`, `server/src/detect/edr_detect_rules.rs`

This duplication suggests detection may be usable at both edge and central ingestion boundaries. The rule evaluator is a key abstraction boundary: telemetry event schemas enter it, and alerts/result reports leave it.

#### Rule content and rule distribution
Rules are file-based and split by format:
- Sigma event rules: `rules/sigma/`, including `rules/sigma/proc_creation_lnx_base64_execution.yml`
- YARA content rules: `rules/yara/`, including `rules/yara/Maldoc_VBA_macro_code.yar`
- The server carries its own rule copy under `server/rules/sigma/` and `server/rules/yara/`.

Sigma rules focus on Linux process, file, and log activity. YARA rules target suspicious document/malware content. Duplicated rule trees mean collector and server rule deployment can diverge unless explicitly synchronized.

#### Server ingestion and persistence
The server’s telemetry and database boundary is concentrated in:
- `server/src/telemetry.rs`
- `server/src/db/events_in.rs`
- `server/src/db/result_reports.rs`
- `server/src/db/initialize_db.rs`

Incoming events are handled by the telemetry layer, stored as input events, evaluated by detection, and persisted/emitted as result reports. `server/events_in.redb` indicates Redb is the embedded persistence backend; no external database service is evidenced.

#### Key operational boundaries
1. **Kernel ↔ collector userspace:** eBPF event transport through `bpf/trial.bpf.c` and `src/trial.skel.rs`.
2. **Collector ↔ server:** telemetry transport, implemented at the application level but with protocol details not visible in the tree.
3. **Raw event ↔ detection:** `edr_detect_rules.rs` modules translate event data into rule matches.
4. **Detection ↔ persistence/reporting:** server DB modules retain raw inputs and detection outputs.
5. **Rule files ↔ runtime evaluator:** Sigma/YARA directories are externally editable detection content loaded by application code.

Main entry points: [`src/telemetry/new.rs`](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/src/telemetry/new.rs) (Telemetry handling), [`server/src/telemetry.rs`](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/telemetry.rs) (Telemetry ingestion), [`server/src/detect/edr_detect_rules.rs`](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/detect/edr_detect_rules.rs) (Central rule evaluator), [`bpf/trial.bpf.c`](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/bpf/trial.bpf.c) (eBPF probes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_kernel["Kernel instrumentation"]
  node_bpf_build["BPF build integration<br/>[build.rs]"]
  node_bpf_probe{{"eBPF probes<br/>BPF C<br/>[trial.bpf.c]"}}
  node_bpf_object{{"BPF object<br/>compiled artifact<br/>[trial.bpf.o]"}}
end

subgraph group_collector["Endpoint collector"]
  node_skeleton["Generated BPF skeleton<br/>Rust bindings<br/>[trial.skel.rs]"]
  node_collector_main["Collector executable<br/>Rust entry point<br/>[main.rs]"]
  node_collector_telemetry["Telemetry handling<br/>event pipeline<br/>[new.rs]"]
  node_collector_detection["Edge rule evaluator<br/>detection module"]
end

subgraph group_transport["Telemetry transport"]
  node_telemetry_link["Collector-server link<br/>application transport"]
end

subgraph group_server["Detection server"]
  node_server_main["Server executable<br/>Rust entry point<br/>[main.rs]"]
  node_server_telemetry["Telemetry ingestion<br/>ingestion layer<br/>[telemetry.rs]"]
  node_input_events[("Input event store<br/>Redb input records<br/>[events_in.rs]")]
  node_server_detection["Central rule evaluator<br/>detection module"]
  node_result_reports[("Result report store<br/>Redb report records<br/>[result_reports.rs]")]
  node_db_init["Database initialization<br/>storage setup<br/>[initialize_db.rs]"]
  node_redb_file[("Embedded Redb database<br/>persistence file<br/>[events_in.redb]")]
end

subgraph group_rules["Rule content"]
  node_collector_sigma["Collector Sigma rules<br/>Sigma rule files"]
  node_collector_yara["Collector YARA rules<br/>YARA rule files"]
  node_server_sigma["Server Sigma rules<br/>Sigma rule files"]
  node_server_yara["Server YARA rules<br/>YARA rule files"]
end

node_bpf_build -->|"compiles"| node_bpf_probe
node_bpf_probe -->|"produces"| node_bpf_object
node_bpf_object -->|"bound by"| node_skeleton
node_skeleton -->|"loads and attaches"| node_collector_main
node_bpf_probe -->|"emits kernel events"| node_collector_telemetry
node_collector_main -->|"runs"| node_collector_telemetry
node_collector_telemetry -->|"events"| node_collector_detection
node_collector_sigma -->|"loads"| node_collector_detection
node_collector_yara -->|"loads"| node_collector_detection
node_collector_telemetry -->|"sends telemetry"| node_telemetry_link
node_telemetry_link -->|"delivers telemetry"| node_server_telemetry
node_server_main -->|"hosts"| node_server_telemetry
node_server_telemetry -->|"persists raw events"| node_input_events
node_server_telemetry -->|"evaluates events"| node_server_detection
node_server_sigma -->|"loads"| node_server_detection
node_server_yara -->|"loads"| node_server_detection
node_server_detection -->|"writes reports"| node_result_reports
node_db_init -->|"initializes"| node_redb_file
node_input_events -->|"stored in"| node_redb_file
node_result_reports -->|"stored in"| node_redb_file

click node_bpf_build "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/build.rs"
click node_bpf_probe "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/bpf/trial.bpf.c"
click node_bpf_object "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/trial.bpf.o"
click node_skeleton "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/src/trial.skel.rs"
click node_collector_main "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/src/main.rs"
click node_collector_telemetry "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/src/telemetry/new.rs"
click node_collector_detection "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/src/detect/edr_detect_rules.rs"
click node_server_main "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/main.rs"
click node_server_telemetry "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/telemetry.rs"
click node_input_events "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/db/events_in.rs"
click node_server_detection "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/detect/edr_detect_rules.rs"
click node_result_reports "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/db/result_reports.rs"
click node_db_init "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/db/initialize_db.rs"
click node_redb_file "https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/events_in.redb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bpf_build,node_bpf_probe,node_bpf_object toneBlue
class node_skeleton,node_collector_main,node_collector_telemetry,node_collector_detection toneAmber
class node_telemetry_link toneMint
class node_server_main,node_server_telemetry,node_input_events,node_server_detection,node_result_reports,node_db_init,node_redb_file toneRose
class node_collector_sigma,node_collector_yara,node_server_sigma,node_server_yara toneIndigo
```

## Components

### Kernel instrumentation

- [BPF build integration](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/build.rs): build · `build.rs`
- [eBPF probes](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/bpf/trial.bpf.c): BPF C · Captures kernel-level security events. · `bpf/trial.bpf.c`
- [BPF object](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/trial.bpf.o): compiled artifact · `trial.bpf.o`

### Endpoint collector

- [Generated BPF skeleton](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/src/trial.skel.rs): Rust bindings · Userspace boundary for loading and attaching probes. · `src/trial.skel.rs`
- [Collector executable](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/src/main.rs): Rust entry point · `src/main.rs`
- [Telemetry handling](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/src/telemetry/new.rs): event pipeline · `src/telemetry/new.rs`
- [Edge rule evaluator](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/src/detect/edr_detect_rules.rs): detection module · Can evaluate events before central ingestion. · `src/detect/edr_detect_rules.rs`

### Telemetry transport

- **Collector-server link**: application transport · Protocol details are not visible.

### Detection server

- [Server executable](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/main.rs): Rust entry point · `server/src/main.rs`
- [Telemetry ingestion](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/telemetry.rs): ingestion layer · `server/src/telemetry.rs`
- [Input event store](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/db/events_in.rs): Redb input records · `server/src/db/events_in.rs`
- [Central rule evaluator](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/detect/edr_detect_rules.rs): detection module · Transforms telemetry into matches and reports. · `server/src/detect/edr_detect_rules.rs`
- [Result report store](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/db/result_reports.rs): Redb report records · `server/src/db/result_reports.rs`
- [Database initialization](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/src/db/initialize_db.rs): storage setup · `server/src/db/initialize_db.rs`
- [Embedded Redb database](https://github.com/rithvik1124/edrlite-linuxtelemetryagent/blob/master/server/events_in.redb): persistence file · `server/events_in.redb`

### Rule content

Collector and server maintain separate rule trees.

- **Collector Sigma rules**: Sigma rule files
- **Collector YARA rules**: YARA rule files
- **Server Sigma rules**: Sigma rule files
- **Server YARA rules**: YARA rule files

## Connections

- BPF build integration → eBPF probes: compiles
- eBPF probes → BPF object: produces
- BPF object → Generated BPF skeleton: bound by
- Generated BPF skeleton → Collector executable: loads and attaches
- eBPF probes → Telemetry handling: emits kernel events
- Collector executable → Telemetry handling: runs
- Telemetry handling → Edge rule evaluator: events
- Collector Sigma rules → Edge rule evaluator: loads
- Collector YARA rules → Edge rule evaluator: loads
- Telemetry handling → Collector-server link: sends telemetry
- Collector-server link → Telemetry ingestion: delivers telemetry
- Server executable → Telemetry ingestion: hosts
- Telemetry ingestion → Input event store: persists raw events
- Telemetry ingestion → Central rule evaluator: evaluates events
- Server Sigma rules → Central rule evaluator: loads
- Server YARA rules → Central rule evaluator: loads
- Central rule evaluator → Result report store: writes reports
- Database initialization → Embedded Redb database: initializes
- Input event store → Embedded Redb database: stored in
- Result report store → Embedded Redb database: stored in