idps-escape

RADAR documentation

Comprehensive documentation for RADAR (Risk-aware Anomaly Detection-based Automated Response) - the automated response system for IDPS-ESCAPE.

⚠️ All commands should be run from project root (/home/alab/soar)

For operational quickstart: See radar/README.md for scenarios overview, deployment outcomes, and visual examples.

Documentation overview

Document	Purpose	Audience	Est. Time
Getting started	Prerequisites, setup, deployment modes	Everyone	30 min
Architecture	System design, principles, components	Developers & Architects	45 min
Ansible playbook	Wazuh manager automation pipeline	DevOps & SRE	60 min
Run RADAR workflow	Detector and monitor creation	Operators & DevOps	20 min
Active response	Response logic, risk engine, tiering	Developers	40 min
Detection rules	Wazuh rule definitions	Security Analysts	25 min
Adversarial ML guidance	Robustness best practices	Security Teams	30 min
Risk engine math	Mathematical specification	Researchers	25 min
Risk engine roadmap	Future CTI integration	Developers	15 min
Scenario guides	Per-scenario deep dives	Operators	15 min each

Getting started

New users (15 minutes)

Scenario: Deploy GeoIP detection with automated email alerts

# From project root (/home/alab/soar)
cd radar

# Deploy Wazuh + RADAR GeoIP scenario (use sudo only if manager local)
sudo ./build-radar.sh geoip_detection --manager local --agent local

# Verify deployment
docker ps | grep wazuh

# Set up detector and monitor
./run-radar.sh geoip_detection

Next steps: Getting started guide → GeoIP scenario

Deployment modes

Manager	Agents	Use Case
Local	Local	Development, testing, demos
Local	Remote	Production with centralized management
Remote	Remote	Full distributed deployment

Details: Getting started - Deployment modes

Choose your scenario

Production-ready scenarios:

Scenario	Detection Type	Command	Guide
GeoIP Detection	Signature	`build-radar.sh geoip_detection`	Guide
Log Volume	RRCF-based	`build-radar.sh log_volume`	Guide
Suspicious Login (Signature)	Signature	`build-radar.sh suspicious_login`	Guide

Demo scenarios (require adaptation for your environment):

Insider Threat 🧪 Synthetic data, RRCF-based
Suspicious Login (Behavior) 🧪 RRCF-based
DDoS Detection 🧪 Synthetic data, RRCF-based
C2 Malware Communication 🧪 Synthetic data, RRCF-based

⚠️ Demo scenarios: Require adaptation of indices/aliases, field mappings, time/category fields, decoders/ingest pipelines, TLS/hostnames, and detector/monitor parameters.

Quick reference by task

I want to…	Go to	Section
Deploy my first scenario	Getting started	Prerequisites
Understand system architecture	Architecture	System components
Configure Ansible automation	Ansible playbook	Overview
Create custom detector	Run RADAR	Detector setup
Write new detection rule	Detection rules	Rule scenarios
Customize active response	Active response	Scenario registry
Configure webhook service	Webhook	Configuration
Run automated tests	Test framework	Introduction
Harden against adversarial ML	Adversarial ML	Baseline initialization
Integrate with SONAR	SONAR data shipping	RADAR integration
Understand risk scoring	Risk engine math	Risk calculation
Manage scenario artifacts	Scenarios folder	Folder structure

Architecture overview

System components

┌─────────────────────────────────────────────────────────┐
│                    RADAR System                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Wazuh Agents  →  Wazuh Manager  →  OpenSearch AD       │
│       ↓                ↓                  ↓             │
│  Log Data      →  Decoders/Rules  →  Detectors          │
│                       ↓                  ↓              │
│                  Active Response  ←  Monitors           │
│                       ↓                                 │
│                  Email / CTI / SOAR                     │
└─────────────────────────────────────────────────────────┘

Key technologies:

