For Engineers — XDRagon Monitor

Three Layers. One Pipeline.

Three-layer service stack

XDRagon Monitor runs as a Docker Compose stack. Services are grouped into data collection, AI processing, and user interface layers — each independently scalable and replaceable.

Collection & Storage

Suricata.x
suricata.service — EVE-JSON output, custom rules, Sigma rule engine, pfBlockerNG integration

TimescaleDB
timescaledb — time-series hypertables for alert logs and metrics with auto-compression

PostgreSQL 16
postgres — relational data, agent configs, compliance evidence store, pgvector extension

Redis 7
redis — Celery broker, task queues, short-lived alert buffers, session state

AI & Processing

FastAPI
backend — REST + WebSocket API, Pydantic v2 schemas, async SQLAlchemy ORM

Celery + APScheduler
worker — 7 autonomous background jobs, queue-based task dispatch, retry logic

Ollama
ollama — local LLM runtime, 6 custom Modelfiles, GPU/CPU inference, context streaming

scikit-learn + XGBoost
ml-engine — ML detectors loaded at startup, inference <15ms per event

Interface & Integration

React 19 + Vite
frontend — TypeScript, Tailwind CSS, Recharts, WebSocket live feed

pfSense / UniFi API
firewall-connector — read-only rule sync, pfBlockerNG log ingestion, UniFi client tracking

10+ Threat Intel Sources
downloader-outside — URLhaus, ThreatFox, AbuseIPDB, VirusTotal, AlienVault OTX, GreyNoise, urlscan.io, Shodan, CISA KEV, MalwareBazaar, CINS Army, Blocklist.de

Endpoint XDR Agent
xdr-agent — Windows + Linux, Go binary, eBPF on Linux, WMI on Windows

Named Detectors. Zero Cloud.

The detection stack

Isolation Forest, XGBoost triage, HDBSCAN clustering, DGA classification, DNS-over-HTTPS detection, JA3/TLS fingerprinting, graph-based lateral movement, semantic alert deduplication, statistical C2 beaconing, and retrospective IOC hunting — every detector runs entirely on-premises. No external inference API, no data leaving your environment.

Layer 1 — Statistical & signature

Statistical C2 Beaconing

detect_beaconing · interval statistics

Statistical interval-regularity analysis of connection timing per source/destination pair. Highly regular check-in intervals — the signature of automated C2 traffic — are flagged without needing a trained model or labeled data. Runs every 15 minutes as an autonomous background job.

Statistical Interval regularity 15 min interval C2 Beaconing

DNS Payload Analysis

dns_tunnel_detector.pkl · payload entropy

DNS tunneling detector measuring abnormal query lengths, TXT/NULL record usage, and subdomain randomness. Detects iodine, dnscat2, and custom exfiltration tools. Conservatively calibrated against real-world DNS profiles to keep noise low, with a whitelist engine for known-good domains.

Payload entropy Whitelist engine Real-time DNS Tunneling

JA3/TLS Fingerprinting

ja3 · TLS handshake analysis

Fingerprints encrypted traffic without decrypting it. JA3 hashes of TLS handshakes are matched against known C2 frameworks — Cobalt Strike, Metasploit, Sliver, and others — exposing malware that hides inside TLS.

JA3 hashes Encrypted traffic Known C2 frameworks TLS Threat

DNS-over-HTTPS Detection

doh_detector · resolver analysis

Detects clients bypassing your internal DNS through known DoH providers — a common technique for hiding C2 resolution and exfiltration from network monitoring (MITRE T1071.004).

DoH providers DNS bypass MITRE T1071.004 DNS Threat

Layer 2 — Machine learning

Isolation Forest

anomaly_detector.pkl · scikit-learn

Unsupervised anomaly detection over a 17-dimensional behavioral baseline of the network. Identifies rare traffic patterns without requiring labeled attack data — the zero-day patterns and low-and-slow movement that signature engines miss.

Unsupervised 17-dim baseline Zero-day patterns Anomaly Detection

Shannon Entropy — DGA

dga_detector.pkl · character n-grams

Domain generation algorithm classifier using character n-gram frequency distributions combined with Shannon entropy scoring. Retrained regularly on a large corpus of known-legitimate domains, so its baseline of legitimate naming patterns never goes stale. Runs at query time on DNS lookups.

