Local-First OSINT & Cellular Intelligence Workbench
Cell tower mapping · Phone enrichment · RF signal detection · Entity correlation
XGhostSignal is a local-first intelligence tool for mapping cell towers, enriching phone number metadata, correlating identifiers across datasets, and analyzing RF signals. It features a CLI (xgs) for power users and a web GUI for visualization.
Your data never leaves your machine. No telemetry, no cloud, no external APIs.
- Phone Intelligence — E.164 normalization, carrier/location lookup, validity checks (scoped to IN, PK, CN, US, RU)
- Cell Tower Mapping — Import and visualize tower data from OpenCelliD, CellMapper, and RTL-Power
- RF Signal Detection — Live RTL-SDR streaming with signal burst detection
- ADS-B Aviation Tracking — Real-time aircraft position data from dump1090
- Entity Correlation — Automatic co-location analysis and graph-based relationship mapping
- Breach Checking — Local LMDB/SQLite-based phone number leak database
- LLM Summarization — Tactical AI summaries via local Ollama (llama3:8b)
- Multiple Export Formats — CSV, JSON, KML (Google Earth), Markdown, SQLite dump
- Plugin System — Extend with custom plugins in
plugins/custom/ - REST API — Full FastAPI backend with Swagger/ReDoc documentation
- Web Dashboard — Leaflet maps + Cytoscape graph visualization, zero build step
# Clone
git clone https://github.com/getxeyronoxz/XGhostSignal.git
cd XGhostSignal
# Setup
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/Mac
# Install
pip install -r requirements.txt
pip install -e .
# Initialize database
xgs init
# Search a phone number
xgs search "+919876543210"
# Generate report
xgs report "+919876543210"
# Start web UI
xgs serve
# Open http://localhost:8080- Python 3.9+
- pip or uv package manager
git clone https://github.com/getxeyronoxz/XGhostSignal.git
cd XGhostSignal
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# .venv\Scripts\activate # Windows
pip install -r requirements.txt
pip install -e . # Installs `xgs` command globallypip install -e ".[dev]" # Includes pytest and testing tools| Command | Description | Example |
|---|---|---|
xgs init |
Initialize SQLite database | xgs init |
xgs search <number> |
Search and enrich a phone number | xgs search "+919876543210" |
xgs report <number> |
Generate Markdown dossier | xgs report "+919876543210" |
xgs summarize <number> |
Generate dossier + LLM summary | xgs summarize "+919876543210" |
xgs ingest <file> --parser-type <type> |
Ingest RF/telecom data | xgs ingest data.csv --parser-type opencellid |
xgs stream <hardware> |
Live hardware capture | xgs stream rtl-sdr |
xgs export <id> --format <fmt> |
Export data | xgs export "+919876543210" --format kml |
xgs serve |
Start web UI server | xgs serve |
opencellid— OpenCelliD CSV exportscellmapper— CellMapper CSV exportsrtl_power— RTL-Power spectrum scanspcap— PCAP/PCAPNG packet captures (requires scapy)sdr_stream— Live RTL-SDR streamingadsb— ADS-B aviation data (requires dump1090)
Start the server:
xgs serveNavigate to http://localhost:8080 for:
- Interactive Map — Leaflet-based tower visualization
- Correlation Graph — Cytoscape.js entity relationship graph
- Console — Real-time operation logging
Once running:
- Swagger UI:
http://localhost:8080/docs - ReDoc:
http://localhost:8080/redoc
Edit core/config.py to modify allowed regions (default: IN, PK, CN, US, RU):
ALLOWED_COUNTRY_CODES = ["IN", "PK", "CN", "US", "RU"]
ALLOWED_MCCS = [404, 405, 410, 460, 310, 311, 312, 313, 314, 315, 316, 250]Default: SQLite at xghostsignal.db (WAL mode, 30s timeout)
Ollama at http://localhost:11434, model llama3:8b (required only for xgs summarize)
core/ Config (country scope, DB path) + SQLAlchemy models
cli_app/ Typer CLI (init, search, report, summarize, ingest, stream, export, serve)
api/ FastAPI REST endpoints (/api/*)
services/ Export, Reports, LLM, Graph analysis
parsers/ Unified Parser Engine (BaseParser ABC + specific parsers)
plugins/ Dynamic plugin loader + default plugins
static/ Vanilla HTML/CSS/JS frontend (no build step)
Raw Data (CSV, PCAP, SDR) → Parsers → Unified Schema → SQLite
↓
Graph Analysis
↓
Export (CSV/JSON/KML/MD/SQL)
- Python 3.9+, Typer (CLI), FastAPI (API), SQLAlchemy (ORM)
- SQLite with WAL mode for concurrent access
- NetworkX for graph correlation
- Phonenumbers for phone parsing
- Scapy for PCAP parsing, PyRtlSdr for RTL-SDR
- Leaflet + Cytoscape.js for web visualization
We welcome contributions! See CONTRIBUTING.md for guidelines.
git clone https://github.com/getxeyronoxz/XGhostSignal.git
cd XGhostSignal
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes
- Run tests:
pytest tests/ -v - Commit:
git commit -m "Add your feature" - Push:
git push origin feature/your-feature - Open a Pull Request
# parsers/custom_parser.py
from parsers.base import BaseParser
class CustomParser(BaseParser):
def parse_file(self, file_path: str):
# Your parsing logic
return records# plugins/custom/my_plugin.py
PLUGIN_NAME = "my_plugin"
def run(arg1: str) -> dict:
return {"status": "success", "result": arg1}XGhostSignal/
├── core/ # Configuration and database models
├── cli_app/ # Typer CLI application
├── api/ # FastAPI REST routes
├── services/ # Business logic (export, reports, LLM, graph)
├── parsers/ # Unified parser engine
├── plugins/ # Plugin system + default plugins
├── static/ # Web frontend (HTML/CSS/JS)
├── tests/ # Test suite
├── docs/ # Documentation
├── main.py # Web server entry point
├── __main__.py # Module entry point
├── pyproject.toml # Package configuration
├── requirements.txt # Dependencies
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Contribution guidelines
├── LICENSE # MIT License
└── AGENTS.md # AI assistant guidance
- Local-first — All data stays on your machine
- No telemetry — No tracking, no external calls (except optional Ollama)
- Path traversal protection — Import/export paths sanitized
- XML escaping — KML export prevents injection
- SQLite WAL mode — Concurrent access without corruption
MIT License — see LICENSE for details.
- OpenCelliD — Cell tower database
- dump1090 — ADS-B decoding
- PyRtlSdr — RTL-SDR support
- Scapy — Packet parsing
- Ollama — Local LLM inference
This tool is for educational and authorized security testing purposes only. Ensure you have proper authorization before conducting any testing. The authors are not responsible for misuse of this tool.