stingray-detector

Passive IMSI-catcher / cell-site-simulator detection with an SDR

A small, passive toolkit for detecting IMSI catchers / cell-site simulators ("Stingrays") with an SDR. It does not transmit, impersonate a network, or capture subscriber identities — it observes the radio environment and flags base stations whose RF and topology characteristics look anomalous.

There are three independent tools:

Tool	What it does	Needs hardware?
lte_cell_monitor.sh	Continuously scans an LTE band, watches for a suspicious PCI appearing next to your known-good cell, logs every scan to JSONL, records appear/disappear events, and captures raw IQ as evidence.	Yes (SDR + srsRAN cell_search)
iq_analyzer.py	Scores recorded IQ captures against five GSM physical-layer heuristics (FCCH offset, burst timing, modulation, phase continuity, jitter) to judge legitimate-vs-rogue.	No (offline on files)
rogue_cell_detector.py	Consumes a set of cell measurements and flags duplicate coverage, power anomalies, and suspicious cells, producing a JSON report.	No (offline on data)

Why this works

A cell-site simulator typically has to mirror a real cell (same/adjacent ARFCN) at higher power so nearby phones prefer it. That leaves observable fingerprints: two distinct cells on one frequency, abnormal power, a cell that appears/disappears, looser frequency/timing control, and degraded modulation. None of these is proof on its own — the tools score indicators so you can prioritise investigation and preserve raw IQ for later analysis.

Install

git clone https://github.com/crcctcpr/stingray-detector.git
cd stingray-detector
python3 -m pip install -r requirements.txt
chmod +x lte_cell_monitor.sh

External dependencies for live monitoring:

• An SDR (developed with a HackRF); hackrf tools for IQ capture.
• srsRAN cell_search (or a compatible tool that prints Found CELL ... EARFCN=.. PHYID=.. .. PRB .. ports PSS power=..).

The two Python tools have no external dependency except NumPy and run on any machine, no radio required.

Quick start

# 1. Offline demo of the topology detector (no hardware)
python3 rogue_cell_detector.py --demo

# 2. Analyse your own measurements
python3 rogue_cell_detector.py --input examples/measurements.sample.json -o report.json

# 3. Analyse a recorded IQ capture (HackRF int8 @ 2 Msps)
python3 iq_analyzer.py mycapture.iq

# 4. Live monitor (edit monitor.conf first — see config.example.conf)
cp config.example.conf monitor.conf
./lte_cell_monitor.sh monitor.conf

Establishing a baseline (important)

The live monitor compares against your environment. Before relying on it:

1. Run cell_search over your band and note the PCI / EARFCN / power of the legitimate cells you normally see. Put the known-good one in BASELINE_PCI.
2. Set WATCH_PCI to a PCI you want flagged when it appears (e.g. a previously unseen cell). Re-run over several days to learn what is normal.
3. Set IQ_FREQ_HZ to the downlink centre frequency of the watched cell to enable automatic IQ evidence capture.

All knobs are environment variables; see config.example.conf.

Output

lte_cell_monitor.sh writes to OUTDIR (default ./imsi-monitor-data/):

• tracking.jsonl — one line per cell per scan
• evidence.log — appear/disappear state-change events
• alerts.log / session_*.log — human-readable session log
• iq-evidence/*.iq — raw IQ captured while the watched cell was present

Legal / ethical use

This is a defensive tool. It is passive and receive-only. Even passive reception of some bands is regulated in some jurisdictions — you are responsible for complying with the laws that apply to you. Do not use it to intercept, decode, or store other people's communications. Intended use: detecting surveillance against networks/devices you are authorised to protect, security research, and education.

License

MIT — see LICENSE.