n-gram model Known-good corpus Regular retraining DNS Threat

XGBoost Triage

triage_model.pkl · gradient boosting

Supervised triage model that recognises well-known attack patterns and routes well-understood, low-risk alerts away from the analyst queue automatically. Analysts only spend time on alerts that actually need human judgement.

Supervised Automated routing Queue reduction Alert Triage

HDBSCAN Alert Clustering

hdbscan · density clustering

Groups related alerts by multi-dimensional similarity — source-IP overlap, MITRE tactic, target overlap, time proximity, and signature distance. Re-clusters every 5 minutes, turning a flood of raw alerts into a handful of actionable incidents.

Unsupervised Multi-dimensional 5 min re-clustering Noise Reduction

Layer 3 — Graph, semantic & retrospective

Graph Lateral Movement

networkx · graph analytics

Builds a communication graph of the network and applies centrality analysis against the learned baseline to surface pivot nodes and new subnet crossings — including how long an attack path has been active, distinguishing automated from hands-on-keyboard movement.

Graph analytics Pivot detection MITRE T1021 Lateral Movement

pgvector RAG Index

nomic-embed-text · 768-dim vectors

Semantic similarity store for the AI analyst's retrieval-augmented generation. Embeds historical alerts, playbook entries, and threat intel summaries into 768-dimensional vectors using nomic-embed-text. Enables analysts to ask natural-language questions over months of alert history.

768 dimensions cosine similarity nomic-embed-text RAG

Semantic Alert Deduplication

pgvector · embedding similarity

Embeds every alert and groups near-duplicates by semantic similarity across event, TLS, and graph detectors — the core of XDR noise reduction. Analysts review one grouped incident instead of dozens of restatements of the same activity.

Embeddings Cross-detector Noise reduction Deduplication

Retrospective IOC Hunting

retro_hunt · historical matching

Every new threat indicator — IP, domain, URL, or file hash — is automatically matched against up to 180 days of historical events, with an hourly background scan plus on-demand backfill. Yesterday's traffic gets re-judged with today's intelligence.

Up to 180 days Hourly scan On-demand backfill Retro-Hunt

MITRE Coverage Heatmap

attack_coverage · ATT&CK Navigator

Live heatmap of detection coverage across all 14 MITRE ATT&CK tactics, with blind-spot recommendations and ATT&CK Navigator export — so you know exactly what the stack sees and what it doesn't.

14 tactics Blind-spot analysis Navigator export Coverage

Threat Actor Profiles

mitre_actors · weekly sync

Known threat actor profiles synced from MITRE — targeted sectors, country of origin, and preferred techniques — linked to IP reputation, so an alert can be traced to the tradecraft of a named group on a dedicated actor detail page.

MITRE-sourced Actor attribution Technique mapping Attribution

On-Prem. Always Private.

Six custom Ollama Modelfiles

Each model is a task-tuned, system-prompted specialisation of qwen2.5:7b-instruct-q4_K_M (~4.7 GB). Embeddings for the pgvector RAG store are handled by nomic-embed-text. Everything runs fully locally via the Ollama runtime — no API keys, no internet required.

soc-alert-classifier

deterministic JSON triage · temp 0.1 / ctx 2048

CLASSIFIER+

# Modelfile: soc-alert-classifier
FROM qwen2.5:7b-instruct-q4_K_M
PARAMETER temperature 0.1
PARAMETER num_ctx 2048
SYSTEM """
You are a classification engine. Given a security alert,
output ONLY valid JSON with severity, category, confidence,
and MITRE ATT&CK technique. No prose. No explanation.
"""

Used by the autonomous classification job every 2 minutes. Low temperature keeps the JSON output reproducible, and every response is validated by Pydantic before it touches the database.

soc-alert-explainer

streamed analyst explanations · temp 0.3 / ctx 4096

ANALYST+

# Modelfile: soc-alert-explainer
FROM qwen2.5:7b-instruct-q4_K_M
PARAMETER temperature 0.3
PARAMETER num_ctx 4096
SYSTEM """
You are a senior SOC analyst. Explain what an alert means,
why it fired, and what to check next — with MITRE ATT&CK
context and concrete, actionable recommendations.
"""

Powers on-demand alert explanations, streamed token-by-token over SSE. The 4K context window carries the full alert plus enrichment data, so explanations are grounded in the actual event — not generic advice.

