Skip to content

Installation and Setup

Jump to bottom
Mohhudib edited this page May 29, 2026 · 5 revisions

Installation & Setup

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

Prerequisites

  • Kali Linux (tested on latest)
  • Python 3.13
  • Docker & Docker Compose
  • Git

Quick Start (recommended)

Step 1 — Clone the Repository

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

Step 2 — 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 3 — 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 4 — 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 5 — 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

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

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

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.

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.

Clone this wiki locally