Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                      Linux Endpoint                          │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                    Agent Layer                         │  │
│  │                                                       │  │
│  │  ┌──────────────┐  OR  ┌───────────────────────────┐ │  │
│  │  │  inotify     │      │  eBPF Sensor              │ │  │
│  │  │  (watchdog)  │      │  (TRACEPOINT_PROBE,       │ │  │
│  │  │  monitor.py  │      │  kernel 6.19+, BCC 0.35)  │ │  │
│  │  └──────┬───────┘      └─────────────┬─────────────┘ │  │
│  │         └──────────┬─────────────────┘               │  │
│  │                    ▼                                  │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐ │  │
│  │  │   Entropy   │  │   Lineage   │  │  Extension   │ │  │
│  │  │   Engine    │  │   Scorer    │  │  Detection   │ │  │
│  │  └─────────────┘  └─────────────┘  └──────────────┘ │  │
│  │         │                 │                │          │  │
│  │         ▼                 ▼                ▼          │  │
│  │  ┌─────────────┐  ┌─────────────────────────────┐   │  │
│  │  │   Markov    │  │   Tree-Aware Auto-Containment│   │  │
│  │  │ Repositioner│  │ SIGSTOP→evidence→iptables→kill│   │  │
│  │  └─────────────┘  └─────────────────────────────┘   │  │
│  └───────────────────────────────────────────────────────┘  │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTP POST /api/events
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                     FastAPI Backend                          │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────┐   │
│  │   Events    │  │   Alerts    │  │      Hosts       │   │
│  │   Router    │  │   Router    │  │      Router      │   │
│  └──────┬──────┘  └─────────────┘  └──────────────────┘   │
│         │                                                   │
│         ▼                                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────┐   │
│  │   Celery    │  │ PostgreSQL  │  │      Redis       │   │
│  │   Workers   │  │  Database   │  │  (3 WS channels) │   │
│  └─────────────┘  └─────────────┘  └────────┬─────────┘   │
└────────────────────────────────────────────┬─┘             │
                                             │ WebSocket      │
                                             ▼               │
┌─────────────────────────────────────────────────────────────┐
│              React 19 SIEM Dashboard (Vite 5)                │
│                                                             │
│  TopBar: Overview · Alerts · Hosts · Detections · AI · PDF  │
│  FacetRail filter │ MetricsStrip │ AlertsHistogram          │
│  AlertsTable + DetailFlyout (D3 force graph)                │
│  StatusBar: agents · EPS · WS status · cluster              │
└─────────────────────────────────────────────────────────────┘

Component Breakdown

Agent (`agent/`)

Runs on the monitored Linux endpoint. Supports two sensor backends: inotify (via watchdog) and eBPF (kernel-level tracepoints). Both emit the same event interface to the rest of the pipeline.

File	Role
`monitor.py`	Main orchestrator — inotify backend; `_validate_watch_path()` exits if WATCH_PATH inside git repo
`monitor_ebpf.py`	eBPF sensor — TRACEPOINT_PROBE rename syscalls; velocity burst detection; ransomware family profiling (LockBit5/Akira/ESXi); IGNORE_COMMS FP suppression; kernel 6.19+, BCC 0.35
`graph.py`	Filesystem graph, BFS canary placement, orphan cleanup
`entropy.py`	Rolling Shannon entropy delta engine; 5000-file LRU memory cap; 65 KB partial reads
`lineage.py`	Process ancestry scorer (0–100); dpkg hash verification (416 K hashes); SHA-256 LRU cache
`adaptive.py`	Markov chain canary repositioner; `_is_safe_target()` blocks system paths
`containment.py`	Tree-aware SIGSTOP → evidence capture → iptables DROP → SIGKILL; PID resolved from /proc
`client.py`	HTTP client that sends events to the backend
`exceptions.py`	Whitelist rules + smart /tmp filter to suppress false positives

Sensor backend selection: Set SENSOR_BACKEND=ebpf (default) or SENSOR_BACKEND=inotify in .env. eBPF requires python3-bpfcc installed and kernel ≥ 6.19.

eBPF sensor capabilities (current — v2.1.0):

