GhostNet: Covert Passive RF Mapping and Mobility Intelligence System

GhostNet is a world-first covert mobility intelligence system that passively maps and tracks the movement of personnel, drones, and ground vehicles using ambient RF emissions without any active signal emission.

Core Features

• Wideband passive RF scanning (70 MHz – 6 GHz)
• AI-based signal classification and feature extraction
• Distributed receiver mesh for location triangulation
• Spatiotemporal heatmaps and motion trails
• Ghost fingerprinting for RF signature identification
• Offline-capable AI models for edge deployment

Hardware Requirements

• SDR Hardware (one or more of):
  • HackRF One
  • RTL-SDR
  • BladeRF
• GPS module for time synchronization
• Network connectivity for mesh operation

System Dependencies

Required System Libraries

Ubuntu/Debian

# Update package lists
sudo apt update

# Core build dependencies
sudo apt install -y \
    python3-dev \
    python3-pip \
    python3-setuptools \
    python3-wheel \
    build-essential \
    cmake \
    git \
    libusb-1.0-0-dev

# SDR Hardware Support
sudo apt install -y \
    rtl-sdr \
    librtlsdr-dev \
    libsoapysdr-dev \
    soapysdr-module-all \
    libuhd-dev \
    uhd-host \
    libiio-dev \
    libiio-utils \
    libairspy-dev

# Optional: Additional SDR modules
sudo apt install -y \
    soapysdr-module-rtlsdr \
    soapysdr-module-hackrf \
    soapysdr-module-bladerf \
    soapysdr-module-uhd \
    soapysdr-module-limesdr \
    soapysdr-module-airspy \
    soapysdr-module-sdrplay

# SDRplay
# Note: SDRplay API must be installed manually from https://www.sdrplay.com/downloads/

macOS

# Using Homebrew
brew install \
    python3 \
    cmake \
    libusb \
    soapysdr \
    rtl-sdr \
    uhd \
    iio \
    airspy

# Optional: Additional SDR support
brew install \
    hackrf \
    bladerf \
    limesdr

# SDRplay
# Note: SDRplay API must be installed manually from https://www.sdrplay.com/downloads/

Windows

1. Install Python 3.8 or later from https://www.python.org/downloads/
2. Install Visual Studio Build Tools 2019 or later
3. Install SDR hardware drivers:
   • RTL-SDR: https://zadig.akeo.ie/
   • SoapySDR: https://github.com/pothosware/SoapySDR/wiki/BuildGuide
   • UHD: https://files.ettus.com/manual/page_install.html
   • libiio: https://wiki.analog.com/resources/tools-software/linux-software/libiio
   • LimeSDR: https://wiki.myriadrf.org/Lime_Suite
   • Airspy: https://airspy.com/download/
   • SDRplay: https://www.sdrplay.com/downloads/

Python Package Installation

1. Create and activate a virtual environment:

# Linux/macOS
python3 -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
.\venv\Scripts\activate

2. Install Python packages:

pip install -r requirements.txt

Hardware Setup

1. Connect your SDR device to your computer
2. Verify device detection:

# For RTL-SDR
rtl_test

# For SoapySDR devices
SoapySDRUtil --find

# For USRP
uhd_usrp_probe

# For PlutoSDR
iio_info

# For LimeSDR
LimeUtil --find

# For Airspy
airspy_info

# For SDRplay
# Check device manager or system information

3. Set up udev rules (Linux only):

# Create udev rules file
sudo nano /etc/udev/rules.d/99-sdr.rules

# Add rules for your devices
# RTL-SDR
SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="2838", GROUP="plugdev", MODE="0666"

# HackRF
SUBSYSTEM=="usb", ATTRS{idVendor}=="1d50", ATTRS{idProduct}=="6089", GROUP="plugdev", MODE="0666"

# BladeRF
SUBSYSTEM=="usb", ATTRS{idVendor}=="1d50", ATTRS{idProduct}=="6066", GROUP="plugdev", MODE="0666"

# Airspy
SUBSYSTEM=="usb", ATTRS{idVendor}=="1d50", ATTRS{idProduct}=="60a1", GROUP="plugdev", MODE="0666"

# Reload udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger

Troubleshooting

1. Device not detected:

   • Check USB connection
   • Verify driver installation
   • Check udev rules (Linux)
   • Try different USB port
   • Check device manager (Windows)

2. Permission issues (Linux):

   • Add user to plugdev group: sudo usermod -a -G plugdev $USER
   • Log out and log back in
   • Check udev rules

3. Driver issues:

   • Reinstall drivers
   • Check manufacturer's website for updates
   • Verify system compatibility

