From 32a4c096b25aafa2644c422710106a9df41de31a Mon Sep 17 00:00:00 2001 From: James Smith Date: Mon, 29 Dec 2025 21:56:59 +0000 Subject: [PATCH] Add CLI arguments and streamline documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add argparse with -p/--port, -H/--host, -d/--debug options - Add --check-deps flag to verify tool availability - Make host and port configurable via command line - Consolidate README with Quick Start section - Simplify installation into side-by-side table format - Add Configuration section for environment variables - Remove verbose API Endpoints and Stats Bar sections πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 311 ++++++++++++------------------------------------------ app.py | 49 ++++++++- 2 files changed, 115 insertions(+), 245 deletions(-) diff --git a/README.md b/README.md index c208d3f..3f8b7e1 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,22 @@ --- +## 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. + +--- + ## What is INTERCEPT? INTERCEPT is a **web-based front-end** that provides a unified, modern interface for signal intelligence tools: @@ -69,59 +85,20 @@ Instead of running command-line tools manually, INTERCEPT handles the process ma ### πŸ“Ά WiFi Reconnaissance - **Monitor mode** management via airmon-ng -- **Network scanning** with airodump-ng -- **Channel hopping** or fixed channel monitoring -- **Deauthentication attacks** for authorized testing +- **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 (WPA3/WPA2/WEP/Open) -- **Real-time radar** display of nearby networks +- **Security overview** chart and real-time radar display - **Client vendor lookup** via OUI database -- **Proximity alerts** - watch list for specific MAC addresses - -#### 🚁 Drone Detection -- **Automatic detection** of drones via SSID patterns and manufacturer OUI -- **Supported brands**: DJI, Parrot, Autel, Skydio, Holy Stone, and many more -- **Distance estimation** from signal strength -- **Visual alerts** with triple audio notification -- **Clickable drone counter** - view all detected drones with details - -#### ⚠️ Rogue AP Detection -- **Automatic detection** of same SSID on multiple BSSIDs -- **Clickable counter** - view which SSIDs triggered alerts -- **Detailed popup** showing all BSSIDs, channels, and signal strength - -#### πŸ“ˆ Signal History Graph -- **Real-time line chart** showing signal strength over time -- **Track any device** - click the πŸ“ˆ button on any network -- **Visual movement detection** - see devices approaching or departing - -#### πŸ•ΈοΈ Network Topology Graph -- **Visual map** of all access points and connected clients -- **Color-coded nodes** - cyan for APs, green for clients, orange for drones -- **Auto-updating** as new devices are discovered - -#### πŸ’‘ Channel Recommendation -- **Automatic analysis** of channel congestion -- **Recommends optimal channels** for both 2.4GHz and 5GHz -- **Considers channel overlap** for accurate 2.4GHz recommendations - -#### πŸ‘οΈ Hidden SSID Revealer -- **Captures hidden SSIDs** from probe requests -- **Displays revealed networks** with BSSID mapping -- **Desktop notifications** when new hidden SSIDs are revealed - -#### πŸ”— Device Correlation -- **Matches WiFi and Bluetooth devices** with same manufacturer -- **OUI-based correlation** to identify multi-radio devices -- **Useful for tracking** devices across protocols - -#### πŸ“‘ Client Probe Analysis -- **Track client probe requests** - see what networks devices are looking for -- **Privacy leak detection** - highlights sensitive network names (home, office, hotel, airport) -- **Vendor identification** - shows device manufacturer -- **Sorted by exposure** - most revealing clients shown first -- **Unique SSID counter** - total unique networks being probed +- **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 @@ -173,27 +150,6 @@ Instead of running command-line tools manually, INTERCEPT handles the process ma --- -## Stats Bar Icons - -| Icon | Meaning | -|------|---------| -| πŸ“Ÿ | POCSAG messages decoded | -| πŸ“  | FLEX messages decoded | -| πŸ“¨ | Total messages received | -| 🌑️ | Unique sensors detected | -| πŸ“Š | Device types found | -| ✈️ | Aircraft being tracked | -| πŸ›°οΈ | Satellites being monitored | -| πŸ“‘ | WiFi Access Points | -| πŸ‘€ | Connected WiFi clients | -| 🀝 | Captured handshakes | -| 🚁 | Detected drones (click for details) | -| ⚠️ | Rogue APs (click for details) | -| πŸ”΅ | Bluetooth devices | -| πŸ“ | BLE beacons detected | - ---- - ## Requirements ### Hardware @@ -203,8 +159,7 @@ Instead of running command-line tools manually, INTERCEPT handles the process ma ### Software - Python 3.7+ -- Flask -- requests (for Celestrak API) +- Flask, skyfield (installed via `requirements.txt`) - rtl-sdr tools (`rtl_fm`) - multimon-ng (for pager decoding) - rtl_433 (for 433MHz sensor decoding) @@ -214,127 +169,43 @@ Instead of running command-line tools manually, INTERCEPT handles the process ma ## Installation -### 1. Install RTL-SDR tools +### Install external tools -**macOS (Homebrew):** -```bash -brew install rtl-sdr -``` +Install the tools for the features you need: -**Ubuntu/Debian:** -```bash -sudo apt-get install rtl-sdr -``` +| Tool | macOS | Ubuntu/Debian | Purpose | +|------|-------|---------------|---------| +| rtl-sdr | `brew install rtl-sdr` | `sudo apt install rtl-sdr` | Required for all SDR features | +| 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 | -**Arch Linux:** -```bash -sudo pacman -S rtl-sdr -``` - -### 2. Install multimon-ng - -**macOS (Homebrew):** -```bash -brew install multimon-ng -``` - -**Ubuntu/Debian:** -```bash -sudo apt-get install multimon-ng -``` - -**From source:** -```bash -git clone https://github.com/EliasOenal/multimon-ng.git -cd multimon-ng -mkdir build && cd build -cmake .. -make -sudo make install -``` - -### 3. Install rtl_433 (optional, for 433MHz sensors) - -**macOS (Homebrew):** -```bash -brew install rtl_433 -``` - -**Ubuntu/Debian:** -```bash -sudo apt-get install rtl-433 -``` - -**From source:** -```bash -git clone https://github.com/merbanan/rtl_433.git -cd rtl_433 -mkdir build && cd build -cmake .. -make -sudo make install -``` - -### 4. Install aircrack-ng (optional, for WiFi) - -**macOS (Homebrew):** -```bash -brew install aircrack-ng -``` - -**Ubuntu/Debian:** -```bash -sudo apt-get install aircrack-ng -``` - -### 5. Install dump1090 (optional, for ADS-B aircraft tracking) - -**macOS (Homebrew):** -```bash -brew install dump1090-mutability -``` - -**Ubuntu/Debian:** -```bash -sudo apt-get install dump1090-mutability -``` - -**From source:** -```bash -git clone https://github.com/flightaware/dump1090.git -cd dump1090 -make -sudo cp dump1090 /usr/local/bin/ -``` - -### 6. Install Bluetooth tools (optional) - -**Ubuntu/Debian:** -```bash -sudo apt-get install bluez bluetooth -``` - -**macOS:** -Bluetooth tools are built-in, though with limited functionality compared to Linux. - -### 7. Install Python dependencies - -```bash -pip install -r requirements.txt -``` - -### 8. Clone and run +### Install and run ```bash git clone https://github.com/smittix/intercept.git cd intercept +pip install -r requirements.txt sudo python3 intercept.py ``` -Open your browser to `http://localhost:5050` +Open `http://localhost:5050` in your browser. > **Note:** Running as root/sudo is recommended for full functionality (monitor mode, raw sockets, etc.) +### 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 @@ -383,64 +254,6 @@ Open your browser to `http://localhost:5050` --- -## API Endpoints - -### Pager & Sensor -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/` | GET | Main web interface | -| `/devices` | GET | List RTL-SDR devices | -| `/start` | POST | Start pager decoding | -| `/stop` | POST | Stop pager decoding | -| `/start_sensor` | POST | Start 433MHz sensor listening | -| `/stop_sensor` | POST | Stop 433MHz sensor listening | -| `/status` | GET | Get decoder status | -| `/stream` | GET | SSE stream for pager messages | -| `/stream_sensor` | GET | SSE stream for sensor data | - -### WiFi -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/wifi/interfaces` | GET | List WiFi interfaces and tools | -| `/wifi/monitor` | POST | Enable/disable monitor mode | -| `/wifi/scan/start` | POST | Start WiFi scanning | -| `/wifi/scan/stop` | POST | Stop WiFi scanning | -| `/wifi/deauth` | POST | Send deauthentication packets | -| `/wifi/handshake/capture` | POST | Start handshake capture | -| `/wifi/handshake/status` | POST | Check handshake capture status | -| `/wifi/networks` | GET | Get discovered networks | -| `/wifi/stream` | GET | SSE stream for WiFi events | - -### Bluetooth -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/bt/interfaces` | GET | List Bluetooth interfaces and tools | -| `/bt/scan/start` | POST | Start Bluetooth scanning | -| `/bt/scan/stop` | POST | Stop Bluetooth scanning | -| `/bt/enum` | POST | Enumerate device services | -| `/bt/devices` | GET | Get discovered devices | -| `/bt/stream` | GET | SSE stream for Bluetooth events | - -### Aircraft (ADS-B) -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/adsb/start` | POST | Start ADS-B tracking | -| `/adsb/stop` | POST | Stop ADS-B tracking | -| `/adsb/aircraft` | GET | Get tracked aircraft | -| `/adsb/stream` | GET | SSE stream for aircraft data | -| `/adsb/tools` | GET | Check ADS-B tool availability | - -### Satellite -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/satellite/add` | POST | Add satellite with TLE data | -| `/satellite/remove` | POST | Remove satellite from tracking | -| `/satellite/list` | GET | Get tracked satellites | -| `/satellite/passes` | GET | Get pass predictions | -| `/satellite/celestrak/` | GET | Fetch satellites from Celestrak | - ---- - ## Troubleshooting ### No devices found @@ -465,6 +278,22 @@ Open your browser to `http://localhost:5050` --- +## 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` + +--- + ## License MIT License - see [LICENSE](LICENSE) for details. @@ -500,7 +329,3 @@ By using INTERCEPT, you acknowledge that: - The developers assume no liability for misuse of this software A disclaimer must be accepted when first launching the application. - - - - diff --git a/app.py b/app.py index 9aa7a53..ad80b5b 100644 --- a/app.py +++ b/app.py @@ -173,6 +173,51 @@ def kill_all() -> Response: def main() -> None: """Main entry point.""" + import argparse + import config + + parser = argparse.ArgumentParser( + description='INTERCEPT - Signal Intelligence Platform', + epilog='Environment variables: INTERCEPT_HOST, INTERCEPT_PORT, INTERCEPT_DEBUG, INTERCEPT_LOG_LEVEL' + ) + parser.add_argument( + '-p', '--port', + type=int, + default=config.PORT, + help=f'Port to run server on (default: {config.PORT})' + ) + parser.add_argument( + '-H', '--host', + default=config.HOST, + help=f'Host to bind to (default: {config.HOST})' + ) + parser.add_argument( + '-d', '--debug', + action='store_true', + default=config.DEBUG, + help='Enable debug mode' + ) + parser.add_argument( + '--check-deps', + action='store_true', + help='Check dependencies and exit' + ) + args = parser.parse_args() + + # Check dependencies only + if args.check_deps: + results = check_all_dependencies() + print("Dependency Status:") + print("-" * 40) + for mode, info in results.items(): + status = "βœ“" if info['ready'] else "βœ—" + print(f"\n{status} {info['name']}:") + for tool, tool_info in info['tools'].items(): + tool_status = "βœ“" if tool_info['installed'] else "βœ—" + req = " (required)" if tool_info['required'] else "" + print(f" {tool_status} {tool}{req}") + sys.exit(0) + print("=" * 50) print(" INTERCEPT // Signal Intelligence") print(" Pager / 433MHz / Aircraft / Satellite / WiFi / BT") @@ -186,9 +231,9 @@ def main() -> None: from routes import register_blueprints register_blueprints(app) - print("Open http://localhost:5050 in your browser") + print(f"Open http://localhost:{args.port} in your browser") print() print("Press Ctrl+C to stop") print() - app.run(host='0.0.0.0', port=5050, debug=False, threaded=True) + app.run(host=args.host, port=args.port, debug=args.debug, threaded=True)