How ishan3299/rift works
1. System boundary
Rift is split into two major execution domains: a kernel-space eBPF probe and a user-space C++20 agent. The kernel side observes process and syscall behavior; the user side turns those raw events into a process graph, detections, persisted history, and an interactive dashboard.
2. Kernel telemetry capture
The eBPF program in ebpf/execve_tracker.bpf.c attaches to Linux tracepoints described in the README (execve, connect, dup2, mmap, mprotect, ptrace, sched_process_exit). Its job is only to observe and emit telemetry, not to make decisions. ebpf/vmlinux.h indicates CO-RE-style kernel type bindings.
3. Event transport into user space
eBPF events are sent through a ring buffer into user space. That ring buffer is the main ingestion boundary: everything downstream depends on the ordered stream of syscall/process events coming from the kernel probe.
4. Central orchestration
src/main.cpp is the runtime entry point and likely wires together the major subsystems: detection, graphing, storage, replay, and TUI/headless output. The repository is organized around these subsystems rather than around HTTP or service layers.
5. Process and behavior graph
The Graph/Node subsystem (src/graph, include/Graph.hpp, include/Node.hpp) builds a live ancestry and behavior graph from process events. The README’s exit/pruning behavior suggests it maintains parent/child relationships, keeps exited nodes visible while descendants remain active, and garbage-collects entire subtrees once no live descendants remain.
6. Threat detection layer
DetectionEngine (src/detection/DetectionEngine.cpp) evaluates incoming activity against rules.json. This is a separate policy layer over the graph: it classifies events/processes by severity, applies path/command matching, and respects global whitelists for PIDs and comms. The detection logic is therefore configuration-driven rather than hardcoded.
7. Persistence for forensics
Storage (src/storage/Storage.cpp) persists event timelines into SQLite, with the README explicitly calling out WAL mode. This makes storage an append-friendly forensic ledger rather than a transactional application database. It supports later replay and offline inspection.
8. Offline replay path
Replay (src/replay/Replay.cpp) consumes the stored SQLite session and replays it without the live kernel hooks. This creates a second ingestion path: live events flow from eBPF, while replayed events flow from the database into the same or similar processing pipeline.
9. Interactive operator view
Dashboard (src/tui/Dashboard.cpp) is the presentation layer for live monitoring. The README indicates an FTXUI-based multi-pane TUI with colored severity presentation and real-time process details. This sits downstream of graph/detection state and is primarily a read-only visualization surface.
10. Configuration boundary
rules.json is the main runtime configuration artifact. It controls detection rules, severities, enabled/disabled rules, and whitelist state without recompilation. This makes the system behavior adjustable at deployment time and is important to show as an external configuration input in the architecture diagram.
11. Operating modes
The binary supports at least three operational modes: live TUI monitoring, record to SQLite, and offline replay, plus --no-tui headless execution for automation/SIEM-style pipelines. This means the same core telemetry/detection stack can feed either an interactive UI or non-interactive workflows.
12. Support tooling and validation
scripts/trigger_threats.py is a test harness for generating suspicious behavior on demand, useful for validating the full pipeline end to end. tests/test_tui_logic.cpp shows that at least some UI logic is unit-tested, which implies the dashboard has separable state/formatting logic from rendering.
13. Build and dependency model
The repo uses CMake and depends on Linux-native tooling and libraries: libbpf/clang/LLVM for eBPF, sqlite3 for storage, and UI/utility libraries such as FTXUI, spdlog, fmt, and nlohmann/json. These dependencies materially shape the architecture: kernel probe compilation is separate from the user-space application build.
14. Recommended diagram structure
A good architecture diagram should show:
- Kernel Space: eBPF tracepoint program
- Transport: ring buffer
- User Space Core: main orchestrator
- Processing subsystems: Graph, Detection, Storage, Replay, Dashboard
- Config input: rules.json
- External persistence: SQLite WAL
- Optional outputs: TUI and headless CLI
Main entry points: main.cpp Main · Replay.cpp Replay · Graph.cpp Graph · DetectionEngine.cpp Detection
Components 14
Kernel Space
eBPF telemetry collection in the kernel.
- eBPF probe · Tracepoint-based execve and syscall observer that emits events from the kernel.
ebpf/execve_tracker.bpf.c - vmlinux.h · Kernel type bindings used to build the probe against running kernels.
ebpf/vmlinux.h
User Space
Core runtime and processing subsystems.
- Ring buffer · Kernel-to-user event boundary carrying ordered telemetry into the agent.
- Main · Entry point that wires ingestion, graphing, detection, storage, replay, and UI modes.
src/main.cpp - Graph · Builds live ancestry and behavior relationships between processes and events.
src/graph/Graph.cpp - Node · Represents process nodes and lifecycle state within the process graph.
include/Node.hpp - Detection · Applies rule-driven threat classification over incoming activity.
src/detection/DetectionEngine.cpp - Storage · Persists event timelines for forensic history and later analysis.
src/storage/Storage.cpp - Replay · Replays stored sessions through the analysis pipeline without live kernel hooks.
src/replay/Replay.cpp - Dashboard · Interactive operator view for live process state and detections.
src/tui/Dashboard.cpp
Config & Data
Runtime configuration and persisted forensic data.
- rules.json · Runtime rule set for severities, matching, and whitelists.
rules.json - SQLite WAL · On-disk storage mode used as the append-friendly forensic database.
Tooling
Support scripts and tests.
- Trigger script · Generates suspicious behavior to exercise the full pipeline.
scripts/trigger_threats.py - TUI tests · Validates dashboard state and formatting logic.
tests/test_tui_logic.cpp
Connections 18
- vmlinux.h → eBPF probe: CO-RE types · Kernel bindings used while compiling the eBPF probe.
- eBPF probe → Ring buffer: emit events · Probe sends syscall and process telemetry to user space.
- Ring buffer → Main: ingest · Main runtime consumes the live event stream.
- Main → Graph: builds · Orchestrates construction of the process graph from telemetry.
- Main → Detection: evaluates · Feeds incoming activity into the detection engine.
- Main → Storage: records · Persists event history for forensics and replay.
- Main → Replay: selects mode · Can switch into offline replay execution.
- Main → Dashboard: renders · Drives the interactive TUI in live mode.
- Graph → Node: contains · Graph manages process node state and relationships.
- Detection → rules.json: loads rules · Detection behavior is driven by external configuration.
- Storage → SQLite WAL: persists to · Event ledger is stored in SQLite with WAL mode.
- Replay → SQLite WAL: reads from · Replay consumes persisted sessions from the database.
- Replay → Graph: rebuilds state · Offline playback reconstructs analysis state from history.
- Replay → Detection: re-evaluates · Replayed events can be run through detection again.
- Graph → Dashboard: feeds view · Live graph state is presented in the operator dashboard.
- Detection → Dashboard: shows alerts · Detection results surface as severity-colored findings.
- Trigger script → eBPF probe: stimulates · Generates behavior that should be captured by the live probe.
- TUI tests → Dashboard: validates · Tests the dashboard logic and state formatting.