argus_uav 0.2.0

A UAV Remote ID Spoofing Defense System

Argus

A UAV Remote ID Spoofing Defense System.

#UAV Swarm Security   #Remote ID Spoofing   #Graph-Theoretic Modeling   #Cryptographic Defenses

---

📑 Table of Contents

🔭 Overview
✨ Key Features
📦 Installation
🚀 Quick Start
🧪 Testing
📁 Project Structure
📚 Documentation
🔬 Research Background
🤝 Contributing
📖 References

---

🔭 Overview

Argus is a research framework for investigating UAV swarm vulnerabilities to Remote ID spoofing attacks. It combines graph-theoretic analysis with cryptographic defenses to detect and prevent:

📄 Paper	👨🏻‍🏫 Presentation

---

✨ Key Features

🎮 Simulation & Attacks

• Swarm Simulation — Dynamic graph-based UAV network modeling with configurable parameters
• Attack Injection — Multiple spoofing scenarios with ground truth tracking

⚔️ Attack Types

Attack Type	Description
🎭 Phantom UAV Injection	Non-existent UAVs broadcasting fake Remote ID messages
📍 Position Falsification	Legitimate UAVs reporting spoofed GPS coordinates
🔀 Coordinated Attacks	Multiple synchronized spoofers disrupting swarm consensus

🔍 Detection Methods

Method	Description	Performance
📊 Spectral Analysis	Laplacian eigenvalue anomaly detection	Fast & lightweight
🎯 Centrality-Based	Graph centrality metric analysis	Good for structural changes
🤖 Machine Learning	Node2Vec embeddings + Isolation Forests	Adaptive detection
🔐 Cryptographic	Ed25519 signature verification	100% TPR, 0% FPR!

📈 Analysis & Visualization

• Consensus Analysis — Quantify attack impact on swarm coordination
• Publication-Quality Plots — ROC curves, heatmaps, comparisons (300 DPI PDF+PNG)
• Live Real-Time Animation — Watch UAVs move and attacks unfold with PySide6 (Qt6)
• Interactive Detection Overlay — Enhanced visualization with detection status

---

📦 Installation

Prerequisites

🐍 Python 3.10 or higher with pip or uv package manager

From PyPI (Recommended)

# Install from PyPI
pip install argus_uav

# Verify installation
argus --help

From Source (For Development)

# Clone the repository
git clone https://github.com/Sang-Buster/Argus.git
cd Argus

# Create virtual environment
uv sync
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Verify installation
argus --help
pytest tests/ -v

---

🚀 Quick Start

🎛️ Interactive CLI (Recommended)

The easiest way to get started:

# Launch interactive mode
argus

# Quick command-line usage
argus --attack phantom --detectors all --mode comparison

# See all options
argus --help

📖 See CLI User Guide for complete documentation.

The CLI provides:

• ✨ Interactive mode — Guided experience for beginners
• 🎬 Live visualization — Watch attacks and detection in real-time
• 📊 Performance comparison — Automated benchmarking and plots
• 🎯 Full coverage — Test any combination of 3 attacks × 4 detection methods

1️⃣ Simulate a Clean UAV Swarm

from argus_uav.core.swarm import Swarm
import numpy as np

# Create reproducible simulation
rng = np.random.default_rng(seed=42)
swarm = Swarm(
    num_uavs=20,
    comm_range=100.0,
    bounds=(1000, 1000, 200),
    rng=rng
)

# Run for 10 seconds
for t in range(10):
    swarm.step(dt=1.0)
    print(f"Time {t}s: {swarm.get_graph().number_of_edges()} links")

2️⃣ Inject and Detect Phantom UAVs

from argus_uav.attacks.phantom_uav import PhantomInjector
from argus_uav.attacks import AttackScenario, AttackType
from argus_uav.detection.spectral import SpectralDetector

# Configure phantom attack
attack = AttackScenario(
    attack_type=AttackType.PHANTOM,
    start_time=5.0,
    duration=10.0,
    phantom_count=3
)

# Setup detection
detector = SpectralDetector()
detector.train([swarm.get_graph().copy() for _ in range(20)])

