## SecureGPS — GPS Spoofing Detection System

SecureGPS is a real-time GPS spoofing detection platform built as a cybersecurity capstone project. It ingests GPS telemetry from tracked devices, applies multiple detection algorithms to identify spoofing attacks, and displays results on a live interactive dashboard.

---

## Features

| Feature | Description |
|---------|-------------|
| Live Dashboard | Real-time interactive map showing device positions with color-coded markers (green = normal, red = spoofed) |
| Speed-Based Detection | Flags unrealistic travel speeds (> 60 m/s) using haversine distance calculation |
| Geofence Violation | Detects when devices report positions outside authorized operating zones |
| HDOP Anomaly Detection | Flags suspiciously perfect GPS signal quality (HDOP < 0.5) — a known spoofing indicator |
| Rapid Bearing Change | Detects impossible direction reversals at high speed (> 160° change at > 20 m/s) |
| HMAC-SHA256 Event Signing | Every event is cryptographically signed for tamper-proof log integrity |
| Signature Verification | `/verify/{id}` endpoint recomputes and validates event signatures on demand |
| Multi-Device Tracking | Tracks multiple devices simultaneously with per-device state |
| Alert Feed | Scrollable sidebar showing recent flagged events with click-to-zoom |
| Demo Simulation | Multi-phase attack simulation script covering all detection methods |

---

## Tech Stack

| Component | Tool |
|-----------|------|
| Language | Python 3.10+ |
| Web Framework | FastAPI |
| Server | Uvicorn |
| Data Validation | Pydantic |
| Database | SQLite |
| Map Visualization | Leaflet.js + OpenStreetMap |
| Template Engine | Jinja2 |
| HTTP Client | HTTPX (async) |

---

## Project Structure

```
GPSSpoofDetector/
├── src/
│   ├── api/
│   │   └── app.py              # FastAPI backend with detection engine
│   ├── demo/
│   │   └── send_scenarios.py   # Multi-phase attack simulation
│   ├── templates/
│   │   └── index.html          # Live dashboard (Leaflet map)
│   ├── database.py             # SQLAlchemy config (reference)
│   └── models.py               # ORM models (reference)
├── requirements.txt
├── securegps.db                # SQLite database (auto-created)
└── README.md
```

---

## Setup Instructions

### 1. Clone and enter the project
```bash
git clone <repository-url>
cd GPSSpoofDetector
```

### 2. Create and activate a virtual environment

**Mac/Linux:**
```bash
python3 -m venv .venv
source .venv/bin/activate
```

**Windows (PowerShell):**
```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
```

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

### 4. Start the server
```bash
uvicorn src.api.app:app --reload
```

### 5. Open the dashboard
Navigate to [http://localhost:8000](http://localhost:8000) in your browser.

---

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Live dashboard with interactive map |
| `/health` | GET | Service health check |
| `/ingest` | POST | Submit GPS telemetry for analysis |
| `/events` | GET | Retrieve recent events (default: 20) |
| `/alerts` | GET | Retrieve only flagged events |
| `/stats` | GET | Event counts and device tracking summary |
| `/verify/{id}` | GET | Verify HMAC signature integrity for an event |
| `/reset` | POST | Clear all events and reset state |
| `/docs` | GET | Swagger API documentation |

---

## Running the Demo

The demo simulation showcases all detection methods with 3 simulated devices and 5 attack phases.

### Steps
1. Start the server (see setup above)
2. Open the dashboard at [http://localhost:8000](http://localhost:8000)
3. In a second terminal, run:
```bash
python src/demo/send_scenarios.py
```

### What You'll See

| Phase | Device | Attack | Detection |
|-------|--------|--------|-----------|
| 1 | driver_01 | Normal driving in Miami | All events allowed |
| 2 | driver_01 | Teleport to New York | Speed violation + Geofence breach |
| 3 | driver_02 | Slow drift out of zone | Geofence violation only |
| 4 | driver_02 | Perfect signal quality | HDOP anomaly |
| 5 | driver_03 | Highway U-turn | Rapid bearing change |

The dashboard updates every 3 seconds — green dots appear for normal events, red dots pop up with details for detected spoofing attempts.

To reset between demo runs, click the "Reset Database" button on the dashboard or run:
```bash
curl -X POST http://localhost:8000/reset
```

---

## Detection Methods Explained

### 1. Speed-Based Detection
Calculates the haversine distance between consecutive GPS reports from the same device and derives the travel speed. Speeds exceeding 60 m/s (~134 mph) are physically implausible for ground vehicles and indicate a potential teleportation attack.

### 2. Geofence Violation
Checks whether reported coordinates fall within authorized operating zones (defined as bounding boxes). A device reporting its position outside all authorized zones triggers an alert — this catches slow-drift attacks where a spoofed signal gradually moves a device off-course.

### 3. HDOP Anomaly
HDOP (Horizontal Dilution of Precision) measures GPS signal quality. Real civilian GPS receivers report HDOP values of 0.8–2.0+. Spoofing devices often produce artificially perfect signals with HDOP < 0.5, which is a well-documented indicator in GPS security research.

### 4. Rapid Bearing Change
Computes the direction of travel between consecutive points. A bearing change greater than 160° at speeds above 20 m/s represents a physically impossible maneuver for a vehicle (e.g., an instant U-turn at highway speed), indicating the GPS data has been manipulated.

---

## Log Integrity Verification

Every event stored in the database is signed with HMAC-SHA256 using a server-side secret key. To verify that an event has not been tampered with:

```
GET /verify/{event_id}
```

This recomputes the signature from the stored event fields and compares it to the original. If `integrity_verified` is `true`, the log is intact.

---

This project is for academic and research purposes as part of the FIU Cybersecurity Capstone Course.
