mirror of
https://github.com/smittix/intercept.git
synced 2026-04-25 07:10:00 -07:00
500ddf59fe
Multi-arch Docker builds: - build-multiarch.sh: Cross-compile amd64+arm64 on x64 and push to registry, so RPi5 can docker pull instead of building natively - docker-compose.yml: Add INTERCEPT_IMAGE env var to support pulling pre-built images from a registry instead of local build - README.md: Docker build section rewritten with multi-arch workflow, registry pull instructions, and build script options Weather satellite antenna guide (sidebar panel): - V-Dipole: ASCII diagram, 53.4cm element length, 120 degree angle, materials, orientation, connection instructions - Turnstile/Crossed Dipole: phasing coax length (37cm RG-58), reflector distance (52cm below), RHCP explanation - QFH Quadrifilar Helix: design overview, materials, height (46cm), hemispherical gain pattern - Placement & LNA: outdoor requirements, coax loss figures, LNA mounting position, Nooelec SAWbird+ recommendation, Bias-T - Quick reference table: wavelength, quarter-wave, elevation, duration, polarization, APT/LRPT bandwidth Also added Weather Satellites and ISS SSTV to README features list, SatDump to acknowledgments. https://claude.ai/code/session_01FjLTkyELaqh27U1wEXngFQ
251 lines
8.0 KiB
Markdown
251 lines
8.0 KiB
Markdown
# INTERCEPT
|
|
|
|
<p align="center">
|
|
<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/platform-macOS%20%7C%20Linux-lightgrey.svg" alt="Platform">
|
|
</p>
|
|
|
|
<p align="center">
|
|
Support the developer of this open-source project
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://www.buymeacoffee.com/smittix" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" ></a>
|
|
</p>
|
|
<p align="center">
|
|
<strong>Signal Intelligence Platform</strong><br>
|
|
A web-based interface for software-defined radio tools.
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img src="static/images/screenshots/intercept-main.png" alt="Screenshot">
|
|
</p>
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Pager Decoding** - POCSAG/FLEX via rtl_fm + multimon-ng
|
|
- **433MHz Sensors** - Weather stations, TPMS, IoT devices via rtl_433
|
|
- **Aircraft Tracking** - ADS-B via dump1090 with real-time map and radar
|
|
- **Vessel Tracking** - AIS ship tracking with VHF DSC distress monitoring
|
|
- **ACARS Messaging** - Aircraft datalink messages via acarsdec
|
|
- **Listening Post** - Frequency scanner with audio monitoring
|
|
- **Weather Satellites** - NOAA APT and Meteor LRPT image decoding via SatDump
|
|
- **ISS SSTV** - Slow-scan TV image reception from the International Space Station
|
|
- **Satellite Tracking** - Pass prediction using TLE data
|
|
- **ADS-B History** - Persistent aircraft history with reporting dashboard (Postgres optional)
|
|
- **WiFi Scanning** - Monitor mode reconnaissance via aircrack-ng
|
|
- **Bluetooth Scanning** - Device discovery and tracker detection (with Ubertooth support)
|
|
- **Meshtastic** - LoRa mesh network integration
|
|
- **Spy Stations** - Number stations and diplomatic HF network database
|
|
- **Remote Agents** - Distributed SIGINT with remote sensor nodes
|
|
- **Offline Mode** - Bundled assets for air-gapped/field deployments
|
|
|
|
---
|
|
|
|
## Installation / Debian / Ubuntu / MacOS
|
|
|
|
```
|
|
|
|
**1. Clone and run:**
|
|
```bash
|
|
git clone https://github.com/smittix/intercept.git
|
|
cd intercept
|
|
./setup.sh
|
|
sudo -E venv/bin/python intercept.py
|
|
```
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
git clone https://github.com/smittix/intercept.git
|
|
cd intercept
|
|
docker compose --profile basic up -d --build
|
|
```
|
|
|
|
> **Note:** Docker requires privileged mode for USB SDR access. SDR devices are passed through via `/dev/bus/usb`.
|
|
|
|
#### Multi-Architecture Builds (amd64 + arm64)
|
|
|
|
Cross-compile on an x64 machine and push to a registry. This is much faster than building natively on an RPi.
|
|
|
|
```bash
|
|
# One-time setup on your x64 build machine
|
|
docker run --privileged --rm tonistiigi/binfmt --install all
|
|
docker buildx create --name intercept-builder --use --bootstrap
|
|
|
|
# Build and push for both architectures
|
|
REGISTRY=ghcr.io/youruser ./build-multiarch.sh --push
|
|
|
|
# On the RPi5, just pull and run
|
|
INTERCEPT_IMAGE=ghcr.io/youruser/intercept:latest docker compose --profile basic up -d
|
|
```
|
|
|
|
Build script options:
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--push` | Push to container registry |
|
|
| `--load` | Load into local Docker (single platform only) |
|
|
| `--arm64-only` | Build arm64 only (for RPi deployment) |
|
|
| `--amd64-only` | Build amd64 only |
|
|
|
|
Environment variables: `REGISTRY`, `IMAGE_NAME`, `IMAGE_TAG`
|
|
|
|
#### Using a Pre-built Image
|
|
|
|
If you've pushed to a registry, you can skip building entirely on the target machine:
|
|
|
|
```bash
|
|
# Set in .env or export
|
|
INTERCEPT_IMAGE=ghcr.io/youruser/intercept:latest
|
|
|
|
# Then just run
|
|
docker compose --profile basic up -d
|
|
```
|
|
|
|
### ADS-B History (Optional)
|
|
|
|
The ADS-B history feature persists aircraft messages to Postgres for long-term analysis.
|
|
|
|
```bash
|
|
# Start with ADS-B history and Postgres
|
|
docker compose --profile history up -d
|
|
```
|
|
|
|
Set the following environment variables (for example in a `.env` file):
|
|
|
|
```bash
|
|
INTERCEPT_ADSB_HISTORY_ENABLED=true
|
|
INTERCEPT_ADSB_DB_HOST=adsb_db
|
|
INTERCEPT_ADSB_DB_PORT=5432
|
|
INTERCEPT_ADSB_DB_NAME=intercept_adsb
|
|
INTERCEPT_ADSB_DB_USER=intercept
|
|
INTERCEPT_ADSB_DB_PASSWORD=intercept
|
|
```
|
|
|
|
### Other ADS-B Settings
|
|
|
|
Set these as environment variables for either local installs or Docker:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `INTERCEPT_ADSB_AUTO_START` | `false` | Auto-start ADS-B tracking when the dashboard loads |
|
|
| `INTERCEPT_SHARED_OBSERVER_LOCATION` | `true` | Share observer location across ADS-B/AIS/SSTV/Satellite modules |
|
|
|
|
**Local install example**
|
|
|
|
```bash
|
|
INTERCEPT_ADSB_AUTO_START=true \
|
|
INTERCEPT_SHARED_OBSERVER_LOCATION=false \
|
|
python app.py
|
|
```
|
|
|
|
**Docker example (.env)**
|
|
|
|
```bash
|
|
INTERCEPT_ADSB_AUTO_START=true
|
|
INTERCEPT_SHARED_OBSERVER_LOCATION=false
|
|
```
|
|
|
|
To store Postgres data on external storage, set `PGDATA_PATH` (defaults to `./pgdata`):
|
|
|
|
```bash
|
|
PGDATA_PATH=/mnt/usbpi1/intercept/pgdata
|
|
```
|
|
|
|
Then open **/adsb/history** for the reporting dashboard.
|
|
|
|
### Open the Interface
|
|
|
|
After starting, open **http://localhost:5050** in your browser. The username and password is <b>admin</b>:<b>admin</b>
|
|
|
|
The credentials can be change in the ADMIN_USERNAME & ADMIN_PASSWORD variables in config.py
|
|
|
|
---
|
|
|
|
## Hardware Requirements
|
|
|
|
| Hardware | Purpose | Price |
|
|
|----------|---------|-------|
|
|
| **RTL-SDR** | Required for all SDR features | ~$25-35 |
|
|
| **WiFi adapter** | Must support promiscuous (monitor) mode | ~$20-40 |
|
|
| **Bluetooth adapter** | Device scanning (usually built-in) | - |
|
|
| **GPS** | Any Linux supported GPS Unit | ~10 |
|
|
|
|
Most features work with a basic RTL-SDR dongle (RTL2832U + R820T2).
|
|
|
|
| :exclamation: Not using an RTL-SDR Device? |
|
|
|-----------------------------------------------
|
|
|Intercept supports any device that SoapySDR supports. You must however have the correct module for your device installed! For example if you have an SDRPlay device you'd need to install soapysdr-module-sdrplay.
|
|
|
|
| :exclamation: GPS Usage |
|
|
|-----------------------------------------------
|
|
|gpsd is needed for real time location. Intercept automatically checks to see if you're running gpsd in the background when any maps are rendered.
|
|
|
|
---
|
|
|
|
## Discord Server
|
|
|
|
<p align="center">
|
|
<a href="https://discord.gg/EyeksEJmWE">Join our Discord</a>
|
|
</p>
|
|
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
- [Usage Guide](docs/USAGE.md) - Detailed instructions for each mode
|
|
- [Distributed Agents](docs/DISTRIBUTED_AGENTS.md) - Remote sensor node deployment
|
|
- [Hardware Guide](docs/HARDWARE.md) - SDR hardware and advanced setup
|
|
- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
|
|
- [Security](docs/SECURITY.md) - Network security and best practices
|
|
|
|
---
|
|
|
|
## Disclaimer
|
|
|
|
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.
|
|
|
|
**This software is for educational and authorized testing purposes only.**
|
|
|
|
- Only use with proper authorization
|
|
- Intercepting communications without consent may be illegal
|
|
- You are responsible for compliance with applicable laws
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](LICENSE)
|
|
|
|
## Author
|
|
|
|
Created by **smittix** - [GitHub](https://github.com/smittix)
|
|
|
|
## Acknowledgments
|
|
|
|
[rtl-sdr](https://osmocom.org/projects/rtl-sdr/wiki) |
|
|
[multimon-ng](https://github.com/EliasOenal/multimon-ng) |
|
|
[rtl_433](https://github.com/merbanan/rtl_433) |
|
|
[dump1090](https://github.com/flightaware/dump1090) |
|
|
[AIS-catcher](https://github.com/jvde-github/AIS-catcher) |
|
|
[acarsdec](https://github.com/TLeconte/acarsdec) |
|
|
[aircrack-ng](https://www.aircrack-ng.org/) |
|
|
[Leaflet.js](https://leafletjs.com/) |
|
|
[SatDump](https://github.com/SatDump/SatDump) |
|
|
[Celestrak](https://celestrak.org/) |
|
|
[Priyom.org](https://priyom.org/)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|