README.md

metadata

title: CLAIRS Autonomous Defense
emoji: 🛡️
colorFrom: gray
colorTo: red
sdk: docker
pinned: false

CLAIRS: Autonomous IoT Network Defense

An OpenEnv-compliant reinforcement learning environment for training AI agents to defend IoT networks against DDoS attacks in real time.

Overview

CLAIRS (Closed-Loop Autonomous Incident Response System) is an LLM-driven anomaly detection and mitigation agent designed to sit at the edge of IoT networks. It monitors real-time telemetry (CPU, PPS, bandwidth, memory, system health) and dynamically issues firewall commands (monitor, rate_limit, block) to mitigate DDoS attacks before they compromise the network.

Architecture

Dynamic Traffic Simulation Engine

Unlike static scripted environments, CLAIRS features a physics-based network traffic simulator that generates realistic traffic patterns:

• Noise & Jitter — Every observation includes controlled randomness (±12 %), making each episode unique
• Action-Responsive Physics — Agent decisions directly affect traffic: blocking reduces PPS by ~95 %, rate limiting by ~60 %
• System Health Degradation — Unmitigated attacks progressively degrade system health, creating urgency for the agent
• Multi-Phase Attack Patterns — Attacks progress through probe, ramp, and surge phases with exponential curves
• Smooth Transitions — Traffic metrics use exponential moving averages, preventing unrealistic jumps

Agentic Context Window

The inference agent maintains a rolling window of the last 3 telemetry snapshots, allowing the LLM to analyse temporal trends (distinguishing momentary spikes from sustained attacks) before making a strict classification decision. The prompt includes trend indicators (SURGING / RISING / STABLE / FALLING) computed from the window.

Observation Space

Field	Type	Range	Description
cpu_usage_percent	float	0–100	CPU load on the IoT gateway
packet_rate_pps	float	0–50 000+	Incoming packets per second
active_connections	int	0–6 000+	Concurrent TCP connections
bandwidth_mbps	float	0–60+	Network bandwidth consumption
memory_usage_percent	float	20–95	Device memory pressure
system_health	float	0–100	Cumulative integrity score

Action Space

Action	Effect	Best For
monitor	No mitigation applied	Normal / benign traffic
rate_limit	Reduce incoming traffic ~60 %	Moderate / stealth attacks
block	Drop incoming traffic ~95 %	Severe volumetric floods

Tasks

ID	Difficulty	Scenario	Optimal Strategy
task_1_easy	Easy	Normal traffic monitoring	Monitor continuously, avoid false positives
task_2_medium	Medium	Volumetric DDoS flood (PPS 5k → 50k)	Detect spike, escalate to block
task_3_hard	Hard	Stealth low-and-slow DDoS	Detect gradual PPS rise, apply rate limiting
task_4_expert	Expert	Multi-wave APT: probe → retreat → surge	Adapt to deceptive retreat phase

Reward Function

Multi-criteria scoring system:

• Action Correctness — Primary signal based on current traffic state and attack severity
• False-Positive Penalty — Blocking or rate-limiting normal traffic is penalised
• Early-Detection Bonus — Catching an attack within the first 3 steps earns extra reward
• Severity Scaling — Appropriate escalation for the attack intensity level
• Health Preservation — Bonus for maintaining system health above 70 %
• Task-Specific Nuance — Stealth attacks (task 3) reward rate_limit over block

All rewards are clamped to [0.01, 0.99] to guarantee mathematical stability within OpenEnv's (0, 1) exclusive range.

Setup & Execution

1. Environment Variables

export API_BASE_URL="https://api-inference.huggingface.co/v1/"
export MODEL_NAME="meta-llama/Meta-Llama-3-8B-Instruct"
export HF_TOKEN="your_token_here"

2. Start the Environment Server

uvicorn server.app:app --host 0.0.0.0 --port 7860

3. Run the Autonomous Agent

python inference.py

Engineering Notes

• Deterministic Fallback — If the LLM API is unreachable, the agent defaults to monitor, which is safe for normal traffic scenarios and prevents inference crashes.
• Resource Efficient — Designed to run within vcpu=2, memory=8GB constraints with no GPU requirement.
• Typed Models — All API schemas are defined as shared Pydantic models in models.py for strict type safety.