Skip to content

Configuration

Jump to bottom
adnanalshrouqi edited this page Jun 18, 2026 · 5 revisions

Configuration

All configuration is done via the .env file in the project root. Copy .env.example to get started:

cp .env.example .env

Required Variables

Variable Example Description
POSTGRES_PASSWORD strong-password-here PostgreSQL password — must match DATABASE_URL
DATABASE_URL postgresql+asyncpg://rsentry:strong-password-here@localhost:5432/rsentry_db PostgreSQL async connection string
REDIS_URL redis://localhost:6379/0 Redis connection string
SECRET_KEY 32-char-random-string Secret key for the FastAPI app
HOST_ID ATOMIC Identifier for this monitored endpoint
BACKEND_URL http://localhost:8000 Backend URL used by the agent to post events
WATCH_PATH /home/mohammad/Documents Directory to monitor — must be outside the project folder
NVIDIA_API_KEY nvapi-... API key for live event AI analysis (also readable as AI_API_KEY)
NVIDIA_API_KEY_ALERTS nvapi-... API key for on-demand alert analysis (also readable as AI_API_KEY_ALERTS)

Optional Variables

Variable Default Description
CANARY_COUNT 30 Number of canary files to place across the watch path (uses 4 prefixes: AAA_, aaa_, ZZZ_, zzz_)
SECRET_KEY — Secret key for the FastAPI app (required in production)
SENSOR_BACKEND ebpf Sensor backend: ebpf (5-syscall + BPF LSM, requires BCC + kernel ≥ 6.19) or inotify (userspace watchdog). Use inotify if kernel is too old or BCC is not installed.
DRY_RUN false Set to true to disable actual containment actions (SIGSTOP, iptables, SIGKILL). Evidence is still captured and all alerts/events are created normally. Safe for testing.
AI_API_KEY_CEREBRAS (unset) Cerebras API key — if set, Cerebras becomes the primary AI provider (fastest, ~200ms); NVIDIA/Groq keys are used as fallback
GROQ_API_KEY (unset) Groq API key — alternative to passing Groq keys through NVIDIA_API_KEY slots
GROQ_BASE_URL https://api.groq.com/openai/v1 Groq API base URL
GROQ_MODEL llama-3.3-70b-versatile Groq model name used for AI analysis

AI Provider Notes

Multi-Provider Fallback Chain

The AI analyst tries providers in this order:

  1. Cerebras — if AI_API_KEY_CEREBRAS is set (fastest, ~200ms)
  2. NVIDIA / Groq (key 1) — NVIDIA_API_KEY
  3. NVIDIA / Groq (key 2) — NVIDIA_API_KEY_ALERTS

Groq keys are auto-detected by the gsk_ prefix. NVIDIA keys start with nvapi-.

Two API Keys

Using two separate keys for live event analysis and on-demand alert analysis prevents one from rate-limiting the other. If you only have one key, set both variables to the same value:

NVIDIA_API_KEY=your-key-here
NVIDIA_API_KEY_ALERTS=your-key-here

Important Notes

WATCH_PATH

Must be set outside the project directory. If WATCH_PATH points inside ~/hybrid-rsentry/, canary files will be placed inside the git repository and corrupt .git/refs/.

✅ Correct: WATCH_PATH=/home/mohammad/Documents
❌ Wrong: WATCH_PATH=/home/mohammad/hybrid-rsentry

The agent will detect this mistake at startup and exit immediately with a clear error message.

Running the Agent with sudo

The agent requires sudo for iptables rules and SIGKILL. Always use sudo -E and source .env first so env vars survive the privilege boundary:

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

BPF LSM Canary Blocking (Optional, Maximum Protection)

For kernel-level canary blocking (-EPERM in nanoseconds, no userspace roundtrip), activate the BPF LSM:

# Add lsm=bpf to your kernel boot parameters:
sudo nano /etc/default/grub
# Set: GRUB_CMDLINE_LINUX="lsm=bpf"
sudo update-grub && sudo reboot

Without this, the eBPF sensor still detects and SIGSTOP-contains, but the blocking happens in userspace after the rename is observed.

Static Docker Network

docker-compose.yml uses a static network 192.168.100.0/24:

Service IP
Backend (FastAPI) 192.168.100.10
PostgreSQL 192.168.100.20
Redis 192.168.100.30

The DATABASE_URL and REDIS_URL in .env use localhost (for the agent running outside Docker) while the Dockerized services use their internal IPs for container-to-container communication. No changes needed to .env — the Docker Compose file injects the correct internal URLs into the containerized services automatically.

Full .env Example

# Database
POSTGRES_PASSWORD=change-me-choose-a-strong-password
DATABASE_URL=postgresql+asyncpg://rsentry:change-me-choose-a-strong-password@localhost:5432/rsentry_db
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=change-me-in-production-use-32-chars

# Agent
HOST_ID=ATOMIC
BACKEND_URL=http://localhost:8000
WATCH_PATH=/home/mohammad/Documents
CANARY_COUNT=30

# Sensor backend — ebpf (default) requires python3-bpfcc + kernel 6.19+
# Set to inotify if BCC is not installed or kernel is too old
# SENSOR_BACKEND=inotify

# Dry run — disables actual containment actions (for testing)
# DRY_RUN=true

# AI — primary + fallback keys
NVIDIA_API_KEY=your-nvidia-or-groq-api-key-here
NVIDIA_API_KEY_ALERTS=your-nvidia-or-groq-api-key-here

# AI — optional Cerebras (becomes primary if set)
# AI_API_KEY_CEREBRAS=csk-your-cerebras-key-here

Clone this wiki locally