Installation and Setup

Installation & Setup

This guide covers the full setup of Hybrid R-Sentry on Kali Linux.

---

Prerequisites

• Kali Linux (tested on latest)
• Python 3.13
• Node.js 22
• Docker & Docker Compose
• Git

For eBPF sensor (default mode):

• Linux kernel ≥ 6.19 (uname -r to check)
• BCC 0.35 + kernel headers:

  sudo apt install python3-bpfcc bpfcc-tools linux-headers-$(uname -r) -y

If your kernel is older than 6.19 or BCC install fails, set SENSOR_BACKEND=inotify in .env and the system will fall back to the watchdog-based sensor automatically.

---

Quick Start (recommended)

Step 1 — Clone the Repository

git clone https://github.com/Mohhudib/hybrid-rsentry.git
cd hybrid-rsentry

Step 2 — Install BCC (for eBPF sensor)

sudo apt install python3-bpfcc bpfcc-tools linux-headers-$(uname -r) -y

This is required for the default eBPF sensor backend. Skip this step and set SENSOR_BACKEND=inotify in .env if your kernel is below 6.19.

Verify your kernel version:

uname -r   # must be ≥ 6.19.0

Step 3 — Run First-Time Setup

bash setup.sh

setup.sh handles everything automatically:

• Installs system packages (python3-venv, libpq-dev, iptables, nodejs, npm, etc.)
• Creates the Python virtual environment at ./venv
• Installs all Python dependencies from requirements.txt
• Installs all Node/React dependencies in frontend/
• Copies .env.example to .env if it doesn't already exist

Step 4 — Configure Environment Variables

nano .env

You must fill in:

• POSTGRES_PASSWORD — choose a strong password
• DATABASE_URL — update the password to match
• NVIDIA_API_KEY — your AI provider API key
• NVIDIA_API_KEY_ALERTS — second AI API key (can be the same if you only have one)
• WATCH_PATH — a directory outside the project folder (e.g. /home/your-username/Documents)

See the Configuration page for the full variable reference.

Step 5 — Start Everything

bash start.sh

start.sh starts all five processes in the correct order and logs to /tmp/rsentry-*.log. Press Ctrl+C to stop all services cleanly.

Step 6 — Open the Dashboard

http://localhost:3000

---

Subsequent Runs

Once the venv and node_modules are installed, just run:

bash start.sh

---

Manual Start (for development or debugging)

Use this when you need to see each process's output in its own terminal.

Terminal 1 — Infrastructure

cd ~/hybrid-rsentry && docker compose up -d

Terminal 2 — Backend

cd ~/hybrid-rsentry
set -a && source .env && set +a
source venv/bin/activate
uvicorn backend.main:app --reload

Terminal 3 — Celery Workers

cd ~/hybrid-rsentry
set -a && source .env && set +a
source venv/bin/activate
PYTHONPATH=. celery -A backend.workers.tasks:celery_app worker --loglevel=info

Terminal 4 — Agent

eBPF sensor (default — kernel ≥ 6.19 + BCC required):

cd ~/hybrid-rsentry
set -a && source .env && set +a
sudo -E venv/bin/python -m agent.monitor

Wait until: [ebpf] mode=enforce lsm=True … then [ebpf] BPF loaded.

inotify fallback (any kernel, no BCC needed):

cd ~/hybrid-rsentry
set -a && source .env && set +a
SENSOR_BACKEND=inotify sudo -E venv/bin/python -m agent.monitor

Wait until: Monitor running. Press Ctrl+C to stop.

sudo -E is mandatory — it preserves WATCH_PATH and the AI keys through the privilege boundary. Without -E, sudo strips env vars and the agent watches the wrong path.

Terminal 5 — Frontend

cd ~/hybrid-rsentry/frontend && npm start

Wait until: VITE v5.x.x ready in … ms and Local: http://localhost:3000/

---

Verifying Everything Works

1. Dashboard shows the LIVE connection indicator
2. Agent log shows canary files being placed: tail -f /tmp/rsentry-agent.log
3. Backend log shows heartbeat events arriving: tail -f /tmp/rsentry-backend.log
4. Celery log shows tasks being received: tail -f /tmp/rsentry-celery.log

Run the one-command pipeline test to verify the full detection flow:

bash test_event.sh

This sends a CANARY_TOUCHED event and verifies a CRITICAL alert + AI analysis is produced end-to-end.

---

eBPF Mode

When SENSOR_BACKEND=ebpf (the default), the agent uses the kernel-level sensor for sub-millisecond detection. There are two optional enhancements:

Confirm BCC is loaded

tail -f /tmp/rsentry-agent.log
# Should show: [ebpf] mode=enforce lsm=True threshold=2 window=3.0s
# If it shows BCC import error, run: sudo apt install python3-bpfcc bpfcc-tools linux-headers-$(uname -r) -y

Enable BPF LSM for kernel-level canary blocking (optional)

Without BPF LSM, detection fires after the rename. With BPF LSM, canary renames are blocked before any bytes are overwritten (-EPERM in nanoseconds):

# Edit grub config
sudo nano /etc/default/grub
# Add lsm=bpf to GRUB_CMDLINE_LINUX:
# GRUB_CMDLINE_LINUX="lsm=bpf"
sudo update-grub && sudo reboot

Fall back to inotify (older kernel / no BCC)

# Add to .env:
SENSOR_BACKEND=inotify
# Then restart the agent only (other services don't need to restart)

---

Troubleshooting

Symptom	Cause	Fix
Agent watches wrong path / monitors all of /home	sudo stripped env vars	Always use sudo -E after sourcing .env
Agent log empty after start	BCC not installed	sudo apt install python3-bpfcc bpfcc-tools linux-headers-$(uname -r) -y
Backend port 8000 in use after git pull	Old uvicorn still running	sudo pkill -f uvicorn && bash start.sh
Frontend port 3000 already in use	Previous node process	kill $(lsof -t -i:3000) 2>/dev/null && bash start.sh
npm install fails with ENOTEMPTY	Corrupted node_modules	rm -rf frontend/node_modules && cd frontend && npm install
CRITICAL alerts not auto-containing	Celery worker down	tail /tmp/rsentry-celery.log — source .env before starting Celery

See the Known Issues & Fixes page for the full list of problems and solutions.

---

Stopping the System

If started with start.sh: press Ctrl+C — all processes stop cleanly.

If started manually:

• Ctrl+C in each terminal (frontend, agent, Celery, backend)
• docker compose down to stop PostgreSQL and Redis

Never run docker compose down -v — the -v flag deletes the Postgres data volume and all stored events and alerts.