# Run with attack
injector = PhantomInjector()
for t in range(20):
    if attack.is_active(float(t)):
        injector.inject(swarm, attack, float(t))

    swarm.step(dt=1.0)
    result = detector.detect(swarm.get_graph())

    metrics = result.compute_metrics()
    print(f"TPR: {metrics['tpr']:.2%}, FPR: {metrics['fpr']:.2%}")

For advanced experiments with custom configurations, use the Python API directly. See the examples/ directory for comprehensive demonstrations.

3️⃣ Compare All Detection Methods

# Run performance comparison with all detectors
argus --attack phantom --detectors all --mode comparison

# Live visualization with specific detectors
argus --attack coordinated --detectors spectral crypto --mode live

# Both live and comparison modes
argus --attack position --detectors centrality --mode both

# Custom swarm configuration
argus --attack phantom --detectors all --mode comparison \
    --num-uavs 50 --comm-range 150

---

🧪 Testing

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=argus --cov-report=html

# Run specific test suites
pytest tests/unit/           # Unit tests only
pytest tests/integration/    # Integration tests only
pytest tests/performance/    # Performance benchmarks

---

📁 Project Structure

src/argus_uav/
├── 🎮 core/           # Simulation engine (UAV, swarm, Remote ID)
├── ⚔️ attacks/        # Attack injection (phantom, position spoof, coordinated)
├── 🔍 detection/      # Detection algorithms (spectral, centrality, ML)
├── 🔐 crypto/         # Ed25519 signing and verification
├── 🤝 consensus/      # Swarm consensus algorithms
├── 📊 evaluation/     # Metrics, visualizations, ROC curves
├── 🧪 experiments/    # Experiment runner and configuration
└── 🛠️ utils/          # Random seeds, logging

tests/
├── unit/              # Unit tests for individual components
├── integration/       # End-to-end scenario tests
├── contract/          # Interface compliance tests
└── performance/       # Benchmark and profiling tests

assets/                # Images, paper, presentation
docs/                  # Documentation and examples
examples/              # Example demonstrations and scripts
results/               # Experiment outputs (gitignored)

---

📚 Documentation

📖 Complete Documentation Index

Quick Links

Guide	Description
🚀 Quickstart Guide	Get started in 10 minutes
📊 Project Status	Complete status & features
🧮 Algorithm Details	Theory and implementation
📋 Data Formats	Specifications and schemas
📖 References	19 research paper citations

---

🔬 Research Background

This project investigates defenses against Remote ID spoofing, a critical security challenge for UAV swarms. Remote ID is mandated by aviation authorities (FAA 14 CFR Part 89) but lacks authentication, making it vulnerable to falsified messages.

🎯 Key Research Questions

1. Can graph-theoretic metrics detect topological anomalies from phantom UAVs?
2. How effective is machine learning (Node2Vec + Isolation Forests) vs pure graph analysis?
3. What is the performance overhead of Ed25519 cryptographic signing for real-time swarms?
4. How do spoofing attacks impact swarm consensus algorithms?

🔧 Methodology

Aspect	Approach
Simulation	Software-only UAV swarm modeling (no hardware required)
Attack Scenarios	Phantom injection, position falsification, coordinated spoofers
Detection	Spectral analysis, centrality metrics, ML embeddings
Defense	Ed25519 digital signatures for message authentication
Evaluation	TPR, FPR, detection latency, consensus error

---

🤝 Contributing

This is a research project. Contributions are welcome!

🌟 Areas of Interest

• 🧠 Additional detection algorithms (GNNs, threshold signatures)
• 📡 Real-world Remote ID traffic datasets
• 🔧 Hardware integration (RTL-SDR, physical UAVs)
• 📈 Scalability optimizations for larger swarms

---

📖 References

1. Peel, L., et al. (2015). "Detecting Change Points in Evolving Networks"
2. Olfati-Saber, R., & Murray, R. M. (2004). "Consensus Problems in Networks"
3. Grover, A., & Leskovec, J. (2016). "node2vec: Scalable Feature Learning"
4. Liu, F. T., et al. (2008). "Isolation Forest"
5. Bernstein, D. J., et al. (2012). "High-speed high-security signatures" (Ed25519)