5-syscall behavioral detection: openat, vfs_write, unlink, rename, execve
proc_profile BPF map: 10,000-entry per-process behavioral profile (files_opened, files_written, files_deleted, files_renamed, child_procs, write_bytes, score 0–100, alerted flag)
BPF LSM canary_inodes map: blocks canary renames with -EPERM in nanoseconds (requires lsm=bpf kernel boot param)
blocked_pids BPF map: velocity burst blocks all subsequent renames by the offending PID at kernel level
Ransomware family profiling: LockBit 5.0 (16-char ext, two-pass), Akira (.akiracrypt, intermittent), ESXi (.vmdk/.vmx/.vmem)
IGNORE_COMMS: 40+ known benign processes suppressed before any scoring (Docker, Redis, git, apt, npm, uvicorn, Celery, Firefox, etc.)
Markov repositioning is disabled in eBPF mode (proc_profile BPF map tracks directory access patterns directly)

Backend (`backend/`)

FastAPI application that receives events, stores them, manages alerts, and pushes live updates.

File	Role
`main.py`	FastAPI app entry point, DB table creation on startup
`routers/events.py`	Ingests agent events, creates alerts, dispatches Celery tasks
`routers/alerts.py`	Alert CRUD, acknowledge, AI analyze, forensic export endpoint
`routers/hosts.py`	Host inventory, risk summary (`alert_count`, `event_count`), contain/release
`routers/ws.py`	WebSocket endpoint subscribing to 3 Redis pub/sub channels
`workers/tasks.py`	All Celery async tasks (WS push, AI analysis, risk update, auto-ACK)
`services/ai_analyst.py`	Multi-provider AI: Cerebras → NVIDIA/Groq fallback; PENDING state; 24h Redis cache
`models/schemas.py`	SQLAlchemy ORM models + Pydantic schemas

Frontend (`frontend/src/`)

React 19 SIEM dashboard with Kibana-style layout, D3 force graph, and live WebSocket updates.

File	Role
`App.jsx`	Root component; TopBar + StatusBar layout; WebSocket + AI state; passes `liveEvent` to AlertsPage
`index.jsx`	Entry point (.jsx required by Vite production build)
`index.css`	CSS variable design system (`--bg`, `--panel`, `--crit`, `--accent` etc.) + SIEM utility classes
`vite.config.js`	Vite: React plugin + proxy (/api, /ws) + `process.env` shim
`components/TopBar.jsx`	Horizontal nav bar (replaces Sidebar) — brand + 6 tabs + alert badge
`components/StatusBar.jsx`	Bottom status bar — agents, EPS, WS status, last refreshed, cluster
`components/FacetRail.jsx`	Left filter panel on Alerts page — collapsible field groups
`components/MetricsStrip.jsx`	6 live metrics (open/critical/high/hosts/EPS/event types)
`components/AlertsHistogram.jsx`	Stacked 30-min histogram from `/api/events`
`components/AlertsTable.jsx`	Sortable alerts table — severity dot, risk meter, status
`components/DetailFlyout.jsx`	Right flyout on alert click — Summary/Entity/MITRE/Filesystem graph/Raw JSON
`components/EventDetailModal.jsx`	Modal on TacticalResponseLog event click — same sections as flyout
`components/FileSystemGraph.jsx`	D3 v7 Obsidian-style force-directed graph — zoom/drag/tooltip; selected node pulled to center
`components/FileSystemTree.jsx`	Text tree (Detections page only) — `highlightPath` + `compact` props
`components/TacticalResponseLog.jsx`	Event rows — now clickable → opens EventDetailModal
`pages/AlertsPage.jsx`	3-column SIEM layout: FacetRail + (MetricsStrip + Histogram + Table) + DetailFlyout
`pages/Overview.jsx`	Dashboard — EventChart, AlertFeed, TacticalResponseLog, HostRiskPanel
`pages/AIAnalystPage.jsx`	AI analysis cards with pending spinners and health check
`pages/HostsPage.jsx`	Host cards with radial risk gauge, alert breakdown, contain/release
`pages/FilesystemPage.jsx`	"Detections" in nav — FileSystemTree with search
`pages/ReportsPage.jsx`	PDF forensic export — date/severity filter + host overview table

Navigation tab mapping (TopBar):

Tab	Page
Overview	Dashboard (EventChart, TacticalResponseLog, etc.)
Alerts	3-column SIEM AlertsPage
Hosts	HostsPage
Detections	FilesystemPage
AI Analyst	AIAnalystPage
Reports	ReportsPage

Simulations (`simulations/`)

Attack simulation scripts used to validate detection performance.

