246
docs/ARCHITECTURE.md
Archivo normal
246
docs/ARCHITECTURE.md
Archivo normal
@@ -0,0 +1,246 @@
|
||||
# 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
|
||||
|
||||
```kotlin
|
||||
// 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
|
||||
```kotlin
|
||||
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
|
||||
```kotlin
|
||||
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
|
||||
```kotlin
|
||||
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
|
||||
|
||||
85
docs/DEVELOPMENT.md
Archivo normal
85
docs/DEVELOPMENT.md
Archivo normal
@@ -0,0 +1,85 @@
|
||||
# Development Setup Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Java Version
|
||||
This project requires **Java 17-21** for building. Java 25+ is not yet supported by Gradle 8.7.
|
||||
|
||||
If you have multiple Java versions installed, set `JAVA_HOME` before building:
|
||||
|
||||
```bash
|
||||
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
|
||||
./gradlew assembleDebug
|
||||
```
|
||||
|
||||
### Android SDK
|
||||
- Minimum SDK: 24 (Android 7.0)
|
||||
- Target SDK: 35 (Android 15)
|
||||
- Compile SDK: 35
|
||||
|
||||
### Required SDK Components
|
||||
- Android SDK Platform 35
|
||||
- Android SDK Build-Tools
|
||||
- Android Emulator (optional, for testing)
|
||||
|
||||
## Building the Project
|
||||
|
||||
### Debug Build
|
||||
```bash
|
||||
./gradlew assembleDebug
|
||||
```
|
||||
|
||||
The APK will be located at:
|
||||
`app/build/outputs/apk/debug/app-debug.apk`
|
||||
|
||||
### Release Build
|
||||
```bash
|
||||
./gradlew assembleRelease
|
||||
```
|
||||
|
||||
Note: Release builds require signing configuration.
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Unit Tests
|
||||
```bash
|
||||
./gradlew test
|
||||
```
|
||||
|
||||
### Instrumented Tests
|
||||
```bash
|
||||
./gradlew connectedAndroidTest
|
||||
```
|
||||
|
||||
## IDE Setup
|
||||
|
||||
### Android Studio
|
||||
1. Open Android Studio
|
||||
2. Select "Open an existing project"
|
||||
3. Navigate to the project directory
|
||||
4. Wait for Gradle sync to complete
|
||||
|
||||
### IntelliJ IDEA
|
||||
1. Open IntelliJ IDEA
|
||||
2. Select "Import Project"
|
||||
3. Choose the `build.gradle.kts` file
|
||||
4. Select "Open as Project"
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Fails with Java Version Error
|
||||
If you see an error related to Java version (e.g., "25.0.1"):
|
||||
1. Check your Java version: `java --version`
|
||||
2. If using Java 25+, switch to Java 21
|
||||
3. Set `JAVA_HOME` to point to Java 21
|
||||
|
||||
### Gradle Sync Issues
|
||||
1. Clear Gradle caches: `./gradlew clean`
|
||||
2. Invalidate caches in Android Studio: File > Invalidate Caches
|
||||
3. Re-sync the project
|
||||
|
||||
### Missing SDK Components
|
||||
Install required components through:
|
||||
- Android Studio SDK Manager
|
||||
- Or command line: `sdkmanager "platforms;android-35"`
|
||||
|
||||
Referencia en una nueva incidencia
Block a user