4. Python package issues:

   • Update pip: pip install --upgrade pip
   • Reinstall packages: pip install -r requirements.txt --force-reinstall
   • Check Python version compatibility

Supported Hardware

• RTL-SDR (RTL2832U based dongles)
• HackRF One
• BladeRF
• USRP (B200, B210, X300, X310, N200, N210)
• LimeSDR
• Airspy (R2, Mini)
• SDRplay (RSP1, RSP1A, RSP2, RSPduo)
• PlutoSDR

Notes

• Some SDR devices require specific firmware versions
• Check manufacturer's documentation for hardware-specific requirements
• Some features may require additional system libraries
• Performance may vary based on system specifications
• USB 3.0 ports recommended for high sample rates

Installation

System Dependencies

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install system dependencies
brew install rtl-sdr
brew install hackrf
brew install bladerf
brew install soapysdr

Ubuntu/Debian

# Install system dependencies
sudo apt-get update
sudo apt-get install -y rtl-sdr hackrf bladerf soapysdr

Windows

• Install Zadig for USB driver installation
• Install SDR drivers from respective manufacturer websites
• Install SoapySDR from https://github.com/pothosware/SoapySDR/wiki/BuildGuide

Python Installation

1. Clone the repository:

git clone https://github.com/yourusername/ghostnet.git
cd ghostnet

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install --upgrade pip
pip install -r requirements.txt

4. Configure the system:

cp config/ghostnet_config.json config/local_config.json
# Edit local_config.json with your settings

Project Structure

ghostnet/
├── src/
│   ├── core/           # Core signal processing and AI components
│   │   ├── signal_processor.py
│   │   └── feature_extractor.py
│   ├── hardware/       # SDR interface and hardware abstraction
│   │   └── sdr_interface.py
│   ├── mesh/           # Distributed receiver coordination
│   │   ├── receiver_mesh.py
│   │   └── triangulation.py
│   ├── models/         # AI models and training code
│   │   └── signal_classifier.py
│   └── web/            # Web interface and API
├── tests/              # Unit and integration tests
├── data/               # Training data and model storage
├── config/             # Configuration files
└── docs/              # Documentation

Usage

1. Start the main GhostNet system:

python src/main.py --config config/local_config.json

2. Access the web interface:

python src/web/app.py

Configuration

The system is configured through a JSON configuration file. Key settings include:

• Signal processing parameters (sample rate, FFT size)
• SDR device settings (frequency, gain, bandwidth)
• Mesh network configuration (node ID, position, port)
• Triangulation parameters (minimum receivers, max distance)
• Logging and storage settings
• Visualization options

See config/ghostnet_config.json for a complete configuration template.

Signal Processing Pipeline

1. RF Acquisition

   • Wideband scanning using SDR hardware
   • Sample rate conversion and filtering
   • IQ data capture

2. Feature Extraction

   • Spectral analysis
   • Burst detection
   • Doppler shift analysis
   • Signal strength measurement

3. Classification

   • AI-based signal classification
   • Target type identification
   • Confidence scoring

4. Triangulation

   • Multi-receiver coordination
   • Time difference of arrival
   • Signal strength mapping
   • 3D position estimation

5. Visualization

   • Real-time heatmaps
   • Motion trails
   • Target tracking
   • System status monitoring

Development

• Follow PEP 8 style guide
• Write unit tests for new features
• Update documentation for API changes
• Use type hints for better code maintainability

Security Notice

This system is designed for authorized use only. Users are responsible for complying with all applicable laws and regulations regarding RF monitoring and surveillance.

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• GNU Radio for SDR support
• PyTorch for AI capabilities
• RTL-SDR community for hardware support

Docker Setup

Prerequisites

• Docker Engine 20.10.0 or later
• Docker Compose 2.0.0 or later
• USB device access (for SDR hardware)
• Git

Quick Start

# Clone the repository
git clone https://github.com/yourusername/ghostnet.git
cd ghostnet

# Build and start the container
docker-compose up --build

Docker Configuration

Base Image

The system uses a multi-stage build to minimize the final image size:

# Base stage for building dependencies
FROM python:3.9-slim-bullseye as builder

# Install build dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    cmake \
    git \
    libusb-1.0-0-dev \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Final stage
FROM python:3.9-slim-bullseye

# Install runtime dependencies
RUN apt-get update && apt-get install -y \
    libusb-1.0-0 \
    libsoapysdr0.8 \
    soapysdr-module-all \
    rtl-sdr \
    uhd-host \
    libiio0 \
    libairspy0 \
    && rm -rf /var/lib/apt/lists/*

# Copy Py