{"id":51012062,"url":"https://github.com/ringmast4r/tower-hunter","last_synced_at":"2026-06-21T04:01:39.834Z","repository":{"id":361536231,"uuid":"1140983705","full_name":"Ringmast4r/Tower-Hunter","owner":"Ringmast4r","description":"Cell tower logger and anomaly detector for Linux mobile devices. Monitors cellular          connections, logs tower data with GPS, and detects suspicious activity.","archived":false,"fork":false,"pushed_at":"2026-01-24T03:57:04.000Z","size":15,"stargazers_count":87,"open_issues_count":0,"forks_count":16,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-31T06:04:56.894Z","etag":null,"topics":["cell-tower","cybersecurity","imsi-catcher","linux","mobile-security","privacy","stingray","surveillance"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ringmast4r.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T03:16:12.000Z","updated_at":"2026-05-26T11:27:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Ringmast4r/Tower-Hunter","commit_stats":null,"previous_names":["ringmast4r/tower-hunter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Ringmast4r/Tower-Hunter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ringmast4r%2FTower-Hunter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ringmast4r%2FTower-Hunter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ringmast4r%2FTower-Hunter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ringmast4r%2FTower-Hunter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ringmast4r","download_url":"https://codeload.github.com/Ringmast4r/Tower-Hunter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ringmast4r%2FTower-Hunter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34593129,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cell-tower","cybersecurity","imsi-catcher","linux","mobile-security","privacy","stingray","surveillance"],"created_at":"2026-06-21T04:01:38.951Z","updated_at":"2026-06-21T04:01:39.822Z","avatar_url":"https://github.com/Ringmast4r.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TowerHunter v3.0 - SimTrack\n\n![GitHub stars](https://img.shields.io/github/stars/Ringmast4r/Tower-Hunter?style=flat-square\u0026color=0066ff)\n![GitHub forks](https://img.shields.io/github/forks/Ringmast4r/Tower-Hunter?style=flat-square\u0026color=0088ff)\n![GitHub watchers](https://img.shields.io/github/watchers/Ringmast4r/Tower-Hunter?style=flat-square\u0026color=00aaff)\n![GitHub repo size](https://img.shields.io/github/repo-size/Ringmast4r/Tower-Hunter?style=flat-square\u0026color=00ccff)\n![GitHub last commit](https://img.shields.io/github/last-commit/Ringmast4r/Tower-Hunter?style=flat-square\u0026color=00eeff)\n![GitHub issues](https://img.shields.io/github/issues/Ringmast4r/Tower-Hunter?style=flat-square\u0026color=0066ff)\n![License](https://img.shields.io/badge/license-Proprietary-0066ff?style=flat-square)\n![Profile Views](https://komarev.com/ghpvc/?username=Ringmast4r\u0026color=0066ff\u0026style=flat-square\u0026label=Profile+Views)\n\nA cell tower logger and anomaly detector designed for mobile security research on Linux-based portable devices.\n\n## What This Is\n\nTowerHunter is a field tool that continuously monitors and logs cellular network connections in real-time. It captures detailed information about cell towers your device connects to, correlates this with GPS location data, and can detect potentially suspicious cellular activity.\n\n**Primary Use Cases:**\n- Security research and IMSI catcher/Stingray detection\n- Cell tower mapping and coverage analysis\n- Mobile network research and education\n- Understanding cellular handoff behavior while traveling\n\n## What This Is NOT\n\n- **Not a hacking tool** - TowerHunter passively monitors your own device's cellular connection\n- **Not cross-platform** - This only runs on Linux with ModemManager and gpsd\n- **Not a consumer app** - Requires specific hardware (cellular modem, GPS) and Linux knowledge\n- **Not for Windows/macOS** - The viewer can display historical data but core functionality requires Linux\n\n## Features\n\n### Cell Tower Logging\n- Captures MCC, MNC, LAC, TAC, and Cell ID from your cellular modem\n- Records operator name, access technology (LTE, 3G, etc.), and signal metrics\n- Logs RSRP and RSRQ values for signal quality analysis\n- Stores data in SQLite database and daily CSV files\n\n### GPS Integration\n- Correlates cell tower connections with your physical location\n- Calculates distance to connected tower using OpenCellID lookups\n- Tracks speed, heading, and altitude via gpsd\n\n### Anomaly Detection\nAlerts are generated for potentially suspicious activity:\n\n| Alert Type | Trigger | Severity |\n|------------|---------|----------|\n| `RAPID_TOWER_CHANGE` | 3+ tower changes within 60 seconds | HIGH |\n| `UNUSUAL_MCC` | Non-US Mobile Country Code detected | MEDIUM |\n| `STRONG_SIGNAL` | RSRP stronger than -80 dBm (unusually close tower) | LOW |\n\n### Web Dashboard\n- Real-time monitoring interface accessible via browser\n- Historical data viewer for analyzing past sessions\n- Export functionality (JSON, CSV)\n\n## Hardware Requirements\n\n- **Linux device** - Tested on ClockworkPi DevTerm running Kali Linux\n- **Cellular modem** - Must be supported by ModemManager (mmcli)\n- **GPS receiver** - Must work with gpsd\n\n## Software Dependencies\n\n```bash\n# Required packages\nsudo apt install modemmanager gpsd gpsd-clients python3\n\n# For remote mode only\nsudo apt install sshpass\n```\n\n## Files\n\n| File | Description |\n|------|-------------|\n| `towerhunter.py` | Main application - runs directly on the device with modem/GPS |\n| `towerhunter-remote.py` | Remote mode - runs on a separate machine, pulls data via SSH |\n| `viewer.py` | Standalone viewer - browse historical data without active collection |\n| `start-towerhunter.sh` | Launch script for main application |\n| `start-viewer.sh` | Launch script for viewer |\n| `start-remote.sh` | Launch script for remote mode |\n\n## Usage\n\n### Direct Mode (on device with modem)\n\n```bash\n# Ensure ModemManager and gpsd are running\nsudo systemctl start ModemManager\nsudo systemctl start gpsd\n\n# Run TowerHunter\npython3 towerhunter.py\n```\n\nAccess the dashboard at `http://localhost:8888`\n\n### Remote Mode (from another machine)\n\nEdit `towerhunter-remote.py` to set your ClockworkPi's IP address:\n```python\nREMOTE_HOST = \"10.0.0.15\"  # Your device's IP\nREMOTE_USER = \"kali\"\nREMOTE_PASS = \"kali\"\n```\n\n```bash\npython3 towerhunter-remote.py\n```\n\n### Viewer Only (browse historical data)\n\n```bash\npython3 viewer.py\n```\n\nAccess at `http://localhost:8889`\n\n## Web Interface\n\n### Live Dashboard (port 8888)\n- Real-time cell tower and GPS data\n- Signal strength graphs\n- Alert notifications\n- Tower history\n\n### Data Viewer (port 8889)\n- Overview statistics\n- Recent readings log\n- Discovered towers list\n- Alert history\n- Data export (JSON/CSV)\n\n## Database Schema\n\n### `cell_logs` - Individual readings\n- Timestamp, cell identifiers (MCC/MNC/LAC/TAC/Cell ID)\n- Operator, access technology, signal metrics\n- GPS coordinates, altitude, speed, heading\n- Tower location (from OpenCellID), distance to tower\n- Anomaly flag\n\n### `towers` - Unique towers discovered\n- Cell ID, operator info\n- First/last seen timestamps\n- Times seen count\n- Average GPS position when connected\n\n### `alerts` - Anomaly events\n- Timestamp, alert type, description\n- Associated cell ID and location\n\n### `tower_locations` - OpenCellID cache\n- Cached tower coordinates to reduce API calls\n\n## Configuration\n\nEdit the `CONFIG` dictionary in the Python files:\n\n```python\nCONFIG = {\n    'poll_interval': 6,           # Seconds between readings\n    'log_dir': Path('...'),       # CSV log directory\n    'export_dir': Path('...'),    # Export directory\n    'db_path': Path('...'),       # SQLite database path\n    'web_port': 8888,             # Dashboard port\n    'anomaly_threshold': 3,       # Tower changes before alert\n}\n```\n\n## API Endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /` | Web dashboard |\n| `GET /api/data` | Current readings (live mode) |\n| `GET /api/stats` | Database statistics |\n| `GET /api/recent` | Recent log entries |\n| `GET /api/towers` | Discovered towers |\n| `GET /api/alerts` | Alert history |\n| `GET /api/logs` | Full log query |\n| `GET /api/export/json` | Export as JSON |\n| `GET /api/export/csv` | Export as CSV |\n\n## Understanding the Data\n\n### Cell Identifiers\n- **MCC** (Mobile Country Code) - Country identifier (310-316 = USA)\n- **MNC** (Mobile Network Code) - Carrier identifier\n- **LAC** (Location Area Code) - Geographic grouping of cells\n- **TAC** (Tracking Area Code) - LTE equivalent of LAC\n- **Cell ID** - Unique identifier for the specific cell/sector\n\n### Signal Metrics\n- **Signal Quality** - Percentage (0-100%)\n- **RSRP** (Reference Signal Received Power) - Typical: -80 to -120 dBm\n- **RSRQ** (Reference Signal Received Quality) - Typical: -10 to -20 dB\n\n### Anomaly Indicators\nRapid tower switching or unusually strong signals *could* indicate an IMSI catcher, but can also be caused by:\n- Driving through areas with dense tower coverage\n- Being near a small cell or DAS (Distributed Antenna System)\n- Network congestion causing load balancing\n- Building interference causing frequent handoffs\n\n**Always investigate alerts in context before drawing conclusions.**\n\n## Limitations\n\n- Requires root/sudo for modemmanager access\n- OpenCellID API has rate limits (uses free public key)\n- GPS fix required for location correlation\n- Tower location accuracy varies (OpenCellID is crowdsourced)\n- Only detects anomalies based on simple heuristics\n\n## License\n\n**Copyright (c) 2025 Ringmast4r. All Rights Reserved.**\n\nThis software is proprietary and confidential. Unauthorized copying, distribution, modification, public display, or public performance of this software, via any medium, is strictly prohibited.\n\n- You may **view** this code for educational purposes only\n- You may **not** copy, fork, modify, or redistribute this code\n- You may **not** use this code in any commercial or personal projects\n- You may **not** claim this work as your own\n\nFor licensing inquiries, contact the repository owner.\n\n## Acknowledgments\n\n- [OpenCellID](https://opencellid.org/) for cell tower location data\n- [ModemManager](https://www.freedesktop.org/wiki/Software/ModemManager/) for modem abstraction\n- [gpsd](https://gpsd.gitlab.io/gpsd/) for GPS handling\n\n---\n\n*This project is the result of independent security research. All code is original work by Ringmast4r.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringmast4r%2Ftower-hunter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fringmast4r%2Ftower-hunter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringmast4r%2Ftower-hunter/lists"}