Metadata-Version: 2.4
Name: argus_uav
Version: 0.2.0
Summary:  A UAV Remote ID Spoofing Defense System 
Project-URL: Homepage, https://github.com/Sang-Buster/Argus
Project-URL: Documentation, https://deepwiki.com/Sang-Buster/Argus
Project-URL: Repository, https://github.com/Sang-Buster/Argus
Author-email: Sang Buster <hello@singsongaftermath.com>
License: MIT License
        
        Copyright (c) 2025 Sang Xing
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: anomaly-detection,cryptography,cybersecurity,detection,drone,graph-theory,machine-learning,network-analysis,remote-id,security,spoofing,swarm,uav
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: networkx>=3.4.2
Requires-Dist: numpy>=2.2.6
Requires-Dist: pycryptodome>=3.23.0
Requires-Dist: pyside6>=6.7.0
Requires-Dist: scikit-learn>=1.7.2
Description-Content-Type: text/markdown

<div align="center">
   <a href="https://github.com/Sang-Buster/Argus">
      <img src="https://raw.githubusercontent.com/Sang-Buster/Argus/refs/heads/main/assets/favicon.svg" width=20% alt="logo">
   </a>   
   <h1>Argus</h1>
   <a href="https://deepwiki.com/Sang-Buster/Argus"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
   <a href="https://pypi.org/project/argus_uav/"><img src="https://img.shields.io/pypi/v/argus_uav" alt="PyPI"></a>
   <a href="https://github.com/Sang-Buster/Argus/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Sang-Buster/Argus" alt="License"></a>
   <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv"></a>
   <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
   <a href="https://github.com/Sang-Buster/Force-Fusion/commits/main"><img src="https://img.shields.io/github/last-commit/Sang-Buster/Argus" alt="Last Commit"></a>
   <h6 align="center"><small>A UAV Remote ID Spoofing Defense System.</small></h6>
   <p><b>#UAV Swarm Security &emsp; #Remote ID Spoofing &emsp; #Graph-Theoretic Modeling &emsp; #Cryptographic Defenses</b></p>
</div>

---

<h2 align="center" id="-table-of-contents">📑 Table of Contents</h2>

<p align="left">
<a href="#-overview">🔭 Overview</a><br>
<a href="#-key-features">✨ Key Features</a><br>
<a href="#-installation">📦 Installation</a><br>
<a href="#-quick-start">🚀 Quick Start</a><br>
<a href="#-testing">🧪 Testing</a><br>
<a href="#-project-structure">📁 Project Structure</a><br>
<a href="#-documentation">📚 Documentation</a><br>
<a href="#-research-background">🔬 Research Background</a><br>
<a href="#-contributing">🤝 Contributing</a><br>
<a href="#-references">📖 References</a><br>
</p>

---

<h2 align="center" id="-overview">🔭 Overview</h2>

**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:

<table>
  <tr>
    <th>📄 Paper</th>
    <th>👨🏻‍🏫 Presentation</th>
  </tr>
  <tr>
    <td align="center">
          <a href="https://github.com/Sang-Buster/Argus/blob/main/assets/paper.pdf"><img src="https://raw.githubusercontent.com/Sang-Buster/Argus/refs/heads/main/assets/paper.png" /></a>
          <a href="https://github.com/Sang-Buster/Argus/blob/main/assets/paper.pdf"><img src="https://img.shields.io/badge/View%20More-282c34?style=for-the-badge&logoColor=white" width="100" /></a>
    </td>
    <td align="center">
          <a href="https://github.com/Sang-Buster/Argus/blob/main/assets/presentation.pdf"><img src="https://raw.githubusercontent.com/Sang-Buster/Argus/refs/heads/main/assets/presentation.png" /></a>
          <a href="https://github.com/Sang-Buster/Argus/blob/main/assets/presentation.pdf"><img src="https://img.shields.io/badge/View%20More-282c34?style=for-the-badge&logoColor=white" width="100" /></a>
    </td>
  </tr>
</table>

---

<h2 align="center" id="-key-features">✨ Key Features</h2>

### 🎮 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

---

<h2 align="center" id="-installation">📦 Installation</h2>

### Prerequisites

> 🐍 Python 3.10 or higher with pip or uv package manager

### From PyPI (Recommended)

```bash
# Install from PyPI
pip install argus_uav

# Verify installation
argus --help
```

### From Source (For Development)

```bash
# 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
```

---

<h2 align="center" id="-quick-start">🚀 Quick Start</h2>

### 🎛️ Interactive CLI (Recommended)

The easiest way to get started:

```bash
# Launch interactive mode
argus

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

# See all options
argus --help
```

> 📖 **See [CLI User Guide](docs/CLI.md) 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

```python
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

```python
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

```bash
# 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
```

---

<h2 align="center" id="-testing">🧪 Testing</h2>

```bash
# 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
```

---

<h2 align="center" id="-project-structure">📁 Project Structure</h2>

```
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)
```

---

<h2 align="center" id="-documentation">📚 Documentation</h2>

**📖 [Complete Documentation Index](docs/README.md)**

### Quick Links

| Guide                                             | Description                 |
| ------------------------------------------------- | --------------------------- |
| 🚀 [Quickstart Guide](docs/QUICKSTART.md)         | Get started in 10 minutes   |
| 📊 [Project Status](docs/STATUS.md)               | Complete status & features  |
| 🧮 [Algorithm Details](docs/algorithm_details.md) | Theory and implementation   |
| 📋 [Data Formats](docs/data_formats.md)           | Specifications and schemas  |
| 📖 [References](docs/references.md)               | 19 research paper citations |

---

<h2 align="center" id="-research-background">🔬 Research Background</h2>

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                    |

---

<h2 align="center" id="-contributing">🤝 Contributing</h2>

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

---

<h2 align="center" id="-references">📖 References</h2>

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)