soc-correlation-engine

batch incident correlation · temp 0.2 / ctx 8192

CORRELATOR+

# Modelfile: soc-correlation-engine
FROM qwen2.5:7b-instruct-q4_K_M
PARAMETER temperature 0.2
PARAMETER num_ctx 8192
SYSTEM """
You correlate multiple security alerts into unified
incidents. Map observed indicators to MITRE ATT&CK,
identify source IP, affected assets, and estimated
attack stage. Output structured JSON only.
"""

Runs every 10 minutes over recent alerts. The 8K context window lets whole alert batches be correlated in a single pass; results surface as grouped incidents in the dashboard.

soc-customer-summary

plain-language summaries · temp 0.5 / ctx 2048

SUMMARY+

# Modelfile: soc-customer-summary
FROM qwen2.5:7b-instruct-q4_K_M
PARAMETER temperature 0.5
PARAMETER num_ctx 2048
SYSTEM """
You translate technical security incidents into plain
language for non-technical readers. No jargon. State what
happened, the impact, and what is being done about it.
"""

Generates the plain-language view of incidents for business stakeholders. Higher temperature for natural prose — but grounded strictly in the incident's own events, never speculation.

soc-nl-filter

NL → validated JSON filters · temp 0.1 / ctx 1024

NL FILTER+

# Modelfile: soc-nl-filter
FROM qwen2.5:7b-instruct-q4_K_M
PARAMETER temperature 0.1
PARAMETER num_ctx 1024
SYSTEM """
You convert natural-language search requests into structured
JSON filter objects. Output ONLY the JSON filter —
never raw SQL, never free text.
"""

Powers natural-language search across Events, Behavior (UEBA), and the network graph. The model only ever emits a structured query that is whitelist-validated before execution — raw SQL never reaches the database, regardless of what the model outputs.

soc-daily-briefing

daily 07:00 briefing · temp 0.4 / ctx 4096

BRIEFER+

# Modelfile: soc-daily-briefing
FROM qwen2.5:7b-instruct-q4_K_M
PARAMETER temperature 0.4
PARAMETER num_ctx 4096
SYSTEM """
You write concise daily security briefings for SMB security
teams. Given 24h alert summaries, produce: executive summary,
top events with context, and recommended actions ranked by
priority. Plain English.
"""

Generates the morning briefing at 07:00 daily as an autonomous background job. Higher temperature for readable prose; the briefing is pinned on the dashboard and can be delivered by email or Telegram.

From Packet to Alert.

From packet capture to alert

Step-by-step data flow with latency targets at each stage and the services responsible.

Packet Capture

Suricata listens on the mirror/SPAN port (or inline with NFQ). EVE-JSON events streamed to Redis queue within milliseconds of detection.

AF_PACKETNFQUEUE<5ms

Event Normalisation

Celery worker consumes Redis queue. Parses EVE-JSON, enriches with GeoIP, reverse-DNS, and threat intel lookups. Inserts into TimescaleDB hypertable.

CeleryGeoIP2<200ms

ML Scoring

Isolation Forest scores each event against the 17-dimensional behavioral baseline in real time. DGA, DoH, and JA3/TLS classifiers score DNS and TLS events; XGBoost triage routes well-understood, low-risk alerts away from the analyst queue. Statistical beaconing analysis runs every 15 minutes.

scikit-learnXGBoost<15ms/event

LLM Classification

soc-alert-classifier assigns severity and MITRE category. Runs in batches every 2 minutes. Structured JSON output validated before storage.

Ollama2 min batchPydantic v2

Incident Correlation

soc-correlation-engine groups related alerts into incidents every 10 minutes, with semantic deduplication collapsing near-identical alerts along the way. Results surface as correlated incidents in the dashboard.

LLM correlation10 minMITRE ATT&CK

Dashboard & Alerting

React frontend subscribes to FastAPI WebSocket. Critical alerts push immediately. Smart alert rules evaluated on each classification event to prevent alert fatigue.

WebSocket7 alert rulesReal-time

Latency & Throughput Targets

EVE-JSON → Redis

< 5ms

Normalisation + enrich

< 200ms

ML scoring / event

< 15ms

LLM classification (batch)

< 3s/batch

WebSocket push to UI

< 50ms

Event throughput

