mirror of
https://github.com/smittix/intercept.git
synced 2026-07-25 01:08:11 -07:00
Fix WiFi monitor parsing, improve setup, reorganize docs
- Fix monitor interface regex parsing (Issues #27, #28) - Add Python 3.9+ version check at startup - Fix setup.sh to handle PEP 668 and auto-create venv - Reorganize README: move detailed content to docs/ folder - Add docs/FEATURES.md, USAGE.md, TROUBLESHOOTING.md, HARDWARE.md
This commit is contained in:
Smittix
@@ -1,533 +1,117 @@
|
|||||||
# INTERCEPT
|
# INTERCEPT
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="https://img.shields.io/badge/python-3.7+-blue.svg" alt="Python 3.7+">
|
<img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+">
|
||||||
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
|
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
|
||||||
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg" alt="Platform">
|
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg" alt="Platform">
|
||||||
<img src="https://img.shields.io/badge/author-smittix-cyan.svg" alt="Author">
|
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<strong>Signal Intelligence Platform</strong>
|
<strong>Signal Intelligence Platform</strong><br>
|
||||||
|
A web-based front-end for signal intelligence tools.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
A sleek, modern web-based front-end for signal intelligence tools.<br>
|
<img src="static/images/screenshots/screenshot2.png" alt="Screenshot">
|
||||||
Unified interface for pager decoding, 433MHz sensors, ADS-B aircraft tracking, satellite monitoring, WiFi reconnaissance, and Bluetooth scanning.
|
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
## Screenshot
|
|
||||||
<img src="static/images/screenshots/screenshot2.png">
|
|
||||||
|
|
||||||
---
|
|
||||||
## Community
|
|
||||||
<p align="center">
|
|
||||||
https://discord.gg/z3g3NJMe
|
|
||||||
</p>
|
|
||||||
|
|
||||||
## Quick Start
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone and install
|
|
||||||
git clone https://github.com/smittix/intercept.git
|
|
||||||
cd intercept
|
|
||||||
pip install -r requirements.txt
|
|
||||||
|
|
||||||
# Run (sudo recommended for full functionality)
|
|
||||||
sudo python3 intercept.py
|
|
||||||
```
|
|
||||||
|
|
||||||
Open `http://localhost:5050` in your browser. See [Installation](#installation) for external tool setup.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Start WITH UV
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone and install
|
|
||||||
git clone https://github.com/smittix/intercept.git
|
|
||||||
cd intercept
|
|
||||||
uv venv --python 3.11.12 # Or your Python version
|
|
||||||
source .venv/bin/activate
|
|
||||||
uv sync
|
|
||||||
|
|
||||||
# Run (sudo recommended for full functionality)
|
|
||||||
sudo python3 intercept.py
|
|
||||||
```
|
|
||||||
|
|
||||||
Open `http://localhost:5050` in your browser. See [Installation](#installation) for external tool setup.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## What is INTERCEPT?
|
## What is INTERCEPT?
|
||||||
|
|
||||||
INTERCEPT is a **web-based front-end** that provides a unified, modern interface for signal intelligence tools:
|
INTERCEPT provides a unified web interface for signal intelligence tools:
|
||||||
|
|
||||||
- **rtl_fm + multimon-ng** - For decoding POCSAG and FLEX pager signals
|
- **Pager Decoding** - POCSAG/FLEX via rtl_fm + multimon-ng
|
||||||
- **rtl_433** - For decoding 433MHz ISM band devices (weather stations, sensors, etc.)
|
- **433MHz Sensors** - Weather stations, TPMS, IoT via rtl_433
|
||||||
- **dump1090 / rtl_adsb** - For ADS-B aircraft tracking with real-time map visualization
|
- **Aircraft Tracking** - ADS-B via dump1090 with real-time map
|
||||||
- **Satellite tracking** - Pass prediction and Iridium burst detection using TLE data
|
- **Satellite Tracking** - Pass prediction using TLE data
|
||||||
- **aircrack-ng** - For WiFi reconnaissance and network analysis
|
- **WiFi Recon** - Monitor mode scanning via aircrack-ng
|
||||||
- **hcitool / bluetoothctl** - For Bluetooth device scanning and tracking
|
- **Bluetooth Scanning** - Device discovery and tracker detection
|
||||||
|
|
||||||
Instead of running command-line tools manually, INTERCEPT handles the process management, output parsing, and presents decoded data in a clean, real-time web interface.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## AI Use
|
## Community
|
||||||
|
|
||||||
This project was built with the help of AI — as a tool, not a shortcut.
|
<p align="center">
|
||||||
I spent significant time reviewing, fixing, testing, and validating the code to ensure it works as intended.
|
<a href="https://discord.gg/z3g3NJMe">Join our Discord</a>
|
||||||
|
</p>
|
||||||
This started as a personal project and was released to help more people get into **Software Defined Radio** by lowering the barrier to entry.
|
|
||||||
|
|
||||||
AI is no different from using a power tool instead of a hand screwdriver: it helps you work faster, not care less. What matters is that the software works, solves a real problem, and is open for others to learn from and improve.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Features
|
## Quick Start
|
||||||
|
|
||||||
### 📟 Pager Decoding
|
```bash
|
||||||
- **Real-time decoding** of POCSAG (512/1200/2400) and FLEX protocols
|
git clone https://github.com/smittix/intercept.git
|
||||||
- **Customizable frequency presets** stored in browser
|
cd intercept
|
||||||
- **Auto-restart** on frequency change while decoding
|
./setup.sh
|
||||||
|
sudo python3 intercept.py
|
||||||
|
```
|
||||||
|
|
||||||
### 📡 433MHz Sensor Decoding
|
Open http://localhost:5050 in your browser.
|
||||||
- **200+ device protocols** supported via rtl_433
|
|
||||||
- **Weather stations** - temperature, humidity, wind, rain
|
|
||||||
- **TPMS** - Tire pressure monitoring sensors
|
|
||||||
- **Doorbells, remotes, and IoT devices**
|
|
||||||
- **Smart meters** and utility monitors
|
|
||||||
|
|
||||||
### ✈️ ADS-B Aircraft Tracking
|
> **Note:** Requires Python 3.9+ and external tools. See [Hardware & Installation](docs/HARDWARE.md).
|
||||||
- **Real-time aircraft tracking** via dump1090 or rtl_adsb
|
|
||||||
- **Full-screen dashboard** - dedicated popout with virtual radar scope
|
|
||||||
- **Interactive Leaflet map** with OpenStreetMap tiles (dark-themed)
|
|
||||||
- **Aircraft trails** - optional flight path history visualization
|
|
||||||
- **Range rings** - distance reference circles from observer position
|
|
||||||
- **Aircraft filtering** - show all, military only, civil only, or emergency only
|
|
||||||
- **Marker clustering** - group nearby aircraft at lower zoom levels
|
|
||||||
- **Reception statistics** - max range, message rate, busiest hour, total seen
|
|
||||||
- **Observer location** - manual input or GPS geolocation
|
|
||||||
- **Audio alerts** - notifications for military and emergency aircraft
|
|
||||||
- **Emergency squawk highlighting** - visual alerts for 7500/7600/7700
|
|
||||||
- **Aircraft details popup** - callsign, altitude, speed, heading, squawk, ICAO
|
|
||||||
|
|
||||||
### 🛰️ Satellite Tracking
|
|
||||||
- **Full-screen dashboard** - dedicated popout with polar plot and ground track
|
|
||||||
- **Polar sky plot** - real-time satellite positions on azimuth/elevation display
|
|
||||||
- **Ground track map** - satellite orbit path with past/future trajectory
|
|
||||||
- **Pass prediction** for satellites using TLE data
|
|
||||||
- **Add satellites** via manual TLE entry or Celestrak import
|
|
||||||
- **Celestrak integration** - fetch by category (Amateur, Weather, ISS, Starlink, etc.)
|
|
||||||
- **Next pass countdown** - time remaining, visibility duration, max elevation
|
|
||||||
- **Telemetry panel** - real-time azimuth, elevation, range, velocity
|
|
||||||
- **Iridium burst detection** monitoring (demo mode)
|
|
||||||
- **Multiple satellite tracking** simultaneously
|
|
||||||
|
|
||||||
### 📶 WiFi Reconnaissance
|
|
||||||
- **Monitor mode** management via airmon-ng
|
|
||||||
- **Network scanning** with airodump-ng and channel hopping
|
|
||||||
- **Handshake capture** with real-time status and auto-detection
|
|
||||||
- **Deauthentication attacks** for authorized testing
|
|
||||||
- **Channel utilization** visualization (2.4GHz and 5GHz)
|
|
||||||
- **Security overview** chart and real-time radar display
|
|
||||||
- **Client vendor lookup** via OUI database
|
|
||||||
- **Drone detection** - automatic detection via SSID patterns and OUI (DJI, Parrot, Autel, etc.)
|
|
||||||
- **Rogue AP detection** - alerts for same SSID on multiple BSSIDs
|
|
||||||
- **Signal history graph** - track signal strength over time for any device
|
|
||||||
- **Network topology** - visual map of APs and connected clients
|
|
||||||
- **Channel recommendation** - optimal channel suggestions based on congestion
|
|
||||||
- **Hidden SSID revealer** - captures hidden networks from probe requests
|
|
||||||
- **Client probe analysis** - privacy leak detection from probe requests
|
|
||||||
- **Device correlation** - matches WiFi and Bluetooth devices by manufacturer
|
|
||||||
|
|
||||||
### 🔵 Bluetooth Scanning
|
|
||||||
- **BLE and Classic** Bluetooth device scanning
|
|
||||||
- **Multiple scan modes** - hcitool, bluetoothctl
|
|
||||||
- **Tracker detection** - AirTag, Tile, Samsung SmartTag, Chipolo
|
|
||||||
- **Device classification** - phones, audio, wearables, computers
|
|
||||||
- **Manufacturer lookup** via OUI database
|
|
||||||
- **Proximity radar** visualization
|
|
||||||
- **Device type breakdown** chart
|
|
||||||
|
|
||||||
### 🔔 Browser Notifications
|
|
||||||
- **Desktop notifications** for critical events (even when tab is in background)
|
|
||||||
- **Alerts for**: Drone detection, Rogue APs, Handshake capture, Hidden SSID reveals
|
|
||||||
- **Permission requested** on first interaction
|
|
||||||
|
|
||||||
### ❓ Help System
|
|
||||||
- **Built-in help page** accessible via ? button in header
|
|
||||||
- **Icon legend** for all stats bar icons
|
|
||||||
- **Mode-by-mode guides** with tips and instructions
|
|
||||||
- **Keyboard shortcut**: Press Escape to close
|
|
||||||
|
|
||||||
### 🎨 User Interface
|
|
||||||
- **Mode-specific header stats** - real-time badges showing key metrics per mode
|
|
||||||
- **UTC clock** - always visible in header for time-critical operations
|
|
||||||
- **Active mode indicator** - shows current mode with pulse animation
|
|
||||||
- **Collapsible sections** - click any header to collapse/expand
|
|
||||||
- **Panel styling** - gradient backgrounds with indicator dots
|
|
||||||
- **Tabbed mode selector** with icons (grouped by SDR/RF and Wireless)
|
|
||||||
- **Consistent design** - unified styling across main dashboard and popouts
|
|
||||||
- **Dark/Light theme toggle** - click moon/sun icon in header, preference saved
|
|
||||||
- **Keyboard shortcuts** - F1 or ? to open help
|
|
||||||
|
|
||||||
### ⌨️ Keyboard Shortcuts
|
|
||||||
| Key | Action |
|
|
||||||
|-----|--------|
|
|
||||||
| F1 | Open help |
|
|
||||||
| ? | Open help (when not typing) |
|
|
||||||
| Escape | Close help/modals |
|
|
||||||
|
|
||||||
### General
|
|
||||||
- **Web-based interface** - no desktop app needed
|
|
||||||
- **Live message streaming** via Server-Sent Events (SSE)
|
|
||||||
- **Audio alerts** with mute toggle
|
|
||||||
- **Message export** to CSV/JSON
|
|
||||||
- **Signal activity meter** and waterfall display
|
|
||||||
- **Message logging** to file with timestamps
|
|
||||||
- **Multi-SDR hardware support** - RTL-SDR, LimeSDR, HackRF
|
|
||||||
- **Automatic device detection** across all supported hardware
|
|
||||||
- **Hardware-specific validation** - frequency/gain ranges per device type
|
|
||||||
- **Configurable gain and PPM correction**
|
|
||||||
- **Device intelligence** dashboard with tracking
|
|
||||||
- **GPS dongle support** - USB GPS receivers for precise observer location
|
|
||||||
- **Disclaimer acceptance** on first use
|
|
||||||
- **Auto-stop** when switching between modes
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
### Hardware
|
- **Python 3.9+**
|
||||||
- **SDR Device** (one of the following):
|
- **SDR Hardware** - RTL-SDR (~$25), LimeSDR, or HackRF
|
||||||
- RTL-SDR compatible dongle (RTL2832U based) - most common, budget-friendly
|
- **External Tools** - rtl-sdr, multimon-ng, rtl_433, dump1090, aircrack-ng
|
||||||
- LimeSDR / LimeSDR Mini - wider frequency range (100 kHz - 3.8 GHz)
|
|
||||||
- HackRF One - ultra-wide frequency range (1 MHz - 6 GHz)
|
|
||||||
- WiFi adapter capable of monitor mode (for WiFi features)
|
|
||||||
- Bluetooth adapter (for Bluetooth features)
|
|
||||||
|
|
||||||
### Software
|
Quick install (Ubuntu/Debian):
|
||||||
- Python 3.9+ recommended (3.7+ may work but is not fully tested)
|
|
||||||
- Flask, skyfield, pyserial (installed via `requirements.txt`)
|
|
||||||
- rtl-sdr tools (`rtl_fm`)
|
|
||||||
- multimon-ng (for pager decoding)
|
|
||||||
- rtl_433 (for 433MHz sensor decoding)
|
|
||||||
- dump1090 or rtl_adsb (for ADS-B aircraft tracking)
|
|
||||||
- aircrack-ng (for WiFi reconnaissance)
|
|
||||||
- BlueZ tools - hcitool, bluetoothctl (for Bluetooth)
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
### Install external tools
|
|
||||||
|
|
||||||
Install the tools for the features you need:
|
|
||||||
|
|
||||||
#### Core SDR Tools
|
|
||||||
|
|
||||||
| Tool | macOS | Ubuntu/Debian | Purpose |
|
|
||||||
|------|-------|---------------|---------|
|
|
||||||
| rtl-sdr | `brew install librtlsdr` | `sudo apt install rtl-sdr` | RTL-SDR support |
|
|
||||||
| multimon-ng | `brew install multimon-ng` | `sudo apt install multimon-ng` | Pager decoding |
|
|
||||||
| rtl_433 | `brew install rtl_433` | `sudo apt install rtl-433` | 433MHz sensors |
|
|
||||||
| dump1090 | `brew install dump1090-mutability` | `sudo apt install dump1090-mutability` | ADS-B aircraft |
|
|
||||||
| aircrack-ng | `brew install aircrack-ng` | `sudo apt install aircrack-ng` | WiFi reconnaissance |
|
|
||||||
| bluez | Built-in (limited) | `sudo apt install bluez bluetooth` | Bluetooth scanning |
|
|
||||||
|
|
||||||
#### Additional SDR Hardware (Optional)
|
|
||||||
|
|
||||||
For LimeSDR or HackRF support, install SoapySDR and the appropriate driver:
|
|
||||||
|
|
||||||
| Tool | macOS | Ubuntu/Debian | Purpose |
|
|
||||||
|------|-------|---------------|---------|
|
|
||||||
| SoapySDR | `brew install soapysdr` | `sudo apt install soapysdr-tools` | Universal SDR abstraction |
|
|
||||||
| LimeSDR | `brew install limesuite soapylms7` | `sudo apt install limesuite soapysdr-module-lms7` | LimeSDR support |
|
|
||||||
| HackRF | `brew install hackrf soapyhackrf` | `sudo apt install hackrf soapysdr-module-hackrf` | HackRF support |
|
|
||||||
| readsb | Build from source | Build from source | ADS-B with SoapySDR |
|
|
||||||
|
|
||||||
> **Note:** RTL-SDR works out of the box. LimeSDR and HackRF require SoapySDR plus the hardware-specific driver.
|
|
||||||
|
|
||||||
### Install and run
|
|
||||||
|
|
||||||
**Option 1: Automated setup (recommended)**
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/smittix/intercept.git
|
sudo apt install rtl-sdr multimon-ng rtl-433 dump1090-mutability aircrack-ng bluez
|
||||||
cd intercept
|
|
||||||
./setup.sh # Installs Python deps and checks for external tools
|
|
||||||
sudo python3 intercept.py
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Option 2: Manual setup**
|
See [Hardware & Installation](docs/HARDWARE.md) for full details.
|
||||||
```bash
|
|
||||||
git clone https://github.com/smittix/intercept.git
|
|
||||||
cd intercept
|
|
||||||
pip install -r requirements.txt
|
|
||||||
sudo python3 intercept.py
|
|
||||||
```
|
|
||||||
|
|
||||||
**Option 3: Using a virtual environment**
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/smittix/intercept.git
|
|
||||||
cd intercept
|
|
||||||
python3 -m venv venv
|
|
||||||
source venv/bin/activate # On Linux/macOS
|
|
||||||
pip install -r requirements.txt
|
|
||||||
sudo venv/bin/python intercept.py
|
|
||||||
```
|
|
||||||
|
|
||||||
Open `http://localhost:5050` in your browser.
|
|
||||||
|
|
||||||
> **Note:** Running as root/sudo is recommended for full functionality (monitor mode, raw sockets, etc.)
|
|
||||||
|
|
||||||
### Check dependencies
|
|
||||||
|
|
||||||
Run the built-in dependency checker to see what's installed and what's missing:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 intercept.py --check-deps
|
|
||||||
```
|
|
||||||
|
|
||||||
This will show the status of all required tools and provide installation instructions for your platform.
|
|
||||||
|
|
||||||
### Command-line options
|
|
||||||
|
|
||||||
```
|
|
||||||
python3 intercept.py --help
|
|
||||||
|
|
||||||
-p, --port PORT Port to run server on (default: 5050)
|
|
||||||
-H, --host HOST Host to bind to (default: 0.0.0.0)
|
|
||||||
-d, --debug Enable debug mode
|
|
||||||
--check-deps Check dependencies and exit
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Usage
|
## Documentation
|
||||||
|
|
||||||
### Pager Mode
|
| Document | Description |
|
||||||
1. **Select Hardware** - Choose your SDR type (RTL-SDR, LimeSDR, or HackRF)
|
|----------|-------------|
|
||||||
2. **Select Device** - Choose your SDR device from the dropdown
|
| [Features](docs/FEATURES.md) | Complete feature list for all modules |
|
||||||
3. **Set Frequency** - Enter a frequency in MHz or use a preset
|
| [Usage Guide](docs/USAGE.md) | Detailed instructions for each mode |
|
||||||
4. **Choose Protocols** - Select which protocols to decode (POCSAG/FLEX)
|
| [Troubleshooting](docs/TROUBLESHOOTING.md) | Solutions for common issues |
|
||||||
5. **Adjust Settings** - Set gain, squelch, and PPM correction as needed
|
| [Hardware & Installation](docs/HARDWARE.md) | SDR hardware and tool installation |
|
||||||
6. **Start Decoding** - Click the green "Start Decoding" button
|
|
||||||
|
|
||||||
### WiFi Mode
|
|
||||||
1. **Select Interface** - Choose a WiFi adapter capable of monitor mode
|
|
||||||
2. **Enable Monitor Mode** - Click "Enable Monitor" (uncheck "Kill processes" to preserve other connections)
|
|
||||||
3. **Start Scanning** - Click "Start Scanning" to begin
|
|
||||||
4. **View Networks** - Networks appear in the output panel with signal strength
|
|
||||||
5. **Track Devices** - Click 📈 on any network to track its signal over time
|
|
||||||
6. **Capture Handshakes** - Click "Capture" on a network to start handshake capture
|
|
||||||
|
|
||||||
### Bluetooth Mode
|
|
||||||
1. **Select Interface** - Choose your Bluetooth adapter
|
|
||||||
2. **Choose Mode** - Select scan mode (hcitool, bluetoothctl)
|
|
||||||
3. **Start Scanning** - Click "Start Scanning"
|
|
||||||
4. **View Devices** - Devices appear with name, address, and classification
|
|
||||||
|
|
||||||
### Aircraft Mode
|
|
||||||
1. **Select Hardware** - Choose your SDR type (RTL-SDR uses dump1090, others use readsb)
|
|
||||||
2. **Check Tools** - Ensure dump1090 or readsb is installed
|
|
||||||
3. **Set Location** - Choose location source:
|
|
||||||
- **Manual Entry** - Type coordinates directly
|
|
||||||
- **Browser GPS** - Use browser's built-in geolocation (requires HTTPS)
|
|
||||||
- **USB GPS Dongle** - Connect a USB GPS receiver for continuous updates
|
|
||||||
4. **Start Tracking** - Click "Start Tracking" to begin ADS-B reception
|
|
||||||
5. **View Map** - Aircraft appear on the interactive Leaflet map
|
|
||||||
6. **Click Aircraft** - Click markers for detailed information
|
|
||||||
7. **Display Options** - Toggle callsigns, altitude, trails, range rings, clustering
|
|
||||||
8. **Filter Aircraft** - Use dropdown to show all, military, civil, or emergency only
|
|
||||||
9. **Full Dashboard** - Click "Full Screen Dashboard" for dedicated radar view
|
|
||||||
|
|
||||||
### Satellite Mode
|
|
||||||
1. **Set Location** - Choose location source:
|
|
||||||
- **Manual Entry** - Type coordinates directly
|
|
||||||
- **Browser GPS** - Use browser's built-in geolocation
|
|
||||||
- **USB GPS Dongle** - Connect a USB GPS receiver for continuous updates
|
|
||||||
2. **Add Satellites** - Click "Add Satellite" to enter TLE data or fetch from Celestrak
|
|
||||||
3. **Calculate Passes** - Click "Calculate Passes" to predict upcoming passes
|
|
||||||
4. **View Sky Plot** - Polar plot shows satellite positions in real-time
|
|
||||||
5. **Ground Track** - Map displays satellite orbit path and current position
|
|
||||||
6. **Full Dashboard** - Click "Full Screen Dashboard" for dedicated satellite view
|
|
||||||
7. **Iridium Mode** - Switch tabs to monitor for Iridium burst transmissions
|
|
||||||
|
|
||||||
### Frequency Presets
|
|
||||||
|
|
||||||
- Click a preset button to quickly set a frequency
|
|
||||||
- Add custom presets using the input field and "Add" button
|
|
||||||
- Right-click a preset to remove it
|
|
||||||
- Click "Reset to Defaults" to restore default frequencies
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Troubleshooting
|
## Development
|
||||||
|
|
||||||
### Python/pip installation issues
|
This project was developed using AI as a coding partner, combining human direction with AI-assisted implementation. The goal: make Software Defined Radio more accessible by providing a clean, unified interface for common SDR tools.
|
||||||
|
|
||||||
**"ModuleNotFoundError: No module named 'flask'":**
|
Contributions and improvements welcome.
|
||||||
```bash
|
|
||||||
# You need to install Python dependencies first
|
|
||||||
pip install -r requirements.txt
|
|
||||||
|
|
||||||
# Or with python3 explicitly
|
|
||||||
python3 -m pip install -r requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
**"TypeError: 'type' object is not subscriptable":**
|
|
||||||
This error occurs on Python 3.7 or 3.8. Please upgrade to Python 3.9 or later:
|
|
||||||
```bash
|
|
||||||
# Check your Python version
|
|
||||||
python3 --version
|
|
||||||
|
|
||||||
# Ubuntu/Debian - install newer Python
|
|
||||||
sudo apt update
|
|
||||||
sudo apt install python3.10
|
|
||||||
|
|
||||||
# Or use pyenv to manage Python versions
|
|
||||||
```
|
|
||||||
|
|
||||||
**"externally-managed-environment" error (Ubuntu 23.04+, Debian 12+):**
|
|
||||||
```bash
|
|
||||||
# Option 1: Use a virtual environment (recommended)
|
|
||||||
python3 -m venv venv
|
|
||||||
source venv/bin/activate
|
|
||||||
pip install -r requirements.txt
|
|
||||||
|
|
||||||
# Option 2: Use pipx for isolated install
|
|
||||||
pipx install flask skyfield
|
|
||||||
|
|
||||||
# Option 3: Override the restriction (not recommended)
|
|
||||||
pip install -r requirements.txt --break-system-packages
|
|
||||||
```
|
|
||||||
|
|
||||||
**"pip: command not found":**
|
|
||||||
```bash
|
|
||||||
# Ubuntu/Debian
|
|
||||||
sudo apt install python3-pip
|
|
||||||
|
|
||||||
# macOS
|
|
||||||
python3 -m ensurepip --upgrade
|
|
||||||
```
|
|
||||||
|
|
||||||
**Permission denied errors:**
|
|
||||||
```bash
|
|
||||||
# Install to user directory instead
|
|
||||||
pip install --user -r requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
### No SDR devices found
|
|
||||||
- Ensure your SDR device is plugged in
|
|
||||||
- Check `rtl_test` (RTL-SDR) or `SoapySDRUtil --find` (LimeSDR/HackRF)
|
|
||||||
- On Linux, you may need udev rules (see setup.sh output)
|
|
||||||
- On Linux, blacklist the DVB-T driver:
|
|
||||||
```bash
|
|
||||||
echo "blacklist dvb_usb_rtl28xxu" | sudo tee /etc/modprobe.d/blacklist-rtl.conf
|
|
||||||
sudo modprobe -r dvb_usb_rtl28xxu
|
|
||||||
```
|
|
||||||
|
|
||||||
### No messages appearing
|
|
||||||
- Verify the frequency is correct for your area
|
|
||||||
- Adjust the gain (try 30-40 dB)
|
|
||||||
- Check that pager services are active in your area
|
|
||||||
- Ensure antenna is connected
|
|
||||||
|
|
||||||
### WiFi monitor mode fails
|
|
||||||
- Ensure you're running as root/sudo
|
|
||||||
- Check your adapter supports monitor mode: `iw list | grep monitor`
|
|
||||||
- Try: `airmon-ng check kill` to stop interfering processes
|
|
||||||
|
|
||||||
### Device busy error
|
|
||||||
- Click "Kill All Processes" to stop any stale processes
|
|
||||||
- Unplug and replug the SDR device
|
|
||||||
- Check if another application is using the device: `lsof | grep rtl`
|
|
||||||
|
|
||||||
### LimeSDR/HackRF not detected
|
|
||||||
- Ensure SoapySDR is installed: `SoapySDRUtil --info`
|
|
||||||
- Check the driver module is loaded: `SoapySDRUtil --find`
|
|
||||||
- Verify permissions (may need udev rules or run as root)
|
|
||||||
|
|
||||||
### GPS dongle not detected
|
|
||||||
- Ensure pyserial is installed: `pip install pyserial`
|
|
||||||
- Check the device is connected: `ls /dev/ttyUSB* /dev/ttyACM*` (Linux) or `ls /dev/tty.usb*` (macOS)
|
|
||||||
- Verify permissions: you may need to add your user to the `dialout` group (Linux):
|
|
||||||
```bash
|
|
||||||
sudo usermod -a -G dialout $USER
|
|
||||||
```
|
|
||||||
- Most GPS dongles use 9600 baud rate (default in INTERCEPT)
|
|
||||||
- The GPS needs a clear view of the sky to get a fix
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Configuration
|
## Disclaimer
|
||||||
|
|
||||||
INTERCEPT can be configured via environment variables:
|
**This software is for educational purposes only.**
|
||||||
|
|
||||||
| Variable | Default | Description |
|
- Only use with proper authorization
|
||||||
|----------|---------|-------------|
|
- Intercepting communications without consent may be illegal
|
||||||
| `INTERCEPT_HOST` | `0.0.0.0` | Server bind address |
|
- WiFi/Bluetooth attacks require explicit permission
|
||||||
| `INTERCEPT_PORT` | `5050` | Server port |
|
- You are responsible for compliance with applicable laws
|
||||||
| `INTERCEPT_DEBUG` | `false` | Enable debug mode |
|
|
||||||
| `INTERCEPT_LOG_LEVEL` | `WARNING` | Log level (DEBUG, INFO, WARNING, ERROR) |
|
|
||||||
| `INTERCEPT_DEFAULT_GAIN` | `40` | Default RTL-SDR gain |
|
|
||||||
|
|
||||||
Example: `INTERCEPT_PORT=8080 sudo python3 intercept.py`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT License - see [LICENSE](LICENSE) for details.
|
MIT License - see [LICENSE](LICENSE)
|
||||||
|
|
||||||
## Author
|
## Author
|
||||||
|
|
||||||
Created by **smittix** - [GitHub](https://github.com/smittix)
|
Created by **smittix** - [GitHub](https://github.com/smittix)
|
||||||
|
|
||||||
## Supported SDR Hardware
|
|
||||||
|
|
||||||
| Hardware | Frequency Range | Gain Range | TX | Notes |
|
|
||||||
|----------|-----------------|------------|-----|-------|
|
|
||||||
| **RTL-SDR** | 24 - 1766 MHz | 0 - 50 dB | No | Most common, budget-friendly (~$25) |
|
|
||||||
| **LimeSDR** | 0.1 - 3800 MHz | 0 - 73 dB | Yes | Wide range, requires SoapySDR |
|
|
||||||
| **HackRF** | 1 - 6000 MHz | 0 - 62 dB | Yes | Ultra-wide range, requires SoapySDR |
|
|
||||||
|
|
||||||
The application automatically detects connected devices and shows hardware-specific capabilities (frequency limits, gain ranges) in the UI.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Acknowledgments
|
## Acknowledgments
|
||||||
|
|
||||||
- [rtl-sdr](https://osmocom.org/projects/rtl-sdr/wiki) - RTL-SDR drivers
|
[rtl-sdr](https://osmocom.org/projects/rtl-sdr/wiki) |
|
||||||
- [multimon-ng](https://github.com/EliasOenal/multimon-ng) - Multi-protocol pager decoder
|
[multimon-ng](https://github.com/EliasOenal/multimon-ng) |
|
||||||
- [rtl_433](https://github.com/merbanan/rtl_433) - 433MHz sensor decoder
|
[rtl_433](https://github.com/merbanan/rtl_433) |
|
||||||
- [dump1090](https://github.com/flightaware/dump1090) - ADS-B decoder for aircraft tracking
|
[dump1090](https://github.com/flightaware/dump1090) |
|
||||||
- [SoapySDR](https://github.com/pothosware/SoapySDR) - Universal SDR abstraction layer
|
[aircrack-ng](https://www.aircrack-ng.org/) |
|
||||||
- [LimeSuite](https://github.com/myriadrf/LimeSuite) - LimeSDR driver and tools
|
[Leaflet.js](https://leafletjs.com/) |
|
||||||
- [aircrack-ng](https://www.aircrack-ng.org/) - WiFi security auditing tools
|
[Celestrak](https://celestrak.org/)
|
||||||
- [BlueZ](http://www.bluez.org/) - Official Linux Bluetooth protocol stack
|
|
||||||
- [Leaflet.js](https://leafletjs.com/) - Interactive maps for aircraft tracking
|
|
||||||
- [OpenStreetMap](https://www.openstreetmap.org/) - Map tile data
|
|
||||||
- [Celestrak](https://celestrak.org/) - Satellite TLE data
|
|
||||||
- Inspired by the SpaceX mission control aesthetic
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚠️ Disclaimer
|
|
||||||
|
|
||||||
**This software is for educational purposes only and intended for use by cybersecurity professionals in controlled environments.**
|
|
||||||
|
|
||||||
By using INTERCEPT, you acknowledge that:
|
|
||||||
- You will only use this tool with proper authorization
|
|
||||||
- Intercepting communications without consent may be illegal in your jurisdiction
|
|
||||||
- WiFi deauthentication and Bluetooth attacks should only be performed on networks/devices you own or have explicit permission to test
|
|
||||||
- You are solely responsible for ensuring compliance with all applicable laws and regulations
|
|
||||||
- The developers assume no liability for misuse of this software
|
|
||||||
|
|
||||||
A disclaimer must be accepted when first launching the application.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,111 @@
|
|||||||
|
# INTERCEPT Features
|
||||||
|
|
||||||
|
Complete feature list for all modules.
|
||||||
|
|
||||||
|
## Pager Decoding
|
||||||
|
|
||||||
|
- **Real-time decoding** of POCSAG (512/1200/2400) and FLEX protocols
|
||||||
|
- **Customizable frequency presets** stored in browser
|
||||||
|
- **Auto-restart** on frequency change while decoding
|
||||||
|
|
||||||
|
## 433MHz Sensor Decoding
|
||||||
|
|
||||||
|
- **200+ device protocols** supported via rtl_433
|
||||||
|
- **Weather stations** - temperature, humidity, wind, rain
|
||||||
|
- **TPMS** - Tire pressure monitoring sensors
|
||||||
|
- **Doorbells, remotes, and IoT devices**
|
||||||
|
- **Smart meters** and utility monitors
|
||||||
|
|
||||||
|
## ADS-B Aircraft Tracking
|
||||||
|
|
||||||
|
- **Real-time aircraft tracking** via dump1090 or rtl_adsb
|
||||||
|
- **Full-screen dashboard** - dedicated popout with virtual radar scope
|
||||||
|
- **Interactive Leaflet map** with OpenStreetMap tiles (dark-themed)
|
||||||
|
- **Aircraft trails** - optional flight path history visualization
|
||||||
|
- **Range rings** - distance reference circles from observer position
|
||||||
|
- **Aircraft filtering** - show all, military only, civil only, or emergency only
|
||||||
|
- **Marker clustering** - group nearby aircraft at lower zoom levels
|
||||||
|
- **Reception statistics** - max range, message rate, busiest hour, total seen
|
||||||
|
- **Observer location** - manual input or GPS geolocation
|
||||||
|
- **Audio alerts** - notifications for military and emergency aircraft
|
||||||
|
- **Emergency squawk highlighting** - visual alerts for 7500/7600/7700
|
||||||
|
- **Aircraft details popup** - callsign, altitude, speed, heading, squawk, ICAO
|
||||||
|
|
||||||
|
## Satellite Tracking
|
||||||
|
|
||||||
|
- **Full-screen dashboard** - dedicated popout with polar plot and ground track
|
||||||
|
- **Polar sky plot** - real-time satellite positions on azimuth/elevation display
|
||||||
|
- **Ground track map** - satellite orbit path with past/future trajectory
|
||||||
|
- **Pass prediction** for satellites using TLE data
|
||||||
|
- **Add satellites** via manual TLE entry or Celestrak import
|
||||||
|
- **Celestrak integration** - fetch by category (Amateur, Weather, ISS, Starlink, etc.)
|
||||||
|
- **Next pass countdown** - time remaining, visibility duration, max elevation
|
||||||
|
- **Telemetry panel** - real-time azimuth, elevation, range, velocity
|
||||||
|
- **Iridium burst detection** monitoring (demo mode)
|
||||||
|
- **Multiple satellite tracking** simultaneously
|
||||||
|
|
||||||
|
## WiFi Reconnaissance
|
||||||
|
|
||||||
|
- **Monitor mode** management via airmon-ng
|
||||||
|
- **Network scanning** with airodump-ng and channel hopping
|
||||||
|
- **Handshake capture** with real-time status and auto-detection
|
||||||
|
- **Deauthentication attacks** for authorized testing
|
||||||
|
- **Channel utilization** visualization (2.4GHz and 5GHz)
|
||||||
|
- **Security overview** chart and real-time radar display
|
||||||
|
- **Client vendor lookup** via OUI database
|
||||||
|
- **Drone detection** - automatic detection via SSID patterns and OUI (DJI, Parrot, Autel, etc.)
|
||||||
|
- **Rogue AP detection** - alerts for same SSID on multiple BSSIDs
|
||||||
|
- **Signal history graph** - track signal strength over time for any device
|
||||||
|
- **Network topology** - visual map of APs and connected clients
|
||||||
|
- **Channel recommendation** - optimal channel suggestions based on congestion
|
||||||
|
- **Hidden SSID revealer** - captures hidden networks from probe requests
|
||||||
|
- **Client probe analysis** - privacy leak detection from probe requests
|
||||||
|
- **Device correlation** - matches WiFi and Bluetooth devices by manufacturer
|
||||||
|
|
||||||
|
## Bluetooth Scanning
|
||||||
|
|
||||||
|
- **BLE and Classic** Bluetooth device scanning
|
||||||
|
- **Multiple scan modes** - hcitool, bluetoothctl
|
||||||
|
- **Tracker detection** - AirTag, Tile, Samsung SmartTag, Chipolo
|
||||||
|
- **Device classification** - phones, audio, wearables, computers
|
||||||
|
- **Manufacturer lookup** via OUI database
|
||||||
|
- **Proximity radar** visualization
|
||||||
|
- **Device type breakdown** chart
|
||||||
|
|
||||||
|
## User Interface
|
||||||
|
|
||||||
|
- **Mode-specific header stats** - real-time badges showing key metrics per mode
|
||||||
|
- **UTC clock** - always visible in header for time-critical operations
|
||||||
|
- **Active mode indicator** - shows current mode with pulse animation
|
||||||
|
- **Collapsible sections** - click any header to collapse/expand
|
||||||
|
- **Panel styling** - gradient backgrounds with indicator dots
|
||||||
|
- **Tabbed mode selector** with icons (grouped by SDR/RF and Wireless)
|
||||||
|
- **Consistent design** - unified styling across main dashboard and popouts
|
||||||
|
- **Dark/Light theme toggle** - click moon/sun icon in header, preference saved
|
||||||
|
- **Browser notifications** - desktop alerts for critical events (drones, rogue APs, handshakes)
|
||||||
|
- **Built-in help page** - accessible via ? button or F1 key
|
||||||
|
|
||||||
|
## Keyboard Shortcuts
|
||||||
|
|
||||||
|
| Key | Action |
|
||||||
|
|-----|--------|
|
||||||
|
| F1 | Open help |
|
||||||
|
| ? | Open help (when not typing) |
|
||||||
|
| Escape | Close help/modals |
|
||||||
|
|
||||||
|
## General
|
||||||
|
|
||||||
|
- **Web-based interface** - no desktop app needed
|
||||||
|
- **Live message streaming** via Server-Sent Events (SSE)
|
||||||
|
- **Audio alerts** with mute toggle
|
||||||
|
- **Message export** to CSV/JSON
|
||||||
|
- **Signal activity meter** and waterfall display
|
||||||
|
- **Message logging** to file with timestamps
|
||||||
|
- **Multi-SDR hardware support** - RTL-SDR, LimeSDR, HackRF
|
||||||
|
- **Automatic device detection** across all supported hardware
|
||||||
|
- **Hardware-specific validation** - frequency/gain ranges per device type
|
||||||
|
- **Configurable gain and PPM correction**
|
||||||
|
- **Device intelligence** dashboard with tracking
|
||||||
|
- **GPS dongle support** - USB GPS receivers for precise observer location
|
||||||
|
- **Disclaimer acceptance** on first use
|
||||||
|
- **Auto-stop** when switching between modes
|
||||||
@@ -0,0 +1,125 @@
|
|||||||
|
# Hardware & Installation
|
||||||
|
|
||||||
|
## Supported SDR Hardware
|
||||||
|
|
||||||
|
| Hardware | Frequency Range | Gain Range | TX | Price | Notes |
|
||||||
|
|----------|-----------------|------------|-----|-------|-------|
|
||||||
|
| **RTL-SDR** | 24 - 1766 MHz | 0 - 50 dB | No | ~$25 | Most common, budget-friendly |
|
||||||
|
| **LimeSDR** | 0.1 - 3800 MHz | 0 - 73 dB | Yes | ~$300 | Wide range, requires SoapySDR |
|
||||||
|
| **HackRF** | 1 - 6000 MHz | 0 - 62 dB | Yes | ~$300 | Ultra-wide range, requires SoapySDR |
|
||||||
|
|
||||||
|
INTERCEPT automatically detects connected devices and shows hardware-specific capabilities in the UI.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
### Hardware
|
||||||
|
- **SDR Device** - RTL-SDR, LimeSDR, or HackRF
|
||||||
|
- **WiFi adapter** capable of monitor mode (for WiFi features)
|
||||||
|
- **Bluetooth adapter** (for Bluetooth features)
|
||||||
|
- **GPS dongle** (optional, for precise location)
|
||||||
|
|
||||||
|
### Software
|
||||||
|
- **Python 3.9+** required
|
||||||
|
- External tools (see installation below)
|
||||||
|
|
||||||
|
## Tool Installation
|
||||||
|
|
||||||
|
### Core SDR Tools
|
||||||
|
|
||||||
|
| Tool | macOS | Ubuntu/Debian | Purpose |
|
||||||
|
|------|-------|---------------|---------|
|
||||||
|
| rtl-sdr | `brew install librtlsdr` | `sudo apt install rtl-sdr` | RTL-SDR support |
|
||||||
|
| multimon-ng | `brew install multimon-ng` | `sudo apt install multimon-ng` | Pager decoding |
|
||||||
|
| rtl_433 | `brew install rtl_433` | `sudo apt install rtl-433` | 433MHz sensors |
|
||||||
|
| dump1090 | `brew install dump1090-mutability` | `sudo apt install dump1090-mutability` | ADS-B aircraft |
|
||||||
|
| aircrack-ng | `brew install aircrack-ng` | `sudo apt install aircrack-ng` | WiFi reconnaissance |
|
||||||
|
| bluez | Built-in (limited) | `sudo apt install bluez bluetooth` | Bluetooth scanning |
|
||||||
|
|
||||||
|
### LimeSDR / HackRF Support (Optional)
|
||||||
|
|
||||||
|
| Tool | macOS | Ubuntu/Debian | Purpose |
|
||||||
|
|------|-------|---------------|---------|
|
||||||
|
| SoapySDR | `brew install soapysdr` | `sudo apt install soapysdr-tools` | Universal SDR abstraction |
|
||||||
|
| LimeSDR | `brew install limesuite soapylms7` | `sudo apt install limesuite soapysdr-module-lms7` | LimeSDR support |
|
||||||
|
| HackRF | `brew install hackrf soapyhackrf` | `sudo apt install hackrf soapysdr-module-hackrf` | HackRF support |
|
||||||
|
| readsb | Build from source | Build from source | ADS-B with SoapySDR |
|
||||||
|
|
||||||
|
> **Note:** RTL-SDR works out of the box. LimeSDR and HackRF require SoapySDR plus the hardware-specific driver.
|
||||||
|
|
||||||
|
## Quick Install Commands
|
||||||
|
|
||||||
|
### Ubuntu/Debian
|
||||||
|
```bash
|
||||||
|
# Core tools
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install rtl-sdr multimon-ng rtl-433 dump1090-mutability aircrack-ng bluez bluetooth
|
||||||
|
|
||||||
|
# LimeSDR (optional)
|
||||||
|
sudo apt install soapysdr-tools limesuite soapysdr-module-lms7
|
||||||
|
|
||||||
|
# HackRF (optional)
|
||||||
|
sudo apt install hackrf soapysdr-module-hackrf
|
||||||
|
```
|
||||||
|
|
||||||
|
### macOS (Homebrew)
|
||||||
|
```bash
|
||||||
|
# Core tools
|
||||||
|
brew install librtlsdr multimon-ng rtl_433 dump1090-mutability aircrack-ng
|
||||||
|
|
||||||
|
# LimeSDR (optional)
|
||||||
|
brew install soapysdr limesuite soapylms7
|
||||||
|
|
||||||
|
# HackRF (optional)
|
||||||
|
brew install hackrf soapyhackrf
|
||||||
|
```
|
||||||
|
|
||||||
|
### Arch Linux
|
||||||
|
```bash
|
||||||
|
# Core tools
|
||||||
|
sudo pacman -S rtl-sdr multimon-ng
|
||||||
|
yay -S rtl_433 dump1090
|
||||||
|
|
||||||
|
# LimeSDR/HackRF (optional)
|
||||||
|
sudo pacman -S soapysdr limesuite hackrf
|
||||||
|
```
|
||||||
|
|
||||||
|
## Linux udev Rules
|
||||||
|
|
||||||
|
If your SDR isn't detected, add udev rules:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo bash -c 'cat > /etc/udev/rules.d/20-rtlsdr.rules << EOF
|
||||||
|
SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="2838", MODE="0666"
|
||||||
|
SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="2832", MODE="0666"
|
||||||
|
EOF'
|
||||||
|
|
||||||
|
sudo udevadm control --reload-rules
|
||||||
|
sudo udevadm trigger
|
||||||
|
```
|
||||||
|
|
||||||
|
Then unplug and replug your device.
|
||||||
|
|
||||||
|
## Blacklist DVB-T Driver (Linux)
|
||||||
|
|
||||||
|
The default DVB-T driver conflicts with rtl-sdr:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
echo "blacklist dvb_usb_rtl28xxu" | sudo tee /etc/modprobe.d/blacklist-rtl.conf
|
||||||
|
sudo modprobe -r dvb_usb_rtl28xxu
|
||||||
|
```
|
||||||
|
|
||||||
|
## Verify Installation
|
||||||
|
|
||||||
|
Check what's installed:
|
||||||
|
```bash
|
||||||
|
python3 intercept.py --check-deps
|
||||||
|
```
|
||||||
|
|
||||||
|
Test SDR detection:
|
||||||
|
```bash
|
||||||
|
# RTL-SDR
|
||||||
|
rtl_test
|
||||||
|
|
||||||
|
# LimeSDR/HackRF
|
||||||
|
SoapySDRUtil --find
|
||||||
|
```
|
||||||
@@ -0,0 +1,184 @@
|
|||||||
|
# Troubleshooting
|
||||||
|
|
||||||
|
Solutions for common issues.
|
||||||
|
|
||||||
|
## Python / Installation Issues
|
||||||
|
|
||||||
|
### "ModuleNotFoundError: No module named 'flask'"
|
||||||
|
|
||||||
|
Install Python dependencies first:
|
||||||
|
```bash
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
# Or with python3 explicitly
|
||||||
|
python3 -m pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### "TypeError: 'type' object is not subscriptable"
|
||||||
|
|
||||||
|
This error occurs on Python 3.7 or 3.8. **INTERCEPT requires Python 3.9 or later.**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check your Python version
|
||||||
|
python3 --version
|
||||||
|
|
||||||
|
# Ubuntu/Debian - install newer Python
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install python3.11 python3.11-venv python3-pip
|
||||||
|
|
||||||
|
# Run with newer Python
|
||||||
|
python3.11 -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
pip install -r requirements.txt
|
||||||
|
sudo venv/bin/python intercept.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### "externally-managed-environment" error (Ubuntu 23.04+, Debian 12+)
|
||||||
|
|
||||||
|
Modern systems use PEP 668 to protect system Python. Use a virtual environment:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Option 1: Virtual environment (recommended)
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
pip install -r requirements.txt
|
||||||
|
sudo venv/bin/python intercept.py
|
||||||
|
|
||||||
|
# Option 2: Use the setup script (auto-creates venv if needed)
|
||||||
|
./setup.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### "pip: command not found"
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Ubuntu/Debian
|
||||||
|
sudo apt install python3-pip
|
||||||
|
|
||||||
|
# macOS
|
||||||
|
python3 -m ensurepip --upgrade
|
||||||
|
```
|
||||||
|
|
||||||
|
### Permission denied during pip install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install to user directory
|
||||||
|
pip install --user -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
## SDR Hardware Issues
|
||||||
|
|
||||||
|
### No SDR devices found
|
||||||
|
|
||||||
|
1. Ensure your SDR device is plugged in
|
||||||
|
2. Check detection:
|
||||||
|
- RTL-SDR: `rtl_test`
|
||||||
|
- LimeSDR/HackRF: `SoapySDRUtil --find`
|
||||||
|
3. On Linux, add udev rules (see below)
|
||||||
|
4. Blacklist conflicting drivers:
|
||||||
|
```bash
|
||||||
|
echo "blacklist dvb_usb_rtl28xxu" | sudo tee /etc/modprobe.d/blacklist-rtl.conf
|
||||||
|
sudo modprobe -r dvb_usb_rtl28xxu
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linux udev rules for RTL-SDR
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo bash -c 'cat > /etc/udev/rules.d/20-rtlsdr.rules << EOF
|
||||||
|
SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="2838", MODE="0666"
|
||||||
|
SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="2832", MODE="0666"
|
||||||
|
EOF'
|
||||||
|
|
||||||
|
sudo udevadm control --reload-rules
|
||||||
|
sudo udevadm trigger
|
||||||
|
```
|
||||||
|
|
||||||
|
Then unplug and replug your RTL-SDR.
|
||||||
|
|
||||||
|
### Device busy error
|
||||||
|
|
||||||
|
1. Click "Kill All Processes" in the UI
|
||||||
|
2. Unplug and replug the SDR device
|
||||||
|
3. Check for other applications: `lsof | grep rtl`
|
||||||
|
|
||||||
|
### LimeSDR/HackRF not detected
|
||||||
|
|
||||||
|
1. Verify SoapySDR is installed: `SoapySDRUtil --info`
|
||||||
|
2. Check driver is loaded: `SoapySDRUtil --find`
|
||||||
|
3. May need udev rules or run as root
|
||||||
|
|
||||||
|
## WiFi Issues
|
||||||
|
|
||||||
|
### Monitor mode fails
|
||||||
|
|
||||||
|
1. Ensure running as root/sudo
|
||||||
|
2. Check adapter supports monitor mode: `iw list | grep monitor`
|
||||||
|
3. Kill interfering processes: `airmon-ng check kill`
|
||||||
|
|
||||||
|
### Permission denied when scanning
|
||||||
|
|
||||||
|
Run INTERCEPT with sudo:
|
||||||
|
```bash
|
||||||
|
sudo python3 intercept.py
|
||||||
|
# Or with venv:
|
||||||
|
sudo venv/bin/python intercept.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### Interface not found after enabling monitor mode
|
||||||
|
|
||||||
|
Some adapters rename when entering monitor mode (e.g., wlan0 → wlan0mon). The interface should auto-select, but if not, manually select the monitor interface from the dropdown.
|
||||||
|
|
||||||
|
## Bluetooth Issues
|
||||||
|
|
||||||
|
### No Bluetooth adapter found
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check if adapter is detected
|
||||||
|
hciconfig
|
||||||
|
|
||||||
|
# Ubuntu/Debian - install BlueZ
|
||||||
|
sudo apt install bluez bluetooth
|
||||||
|
```
|
||||||
|
|
||||||
|
### Permission denied
|
||||||
|
|
||||||
|
Run with sudo or add your user to the bluetooth group:
|
||||||
|
```bash
|
||||||
|
sudo usermod -a -G bluetooth $USER
|
||||||
|
```
|
||||||
|
|
||||||
|
## GPS Issues
|
||||||
|
|
||||||
|
### GPS dongle not detected
|
||||||
|
|
||||||
|
1. Install pyserial: `pip install pyserial`
|
||||||
|
2. Check device is connected:
|
||||||
|
- Linux: `ls /dev/ttyUSB* /dev/ttyACM*`
|
||||||
|
- macOS: `ls /dev/tty.usb*`
|
||||||
|
3. Add user to dialout group (Linux):
|
||||||
|
```bash
|
||||||
|
sudo usermod -a -G dialout $USER
|
||||||
|
```
|
||||||
|
4. Most GPS dongles use 9600 baud (default in INTERCEPT)
|
||||||
|
5. GPS needs clear sky view to get a fix
|
||||||
|
|
||||||
|
## Decoding Issues
|
||||||
|
|
||||||
|
### No messages appearing (Pager mode)
|
||||||
|
|
||||||
|
1. Verify frequency is correct for your area
|
||||||
|
2. Adjust gain (try 30-40 dB)
|
||||||
|
3. Check pager services are active in your area
|
||||||
|
4. Ensure antenna is connected
|
||||||
|
|
||||||
|
### No aircraft appearing (ADS-B mode)
|
||||||
|
|
||||||
|
1. Verify dump1090 or readsb is installed
|
||||||
|
2. Check antenna is connected (1090 MHz antenna recommended)
|
||||||
|
3. Ensure clear view of sky
|
||||||
|
4. Set correct observer location for range calculations
|
||||||
|
|
||||||
|
### Satellite passes not calculating
|
||||||
|
|
||||||
|
1. Ensure skyfield is installed: `pip install skyfield`
|
||||||
|
2. Check TLE data is valid and recent
|
||||||
|
3. Verify observer location is set correctly
|
||||||
+125
@@ -0,0 +1,125 @@
|
|||||||
|
# INTERCEPT Usage Guide
|
||||||
|
|
||||||
|
Detailed instructions for each mode.
|
||||||
|
|
||||||
|
## Pager Mode
|
||||||
|
|
||||||
|
1. **Select Hardware** - Choose your SDR type (RTL-SDR, LimeSDR, or HackRF)
|
||||||
|
2. **Select Device** - Choose your SDR device from the dropdown
|
||||||
|
3. **Set Frequency** - Enter a frequency in MHz or use a preset
|
||||||
|
4. **Choose Protocols** - Select which protocols to decode (POCSAG/FLEX)
|
||||||
|
5. **Adjust Settings** - Set gain, squelch, and PPM correction as needed
|
||||||
|
6. **Start Decoding** - Click the green "Start Decoding" button
|
||||||
|
|
||||||
|
### Frequency Presets
|
||||||
|
|
||||||
|
- Click a preset button to quickly set a frequency
|
||||||
|
- Add custom presets using the input field and "Add" button
|
||||||
|
- Right-click a preset to remove it
|
||||||
|
- Click "Reset to Defaults" to restore default frequencies
|
||||||
|
|
||||||
|
## 433MHz Sensor Mode
|
||||||
|
|
||||||
|
1. **Select Hardware** - Choose your SDR type
|
||||||
|
2. **Select Device** - Choose your SDR device
|
||||||
|
3. **Start Decoding** - Click "Start Decoding"
|
||||||
|
4. **View Sensors** - Decoded sensor data appears in real-time
|
||||||
|
|
||||||
|
Supports 200+ protocols including weather stations, TPMS, doorbells, and IoT devices.
|
||||||
|
|
||||||
|
## WiFi Mode
|
||||||
|
|
||||||
|
1. **Select Interface** - Choose a WiFi adapter capable of monitor mode
|
||||||
|
2. **Enable Monitor Mode** - Click "Enable Monitor" (uncheck "Kill processes" to preserve other connections)
|
||||||
|
3. **Start Scanning** - Click "Start Scanning" to begin
|
||||||
|
4. **View Networks** - Networks appear in the output panel with signal strength
|
||||||
|
5. **Track Devices** - Click the chart icon on any network to track its signal over time
|
||||||
|
6. **Capture Handshakes** - Click "Capture" on a network to start handshake capture
|
||||||
|
|
||||||
|
### Tips
|
||||||
|
|
||||||
|
- Run with `sudo` for monitor mode to work
|
||||||
|
- Check your adapter supports monitor mode: `iw list | grep monitor`
|
||||||
|
- Use "Kill processes" option if NetworkManager interferes
|
||||||
|
|
||||||
|
## Bluetooth Mode
|
||||||
|
|
||||||
|
1. **Select Interface** - Choose your Bluetooth adapter
|
||||||
|
2. **Choose Mode** - Select scan mode (hcitool, bluetoothctl)
|
||||||
|
3. **Start Scanning** - Click "Start Scanning"
|
||||||
|
4. **View Devices** - Devices appear with name, address, and classification
|
||||||
|
|
||||||
|
### Tracker Detection
|
||||||
|
|
||||||
|
INTERCEPT automatically detects known trackers:
|
||||||
|
- Apple AirTag
|
||||||
|
- Tile
|
||||||
|
- Samsung SmartTag
|
||||||
|
- Chipolo
|
||||||
|
|
||||||
|
## Aircraft Mode (ADS-B)
|
||||||
|
|
||||||
|
1. **Select Hardware** - Choose your SDR type (RTL-SDR uses dump1090, others use readsb)
|
||||||
|
2. **Check Tools** - Ensure dump1090 or readsb is installed
|
||||||
|
3. **Set Location** - Choose location source:
|
||||||
|
- **Manual Entry** - Type coordinates directly
|
||||||
|
- **Browser GPS** - Use browser's built-in geolocation (requires HTTPS)
|
||||||
|
- **USB GPS Dongle** - Connect a USB GPS receiver for continuous updates
|
||||||
|
4. **Start Tracking** - Click "Start Tracking" to begin ADS-B reception
|
||||||
|
5. **View Map** - Aircraft appear on the interactive Leaflet map
|
||||||
|
6. **Click Aircraft** - Click markers for detailed information
|
||||||
|
7. **Display Options** - Toggle callsigns, altitude, trails, range rings, clustering
|
||||||
|
8. **Filter Aircraft** - Use dropdown to show all, military, civil, or emergency only
|
||||||
|
9. **Full Dashboard** - Click "Full Screen Dashboard" for dedicated radar view
|
||||||
|
|
||||||
|
### Emergency Squawks
|
||||||
|
|
||||||
|
The system highlights aircraft transmitting emergency squawks:
|
||||||
|
- **7500** - Hijack
|
||||||
|
- **7600** - Radio failure
|
||||||
|
- **7700** - General emergency
|
||||||
|
|
||||||
|
## Satellite Mode
|
||||||
|
|
||||||
|
1. **Set Location** - Choose location source:
|
||||||
|
- **Manual Entry** - Type coordinates directly
|
||||||
|
- **Browser GPS** - Use browser's built-in geolocation
|
||||||
|
- **USB GPS Dongle** - Connect a USB GPS receiver for continuous updates
|
||||||
|
2. **Add Satellites** - Click "Add Satellite" to enter TLE data or fetch from Celestrak
|
||||||
|
3. **Calculate Passes** - Click "Calculate Passes" to predict upcoming passes
|
||||||
|
4. **View Sky Plot** - Polar plot shows satellite positions in real-time
|
||||||
|
5. **Ground Track** - Map displays satellite orbit path and current position
|
||||||
|
6. **Full Dashboard** - Click "Full Screen Dashboard" for dedicated satellite view
|
||||||
|
7. **Iridium Mode** - Switch tabs to monitor for Iridium burst transmissions
|
||||||
|
|
||||||
|
### Adding Satellites from Celestrak
|
||||||
|
|
||||||
|
1. Click "Add Satellite"
|
||||||
|
2. Select "Fetch from Celestrak"
|
||||||
|
3. Choose a category (Amateur, Weather, ISS, Starlink, etc.)
|
||||||
|
4. Select satellites to add
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
INTERCEPT can be configured via environment variables:
|
||||||
|
|
||||||
|
| Variable | Default | Description |
|
||||||
|
|----------|---------|-------------|
|
||||||
|
| `INTERCEPT_HOST` | `0.0.0.0` | Server bind address |
|
||||||
|
| `INTERCEPT_PORT` | `5050` | Server port |
|
||||||
|
| `INTERCEPT_DEBUG` | `false` | Enable debug mode |
|
||||||
|
| `INTERCEPT_LOG_LEVEL` | `WARNING` | Log level (DEBUG, INFO, WARNING, ERROR) |
|
||||||
|
| `INTERCEPT_DEFAULT_GAIN` | `40` | Default RTL-SDR gain |
|
||||||
|
|
||||||
|
Example: `INTERCEPT_PORT=8080 sudo python3 intercept.py`
|
||||||
|
|
||||||
|
## Command-line Options
|
||||||
|
|
||||||
|
```
|
||||||
|
python3 intercept.py --help
|
||||||
|
|
||||||
|
-p, --port PORT Port to run server on (default: 5050)
|
||||||
|
-H, --host HOST Host to bind to (default: 0.0.0.0)
|
||||||
|
-d, --debug Enable debug mode
|
||||||
|
--check-deps Check dependencies and exit
|
||||||
|
```
|
||||||
@@ -14,6 +14,17 @@ Requires RTL-SDR hardware for RF modes.
|
|||||||
"""
|
"""
|
||||||
|
|
||||||
import sys
|
import sys
|
||||||
|
|
||||||
|
# Check Python version early, before imports that use 3.9+ syntax
|
||||||
|
if sys.version_info < (3, 9):
|
||||||
|
print(f"Error: Python 3.9 or higher is required.")
|
||||||
|
print(f"You are running Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")
|
||||||
|
print("\nTo fix this:")
|
||||||
|
print(" - On Ubuntu/Debian: sudo apt install python3.9 (or newer)")
|
||||||
|
print(" - On macOS: brew install python@3.11")
|
||||||
|
print(" - Or use pyenv to install a newer version")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
import site
|
import site
|
||||||
|
|
||||||
# Ensure user site-packages is available (may be disabled when running as root/sudo)
|
# Ensure user site-packages is available (may be disabled when running as root/sudo)
|
||||||
|
|||||||
+14
-7
@@ -335,19 +335,26 @@ def toggle_monitor_mode():
|
|||||||
monitor_iface = list(new_interfaces)[0]
|
monitor_iface = list(new_interfaces)[0]
|
||||||
|
|
||||||
if not monitor_iface:
|
if not monitor_iface:
|
||||||
|
# Patterns to extract monitor interface name from airmon-ng output
|
||||||
|
# Interface names: start with letter, contain alphanumeric/underscore/dash
|
||||||
patterns = [
|
patterns = [
|
||||||
r'monitor mode.*enabled.*on\s+(\S+)',
|
# Look for interface names ending in 'mon' (most reliable)
|
||||||
r'\(monitor mode.*enabled.*?(\S+mon)\)',
|
r'\b([a-zA-Z][a-zA-Z0-9_-]*mon)\b',
|
||||||
r'created\s+(\S+mon)',
|
# Airmon-ng format: [phyX]interfacename
|
||||||
r'\bon\s+(\S+mon)\b',
|
r'\[phy\d+\]([a-zA-Z][a-zA-Z0-9_-]*mon)',
|
||||||
r'\b(\S+mon)\b.*monitor',
|
# "enabled for/on [phyX]interface" format
|
||||||
|
r'enabled.*?\[phy\d+\]([a-zA-Z][a-zA-Z0-9_-]*)',
|
||||||
|
# Original interface with 'mon' appended
|
||||||
r'\b(' + re.escape(interface) + r'mon)\b',
|
r'\b(' + re.escape(interface) + r'mon)\b',
|
||||||
]
|
]
|
||||||
for pattern in patterns:
|
for pattern in patterns:
|
||||||
match = re.search(pattern, output, re.IGNORECASE)
|
match = re.search(pattern, output, re.IGNORECASE)
|
||||||
if match:
|
if match:
|
||||||
monitor_iface = match.group(1)
|
candidate = match.group(1)
|
||||||
break
|
# Validate it looks like an interface name (not channel info like "10)")
|
||||||
|
if candidate and not candidate[0].isdigit() and ')' not in candidate:
|
||||||
|
monitor_iface = candidate
|
||||||
|
break
|
||||||
|
|
||||||
if not monitor_iface:
|
if not monitor_iface:
|
||||||
try:
|
try:
|
||||||
|
|||||||
@@ -57,19 +57,54 @@ install_python_deps() {
|
|||||||
|
|
||||||
if ! check_cmd python3; then
|
if ! check_cmd python3; then
|
||||||
echo -e "${RED}Error: Python 3 is not installed${NC}"
|
echo -e "${RED}Error: Python 3 is not installed${NC}"
|
||||||
echo "Please install Python 3.7 or later"
|
echo "Please install Python 3.9 or later"
|
||||||
exit 1
|
exit 1
|
||||||
fi
|
fi
|
||||||
|
|
||||||
|
# Check Python version (need 3.9+)
|
||||||
PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
|
PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
|
||||||
|
PYTHON_MAJOR=$(python3 -c 'import sys; print(sys.version_info.major)')
|
||||||
|
PYTHON_MINOR=$(python3 -c 'import sys; print(sys.version_info.minor)')
|
||||||
echo "Python version: $PYTHON_VERSION"
|
echo "Python version: $PYTHON_VERSION"
|
||||||
|
|
||||||
if check_cmd pip3; then
|
if [ "$PYTHON_MAJOR" -lt 3 ] || ([ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 9 ]); then
|
||||||
pip3 install -r requirements.txt
|
echo -e "${RED}Error: Python 3.9 or later is required${NC}"
|
||||||
elif check_cmd pip; then
|
echo "You have Python $PYTHON_VERSION"
|
||||||
|
echo ""
|
||||||
|
echo "Please upgrade Python:"
|
||||||
|
echo " Ubuntu/Debian: sudo apt install python3.11"
|
||||||
|
echo " macOS: brew install python@3.11"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check if we're in a virtual environment
|
||||||
|
if [ -n "$VIRTUAL_ENV" ]; then
|
||||||
|
echo "Using virtual environment: $VIRTUAL_ENV"
|
||||||
|
pip install -r requirements.txt
|
||||||
|
elif [ -d "venv" ]; then
|
||||||
|
echo "Found existing venv, activating..."
|
||||||
|
source venv/bin/activate
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
else
|
else
|
||||||
python3 -m pip install -r requirements.txt
|
# Try direct pip install first, fall back to venv if it fails (PEP 668)
|
||||||
|
echo "Attempting to install dependencies..."
|
||||||
|
if python3 -m pip install -r requirements.txt 2>/dev/null; then
|
||||||
|
echo -e "${GREEN}Python dependencies installed successfully${NC}"
|
||||||
|
return
|
||||||
|
fi
|
||||||
|
|
||||||
|
# If pip install failed (likely PEP 668), create a virtual environment
|
||||||
|
echo ""
|
||||||
|
echo -e "${YELLOW}System Python is externally managed (PEP 668).${NC}"
|
||||||
|
echo "Creating virtual environment..."
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
pip install -r requirements.txt
|
||||||
|
echo ""
|
||||||
|
echo -e "${YELLOW}NOTE: A virtual environment was created.${NC}"
|
||||||
|
echo "You must activate it before running INTERCEPT:"
|
||||||
|
echo " source venv/bin/activate"
|
||||||
|
echo " sudo venv/bin/python intercept.py"
|
||||||
fi
|
fi
|
||||||
|
|
||||||
echo -e "${GREEN}Python dependencies installed successfully${NC}"
|
echo -e "${GREEN}Python dependencies installed successfully${NC}"
|
||||||
@@ -238,7 +273,12 @@ main() {
|
|||||||
echo -e "${GREEN}Setup complete!${NC}"
|
echo -e "${GREEN}Setup complete!${NC}"
|
||||||
echo ""
|
echo ""
|
||||||
echo "To start INTERCEPT:"
|
echo "To start INTERCEPT:"
|
||||||
echo " sudo python3 intercept.py"
|
if [ -d "venv" ]; then
|
||||||
|
echo " source venv/bin/activate"
|
||||||
|
echo " sudo venv/bin/python intercept.py"
|
||||||
|
else
|
||||||
|
echo " sudo python3 intercept.py"
|
||||||
|
fi
|
||||||
echo ""
|
echo ""
|
||||||
echo "Then open http://localhost:5050 in your browser"
|
echo "Then open http://localhost:5050 in your browser"
|
||||||
echo ""
|
echo ""
|
||||||
|
|||||||
Reference in New Issue
Block a user