wifiattack/docs/ARCHITECTURE.md

Architecture Overview

Application Architecture

WiFi Attack Detector follows the MVVM (Model-View-ViewModel) architecture pattern with clean separation of concerns.

┌─────────────────────────────────────────────────────────────────┐
│                         Presentation Layer                       │
│  ┌─────────────────┐     ┌──────────────────────────────────┐   │
│  │  MainActivity   │────▶│      Composable Screens          │   │
│  └────────┬────────┘     │  ┌──────────┐  ┌──────────────┐  │   │
│           │              │  │Dashboard │  │ChannelStats  │  │   │
│           ▼              │  └──────────┘  └──────────────┘  │   │
│  ┌─────────────────┐     │  ┌──────────┐  ┌──────────────┐  │   │
│  │ WifiAttack      │────▶│  │ Attacks  │  │  Direction   │  │   │
│  │   ViewModel     │     │  └──────────┘  └──────────────┘  │   │
│  └────────┬────────┘     └──────────────────────────────────┘   │
│           │                                                      │
└───────────┼──────────────────────────────────────────────────────┘
            │
            ▼
┌───────────────────────────────────────────────────────────────────┐
│                         Service Layer                             │
│  ┌─────────────────────────┐    ┌─────────────────────────────┐  │
│  │   WifiScannerService    │    │  DirectionSensorManager     │  │
│  │  ┌───────────────────┐  │    │  ┌───────────────────────┐  │  │
│  │  │ WiFi Scanning     │  │    │  │ Accelerometer         │  │  │
│  │  │ Attack Detection  │  │    │  │ Magnetometer          │  │  │
│  │  │ Channel Analysis  │  │    │  │ Direction Calculation │  │  │
│  │  └───────────────────┘  │    │  └───────────────────────┘  │  │
│  └─────────────────────────┘    └─────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
            │
            ▼
┌───────────────────────────────────────────────────────────────────┐
│                         Data Layer                                │
│  ┌──────────────────┐  ┌───────────────┐  ┌──────────────────┐   │
│  │  WifiNetworkInfo │  │  ChannelStats │  │   AttackEvent    │   │
│  └──────────────────┘  └───────────────┘  └──────────────────┘   │
└───────────────────────────────────────────────────────────────────┘

Component Details

Presentation Layer

MainActivity

• Entry point of the application
• Handles permission requests
• Sets up Jetpack Compose content
• Provides ViewModel to composables

WifiAttackViewModel

• Central ViewModel managing all application state
• Exposes StateFlows for UI consumption
• Coordinates between WiFi scanning and direction tracking
• Handles user actions and navigation

Screens

• DashboardScreen: Overview with status, threat level, and quick stats
• ChannelStatsScreen: Detailed per-channel analysis with filtering
• AttacksScreen: Attack history with categorization
• DirectionScreen: Compass-based signal direction tracker

Service Layer

WifiScannerService

• Manages WiFi scanning using WifiManager
• Registers BroadcastReceiver for scan results
• Analyzes scan results for anomalies
• Calculates channel statistics
• Detects potential attacks using heuristics

// Key Detection Heuristics
- Network count changes (beacon flood)
- RSSI fluctuations (jamming)
- Duplicate SSIDs (evil twin)
- Hidden network patterns

DirectionSensorManager

• Uses SensorManager for compass data
• Combines accelerometer and magnetometer readings
• Calculates device orientation (azimuth, pitch, roll)
• Records signal strength at different orientations
• Estimates signal source direction

Data Layer

WifiNetworkInfo

data class WifiNetworkInfo(
    val ssid: String,
    val bssid: String,
    val rssi: Int,
    val frequency: Int,
    val channel: Int,
    val capabilities: String,
    val timestamp: Long
)

ChannelStats

data class ChannelStats(
    val channel: Int,
    val band: WifiBand,
    val networksCount: Int,
    val averageRssi: Int,
    val suspiciousActivityScore: Int,
    val deauthPacketCount: Int,
    val lastUpdateTime: Long
)

AttackEvent

data class AttackEvent(
    val id: String,
    val attackType: AttackType,
    val targetBssid: String?,
    val targetSsid: String?,
    val channel: Int,
    val estimatedDirection: Float?,
    val signalStrength: Int,
    val confidence: Int,
    val timestamp: Long,
    val isActive: Boolean
)

Data Flow

┌──────────────┐     ┌───────────────────┐     ┌──────────────────┐
│ WifiManager  │────▶│ WifiScannerService│────▶│ StateFlow<List>  │
│ (Android OS) │     │ (Analysis Engine) │     │ (Reactive State) │
└──────────────┘     └───────────────────┘     └────────┬─────────┘
                                                        │
                                                        ▼
┌──────────────┐     ┌───────────────────┐     ┌──────────────────┐
│ SensorManager│────▶│DirectionSensor    │────▶│ StateFlow<Float> │
│ (Android OS) │     │      Manager      │     │   (Azimuth)      │
└──────────────┘     └───────────────────┘     └────────┬─────────┘
                                                        │
                                                        ▼
                     ┌───────────────────┐     ┌──────────────────┐
                     │ WifiAttackViewModel│◀───│ Collect as State │
                     └─────────┬─────────┘     └──────────────────┘
                               │
                               ▼
                     ┌───────────────────┐
                     │ Composable UI     │
                     │ (Recomposition)   │
                     └───────────────────┘

Attack Detection Algorithm

Suspicious Activity Score Calculation

Score = 0

IF network_count_variance >= 5:
    Score += 30
ELSE IF network_count_variance >= 3:
    Score += 15

FOR each network:
    IF rssi_variance >= 20:
        Score += 20
    ELSE IF rssi_variance >= 10:
        Score += 10

FOR each ssid_group:
    IF same_ssid_count > 1:
        Score += same_ssid_count * 10

hidden_count = COUNT(hidden_networks)
IF hidden_count > 2:
    Score += hidden_count * 5

RETURN CLAMP(Score, 0, 100)

Attack Type Classification

Condition	Attack Type
deauth_packets > 50	Deauthentication
same_ssid_networks > 2	Evil Twin
network_count > 20	Beacon Flood
suspicious_score >= 70	Unknown

Direction Tracking Algorithm

1. Collect Readings: Record RSSI at each device orientation
2. Bucket Grouping: Group readings into 10° buckets
3. Average Calculation: Calculate average RSSI per bucket
4. Direction Estimation: Find bucket with highest average RSSI
5. Smoothing: Apply moving average for stability

direction_buckets = GROUP_BY(readings, direction / 10 * 10)
bucket_averages = MAP(direction_buckets, AVERAGE(rssi))
estimated_direction = MAX_KEY(bucket_averages)

Threading Model

Main Thread (UI)
    │
    ├── Compose Recomposition
    ├── User Input Handling
    │
    ▼
ViewModel Scope (viewModelScope)
    │
    ├── State Flow Collection
    ├── Coordination Logic
    │
    ▼
IO Dispatcher (Dispatchers.IO)
    │
    ├── WiFi Scanning Loop
    ├── Broadcast Receiver Callbacks
    │
    ▼
Default Dispatcher
    │
    └── Sensor Callbacks (SensorManager)

Future Improvements

1. Root Detection Mode: Access /proc/net/wireless for actual error counts
2. Machine Learning: Train model on attack patterns
3. Persistent Storage: Room database for historical analysis
4. Background Service: Foreground service for continuous monitoring
5. Notifications: Alert system for detected attacks
6. Export Functionality: Export logs for external analysis