File	Role
`sim_common.py`	Shared engine — profile, corpus population, run_attack, backup/restore
`sim_lockbit.py`	LockBit 5.0 two-pass simulation with 16-char extension
`sim_akira.py`	Akira intermittent encryption simulation
`sim_qilin.py`	Qilin percent-encryption simulation
`sim_dfs.py`	Generic depth-first traversal simulation — triggers canary detection
`sim_depth.py`	Generic depth-first simulation with configurable traversal depth
`sim_random.py`	Generic random-order encryption simulation — triggers entropy spike
`sim_all.py`	Runs all simulations sequentially — full detection coverage validation
`sim_writeoffset_only.py`	Isolates write-offset detection layer — proves layer necessity independent of entropy/canary signals

Data Flow

File modified on disk
        │
        ▼
inotify (watchdog) OR eBPF TRACEPOINT_PROBE fires
        │
        ▼
monitor._handle_event() / eBPF perf event callback
   ├── _validate_watch_path() checked at startup
   ├── is_whitelisted? → skip
   ├── is_canary? → CRITICAL immediately
   ├── ransomware extension rename? → CRITICAL or HIGH
   ├── entropy.observe() → entropy delta
   ├── lineage.score_for_event() → suspicion score
   └── combined_score() → final severity
        │
        ▼
client.send_event() → POST /api/events
        │
        ▼
Backend creates Event + Alert in PostgreSQL
        │
        ├── push_event_ws.delay() → Redis rsentry:events
        ├── push_alert_ws.delay() → Redis rsentry:alerts
        ├── update_host_risk.delay() → recalculate risk score
        └── analyze_event_ai.delay()
              │
              ├── publish PENDING → Redis rsentry:ai (immediate)
              ├── call AI provider (Cerebras → NVIDIA → Groq)
              ├── cache result in Redis (24h)
              └── publish ai_analysis_update → Redis rsentry:ai
                          │
                          ▼
                WebSocket → React SIEM dashboard

Demo Tools (root)

File	Role
`demo_forensic.py`	Standalone forensic walkthrough — BEFORE/ATTACK/AFTER cycle against a persistent corpus; leaves artifacts on disk for manual inspection (unlike sandboxed simulations which clean up automatically)

Database Schema

Table	Description
`hosts`	Registered endpoints with risk score and containment status
`events`	All detection events from the agent
`alerts`	Alerts generated for HIGH/CRITICAL/MEDIUM events
`evidence`	Forensic evidence captured during containment

Docker Network

docker-compose.yml uses a static bridged network (192.168.100.0/24) to give each service a predictable IP:

Service	Container IP
FastAPI backend	`192.168.100.10`
PostgreSQL	`192.168.100.20`
Redis	`192.168.100.30`

The agent runs outside Docker on Kali and connects to localhost:8000 (backend) / localhost:5432 (Postgres) / localhost:6379 (Redis) via the host-mapped ports. Containerized Celery workers use the internal IPs injected by Compose.

Redis Channels

Channel	Purpose
`rsentry:alerts`	New alerts and acknowledgment notifications
`rsentry:events`	New detection events for live feed
`rsentry:ai`	AI analysis results (PENDING + final), health check results

Frontend Design System

The dashboard uses a CSS variable design system defined in index.css:

Variable	Value	Purpose
`--bg`	`#131519`	Page background
`--panel`	`#191b21`	Card / panel background
`--panel-2`	`#1e2027`	Elevated panel
`--border`	`#2b2e37`	Borders
`--crit`	`#d8503c`	Critical severity
`--high`	`#d6873a`	High severity
`--med`	`#c9b13f`	Medium severity
`--low`	`#5b8fb0`	Low severity
`--accent`	`#4f8cc9`	Interactive accent
`--ok`	`#4e9e7e`	Success / healthy

Typography: IBM Plex Sans (body) + IBM Plex Mono (code/data fields), loaded from Google Fonts via index.html. Icons: Font Awesome 6.5.1 (CDN).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Architecture

Architecture

System Overview

Component Breakdown

Agent (`agent/`)

Backend (`backend/`)

Frontend (`frontend/src/`)

Simulations (`simulations/`)

Data Flow

Demo Tools (root)

Database Schema

Docker Network

Redis Channels

Frontend Design System

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Architecture

Architecture

System Overview

Component Breakdown

Agent (agent/)

Backend (backend/)

Frontend (frontend/src/)

Simulations (simulations/)

Data Flow

Demo Tools (root)

Database Schema

Docker Network

Redis Channels

Frontend Design System

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Agent (`agent/`)

Backend (`backend/`)

Frontend (`frontend/src/`)

Simulations (`simulations/`)