Oros42/IMSI-catcher: reading GSM identities with an SDR and gr-gsm

What Oros42/IMSI-catcher actually does

The repository is small: one main script, simple_IMSI-catcher.py, a second script called immediate_assignment_catcher.py, a scan-and-livemon helper the README marks as no longer used, a Dockerfile, an SQL schema and an mcc-mnc directory. The README states the purpose in one line: the program shows IMSI numbers, country, brand and operator of cellphones around you. It then adds a warning that it was made to understand how GSM networks work, not for bad hacking.

The audience follows from that. This is for someone with an SDR who wants to see GSM identifiers appear on screen and learn which fields mean what. It is not for someone who wants to locate a phone: an IMSI is a subscriber identity, and the script reports what it decodes, not where the handset is. The README's own framing should be taken literally, because the rest of the repository is built around that single decoding path.

The decode path: grgsm_livemon to simple_IMSI-catcher.py

There is no radio code in this project. The README is explicit that grgsm_livemon decodes GSM signals and simple_IMSI-catcher.py finds IMSIs. The two run in separate terminals and talk over a network interface.

By default the script listens on interface lo and port 4729. It reads the GSMTAP frames that grgsm_livemon emits, and prints the identity fields it can extract. The -s or --sniff flag changes the input: instead of listening on the port, the script sniffs the interface directly, which the help text says requires root or suid access. That is why the README's two-terminal example starts the script with sudo.

Two details matter for anyone reading the code. First, the script has an -a or --alltmsi option, described as showing TMSI values that have not been matched to an IMSI, off by default. Second, the -m or --imsi option takes a single IMSI to track, and the help text shows both a plain digit string and a spaced format. Output can be written to a SQLite file with -w, to a text file with -t, or to MySQL with -z, which reads configuration from a .env file copied from .env.dist. The README also points at Wireshark as an alternative view, with a capture filter for gsmtap on lo.

Installing it and getting a first IMSI on screen

The README lists one Linux PC and one SDR receiver. Tested systems are Debian 10, Ubuntu 20.04 or LinuxMint 22.2 and newer, and Kali 2025 and newer. Tested receivers are an RTL2832U DVB-T key with an antenna, an OsmocomBB phone, a HackRF and a BladeRF. The README warns against Python 3.9 because of a ctypes bug.

Clone the repository and install the dependencies in one step. The apt line brings in numpy, scipy, scapy and gr-gsm, which is the heavy part.

git clone https://github.com/Oros42/IMSI-catcher.git
cd IMSI-catcher
sudo apt install python3-numpy python3-scipy python3-scapy gr-gsm

The README also gives a wget alternative that downloads the master zip and unpacks it into IMSI-catcher-master. After that, open two terminals. In the first, start the catcher in sniff mode; in the second, start the live monitor.

sudo python3 simple_IMSI-catcher.py -s

grgsm_livemon

Now tune the frequency until the monitor prints hex frames. The README shows the shape of that output: lines of hexadecimal bytes beginning with values such as 15 06 21 00. To find a frequency, run grgsm_scanner, which prints ARFCN, frequency, CID, LAC, MCC, MNC and power per cell, for example ARFCN 976, Freq 925.4M, MCC 208, MNC 20. You can then start the monitor on that frequency directly.

grgsm_livemon -f 925.4M

If you use a HackRF, the README points to kalibrate-hackrf instead, built from source with bootstrap, configure, make and make install, then run as kal -s GSM900. The README also documents a Docker route for gr-gsm that it labels not recommended, using the atomicpowerman/imsi-catcher image with host networking and the USB bus mounted.

Where the setup breaks, and when this is the wrong tool

The most likely failure is upstream of this repository. If grgsm_livemon does not print decoded frames, simple_IMSI-catcher.py has nothing to parse, and no option in its help text will fix that. Frequency selection is manual: you scan, pick a cell, and pass a frequency, so a wrong ARFCN means silence. The README's own note about Python 3.9 is a reminder that the interpreter version can break the ctypes path.

There is a second, more fundamental boundary. This is a passive receive setup driven by an SDR. It is not a detector product, and nothing in the repository claims to tell you whether an IMSI catcher is operating near you. If your question is whether your own phone is being tracked, this tool does not answer it; it decodes broadcast and signalling traffic from the network side with your own hardware. The README's warning line should be read as the project's own statement of scope.

The Docker path is also marked as not recommended, which is unusual to see stated so plainly, and it is a fair signal that the maintainer expects the native gr-gsm install. The scan-and-livemon helper is labelled no longer used, so treat it as historical rather than a supported entry point.

How it differs from SDR frameworks and from phone-side tools

The closest alternative in practice is not another IMSI tool but the underlying stack used directly. With gr-gsm alone, you get grgsm_livemon and grgsm_scanner and you read raw GSMTAP frames, either in the terminal or in Wireshark with a gsmtap filter. That approach gives you every field the decoder exposes. Oros42/IMSI-catcher trades that completeness for a narrow, readable output: IMSI, country, brand and operator, plus optional TMSI display and optional logging to SQLite, TXT or MySQL. If you need protocol-level detail, Wireshark on the same stream is the better view; if you want a line per subscriber identity, the script is the shorter path.

A second contrast is with tools that run on the handset side, such as the OsmocomBB project the README lists as supported hardware. Those work from a modified phone baseband. This project works from a separate receiver listening to the air interface, which means it needs its own antenna and tuning and does not depend on the phone you carry.

Licence, maintenance and what an upgrade costs

The repository is licensed CC0-1.0, a public domain dedication. For anyone embedding or redistributing the script, that removes the attribution and copyleft questions that GPL-licensed SDR code usually raises, but it also means there is no warranty language to lean on. The dependencies are a separate matter: gr-gsm, scapy, numpy and scipy carry their own licences, and the Dockerfile pulls gr-gsm from the bkerler fork and builds it from source, so a container build depends on that repository still being reachable.

On maintenance, the last push to master was on 2026-06-06. There are no retrieved releases, so there is no versioned artefact to pin and no changelog to read between updates. Upgrades therefore mean pulling master and re-reading the README, and the practical cost sits in gr-gsm: the README's warning about Python 3.9 and the Dockerfile's from-source build both show that the decoder, not this script, is where environment drift shows up. Nothing in the repository documents a rollback path, so keep your own copy of a working checkout if you depend on a specific behaviour.

Editorial conclusion

Adopt it if you already run gr-gsm and want a short script that turns its output into IMSI, MCC/MNC and operator lines, or if you are studying GSM broadcast channels on hardware you own. Do not adopt it as a monitoring product: it is receive-only, it needs a live SDR and a tuned frequency, and its own README calls it a way to understand how GSM networks work. Before anything else, check that your SDR is supported and that grgsm_livemon prints decoded hex frames, because simple_IMSI-catcher.py only parses that stream.

Frequently asked questions

Official sources

1. Issues
2. License: CC0-1.0
3. Oros42/IMSI-catcher on GitHub
4. README