🛡️ SatGuard - Satellite Telemetry Security Analyzer

Advanced GPS Spoofing Detection & Satellite Telemetry Analysis Toolkit

English • Türkçe • Documentation • Demo

---

🎯 Overview

SatGuard is an open-source toolkit for analyzing satellite terminal telemetry data and detecting GPS spoofing/jamming attacks. Designed for security researchers, journalists, and human rights organizations monitoring state-level electronic warfare against civilian satellite infrastructure.

Key Capabilities

• 🔍 Telemetry Parser - Parse and analyze Starlink debug telemetry data
• 🚨 Anomaly Detection - ML-powered GPS spoofing detection algorithms
• 📊 Interactive Dashboard - Real-time visualization of satellite health metrics
• 🌍 Multi-Region Analysis - Compare interference patterns across geographies
• 📱 Mobile-Ready - Responsive design for field deployment

---

🚀 Quick Start

# Clone the repository
git clone https://github.com/zencefilefendi/satguard.git
cd satguard

# Install dependencies
pip install -r requirements.txt

# Run analysis on telemetry data
python -m satguard analyze --input data/telemetry.json

# Start the dashboard
python -m satguard dashboard --port 8080

---

📦 Installation

Requirements

• Python 3.10+
• Node.js 18+ (for dashboard)
• 512MB RAM minimum

From PyPI

pip install satguard

From Source

git clone https://github.com/zencefilefendi/satguard.git
cd satguard
pip install -e .

---

🔬 Features

1. Telemetry Parser

Parse raw Starlink debug telemetry into structured analysis:

from satguard import TelemetryParser

parser = TelemetryParser()
data = parser.parse_file("debug_export.json")

print(f"GPS Status: {data.gps.status}")
print(f"Satellites: {data.gps.satellite_count}")
print(f"Spoofing Detected: {data.gps.is_inhibited}")

2. GPS Spoofing Detection

Multi-factor detection algorithm analyzing:

Indicator	Normal	Jamming	Spoofing
Satellite Count	10-18	0-5	10-18
GPS Valid	✅	❌	✅
Inhibit Flag	❌	❌	✅
Packet Loss	<1%	Variable	15-30%

from satguard import SpoofingDetector

detector = SpoofingDetector()
result = detector.analyze(telemetry_data)

print(f"Attack Type: {result.attack_type}")  # SPOOFING, JAMMING, or NONE
print(f"Confidence: {result.confidence}%")
print(f"Severity: {result.severity}")

3. Performance Impact Analysis

Quantify the impact of GPS interference on connectivity:

from satguard import PerformanceAnalyzer

analyzer = PerformanceAnalyzer()
impact = analyzer.measure_impact(telemetry_data)

print(f"Packet Loss: {impact.packet_loss_percent}%")
print(f"Stable Connection Time: {impact.stable_seconds}s")
print(f"Pointing Error: {impact.pointing_error_deg}°")
print(f"Service Level: {impact.service_level}")  # BROADBAND, DEGRADED, UNUSABLE

4. Interactive Dashboard

Real-time monitoring with WebSocket support:

satguard dashboard --config config.yaml

Features:

• Live telemetry streaming
• GPS constellation visualization
• Historical trend analysis
• Alert notifications
• Export to PDF/CSV

---

📊 Example Output

╔══════════════════════════════════════════════════════════════╗
║                    SATGUARD ANALYSIS REPORT                  ║
╠══════════════════════════════════════════════════════════════╣
║  Terminal ID: [REDACTED]                                     ║
║  Location: Iran (IR)                                         ║
║  Analysis Time: 2026-01-15 14:32:00 UTC                      ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  🚨 GPS SPOOFING DETECTED                                    ║
║                                                              ║
║  Evidence:                                                   ║
║  ├─ GPS Valid: true (hardware functional)                    ║
║  ├─ Satellites: 18 (normal count)                            ║
║  ├─ Inhibit Flag: TRUE (anti-spoofing triggered)             ║
║  └─ Confidence: 94.2%                                        ║
║                                                              ║
║  Impact Assessment:                                          ║
║  ├─ Packet Loss: 22.4% (sustained)                           ║
║  ├─ Stable Connection: 0 seconds                             ║
║  ├─ Pointing Error: 1.06° (3.3x uncertainty)                 ║
║  └─ Service Level: SEVERELY DEGRADED                         ║
║                                                              ║
║  Recommendation:                                             ║
║  └─ Deploy RF shielding or relocate terminal                 ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

---

🗺️ Regional Analysis

SatGuard includes data on known GPS interference zones:

Region	Primary Attack Type	Typical Impact
Iran	Spoofing	20-30% packet loss
Eastern Mediterranean	Spoofing	15-25% packet loss
Ukraine/Russia Border	Jamming + Spoofing	Variable
North Korea Border	Jamming	Signal loss

---

🔧 Configuration

Create config.yaml:

satguard:
  analysis:
    spoofing_threshold: 0.85
    min_satellites_normal: 8
    max_packet_loss_normal: 0.05
    
  dashboard:
    port: 8080
    refresh_interval: 5
    enable_alerts: true
    
  export:
    format: ["json", "csv", "pdf"]
    redact_pii: true

---

📚 Documentation

• Full Documentation
• API Reference
• Türkçe Dokümantasyon
• Detection Algorithms
• Contributing Guide

---

🙏 Attribution & Acknowledgments

This project builds upon groundbreaking research in satellite security:

Primary Research Credit:
Nariman Gharib - Original technical analysis of Starlink GPS spoofing during Iran's January 2026 internet shutdown.
Repository: starlink-iran-gps-spoofing

The detection algorithms and analysis methodology in SatGuard are derived from and extend this foundational work. We are deeply grateful for the original research that made this possible.

Additional References

• SpaceX Starlink technical documentation
• GPS.gov interference detection guidelines
• Academic papers on GNSS spoofing detection

---

📄 License

MIT License - See LICENSE for details.

This is free software. You can use, modify, and distribute it freely while maintaining attribution.

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Priority areas:

• Support for OneWeb/Kuiper telemetry
• Mobile app (React Native)
• Machine learning model improvements
• Additional language translations

---

⚠️ Disclaimer

This tool is for defensive security research only. Do not use for:

• Interfering with satellite communications
• GPS spoofing or jamming
• Any illegal activities

Users are responsible for compliance with local laws.

---

📬 Contact

• Author: Zencefil Efendi
• Twitter: @zencefilefendi
• Email: zencefilefendi@gmail.com

---

Built with 🛡️ for Internet Freedom

Protecting civilian satellite infrastructure from state-level attacks