drone-detector/docs/THREAT_ASSESSMENT.md

# Threat Assessment and Security Features

## RSSI-Based Threat Classification

The drone detection system now includes intelligent threat assessment based on signal strength (RSSI) and drone type classification. This is specifically designed for government sites, water facilities, nuclear plants, and other sensitive Swedish installations.

### Threat Levels

The system automatically classifies detections into 5 threat levels:

#### 🔴 CRITICAL THREAT (RSSI ≥ -40 dBm)
- **Distance**: 0-50 meters from device
- **Action**: Immediate security response required
- **Description**: Drone within security perimeter
- **Alerts**: All available channels (SMS, email, webhook)

#### 🟠 HIGH THREAT (RSSI -55 to -40 dBm)
- **Distance**: 50-200 meters from device  
- **Action**: Security response recommended
- **Description**: Drone approaching facility
- **Alerts**: SMS and email notifications

#### 🟡 MEDIUM THREAT (RSSI -70 to -55 dBm)
- **Distance**: 200m-1km from device
- **Action**: Enhanced monitoring
- **Description**: Drone in facility vicinity
- **Alerts**: SMS notifications (configurable)

#### 🟢 LOW THREAT (RSSI -85 to -70 dBm)
- **Distance**: 1-5 kilometers from device
- **Action**: Standard monitoring
- **Description**: Drone detected at distance
- **Alerts**: Log only (configurable)

#### ⚪ MONITORING (RSSI < -85 dBm)
- **Distance**: 5-15 kilometers from device
- **Action**: Passive monitoring
- **Description**: Long-range detection
- **Alerts**: Log only

### Drone Type Classification

Threat levels are adjusted based on drone type:

- **Type 0 (Consumer/Hobby)**: Standard threat assessment
- **Type 1 (Professional/Military)**: Escalated threat level
- **Type 2 (Racing/High-speed)**: Escalated if within close range
- **Type 3 (Unknown/Custom)**: Standard threat assessment

### Distance Calculation

The system estimates drone distance using RSSI with the formula:
```
Distance (m) = 10^((RSSI_at_1m - RSSI) / (10 * path_loss_exponent))
```

Where:
- `RSSI_at_1m = -30 dBm` (typical RSSI at 1 meter)
- `path_loss_exponent = 3` (outdoor environment with obstacles)

## Alert Rule Configuration

### Enhanced Alert Conditions

Alert rules now support advanced threat-based conditions:

```javascript
{
  "conditions": {
    "min_threat_level": "high",        // Minimum threat level to trigger
    "rssi_threshold": -55,             // Minimum RSSI value
    "max_distance": 200,               // Maximum distance in meters
    "drone_types": [0, 1, 2],         // Allowed drone types
    "device_ids": [1941875381]        // Specific devices to monitor
  },
  "actions": {
    "sms": true,
    "phone_number": "+46701234567",
    "email": true,
    "channels": ["sms", "email"]      // Alert channels
  },
  "cooldown_minutes": 5               // Cooldown between alerts
}
```

### Security Features for Sensitive Sites

#### Automatic Critical Threat Handling
- Critical threats (RSSI ≥ -40 dBm) automatically trigger all available alert channels
- Bypasses normal cooldown periods for immediate notification
- Includes estimated distance and threat description in alerts

#### Swedish Government Site Integration
The system is pre-configured with coordinates for:
- Government offices and Riksdag
- Water treatment facilities
- Nuclear power plants
- Military installations
- Major airports

## Python Simulation Script

### Swedish Drone Detection Simulator

The included `drone_simulator.py` script generates realistic drone detection data with Swedish coordinates:

```bash
# Install dependencies
pip install -r requirements.txt

# Run basic simulation
python drone_simulator.py

# Custom simulation parameters
python drone_simulator.py --devices 10 --detection-interval 30 --duration 7200

# List available Swedish locations
python drone_simulator.py --list-locations
```

### Simulation Features

- **Realistic RSSI Calculation**: Based on actual distance and path loss
- **Threat-Based Scenarios**: Different probability weights for each threat level
- **Swedish Coordinates**: Real coordinates for sensitive facilities
- **Multiple Device Types**: Government, water, nuclear, military, airport sites
- **Continuous Heartbeats**: Device health monitoring
- **Battery Simulation**: Realistic battery drain and status changes

### Threat Scenario Probabilities

- **Low Threat**: 70% (5-15km range, RSSI -90 to -70 dBm)
- **Medium Threat**: 20% (200m-5km range, RSSI -70 to -55 dBm)
- **High Threat**: 8% (50-200m range, RSSI -55 to -40 dBm)
- **Critical Threat**: 2% (0-50m range, RSSI -40 to -25 dBm)

## API Enhancements

### Detection Response Format

The API now returns threat assessment data:

```json
{
  "id": "uuid",
  "device_id": 1941875381,
  "drone_id": 1001,
  "rssi": -45,
  "threat_level": "high",
  "estimated_distance": 150,
  "requires_action": true,
  "geo_lat": 59.3293,
  "geo_lon": 18.0686,
  "timestamp": "2025-08-16T10:30:00Z"
}
```

### Enhanced Alert Messages

SMS alerts now include comprehensive threat information:

```
🚨 SECURITY ALERT 🚨
THREAT LEVEL: HIGH
HIGH THREAT: Drone approaching facility (50-200m)

📍 LOCATION: Riksdag Stockholm
🔧 DEVICE: SecureGuard-001
📏 DISTANCE: ~150m
📶 SIGNAL: -45 dBm
🚁 DRONE TYPE: Professional/Military
⏰ TIME: 2025-08-16 10:30:00

⚠️ IMMEDIATE ACTION REQUIRED
Security personnel should respond immediately.
```

## Database Schema Updates

New fields added to `DroneDetection` model:

- `threat_level`: ENUM('monitoring', 'low', 'medium', 'high', 'critical')
- `estimated_distance`: INTEGER (meters)
- `requires_action`: BOOLEAN

## Security Recommendations

### For Government Sites
- Set `min_threat_level` to "high" for critical facilities
- Use multiple alert channels for redundancy
- Configure short cooldown periods (2-5 minutes)
- Monitor all drone types including consumer drones

### For Water Facilities
- Set `min_threat_level` to "medium" for early warning
- Focus on perimeter monitoring (max_distance: 500m)
- Longer cooldown periods acceptable (10-15 minutes)

### For Nuclear Facilities
- Set `min_threat_level` to "medium" with escalation to "critical"
- Immediate response required for high/critical threats
- No cooldown for critical threats
- Monitor professional/military drone types with high priority

### For Military Installations
- Maximum security configuration
- All threat levels trigger alerts
- Multiple redundant alert channels
- Real-time monitoring and response protocols