Wazuh: Security monitoring and SIEM platform
OpenSearch RCF: Random Cut Forest anomaly detection algorithm
Ansible: Infrastructure-as-Code deployment automation
Docker: Containerized components and services
Flask: Webhook service for alert routing

Details: Architecture documentation

Key concepts

Detection approaches

Signature-based: Rules match known patterns (e.g., GeoIP whitelist violations, failed login thresholds)
Behavior-based: ML models detect statistical deviations (e.g., unusual log volume spikes, anomalous access patterns)
Hybrid: Combine both for defense in depth and reduced false positives

See: Architecture - Design principles

Automation pipeline

build-radar.sh  →  Ansible playbook  →  Wazuh deployed
      ↓
run-radar.sh   →  Data ingestion  →  Detector created  →  Monitor configured
      ↓
Anomaly detected  →  Webhook triggered  →  Active Response  →  Email/SOAR/CTI

See: Run RADAR workflow

Ansible playbook

Risk engine

RADAR calculates normalized risk scores (0.0 to 1.0) combining:

RRCF anomaly grade + confidence (behavior-based scenarios)
Signature-based likelihood × impact (rule-based scenarios)
CTI enrichment flags (optional SATRAP integration)

See: Risk engine mathematical specification

Scenario deep dives

Comprehensive guides for each production scenario:

GeoIP Detection: Detect logins from non-whitelisted countries using signature-based rules
Log Volume Monitoring: Monitor for abnormal log generation spikes using RRCF algorithm
Suspicious Login: Identify brute force attacks and impossible travel patterns (signature + behavior)

Each guide includes:

Objectives and security use cases
Detection methodology (signature vs RRCF)
Active response behavior and risk tiering
Manual setup instructions (agent + manager)
OpenSearch detector configuration
Expected outcomes and validation

Integration

SONAR → RADAR data flow

SONAR multivariate anomalies can trigger RADAR automated responses via Wazuh data streams:

SONAR detects anomaly → Ships to wazuh-anomalies-mvad data stream
RADAR monitors index → Matches high-confidence events based on rules
Active response executes → Email/CTI/SOAR actions based on risk tier

Configuration: SONAR data shipping guide

External integrations

Flowintel (case management): Automatic case creation for high-risk alerts - Active response
SATRAP CTI (threat intelligence): IP/domain enrichment via CTI feeds - Risk engine roadmap
Keycloak (identity management): User authentication context - Suspicious login scenario

Troubleshooting

Common issues

Problem	Solution	Reference
Containers not starting	Check Docker resources (memory/CPU)	Getting started - Prerequisites
Detector not creating	Verify OpenSearch AD plugin installed	Getting started - Prerequisites
Webhook not receiving alerts	Check URL/port in monitor configuration	Webhook README
Active response not firing	Verify rule trigger conditions and severity	Detection rules
Email not sending	Check SMTP environment variables	Active response
Ansible playbook fails	Review prerequisites and SSH keys	Ansible playbook - Prerequisites

Debug commands

# From project root (/home/alab/soar)

# Check RADAR containers
docker ps | grep wazuh

# View Wazuh manager logs
docker logs wazuh.manager

# Check webhook service logs
docker logs webhook-server

# Verify OpenSearch indices
curl -k -u admin:admin https://localhost:9200/_cat/indices?v

# Check OpenSearch AD detectors
curl -k -u admin:admin https://localhost:9200/_plugins/_anomaly_detection/detectors

# View active response logs
docker exec wazuh.manager tail -f /var/ossec/logs/active-responses.log

Testing

Test framework

RADAR includes a comprehensive automated test framework supporting:

4 threat scenarios: Insider threat, DDoS, malware C2, suspicious login
Full pipeline: Dataset ingestion → preprocessing → detector setup → attack simulation → evaluation
Metrics computation: True/False Positives/Negatives, precision, recall, F1-score
Ansible automation: Complete infrastructure-as-code test execution

