RavenXcope Documentation
Welcome to the RavenXcope technical documentation — a comprehensive defense center platform for network sensor management, security analytics, and threat monitoring.
What is RavenXcope?
RavenXcope is a multi-service platform that provides:
- Sensor lifecycle management — Register, enroll, monitor, and configure network sensors across distributed locations.
- Virtual sensor deployment — Deploy and manage virtual sensor workloads on physical sensor hosts.
- Security analytics — Aggregate and visualize IDS/IPS alerts from OpenSearch with rich filtering, charting, and PDF export.
- Organization-scoped access control — Multi-tenant user, role, and permission management.
- AI-powered analytics chat — Optional LLM-backed conversational analytics with citation support.
Platform Architecture
RavenXcope separates the platform into three main flows: the control plane for onboarding, identity, commands, and status; the data plane for IDS/IPS alerts from sensor hosts into the analytics pipeline; and the state/read plane for persistence, metrics, cache, and dashboard queries.
Documentation Sections
Backend
Technical documentation for the Ravenxcope Backend — the central .NET API service. Covers architecture, startup pipeline, configuration, and all feature modules (auth, sensors, analytics, assets, locations, organizations, roles, and permissions), plus its control-plane integrations (claim codes, gRPC mTLS, NATS).
Frontend
Technical documentation for the Ravenxcope Frontend — a React single-page application. Covers architecture, routing, authentication, API integration, and all feature modules (sensor dashboard, analytics, user/role management).
Sensor
The unified ravenxcope-sensor Go binary that runs on each sensor host. Covers enrollment + PKI, Suricata supervision, heartbeat, and the eve.json alert relay. Supersedes the legacy sensor-agent and sensor-suricata client.
Data Collector
The sensor-api service that receives alerts over gRPC and produces them to Kafka (sensor_events).
Event Aggregator
event-stream-aggr — consumes sensor_events, enriches with geo/IP data, and produces snort_alerts + ravenxcope_threat_geo_events.
Suricata Image
The containerized Suricata IDS/IPS engine: entrypoint, IDS vs IPS templates, and bundled config files.
NATS Provisioner
The decentralized-auth control service that issues NATS account/user credentials for secure sensor command and status messaging.
Deployment
The defense_center-deployment compose stack: service inventory, messaging/storage (Kafka, Logstash, OpenSearch, Postgres, Redis, InfluxDB), and the backend configuration reference.
Scenarios
End-to-end walkthroughs that tie the services together: the Control Plane (onboarding and commanding a sensor) and the Data Plane (an alert's journey from Suricata to the dashboard).
Quick Links
| Topic | Backend | Frontend |
|---|---|---|
| Overview | Backend Overview | Frontend Overview |
| Architecture | Backend Architecture | Frontend Architecture |
| Configuration | Backend Config | Frontend Config |
| Deployment | Backend Runbook | Frontend Runbook |
| Development | Backend Dev Guide | Frontend Dev Guide |
Start here: new to the architecture? Read Evolution from Mataelang, then the Control Plane and Data Plane scenarios.