diff --git a/README.md b/README.md index de362a7..e1d6292 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ Support the developer of this open-source project - **WiFi Scanning** - Monitor mode reconnaissance via aircrack-ng - **Bluetooth Scanning** - Device discovery and tracker detection - **Spy Stations** - Number stations and diplomatic HF network database +- **Remote Agents** - Distributed SIGINT with remote sensor nodes --- @@ -114,6 +115,7 @@ Most features work with a basic RTL-SDR dongle (RTL2832U + R820T2). ## 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 diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 5a93cff..5c53cdb 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -38,22 +38,22 @@ Complete feature list for all modules. - **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 +## 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
@@ -165,6 +165,35 @@ Technical Surveillance Countermeasures (TSCM) screening for detecting wireless s
- No cryptographic de-randomization
- Passive screening only (no active probing by default)
+## 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
+
## User Interface
- **Mode-specific header stats** - real-time badges showing key metrics per mode
diff --git a/docs/USAGE.md b/docs/USAGE.md
index 7abdf04..eff954e 100644
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -74,42 +74,42 @@ INTERCEPT automatically detects known trackers:
### Emergency Squawks
-The system highlights aircraft transmitting emergency squawks:
-- **7500** - Hijack
-- **7600** - Radio failure
-- **7700** - General emergency
-
-## ADS-B History (Optional)
-
-The history dashboard persists aircraft messages and per-aircraft snapshots to Postgres for long-running tracking and reporting.
-
-### Enable History
-
-Set the following environment variables (Docker recommended):
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `INTERCEPT_ADSB_HISTORY_ENABLED` | `false` | Enables history storage and reporting |
-| `INTERCEPT_ADSB_DB_HOST` | `localhost` | Postgres host (use `adsb_db` in Docker) |
-| `INTERCEPT_ADSB_DB_PORT` | `5432` | Postgres port |
-| `INTERCEPT_ADSB_DB_NAME` | `intercept_adsb` | Database name |
-| `INTERCEPT_ADSB_DB_USER` | `intercept` | Database user |
-| `INTERCEPT_ADSB_DB_PASSWORD` | `intercept` | Database password |
-
-### Docker Setup
-
-`docker-compose.yml` includes an `adsb_db` service and a persistent volume for history storage:
-
-```bash
-docker compose up -d
-```
-
-### Using the History Dashboard
-
-1. Open **/adsb/history**
-2. Use **Start Tracking** to run ADS-B in headless mode
-3. View aircraft history and timelines
-4. Stop tracking when desired (session history is recorded)
+The system highlights aircraft transmitting emergency squawks:
+- **7500** - Hijack
+- **7600** - Radio failure
+- **7700** - General emergency
+
+## ADS-B History (Optional)
+
+The history dashboard persists aircraft messages and per-aircraft snapshots to Postgres for long-running tracking and reporting.
+
+### Enable History
+
+Set the following environment variables (Docker recommended):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `INTERCEPT_ADSB_HISTORY_ENABLED` | `false` | Enables history storage and reporting |
+| `INTERCEPT_ADSB_DB_HOST` | `localhost` | Postgres host (use `adsb_db` in Docker) |
+| `INTERCEPT_ADSB_DB_PORT` | `5432` | Postgres port |
+| `INTERCEPT_ADSB_DB_NAME` | `intercept_adsb` | Database name |
+| `INTERCEPT_ADSB_DB_USER` | `intercept` | Database user |
+| `INTERCEPT_ADSB_DB_PASSWORD` | `intercept` | Database password |
+
+### Docker Setup
+
+`docker-compose.yml` includes an `adsb_db` service and a persistent volume for history storage:
+
+```bash
+docker compose up -d
+```
+
+### Using the History Dashboard
+
+1. Open **/adsb/history**
+2. Use **Start Tracking** to run ADS-B in headless mode
+3. View aircraft history and timelines
+4. Stop tracking when desired (session history is recorded)
## Satellite Mode
@@ -130,6 +130,58 @@ docker compose up -d
3. Choose a category (Amateur, Weather, ISS, Starlink, etc.)
4. Select satellites to add
+## Remote Agents (Distributed SIGINT)
+
+Deploy lightweight sensor nodes across multiple locations and aggregate data to a central controller.
+
+### Setting Up an Agent
+
+1. **Install INTERCEPT** on the remote machine
+2. **Create config file** (`intercept_agent.cfg`):
+ ```ini
+ [agent]
+ name = sensor-node-1
+ port = 8020
+
+ [controller]
+ url = http://192.168.1.100:5050
+ api_key = your-secret-key
+ push_enabled = true
+
+ [modes]
+ pager = true
+ sensor = true
+ adsb = true
+ ```
+3. **Start the agent**:
+ ```bash
+ python intercept_agent.py --config intercept_agent.cfg
+ ```
+
+### Registering Agents in the Controller
+
+1. Navigate to `/controller/manage` in the main INTERCEPT instance
+2. Enter agent details:
+ - **Name**: Must match config file (e.g., `sensor-node-1`)
+ - **Base URL**: Agent address (e.g., `http://192.168.1.50:8020`)
+ - **API Key**: Must match config file
+3. Click "Register Agent"
+4. Use "Test" to verify connectivity
+
+### Using Remote Agents
+
+Once registered, agents appear in mode dropdowns:
+
+1. **Select agent** from the dropdown in supported modes
+2. **Start mode** - Commands are proxied to the remote agent
+3. **View data** - Data streams back to your browser via SSE
+
+### Multi-Agent Streaming
+
+Enable "Show All Agents" to aggregate data from all registered agents simultaneously.
+
+For complete documentation, see [Distributed Agents Guide](DISTRIBUTED_AGENTS.md).
+
## Configuration
INTERCEPT can be configured via environment variables:
diff --git a/docs/_config.yml b/docs/_config.yml
index 8dc81ca..d759c52 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -15,3 +15,4 @@ exclude:
- USAGE.md
- FEATURES.md
- HARDWARE.md
+ - DISTRIBUTED_AGENTS.md
diff --git a/docs/images/dashboard.png b/docs/images/dashboard.png
index e24c503..f125326 100644
Binary files a/docs/images/dashboard.png and b/docs/images/dashboard.png differ
diff --git a/docs/images/remote-agents.png b/docs/images/remote-agents.png
new file mode 100644
index 0000000..35b9c56
Binary files /dev/null and b/docs/images/remote-agents.png differ
diff --git a/docs/index.html b/docs/index.html
index a36688a..8f0bc54 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -18,6 +18,7 @@
Features
Screenshots
Install
+ Remote Agents
GitHub
@@ -123,6 +124,12 @@
Number stations and diplomatic HF network database. Frequencies, schedules, and background info from priyom.org.
+ +Distributed signal intelligence with remote sensor nodes. Deploy agents across multiple locations and aggregate data to a central controller.
+
Device Analysis
+
+ Remote Agents
+