mirror of
https://github.com/smittix/intercept.git
synced 2026-07-02 14:58:58 -07:00
docs: refactor documentation to remove duplication and improve clarity
- README: remove CW/Morse notes, condense multi-arch Docker detail, fix screenshot path, tighten credentials note - FEATURES.md: replace 550-line bullet dump with a concise mode→link table - USAGE.md: replace 140-line Webhooks section with pointer to new WEBHOOKS.md; remove duplicate Configuration and CLI Options sections - docs/WEBHOOKS.md: new file with full webhook setup, payload format, and Discord relay guide - HARDWARE.md: remove duplicate Quick Install / Python Environment / Running INTERCEPT sections; add Icecast setup section - TROUBLESHOOTING.md: replace Icecast install/config block with pointer to HARDWARE.md; replace duplicate udev rules with pointer to HARDWARE.md - SECURITY.md: update auth section to reflect admin/admin login (was "no authentication mechanism") - UI_GUIDE.md: add contributor/developer notice at the top Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
James Smith
+43
-553
@@ -1,553 +1,43 @@
|
||||
# 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
|
||||
|
||||
## Sub-GHz Analyzer
|
||||
|
||||
- **HackRF-based** signal capture and analysis for 300-928 MHz ISM bands
|
||||
- **Protocol decoding** - identify and decode common Sub-GHz protocols
|
||||
- **Signal replay/transmit** capabilities for authorized testing
|
||||
- **Wideband spectrum analysis** with real-time visualization
|
||||
- **I/Q capture** - record raw samples for offline analysis
|
||||
|
||||
## Spy Stations (Number Stations)
|
||||
|
||||
- **Comprehensive database** of active number stations and diplomatic networks
|
||||
- **Station profiles** - frequencies, schedules, operators, descriptions
|
||||
- **Filter by type** - number stations vs diplomatic networks
|
||||
- **Filter by country** - Russia, Cuba, Israel, Poland, North Korea, etc.
|
||||
- **Filter by mode** - USB, AM, CW, OFDM
|
||||
- **Tune integration** - click to tune Listening Post to station frequency
|
||||
- **Source links** - references to priyom.org for detailed information
|
||||
- **Famous stations** - UVB-76 "The Buzzer", Cuban HM01, Israeli E17z
|
||||
|
||||
## 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
|
||||
- **Persistent ADS-B history** - optional Postgres-backed message and snapshot storage
|
||||
- **History reporting dashboard** - session controls, aircraft timelines, and detail modal
|
||||
- **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
|
||||
|
||||
<p align="center">
|
||||
<img src="/static/images/screenshots/screenshot_radar.png" alt="Screenshot">
|
||||
</p>
|
||||
|
||||
## AIS Vessel Tracking
|
||||
|
||||
- **Real-time vessel tracking** via AIS-catcher or rtl_ais
|
||||
- **Full-screen dashboard** - dedicated popout with maritime map
|
||||
- **Interactive Leaflet map** with OpenStreetMap tiles (dark-themed)
|
||||
- **Vessel trails** - optional track history visualization
|
||||
- **Vessel details popup** - name, MMSI, callsign, destination, ship type, speed, heading
|
||||
- **Country identification** - flag lookup via Maritime Identification Digits (MID)
|
||||
|
||||
### VHF DSC Channel 70 Monitoring
|
||||
|
||||
Digital Selective Calling (DSC) monitoring on the international maritime distress frequency.
|
||||
|
||||
- **Real-time DSC decoding** - Distress, Urgency, Safety, and Routine messages
|
||||
- **MMSI country lookup** - 180+ Maritime Identification Digit codes
|
||||
- **Distress nature identification** - Fire, Flooding, Collision, Sinking, Piracy, MOB, etc.
|
||||
- **Position extraction** - Automatic lat/lon parsing from distress messages
|
||||
- **Map markers** - Distress positions plotted with pulsing alert markers
|
||||
- **Visual alert overlay** - Prominent popup for DISTRESS and URGENCY messages
|
||||
- **Audio alerts** - Notification sound for critical messages
|
||||
- **Alert persistence** - Critical alerts stored permanently in database
|
||||
- **Acknowledgement workflow** - Track response status with notes
|
||||
- **SDR conflict detection** - Prevents device collisions with AIS tracking
|
||||
- **Alert summary** - Dashboard counts for unacknowledged distress/urgency
|
||||
|
||||
## ACARS Messaging
|
||||
|
||||
- **Real-time ACARS decoding** via acarsdec
|
||||
- **Aircraft datalink messages** - operational, weather, and position reports
|
||||
- **Multi-SDR support** - RTL-SDR, HackRF, LimeSDR, Airspy, SDRplay
|
||||
- **Message filtering** - filter by message type, flight, or registration
|
||||
|
||||
## VDL2 (VHF Data Link Mode 2)
|
||||
|
||||
- **Real-time VDL2 decoding** via dumpvdl2 on standard VDL2 frequencies
|
||||
- **ACARS-over-AVLC** message capture with full frame parsing
|
||||
- **Signal analysis** - frequency, signal level, noise level, SNR, burst length
|
||||
- **AVLC frame details** - source/destination addresses, frame type, command/response
|
||||
- **Raw JSON inspection** - expandable raw message data for each frame
|
||||
- **Multi-frequency monitoring** - simultaneous reception on multiple VDL2 channels
|
||||
- **Multi-SDR support** - RTL-SDR, HackRF, LimeSDR, Airspy, SDRplay
|
||||
- **CSV/JSON export** - export captured messages for offline analysis
|
||||
- **Integrated with ADS-B dashboard** - VDL2 messages linked to aircraft tracking
|
||||
|
||||
## CW/Morse Code Decoder
|
||||
|
||||
- **Custom Goertzel tone detection** for CW (continuous wave) Morse decoding
|
||||
- **OOK/AM envelope detection** mode for on-off keying signals in ISM bands
|
||||
- **HF frequency presets** for amateur CW bands (160m-10m)
|
||||
- **ISM band presets** for OOK envelope mode (315 MHz, 433 MHz, 868 MHz, 915 MHz)
|
||||
- **Real-time character and word output** with WPM estimation
|
||||
- **Multi-SDR support** - RTL-SDR, HackRF, LimeSDR, Airspy, SDRplay
|
||||
|
||||
## WeFax (Weather Fax)
|
||||
|
||||
- **HF weather fax reception** from marine and meteorological broadcast stations
|
||||
- **Broadcast timeline** with scheduled transmission times by station
|
||||
- **Auto-scheduler** for unattended capture of scheduled broadcasts
|
||||
- **Image gallery** with timestamped decoded weather charts
|
||||
- **Station presets** for major WeFax broadcasters worldwide
|
||||
- **Multi-SDR support** - RTL-SDR, HackRF, LimeSDR, Airspy, SDRplay
|
||||
|
||||
## Listening Post
|
||||
|
||||
- **Wideband frequency scanning** via rtl_power sweep with SNR filtering
|
||||
- **Real-time audio monitoring** with FM and SSB demodulation
|
||||
- **Cross-module frequency routing** from scanner to decoders
|
||||
- **Waterfall spectrum display** for visual signal identification
|
||||
- **Customizable frequency presets** and band bookmarks
|
||||
- **Multi-SDR support** - RTL-SDR, LimeSDR, HackRF, Airspy, SDRplay
|
||||
|
||||
## Weather Satellites
|
||||
|
||||
- **NOAA APT** and **Meteor LRPT** image decoding via SatDump
|
||||
- **Auto-scheduler** with pass prediction and automatic capture
|
||||
- **Polar plot** - real-time satellite position on azimuth/elevation display
|
||||
- **Ground track map** - orbit path with past/future trajectory
|
||||
- **Image gallery** with timestamped decoded imagery
|
||||
|
||||
## WebSDR
|
||||
|
||||
- **KiwiSDR network integration** for remote HF/shortwave listening
|
||||
- **WebSocket audio streaming** from remote receivers
|
||||
- **Receiver discovery** with automatic caching
|
||||
- **Frequency tuning** with band presets
|
||||
|
||||
## ISS SSTV
|
||||
|
||||
- **ISS SSTV image reception** on 145.800 MHz FM during special event transmissions
|
||||
- **Real-time ISS tracking** with world map and pass predictions
|
||||
- **Doppler correction** - optional lat/lon input for real-time frequency shift compensation
|
||||
- **Next pass countdown** - time remaining until ISS is overhead
|
||||
- **Image gallery** with timestamped decoded imagery
|
||||
- **TLE updates** - fetch latest ISS orbital elements
|
||||
- **Multi-SDR support** - RTL-SDR, HackRF, LimeSDR, Airspy, SDRplay
|
||||
|
||||
## HF SSTV
|
||||
|
||||
- **Terrestrial SSTV decoding** across HF (80m-10m), VHF (6m, 2m), and UHF (70cm) bands
|
||||
- **Predefined frequency lookup** for 13 active SSTV calling frequencies
|
||||
- **Auto-modulation selection** - frequency table maps to correct mode (USB, LSB, FM)
|
||||
- **Image gallery** with decoded transmissions
|
||||
- **Common modes supported** - PD120, PD180, Martin1, Scottie1, Robot36
|
||||
|
||||
## APRS
|
||||
|
||||
- **Amateur packet radio** position reports and telemetry via direwolf
|
||||
- **Region-specific frequencies** - 144.390 MHz (North America), 144.800 MHz (Europe), and more
|
||||
- **Real-time position tracking** on interactive map
|
||||
- **Message and telemetry display** from APRS network
|
||||
|
||||
## Utility Meter Reading
|
||||
|
||||
- **Smart meter monitoring** via rtl_amr for electric, gas, and water meters
|
||||
- **Real-time JSON output** with meter ID, consumption, and signal data
|
||||
- **Multiple meter protocol support** via rtl_tcp integration
|
||||
|
||||
## Space Weather
|
||||
|
||||
- **Real-time solar indices** - Solar Flux Index (SFI), Kp index, A-index, sunspot number
|
||||
- **NOAA Space Weather Scales** - Geomagnetic storms (G), solar radiation (S), radio blackouts (R)
|
||||
- **HF band conditions** - Day/night propagation from HamQSL for 80m through 10m bands
|
||||
- **Solar wind monitoring** - Speed, density, and IMF Bz from DSCOVR satellite
|
||||
- **X-ray flux chart** - GOES X-ray data with flare class scale (A/B/C/M/X)
|
||||
- **Flare probability** - 1-day and 3-day C/M/X-class flare forecasts
|
||||
- **Solar imagery** - NASA SDO 193A, 304A, and magnetogram images
|
||||
- **D-RAP absorption maps** - HF radio absorption at 5-30 MHz frequency bands
|
||||
- **Aurora forecast** - OVATION aurora oval visualization
|
||||
- **SWPC alerts** - Real-time space weather alerts and warnings
|
||||
- **Active solar regions** - Current sunspot region data with location and area
|
||||
- **Auto-refresh** - 5-minute polling with manual refresh option
|
||||
- **No SDR required** - Data fetched from NOAA SWPC, NASA SDO, and HamQSL public APIs
|
||||
|
||||
## Radiosonde Weather Balloon Tracking
|
||||
|
||||
- **400-406 MHz reception** via radiosonde_auto_rx for weather balloon telemetry
|
||||
- **Frequency presets** for common radiosonde bands
|
||||
- **Real-time telemetry** - altitude, temperature, humidity, pressure, GPS position
|
||||
- **Interactive map** with balloon trajectory and burst point prediction
|
||||
- **Station location** with configurable observer position
|
||||
- **Distance tracking** - real-time distance-to-balloon calculation
|
||||
- **Multi-SDR support** - RTL-SDR, HackRF, LimeSDR, Airspy, SDRplay
|
||||
|
||||
## 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
|
||||
- **Multiple satellite tracking** simultaneously
|
||||
|
||||
<p align="center">
|
||||
<img src="/static/images/screenshots/screenshot_sat.png" alt="Screenshot">
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="/static/images/screenshots/screenshot_sat_2.png" alt="Screenshot">
|
||||
</p>
|
||||
|
||||
## 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, bleak
|
||||
- **Tracker detection** - AirTag, Tile, Samsung SmartTag, Chipolo
|
||||
- **Device classification** - phones, audio, wearables, computers
|
||||
- **Manufacturer lookup** via OUI database and Bluetooth Company IDs
|
||||
- **Proximity radar** visualization
|
||||
- **Device type breakdown** chart
|
||||
|
||||
## BT Locate (SAR Bluetooth Device Location)
|
||||
|
||||
Search and rescue Bluetooth device location with GPS-tagged signal trail mapping.
|
||||
|
||||
### Core Features
|
||||
- **Target tracking** - Locate devices by MAC address, name pattern, or IRK (Identity Resolving Key)
|
||||
- **RPA resolution** - Resolve BLE Resolvable Private Addresses using IRK for tracking devices with randomized addresses
|
||||
- **IRK auto-detection** - Extract IRKs from paired devices on macOS and Linux
|
||||
- **GPS-tagged signal trail** - Every detection is tagged with GPS coordinates for trail mapping
|
||||
- **Proximity bands** - IMMEDIATE (<1m), NEAR (1-5m), FAR (>5m) with color-coded HUD
|
||||
- **RSSI history chart** - Real-time signal strength sparkline for trend analysis
|
||||
- **Distance estimation** - Log-distance path loss model with environment presets
|
||||
- **Audio proximity alerts** - Web Audio API tones that increase in pitch as signal strengthens
|
||||
- **Hand-off from Bluetooth mode** - One-click transfer of a device from BT scanner to BT Locate
|
||||
|
||||
### Environment Presets
|
||||
- **Open Field** (n=2.0) - Free space path loss
|
||||
- **Outdoor** (n=2.2) - Typical outdoor environment
|
||||
- **Indoor** (n=3.0) - Indoor with walls and obstacles
|
||||
|
||||
### Map & Trail
|
||||
- Interactive Leaflet map with GPS trail visualization
|
||||
- Trail points color-coded by proximity band
|
||||
- Polyline connecting detection points for path visualization
|
||||
- Supports user-configured tile providers
|
||||
|
||||
### Requirements
|
||||
- Bluetooth adapter (built-in or USB)
|
||||
- GPS receiver (optional, falls back to manual coordinates)
|
||||
|
||||
## WiFi Locate
|
||||
|
||||
Locate a WiFi access point by BSSID using real-time signal strength tracking.
|
||||
|
||||
### Core Features
|
||||
- **Target by BSSID** - Enter any MAC address or hand off from the WiFi scanner
|
||||
- **Real-time signal meter** - Large dBm display with color-coded strength (good/medium/weak)
|
||||
- **20-segment signal bar** - Visual proximity indicator with red/yellow/green segments
|
||||
- **RSSI history chart** - Canvas sparkline showing signal trend over time
|
||||
- **Distance estimation** - Log-distance path loss model with configurable environment presets
|
||||
- **Audio proximity alerts** - Web Audio API tones that increase in pitch and frequency as signal strengthens
|
||||
- **Signal lost detection** - 30-second timeout with visual overlay when target disappears
|
||||
- **Hand-off from WiFi mode** - One-click transfer from WiFi detail drawer to WiFi Locate
|
||||
- **Stats tracking** - Current, min, max, and average RSSI across session
|
||||
|
||||
### Environment Presets
|
||||
- **Open Field** (n=2.0) - Free space path loss
|
||||
- **Outdoor** (n=2.8) - Typical outdoor environment (default)
|
||||
- **Indoor** (n=3.5) - Indoor with walls and obstacles
|
||||
|
||||
### Mode Transition
|
||||
- WiFi scan is preserved when switching between WiFi and WiFi Locate modes
|
||||
- Deep scan auto-starts if not already running
|
||||
|
||||
### Requirements
|
||||
- WiFi adapter capable of monitor mode
|
||||
- aircrack-ng suite for deep scanning
|
||||
|
||||
## GPS Mode
|
||||
|
||||
Real-time GPS position tracking with live map visualization.
|
||||
|
||||
### Features
|
||||
- **Live position tracking** - Real-time latitude, longitude, altitude display
|
||||
- **Interactive map** - Current position on Leaflet map with track history
|
||||
- **Speed and heading** - Real-time speed (km/h) and compass heading
|
||||
- **Satellite info** - Number of satellites in view and fix quality
|
||||
- **Track recording** - Record GPS tracks with export capability
|
||||
- **Accuracy display** - Horizontal and vertical position accuracy (EPX/EPY)
|
||||
|
||||
### Requirements
|
||||
- USB GPS receiver connected via gpsd
|
||||
- gpsd daemon running (`sudo gpsd /dev/ttyUSB0 -F /var/run/gpsd.sock`)
|
||||
|
||||
## TSCM Counter-Surveillance Mode
|
||||
|
||||
Technical Surveillance Countermeasures (TSCM) screening for detecting wireless surveillance indicators.
|
||||
|
||||
### Wireless Sweep Features
|
||||
- **BLE scanning** with manufacturer data detection (AirTags, Tile, SmartTags, ESP32)
|
||||
- **WiFi scanning** for rogue APs, hidden SSIDs, camera devices
|
||||
- **RF spectrum analysis** (RTL-SDR or HackRF) - FM bugs, ISM bands, video transmitters
|
||||
- **Cross-protocol correlation** - links devices across BLE/WiFi/RF
|
||||
- **Baseline comparison** - detect new/unknown devices vs known environment
|
||||
|
||||
### MAC-Randomization Resistant Detection
|
||||
- **Device fingerprinting** based on advertisement payloads, not MAC addresses
|
||||
- **Behavioral clustering** - groups observations into probable physical devices
|
||||
- **Session tracking** - monitors device presence windows
|
||||
- **Timing pattern analysis** - detects characteristic advertising intervals
|
||||
- **RSSI trajectory correlation** - identifies co-located devices
|
||||
|
||||
### Risk Assessment
|
||||
- **Three-tier scoring model**:
|
||||
- Informational (0-2): Known or expected devices
|
||||
- Needs Review (3-5): Unusual devices requiring assessment
|
||||
- High Interest (6+): Multiple indicators warrant investigation
|
||||
- **Risk indicators**: Stable RSSI, audio-capable, ESP32 chipsets, hidden identity, MAC rotation
|
||||
- **Audit trail** - full evidence chain for each link/flag
|
||||
- **Client-safe disclaimers** - findings are indicators, not confirmed surveillance
|
||||
|
||||
### Limitations (Documented)
|
||||
- Cannot detect non-transmitting devices
|
||||
- False positives/negatives expected
|
||||
- Results require professional verification
|
||||
- No cryptographic de-randomization
|
||||
- Passive screening only (no active probing by default)
|
||||
|
||||
## Drone Intelligence
|
||||
|
||||
Multi-vector UAV detection and identification system combining three complementary detection methods into unified contact tracking.
|
||||
|
||||
### Detection Vectors
|
||||
|
||||
- **Remote ID (WiFi/BLE)** — Parses ASTM F3411-22a broadcast frames from WiFi Beacon and BLE Advertisement packets. Extracts drone ID, operator ID, drone type, GPS position, altitude, speed, and emergency status. Mandatory for all drones >250g in the US/EU since 2023.
|
||||
- **RTL-SDR RF (433/868 MHz)** — Monitors ISM bands for control link and telemetry signals characteristic of consumer and FPV drones. Detects DJI OcuSync, FrSky, FlySky, and generic FSK/GFSK drone control protocols.
|
||||
- **HackRF (2.4/5.8 GHz)** — Wide-scan of video downlink and telemetry bands used by most consumer drones. Detects power above noise floor across 2.400–2.483 GHz and 5.725–5.875 GHz ISM bands.
|
||||
|
||||
### Contact Correlation
|
||||
|
||||
The `DroneCorrelator` merges raw observations from all three vectors into unified `DroneContact` objects:
|
||||
- **TTL-based store** — contacts expire after 120 seconds of no activity
|
||||
- **Multi-vector fusion** — a single contact can be seen on 1–3 vectors simultaneously
|
||||
- **Deduplication** — observations from the same vector within 5 seconds are collapsed
|
||||
|
||||
### Risk Scoring
|
||||
|
||||
| Level | Criteria |
|
||||
|-------|----------|
|
||||
| High | No Remote ID broadcast (non-compliant) or ASTM non-conformant frame |
|
||||
| Medium | Multiple detection vectors active, or RSSI delta >15 dB between vectors |
|
||||
| Low | Compliant Remote ID present, single detection vector |
|
||||
|
||||
### Live Map
|
||||
|
||||
Remote ID contacts with GPS position data are plotted on a Leaflet map. Markers show drone ID and last known coordinates. Map updates in real time via SSE.
|
||||
|
||||
### Requirements
|
||||
|
||||
- WiFi adapter capable of monitor mode (for BLE/WiFi Remote ID)
|
||||
- RTL-SDR dongle (for 433/868 MHz RF detection)
|
||||
- HackRF One (optional, for 2.4/5.8 GHz detection)
|
||||
- Python package: `opendroneid>=1.0`
|
||||
|
||||
## Meshtastic Mesh Networks
|
||||
|
||||
Integration with Meshtastic LoRa mesh networking devices for decentralized communication.
|
||||
|
||||
### Device Support
|
||||
- **Heltec** - LoRa32 series
|
||||
- **T-Beam** - TTGO T-Beam with GPS
|
||||
- **RAK** - WisBlock series
|
||||
- Any Meshtastic-compatible device via USB/Serial
|
||||
|
||||
### Features
|
||||
- **Real-time messaging** - Stream messages as they arrive
|
||||
- **Channel configuration** - Set encryption keys and channel names
|
||||
- **Node information** - View connected nodes with signal metrics
|
||||
- **Message history** - Up to 500 messages retained
|
||||
- **Signal quality** - RSSI and SNR for each message
|
||||
- **Hop tracking** - See message hop count
|
||||
|
||||
### Requirements
|
||||
- Physical Meshtastic device connected via USB
|
||||
- Meshtastic Python SDK (`pip install meshtastic`)
|
||||
|
||||
## Ubertooth One BLE Scanning
|
||||
|
||||
Advanced Bluetooth Low Energy scanning using Ubertooth One hardware.
|
||||
|
||||
### Capabilities
|
||||
- **40-channel scanning** - Capture BLE advertisements across all channels
|
||||
- **Raw payload access** - Full advertising data for analysis
|
||||
- **Passive sniffing** - No active scanning required
|
||||
- **MAC address extraction** - Public and random address types
|
||||
- **RSSI measurement** - Signal strength for proximity estimation
|
||||
|
||||
### Integration
|
||||
- Works alongside standard BlueZ/DBus Bluetooth scanning
|
||||
- Automatically detected when ubertooth-btle is available
|
||||
- Falls back to standard adapter if Ubertooth not present
|
||||
|
||||
### Requirements
|
||||
- Ubertooth One hardware
|
||||
- ubertooth-btle command-line tool installed
|
||||
- libubertooth library
|
||||
|
||||
## Remote Agents (Distributed SIGINT)
|
||||
|
||||
Deploy lightweight sensor nodes across multiple locations and aggregate data to a central controller.
|
||||
|
||||
### Architecture
|
||||
- **Hub-and-spoke model** - Central controller with multiple remote agents
|
||||
- **Push and Pull modes** - Agents can push data automatically or respond to on-demand requests
|
||||
- **API key authentication** - Secure communication between agents and controller
|
||||
|
||||
### Agent Features
|
||||
- **Standalone deployment** - Run on Raspberry Pi, mini PCs, or any Linux device with SDR
|
||||
- **All modes supported** - Pager, sensor, ADS-B, AIS, WiFi, Bluetooth, and more
|
||||
- **GPS integration** - Automatic location tagging from USB GPS receivers
|
||||
- **Multi-SDR support** - Run multiple modes simultaneously on agents with multiple SDRs
|
||||
- **Capability discovery** - Controller auto-detects available modes and devices
|
||||
|
||||
### Controller Features
|
||||
- **Agent management UI** - Register, test, and remove agents from `/controller/manage`
|
||||
- **Real-time status** - Health monitoring with online/offline indicators
|
||||
- **Unified data stream** - Aggregate data from all agents via SSE
|
||||
- **Dashboard integration** - Agent selector in ADS-B, AIS, and main dashboards
|
||||
- **Device conflict detection** - Smart warnings when SDR is in use
|
||||
|
||||
### Use Cases
|
||||
- **Wide-area monitoring** - Cover larger geographic areas with distributed sensors
|
||||
- **Remote installations** - Deploy sensors in locations without direct access
|
||||
- **Redundancy** - Multiple nodes for reliable coverage
|
||||
- **Triangulation** - Use multiple GPS-enabled agents for signal location
|
||||
|
||||
## System Health
|
||||
|
||||
- **Telemetry dashboard** with real-time system metrics
|
||||
- **Process monitoring** for all running SDR tools and decoders
|
||||
- **CPU, memory, and disk usage** tracking
|
||||
- **SDR device status** overview
|
||||
- **No SDR required** - monitors system health independently
|
||||
|
||||
## User Interface
|
||||
|
||||
- **Mode-specific header stats** - real-time badges showing key metrics per mode
|
||||
- **UTC clock** - always visible in header for time-critical operations
|
||||
- **SSE connection status indicator** - real-time connection state with SSEManager and exponential backoff reconnection
|
||||
- **Accessibility** - aria-labels, form label associations, keyboard list navigation, and destructive action confirmation modals
|
||||
- **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 |
|
||||
|
||||
## Offline Mode
|
||||
|
||||
Run iNTERCEPT without internet connectivity by using bundled local assets.
|
||||
|
||||
### Bundled Assets
|
||||
- **Leaflet 1.9.4** - Map library with marker images
|
||||
- **Chart.js 4.4.1** - Signal strength graphs
|
||||
- **Inter font** - Primary UI font (400, 500, 600, 700 weights)
|
||||
- **JetBrains Mono font** - Monospace/code font (400, 500, 600, 700 weights)
|
||||
|
||||
### Settings Modal
|
||||
Access via the gear icon in the navigation bar:
|
||||
- **Offline Tab** - Toggle offline mode, configure asset sources (CDN vs local)
|
||||
- **Display Tab** - Theme and animation preferences
|
||||
- **About Tab** - Version info and links
|
||||
|
||||
### Map Tile Providers
|
||||
Choose from multiple tile sources for maps:
|
||||
- **OpenStreetMap** - Default, general purpose
|
||||
- **CartoDB Dark** - Dark themed, matches UI
|
||||
- **CartoDB Positron** - Light themed
|
||||
- **ESRI World Imagery** - Satellite imagery
|
||||
- **Custom URL** - Connect to your own tile server (e.g., local OpenStreetMap tile cache)
|
||||
|
||||
### Local Asset Status
|
||||
The settings modal shows availability status for each bundled asset:
|
||||
- Green "Available" badge when asset is present
|
||||
- Red "Missing" badge when asset is not found
|
||||
- Click "Check Assets" to refresh status
|
||||
|
||||
### Use Cases
|
||||
- **Air-gapped environments** - Run on isolated networks
|
||||
- **Field deployments** - Operate without reliable internet
|
||||
- **Local tile servers** - Use pre-cached map tiles for specific regions
|
||||
- **Reduced latency** - Faster loading with local assets
|
||||
|
||||
## General
|
||||
|
||||
- **Web-based interface** - no desktop app needed
|
||||
- **Production server** - gunicorn + gevent via `start.sh` for concurrent SSE/WebSocket handling (falls back to Flask dev server)
|
||||
- **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
|
||||
- **HTTPS support** via `INTERCEPT_HTTPS` configuration for secure deployments
|
||||
- **Voice alerts** for configurable event notifications across modes
|
||||
- **Multi-SDR hardware support** - RTL-SDR, LimeSDR, HackRF, Airspy, SDRplay
|
||||
- **Automatic device detection** across all supported hardware
|
||||
- **Hardware-specific validation** - frequency/gain ranges per device type
|
||||
- **Tool path overrides** via `INTERCEPT_*_PATH` environment variables
|
||||
- **Native Homebrew detection** for Apple Silicon tool paths
|
||||
- **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
|
||||
|
||||
# INTERCEPT Features
|
||||
|
||||
Quick reference for all supported modes. Click any mode for full usage instructions.
|
||||
|
||||
| Mode | Description | Tools Required |
|
||||
|------|-------------|----------------|
|
||||
| [Pager Decoding](USAGE.md#pager-mode) | POCSAG 512/1200/2400 and FLEX decoding | RTL-SDR, multimon-ng |
|
||||
| [433MHz Sensors](USAGE.md#433mhz-sensor-mode) | 200+ device protocols — weather, TPMS, IoT | RTL-SDR, rtl_433 |
|
||||
| [Sub-GHz Analyzer](USAGE.md#sub-ghz-analyzer) | 300–928 MHz ISM capture, decode, replay | HackRF |
|
||||
| [Aircraft Tracking (ADS-B)](USAGE.md#aircraft-mode-ads-b) | Real-time radar map, virtual radar scope, filtering | RTL-SDR, dump1090 |
|
||||
| [ADS-B History](USAGE.md#ads-b-history-optional) | Persistent aircraft history and reporting dashboard | PostgreSQL (optional) |
|
||||
| [Vessel Tracking (AIS)](USAGE.md#ais-vessel-tracking) | Maritime map, DSC Channel 70 distress monitoring | RTL-SDR, AIS-catcher |
|
||||
| [ACARS Messaging](USAGE.md#acars-messaging) | Aircraft datalink messages | RTL-SDR, acarsdec |
|
||||
| [VDL2](USAGE.md#vdl2-aircraft-datalink) | VHF Data Link Mode 2 aircraft datalink | RTL-SDR, dumpvdl2 |
|
||||
| [Listening Post](USAGE.md#listening-post) | Wideband scanner with real-time audio streaming | RTL-SDR/HackRF, Icecast |
|
||||
| [Weather Satellites](USAGE.md#weather-satellites) | NOAA APT and Meteor LRPT image decoding | RTL-SDR, SatDump |
|
||||
| [WebSDR](USAGE.md#websdr) | Remote HF/shortwave listening via KiwiSDR network | None (web-based) |
|
||||
| [ISS SSTV](USAGE.md#iss-sstv) | Slow-scan TV image reception from the ISS | RTL-SDR, slowrx |
|
||||
| [HF SSTV](USAGE.md#hf-sstv) | Terrestrial SSTV on shortwave and VHF | RTL-SDR, slowrx |
|
||||
| [APRS](USAGE.md#aprs) | Amateur packet radio position reports and telemetry | RTL-SDR/TNC, direwolf |
|
||||
| [Satellite Tracking](USAGE.md#satellite-mode) | Pass prediction, polar plot, ground track map | RTL-SDR (optional) |
|
||||
| [Utility Meters](USAGE.md#utility-meters) | Electric, gas, and water meter reading | RTL-SDR, rtlamr |
|
||||
| [WiFi Scanning](USAGE.md#wifi-mode) | Monitor mode reconnaissance, network discovery | Monitor-mode WiFi adapter |
|
||||
| [Bluetooth Scanning](USAGE.md#bluetooth-mode) | Device discovery, tracker detection (AirTag, Tile…) | Bluetooth adapter |
|
||||
| [BT Locate](USAGE.md#bt-locate-sar-device-location) | GPS-tagged signal trail and proximity alerts | Bluetooth + GPS |
|
||||
| [WiFi Locate](USAGE.md#wifi-locate-mode) | Locate APs by BSSID with signal meter and distance | WiFi adapter |
|
||||
| [GPS](USAGE.md#gps-mode) | Real-time position, speed, altitude, satellite map | GPS receiver, gpsd |
|
||||
| [TSCM](USAGE.md#tscm-counter-surveillance) | RF baseline comparison and threat detection | RTL-SDR + BT + WiFi |
|
||||
| [Drone Intelligence](USAGE.md#drone-intelligence) | UAV detection via Remote ID, RF, and HackRF | RTL-SDR / HackRF |
|
||||
| [Spy Stations](USAGE.md#spy-stations) | Number stations and diplomatic HF network database | None (database lookup) |
|
||||
| [Meshtastic](USAGE.md#meshtastic) | LoRa mesh network integration | Meshtastic device |
|
||||
| [Space Weather](USAGE.md#space-weather) | Solar and geomagnetic data from NOAA/NASA | None (web-based) |
|
||||
| [Remote Agents](USAGE.md#remote-agents-distributed-sigint) | Distributed SIGINT with remote sensor nodes | Multiple SDR nodes |
|
||||
| [Offline Mode](USAGE.md#offline-mode) | Bundled assets for air-gapped/field deployments | Any |
|
||||
|
||||
## Detailed Docs
|
||||
|
||||
- [Usage Guide](USAGE.md) — per-mode setup and operation
|
||||
- [Hardware Guide](HARDWARE.md) — SDR hardware, drivers, multiple dongles, Icecast
|
||||
- [Webhooks](WEBHOOKS.md) — alert rules and webhook integration
|
||||
- [Distributed Agents](DISTRIBUTED_AGENTS.md) — remote sensor node deployment
|
||||
- [Troubleshooting](TROUBLESHOOTING.md) — common issues and solutions
|
||||
- [Security](SECURITY.md) — network security and best practices
|
||||
|
||||
+55
-82
@@ -12,41 +12,11 @@ INTERCEPT automatically detects connected devices.
|
||||
|
||||
---
|
||||
|
||||
## Quick Install
|
||||
## Manual Installation
|
||||
|
||||
### Recommended: Use the Setup Script
|
||||
For most users `./setup.sh` handles everything. The steps below are for manual installs or when you need fine-grained control.
|
||||
|
||||
The setup script provides an interactive menu with install profiles for selective installation:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/smittix/intercept.git
|
||||
cd intercept
|
||||
./setup.sh
|
||||
```
|
||||
|
||||
On first run, a guided wizard walks you through profile selection:
|
||||
|
||||
| Profile | What it installs |
|
||||
|---------|-----------------|
|
||||
| Core SIGINT | rtl_sdr, multimon-ng, rtl_433, dump1090, acarsdec, dumpvdl2, ffmpeg, gpsd |
|
||||
| Maritime & Radio | AIS-catcher, direwolf |
|
||||
| Weather & Space | SatDump, radiosonde_auto_rx |
|
||||
| RF Security | aircrack-ng, HackRF, BlueZ, hcxtools, Ubertooth, SoapySDR |
|
||||
| Full SIGINT | All of the above |
|
||||
|
||||
For headless/CI installs:
|
||||
```bash
|
||||
./setup.sh --non-interactive # Install everything
|
||||
./setup.sh --profile=core,maritime # Install specific profiles
|
||||
```
|
||||
|
||||
After installation, use the menu to manage your setup:
|
||||
```bash
|
||||
./setup.sh # Opens interactive menu
|
||||
./setup.sh --health-check # Verify installation
|
||||
```
|
||||
|
||||
### Manual Install: macOS (Homebrew)
|
||||
### macOS (Homebrew)
|
||||
|
||||
```bash
|
||||
# Install Homebrew if needed
|
||||
@@ -68,7 +38,7 @@ brew install soapysdr limesuite soapylms7
|
||||
brew install hackrf soapyhackrf
|
||||
```
|
||||
|
||||
### Manual Install: Debian / Ubuntu / Raspberry Pi OS
|
||||
### Debian / Ubuntu / Raspberry Pi OS
|
||||
|
||||
```bash
|
||||
# Update package lists
|
||||
@@ -264,54 +234,6 @@ SoapySDRUtil --find
|
||||
|
||||
---
|
||||
|
||||
## Python Environment
|
||||
|
||||
### Using setup.sh (Recommended)
|
||||
```bash
|
||||
./setup.sh
|
||||
```
|
||||
|
||||
The setup wizard automatically:
|
||||
- Detects your OS (macOS, Debian/Ubuntu, DragonOS)
|
||||
- Lets you choose install profiles (Core, Maritime, Weather, Security, Full, Custom)
|
||||
- Creates a virtual environment with system site-packages
|
||||
- Installs Python dependencies (core + optional)
|
||||
- Runs a health check to verify everything works
|
||||
|
||||
After initial setup, use the menu to manage your environment:
|
||||
- **Install / Add Modules** — add tools you didn't install initially
|
||||
- **System Health Check** — verify all tools and dependencies
|
||||
- **Environment Configurator** — set `INTERCEPT_*` variables interactively
|
||||
- **Update Tools** — rebuild source-built tools (dump1090, SatDump, etc.)
|
||||
- **View Status** — see what's installed at a glance
|
||||
|
||||
### Manual setup
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running INTERCEPT
|
||||
|
||||
After installation:
|
||||
|
||||
```bash
|
||||
sudo ./start.sh
|
||||
|
||||
# Custom port
|
||||
sudo ./start.sh -p 8080
|
||||
|
||||
# HTTPS
|
||||
sudo ./start.sh --https
|
||||
```
|
||||
|
||||
Open **http://localhost:5050** in your browser.
|
||||
|
||||
---
|
||||
|
||||
## Complete Tool Reference
|
||||
|
||||
| Tool | Package (Debian) | Package (macOS) | Required For |
|
||||
@@ -410,6 +332,57 @@ brew install librtlsdr
|
||||
|
||||
---
|
||||
|
||||
## Listening Post — Icecast Setup
|
||||
|
||||
The Listening Post streams audio via Icecast (2-10 second latency). INTERCEPT starts Icecast automatically when you begin listening, but you must install and configure it first.
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install icecast2
|
||||
|
||||
# macOS
|
||||
brew install icecast
|
||||
```
|
||||
|
||||
### Configure
|
||||
|
||||
On Debian/Ubuntu you'll be prompted during install. Otherwise edit `/etc/icecast2/icecast.xml`:
|
||||
|
||||
```xml
|
||||
<icecast>
|
||||
<authentication>
|
||||
<source-password>hackme</source-password>
|
||||
<admin-password>your-admin-password</admin-password>
|
||||
</authentication>
|
||||
<hostname>localhost</hostname>
|
||||
<listen-socket>
|
||||
<port>8000</port>
|
||||
</listen-socket>
|
||||
</icecast>
|
||||
```
|
||||
|
||||
### Start
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo systemctl enable icecast2 && sudo systemctl start icecast2
|
||||
|
||||
# macOS
|
||||
brew services start icecast
|
||||
```
|
||||
|
||||
Verify it's running at http://localhost:8000.
|
||||
|
||||
### INTERCEPT defaults
|
||||
|
||||
INTERCEPT expects Icecast on `127.0.0.1:8000` with source password `hackme` and mount `/listen.mp3`. To change these, update the defaults in `routes/listening_post.py` or adjust via the Listening Post config panel in the UI.
|
||||
|
||||
For audio troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md#audio-streaming-issues).
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Bluetooth on macOS**: Uses bleak library (CoreBluetooth backend), bluez tools not needed
|
||||
|
||||
+5
-3
@@ -23,13 +23,15 @@ By default, INTERCEPT binds to `0.0.0.0:5050`, making it accessible from any net
|
||||
sudo ./start.sh -H 127.0.0.1
|
||||
```
|
||||
|
||||
3. **Trusted Networks Only**: Only run INTERCEPT on networks you trust. The application has no authentication mechanism.
|
||||
3. **Trusted Networks Only**: Only run INTERCEPT on networks you trust. Default credentials are admin / admin — change them before network exposure.
|
||||
|
||||
## Authentication
|
||||
|
||||
INTERCEPT does **not** include authentication. This is by design for ease of use as a personal tool. If you need to expose INTERCEPT to untrusted networks:
|
||||
INTERCEPT includes basic username/password authentication (default credentials: **admin / admin**). **Change these before exposing the application on any network** — update `ADMIN_USERNAME` and `ADMIN_PASSWORD` in `config.py`.
|
||||
|
||||
1. Use a reverse proxy (nginx, Caddy) with authentication
|
||||
For additional protection when exposing INTERCEPT beyond your local machine:
|
||||
|
||||
1. Use a reverse proxy (nginx, Caddy) with authentication or TLS
|
||||
2. Use a VPN to access your home network
|
||||
3. Use SSH port forwarding: `ssh -L 5050:localhost:5050 your-server`
|
||||
|
||||
|
||||
+4
-81
@@ -110,17 +110,7 @@ pip install --user -r requirements.txt
|
||||
|
||||
### 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.
|
||||
See [HARDWARE.md — RTL-SDR Setup](HARDWARE.md#rtl-sdr-setup-linux) for udev rules and driver blacklisting.
|
||||
|
||||
### Device busy error
|
||||
|
||||
@@ -189,78 +179,11 @@ which rx_fm
|
||||
|
||||
If `rx_fm` is installed, select your device from the SDR dropdown in the Listening Post - HackRF, Airspy, LimeSDR, and SDRPlay are all supported.
|
||||
|
||||
### Setting up Icecast for Listening Post Audio
|
||||
### Listening Post — No Audio / Icecast Errors
|
||||
|
||||
The Listening Post uses Icecast for low-latency audio streaming (2-10 second latency). Intercept will automatically start Icecast when you begin listening, but you must install and configure it first.
|
||||
For Icecast install and configuration, see [HARDWARE.md — Listening Post Setup](HARDWARE.md#listening-post--icecast-setup).
|
||||
|
||||
**Install Icecast:**
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install icecast2
|
||||
|
||||
# macOS
|
||||
brew install icecast
|
||||
```
|
||||
|
||||
**Configure Icecast:**
|
||||
|
||||
During installation on Debian/Ubuntu, you'll be prompted to configure. Otherwise, edit `/etc/icecast2/icecast.xml`:
|
||||
|
||||
```xml
|
||||
<icecast>
|
||||
<authentication>
|
||||
<!-- Source password - used by ffmpeg to send audio -->
|
||||
<source-password>hackme</source-password>
|
||||
<!-- Admin password for web interface -->
|
||||
<admin-password>your-admin-password</admin-password>
|
||||
</authentication>
|
||||
<hostname>localhost</hostname>
|
||||
<listen-socket>
|
||||
<port>8000</port>
|
||||
</listen-socket>
|
||||
</icecast>
|
||||
```
|
||||
|
||||
**Start Icecast:**
|
||||
```bash
|
||||
# Ubuntu/Debian (as service)
|
||||
sudo systemctl enable icecast2
|
||||
sudo systemctl start icecast2
|
||||
|
||||
# Or run directly
|
||||
icecast -c /etc/icecast2/icecast.xml
|
||||
|
||||
# macOS
|
||||
brew services start icecast
|
||||
# Or: icecast -c /usr/local/etc/icecast.xml
|
||||
```
|
||||
|
||||
**Verify Icecast is running:**
|
||||
- Open http://localhost:8000 in your browser
|
||||
- You should see the Icecast status page
|
||||
|
||||
**Configure Intercept (optional):**
|
||||
|
||||
The default configuration expects Icecast on `127.0.0.1:8000` with source password `hackme` and mount point `/listen.mp3`. To change these, modify the scanner config in your API calls or update the defaults in `routes/listening_post.py`:
|
||||
|
||||
```python
|
||||
scanner_config = {
|
||||
# ... other settings ...
|
||||
'icecast_host': '127.0.0.1',
|
||||
'icecast_port': 8000,
|
||||
'icecast_mount': '/listen.mp3',
|
||||
'icecast_source_password': 'hackme',
|
||||
}
|
||||
```
|
||||
|
||||
**Troubleshooting Icecast:**
|
||||
|
||||
- **"Connection refused" errors**: Ensure Icecast is running on the configured port
|
||||
- **"Authentication failed"**: Check the source password matches between Icecast config and Intercept
|
||||
- **No audio playing**: Check Icecast status page (http://localhost:8000) to verify the mount point is active
|
||||
- **High latency**: Ensure nginx/reverse proxy isn't buffering - add `proxy_buffering off;` to nginx config
|
||||
|
||||
### Audio Streaming Issues - Detailed Debugging
|
||||
### Audio Streaming Issues
|
||||
|
||||
If the Listening Post shows "Icecast mount not active" errors or audio doesn't play:
|
||||
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# iNTERCEPT UI Guide
|
||||
|
||||
> **This is a contributor/developer reference.** It documents the design system, CSS tokens, and patterns for adding new modes or dashboards. If you're looking for usage instructions, see [USAGE.md](USAGE.md).
|
||||
|
||||
This guide documents the UI design system, components, and patterns used in iNTERCEPT.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
+2
-183
@@ -570,187 +570,6 @@ For complete documentation, see [Distributed Agents Guide](DISTRIBUTED_AGENTS.md
|
||||
|
||||
## Webhooks & Notifications
|
||||
|
||||
INTERCEPT has a built-in alert engine that fires webhooks when decoded events match configurable rules. This lets you forward pager messages (or events from any other mode) to Discord, Slack, n8n, Home Assistant, or any HTTP endpoint.
|
||||
INTERCEPT has a built-in alert engine that fires webhooks on decoded events. Configure rules in the Alerts panel to forward pager messages, ADS-B alerts, WiFi events, or anything else to Discord, Slack, n8n, Home Assistant, or any HTTP endpoint.
|
||||
|
||||
### How it works
|
||||
|
||||
1. You configure **alert rules** via the Alerts UI — each rule defines which mode and event type to watch, optional match criteria, and a severity level.
|
||||
2. When an incoming event matches a rule, INTERCEPT stores it in the alert log and POSTs a JSON payload to your configured webhook URL.
|
||||
3. All modes are supported: pager, sensor, ADS-B, AIS, ACARS, WiFi, Bluetooth, and more.
|
||||
|
||||
### Enable the webhook
|
||||
|
||||
Set these environment variables in your `.env` file or `docker-compose.yml`:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `ALERT_WEBHOOK_URL` | _(empty)_ | URL to POST alert payloads to |
|
||||
| `ALERT_WEBHOOK_SECRET` | _(empty)_ | Optional token sent as `X-Alert-Token` header |
|
||||
| `ALERT_WEBHOOK_TIMEOUT` | `5` | HTTP timeout in seconds |
|
||||
|
||||
**Local install (`.env`):**
|
||||
```env
|
||||
ALERT_WEBHOOK_URL=https://your-endpoint.example.com/intercept-alerts
|
||||
ALERT_WEBHOOK_SECRET=mysecrettoken
|
||||
```
|
||||
|
||||
**Docker (`.env` or `docker-compose.yml` environment block):**
|
||||
```env
|
||||
ALERT_WEBHOOK_URL=https://your-endpoint.example.com/intercept-alerts
|
||||
ALERT_WEBHOOK_SECRET=mysecrettoken
|
||||
```
|
||||
|
||||
### Create an alert rule
|
||||
|
||||
1. Open the **Alerts** panel in INTERCEPT
|
||||
2. Click **New Rule**
|
||||
3. Configure:
|
||||
- **Mode**: `pager` (or any other mode, or leave blank to match all)
|
||||
- **Event type**: `message` for pager decodes (or blank to match all event types)
|
||||
- **Match criteria**: leave empty to forward everything, or add filters (e.g. capcode equals `1234567`, or message contains `FIRE`)
|
||||
- **Severity**: `low`, `medium`, or `high`
|
||||
4. Save and enable the rule
|
||||
|
||||
### Webhook payload format
|
||||
|
||||
INTERCEPT sends a POST request with `Content-Type: application/json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 42,
|
||||
"rule_id": 1,
|
||||
"mode": "pager",
|
||||
"event_type": "message",
|
||||
"severity": "medium",
|
||||
"title": "My Pager Rule",
|
||||
"message": "message | 1234567",
|
||||
"created_at": "2026-04-13T10:00:00+00:00",
|
||||
"payload": {
|
||||
"mode": "pager",
|
||||
"event_type": "message",
|
||||
"event": {
|
||||
"capcode": "1234567",
|
||||
"message": "UNIT 4 RESPOND TO 123 MAIN ST",
|
||||
"type": "POCSAG1200"
|
||||
},
|
||||
"rule": { "id": 1, "name": "My Pager Rule" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sending to Discord
|
||||
|
||||
Discord webhooks expect a specific JSON format (`content`, `embeds`), so you need a small relay between INTERCEPT and Discord. Two options:
|
||||
|
||||
**Option A — No-code relay (recommended)**
|
||||
|
||||
Use [n8n](https://n8n.io), [Make](https://make.com), or [Pipedream](https://pipedream.com) to receive INTERCEPT's webhook and forward it to Discord with a custom message template. Point `ALERT_WEBHOOK_URL` at your workflow's ingest URL.
|
||||
|
||||
**Option B — Self-hosted Python relay**
|
||||
|
||||
Save this as `discord_relay.py` and run it alongside INTERCEPT:
|
||||
|
||||
```python
|
||||
from flask import Flask, request
|
||||
import urllib.request, json
|
||||
|
||||
app = Flask(__name__)
|
||||
|
||||
DISCORD_WEBHOOK_URL = "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"
|
||||
|
||||
@app.post("/relay")
|
||||
def relay():
|
||||
data = request.get_json(force=True)
|
||||
mode = data.get("mode", "unknown").upper()
|
||||
title = data.get("title", "Alert")
|
||||
message = data.get("message", "")
|
||||
event = data.get("payload", {}).get("event", {})
|
||||
|
||||
# Build a readable Discord message
|
||||
lines = [f"**[{mode}]** {title}", message]
|
||||
if event.get("capcode"):
|
||||
lines.append(f"Capcode: `{event['capcode']}`")
|
||||
if event.get("type"):
|
||||
lines.append(f"Protocol: {event['type']}")
|
||||
|
||||
payload = json.dumps({"content": "\n".join(lines)}).encode()
|
||||
req = urllib.request.Request(
|
||||
DISCORD_WEBHOOK_URL,
|
||||
data=payload,
|
||||
headers={"Content-Type": "application/json"},
|
||||
method="POST",
|
||||
)
|
||||
urllib.request.urlopen(req, timeout=5)
|
||||
return "", 204
|
||||
|
||||
app.run(host="0.0.0.0", port=5051)
|
||||
```
|
||||
|
||||
Then set:
|
||||
```env
|
||||
ALERT_WEBHOOK_URL=http://localhost:5051/relay
|
||||
```
|
||||
|
||||
Run the relay: `python3 discord_relay.py`
|
||||
|
||||
The relay formats pager decodes as Discord messages like:
|
||||
|
||||
```
|
||||
[PAGER] My Pager Rule
|
||||
message | 1234567
|
||||
Capcode: `1234567`
|
||||
Protocol: POCSAG1200
|
||||
```
|
||||
|
||||
### Filtering specific capcodes
|
||||
|
||||
To only forward decodes from a specific capcode, set the rule's **Match criteria**:
|
||||
|
||||
| Field | Operator | Value |
|
||||
|-------|----------|-------|
|
||||
| `capcode` | equals | `1234567` |
|
||||
|
||||
Multiple rules can coexist — e.g. one rule for all pager traffic to a general Discord channel, and a second rule for emergency capcodes with `high` severity to a separate channel (using a second relay instance on a different port).
|
||||
|
||||
## 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 ./start.sh`
|
||||
|
||||
## Command-line Options
|
||||
|
||||
### Production server (recommended)
|
||||
|
||||
```
|
||||
sudo ./start.sh --help
|
||||
|
||||
-p, --port PORT Port to listen on (default: 5050)
|
||||
-H, --host HOST Host to bind to (default: 0.0.0.0)
|
||||
-d, --debug Run in debug mode (Flask dev server)
|
||||
--https Enable HTTPS with self-signed certificate
|
||||
--check-deps Check dependencies and exit
|
||||
```
|
||||
|
||||
> **Note:** `sudo` is required for SDR hardware access, WiFi monitor mode, and Bluetooth low-level operations.
|
||||
|
||||
`start.sh` auto-detects gunicorn + gevent and runs a production WSGI server with cooperative greenlets — this handles multiple SSE streams and WebSocket connections concurrently without blocking. Falls back to the Flask dev server if gunicorn is not installed.
|
||||
|
||||
### Development server
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
See [WEBHOOKS.md](WEBHOOKS.md) for configuration, payload format, and Discord relay setup.
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
# Webhooks & Alert Notifications
|
||||
|
||||
INTERCEPT has a built-in alert engine that fires webhooks when decoded events match configurable rules. Forward pager messages (or events from any other mode) to Discord, Slack, n8n, Home Assistant, or any HTTP endpoint.
|
||||
|
||||
## How it works
|
||||
|
||||
1. Configure **alert rules** in the Alerts UI — each rule defines which mode and event type to watch, optional match criteria, and a severity level.
|
||||
2. When an incoming event matches a rule, INTERCEPT stores it in the alert log and POSTs a JSON payload to your configured webhook URL.
|
||||
3. All modes are supported: pager, sensor, ADS-B, AIS, ACARS, WiFi, Bluetooth, and more.
|
||||
|
||||
## Configuration
|
||||
|
||||
Set these environment variables in your `.env` file or `docker-compose.yml`:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `ALERT_WEBHOOK_URL` | _(empty)_ | URL to POST alert payloads to |
|
||||
| `ALERT_WEBHOOK_SECRET` | _(empty)_ | Optional token sent as `X-Alert-Token` header |
|
||||
| `ALERT_WEBHOOK_TIMEOUT` | `5` | HTTP timeout in seconds |
|
||||
|
||||
```env
|
||||
ALERT_WEBHOOK_URL=https://your-endpoint.example.com/intercept-alerts
|
||||
ALERT_WEBHOOK_SECRET=mysecrettoken
|
||||
```
|
||||
|
||||
## Creating alert rules
|
||||
|
||||
1. Open the **Alerts** panel in INTERCEPT
|
||||
2. Click **New Rule**
|
||||
3. Configure:
|
||||
- **Mode**: `pager` (or any other mode, or leave blank to match all)
|
||||
- **Event type**: `message` for pager decodes (or blank to match all event types)
|
||||
- **Match criteria**: leave empty to forward everything, or add filters (e.g. capcode equals `1234567`, or message contains `FIRE`)
|
||||
- **Severity**: `low`, `medium`, or `high`
|
||||
4. Save and enable the rule
|
||||
|
||||
## Webhook payload format
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 42,
|
||||
"rule_id": 1,
|
||||
"mode": "pager",
|
||||
"event_type": "message",
|
||||
"severity": "medium",
|
||||
"title": "My Pager Rule",
|
||||
"message": "message | 1234567",
|
||||
"created_at": "2026-04-13T10:00:00+00:00",
|
||||
"payload": {
|
||||
"mode": "pager",
|
||||
"event_type": "message",
|
||||
"event": {
|
||||
"capcode": "1234567",
|
||||
"message": "UNIT 4 RESPOND TO 123 MAIN ST",
|
||||
"type": "POCSAG1200"
|
||||
},
|
||||
"rule": { "id": 1, "name": "My Pager Rule" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Sending to Discord
|
||||
|
||||
Discord webhooks expect a different JSON format, so you need a relay between INTERCEPT and Discord.
|
||||
|
||||
**Option A — No-code relay (recommended)**
|
||||
|
||||
Use [n8n](https://n8n.io), [Make](https://make.com), or [Pipedream](https://pipedream.com) to receive INTERCEPT's webhook and forward it to Discord with a custom message template. Point `ALERT_WEBHOOK_URL` at your workflow's ingest URL.
|
||||
|
||||
**Option B — Self-hosted Python relay**
|
||||
|
||||
Save as `discord_relay.py` and run it alongside INTERCEPT:
|
||||
|
||||
```python
|
||||
from flask import Flask, request
|
||||
import urllib.request, json
|
||||
|
||||
app = Flask(__name__)
|
||||
|
||||
DISCORD_WEBHOOK_URL = "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"
|
||||
|
||||
@app.post("/relay")
|
||||
def relay():
|
||||
data = request.get_json(force=True)
|
||||
mode = data.get("mode", "unknown").upper()
|
||||
title = data.get("title", "Alert")
|
||||
message = data.get("message", "")
|
||||
event = data.get("payload", {}).get("event", {})
|
||||
|
||||
lines = [f"**[{mode}]** {title}", message]
|
||||
if event.get("capcode"):
|
||||
lines.append(f"Capcode: `{event['capcode']}`")
|
||||
if event.get("type"):
|
||||
lines.append(f"Protocol: {event['type']}")
|
||||
|
||||
payload = json.dumps({"content": "\n".join(lines)}).encode()
|
||||
req = urllib.request.Request(
|
||||
DISCORD_WEBHOOK_URL,
|
||||
data=payload,
|
||||
headers={"Content-Type": "application/json"},
|
||||
method="POST",
|
||||
)
|
||||
urllib.request.urlopen(req, timeout=5)
|
||||
return "", 204
|
||||
|
||||
app.run(host="0.0.0.0", port=5051)
|
||||
```
|
||||
|
||||
Set `ALERT_WEBHOOK_URL=http://localhost:5051/relay` and run: `python3 discord_relay.py`
|
||||
|
||||
## Filtering specific capcodes
|
||||
|
||||
To only forward decodes from a specific capcode, set the rule's **Match criteria**:
|
||||
|
||||
| Field | Operator | Value |
|
||||
|-------|----------|-------|
|
||||
| `capcode` | equals | `1234567` |
|
||||
|
||||
Multiple rules can coexist — e.g. one rule for all pager traffic and a second rule for emergency capcodes with `high` severity routed to a separate channel.
|
||||
Reference in New Issue
Block a user