zencefilefendi/satguard

# 🛡️ SatGuard - Satellite Telemetry Security Analyzer ## 🎯 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 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](docs/) - [API Reference](docs/api.md) - [Türkçe Dokümantasyon](docs/README_TR.md) - [Detection Algorithms](docs/algorithms.md) - [Contributing Guide](CONTRIBUTING.md) ## 🙏 Attribution & Acknowledgments This project builds upon groundbreaking research in satellite security: 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](LICENSE) for details. This is free software. You can use, modify, and distribute it freely while maintaining attribution. ## ⚠️ 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](https://twitter.com/zencefil_efendi) - **Email:** zencefilefendi@gmail.com