Complete guide: RADAR test framework README (706 lines - comprehensive)

Quick start:

# From project root
cd radar/radar-test-framework
ansible-playbook -i inventory.yaml test_scenario.yaml

Command reference

build-radar.sh

Deploy RADAR scenario with Wazuh infrastructure.

Syntax:

./build-radar.sh <scenario> --manager <local|remote> --agent <local|remote> [OPTIONS]

Examples:

# Local development deployment
./build-radar.sh geoip_detection --manager local --agent local

# Production with remote agents
./build-radar.sh log_volume --manager local --agent remote

# Use existing manager
./build-radar.sh suspicious_login --manager local --agent local --manager_exists true

Options:

--manager_exists <true|false>: Skip manager deployment if already exists (default: false)

Details: Getting started

run-radar.sh

Create OpenSearch detector and monitor for scenario.

Syntax:

./run-radar.sh <scenario>

Examples:

# Create log volume detector + monitor
./run-radar.sh log_volume

# Create GeoIP detector + monitor
./run-radar.sh geoip_detection

Outputs:

DET_ID=<detector-id>: OpenSearch detector identifier
MON_ID=<monitor-id>: OpenSearch monitor identifier

Details: Run RADAR workflow

Glossary

Term	Definition
RADAR	Risk-aware Anomaly Detection-based Automated Response
RRCF	Robust Random Cut Forest - streaming anomaly detection algorithm
RCF	Random Cut Forest - AWS/Amazon anomaly detection algorithm base
SOAR	Security Orchestration, Automation, and Response
AD	Anomaly Detection
CTI	Cyber Threat Intelligence
AR	Active Response
UEBA	User and Entity Behavior Analytics
IaC	Infrastructure-as-Code (Ansible-based deployment)
SIEM	Security Information and Event Management

FAQ

Q: Can I deploy RADAR without OpenSearch AD plugin?
A: Signature-based scenarios (GeoIP, Suspicious Login signature mode) work without it. RRCF-based scenarios (Log Volume, behavior-based detection) require the OpenSearch AD plugin.

Q: Which scenarios are production-ready?
A: GeoIP Detection, Log Volume Monitoring, and Suspicious Login (signature mode) are production-ready. Demo scenarios in /radar/archives/ require adaptation to your environment.

Q: How do I integrate RADAR with SONAR?
A: Configure SONAR data shipping to send anomalies to Wazuh data streams. RADAR monitors these streams and triggers automated responses. See SONAR data shipping guide.

Q: What Wazuh versions are supported?
A: Tested with Wazuh v4.14.1. See Getting started - Prerequisites for compatibility details.

Q: Can I run RADAR in Kubernetes?
A: Not currently supported. RADAR uses Docker Compose for deployment.

Q: How do I customize active responses?
A: Edit scenario-specific Python scripts in radar/scenarios/<scenario>/active_responses/. See Active response - Scenario registry.

Contributing

Adding a new scenario

Create folder structure in radar/scenarios/:

radar/scenarios/my_scenario/
├── active_responses/
├── decoders/
├── rules/
├── ingest_scripts/
└── README.md

Follow naming conventions:
- Decoders: radar-<scenario>-decoder.xml
- Rules: radar-<scenario>-rules.xml
- Active response: radar_<scenario>_ar.py
Add documentation:
- Create docs/manual/radar_docs/radar-scenarios/<scenario>_explained.md
- Update radar/scenarios/README.md
Register in active response:
- Add scenario to registry in radar_ar.py
- Define risk calculation logic

See: Ansible playbook - Extending

Scenarios folder

Version compatibility

RADAR Version	Wazuh	OpenSearch	Docker	Ansible
v0.7.x	4.14.1	2.x	20.10+	2.9+
v0.6.x	4.7.x	1.3+	20.10+	2.9+

Additional resources

External documentation

Project documentation

This site is open source. Improve this page.