10K+ ev/s

Resource Baseline (Segmented Mode)

CPU (idle)

4–8 cores

RAM (all services)

12–16 GB

Storage (90-day logs)

~120 GB

LLM inference (GPU)

RTX 3060+

LLM inference (CPU)

~8s/response

Security & Privacy

Built-in security posture

XDRagon Monitor is designed to handle sensitive network telemetry — and is built like the target it will inevitably become. These are the architectural decisions that govern how data is handled, transported, and protected.

mTLS service mesh

All inter-service communication is encrypted with mutual TLS. Certificates auto-generated at first run via internal CA. Redis, TimescaleDB, and Ollama only accept authenticated connections from the FastAPI backend.

Zero cloud dependency

No telemetry, no licensing calls, no model downloads after initial setup. Every inference runs on the local Ollama runtime. Threat intel APIs are optional and individually configurable — the platform functions fully offline.

Air-gap compatible

Docker images and Ollama models can be loaded from a private registry or USB media. The platform runs on networks with no internet access. Sigma rules and threat intel can be synced manually or via internal feeds.

Role-based access & MFA

Two built-in roles — admin and analyst — with offline TOTP multi-factor authentication, bcrypt password hashing, and JWT-based sessions with configurable expiry. Every user action lands in the audit log. Integration API keys are stored as SHA-256 hashes; the raw key is shown exactly once.

Read-only sensor mode

The network sensor (Suricata) operates in passive IDS mode by default. IPS blocking requires explicit opt-in and separate configuration. All firewall integrations (pfSense, OPNsense, FortiGate, Sophos, UniFi) are read-only — XDRagon Monitor never modifies firewall rules without operator approval.

Append-only audit trail

All alert classifications, analyst actions, and compliance evidence entries land in an append-only audit trail with row-level security and cryptographic timestamps for legal defensibility.

Modern token architecture

Short-lived in-memory access tokens paired with httpOnly refresh cookies — no tokens in localStorage, ever. Refresh tokens rotate on every use, and replay detection revokes the entire token family if a stolen token is reused. CSRF protection on all state-changing requests.

Secrets encrypted at rest

Every stored secret — API keys, integration tokens, firewall credentials — is Fernet-encrypted in PostgreSQL rather than sitting in plaintext config files, and masked in every API response. A compromised database dump does not hand over your keys.

Tested like a target

The platform runs its own DAST scanner against every build, and a CI authorization gate flags API routes missing authentication, so unprotected endpoints are caught before merge. Backed by 800+ automated tests.

Verifiable releases (SLSA/Sigstore)

Releases ship with SLSA build provenance, keyless-signed via Sigstore. Anyone can cryptographically verify that the artifact they run was built from the public source — provable supply-chain integrity for the software watching your network.

Integration

REST API & WebSocket

The FastAPI backend exposes a full REST API with OpenAPI docs at /docs. WebSocket endpoints power real-time alert streaming. All endpoints accept JWT bearer tokens or API keys.

Key REST Endpoints

GET /api/v1/alerts	Paginated alert list with filters
POST /api/v1/ai/analyze	Trigger on-demand LLM analysis
GET /api/v1/compliance/score	Current NIS2/NIST/CIS scores
GET /api/v1/dns/analytics	DNS threat and DGA results
POST /api/v1/hunt	Natural-language threat hunt
WS /ws/alerts	Real-time alert stream

Example: Trigger Analysis

# Analyze alert ID 12345
curl -X POST https://your-xdragon.local/api/v1/ai/analyze \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alert_id": 12345, "model": "analyst"}'

# Response
{
  "severity": "high",
  "summary": "Suspected C2 beaconing to 185.220.101.x",
  "mitre": "T1071.001",
  "confidence": 0.87,
  "actions": ["block_ip", "isolate_host"]
}

Built by practitioners,
for practitioners

End-to-end detection pipeline

Three-layer service stack

The detection stack

Six custom Ollama Modelfiles

From packet capture to alert

Built-in security posture

REST API & WebSocket

Installation guide & full documentation

Built by practitioners,for practitioners

End-to-end detection pipeline

Three-layer service stack

The detection stack

Six custom Ollama Modelfiles

From packet capture to alert

Built-in security posture

REST API & WebSocket

Installation guide & full documentation

Built by practitioners,
for practitioners