# IMSI-catcher: Discover Cellphone IMSI Numbers with SDR

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/oros42-imsi-catcher
Generated for open source discovery and AI-assisted research.

IMSI-catcher is a Python program designed for educational purposes, allowing users to understand how GSM networks function. It utilizes Software Defined Radio (SDR) receivers like RTL-SDR or HackRF to detect and display IMSI numbers, country, brand, and operator of nearby cellphones. This tool provides a practical way to explore mobile communication protocols and security aspects.

GitHub: https://github.com/Oros42/IMSI-catcher
OSRepos URL: https://osrepos.com/repo/oros42-imsi-catcher

## Summary

IMSI-catcher is a Python program designed for educational purposes, allowing users to understand how GSM networks function. It utilizes Software Defined Radio (SDR) receivers like RTL-SDR or HackRF to detect and display IMSI numbers, country, brand, and operator of nearby cellphones. This tool provides a practical way to explore mobile communication protocols and security aspects.

## Topics

- IMSI-catcher
- GSM
- SDR
- Python
- Cellphone Security
- Radio Frequency
- HackRF
- RTL-SDR

## Repository Information

Last analyzed by OSRepos: Thu Nov 20 2025 00:01:35 GMT+0000 (Western European Standard Time)
Detail views: 29
GitHub clicks: 10

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## Introduction
IMSI-catcher is an open-source Python program that enables users to detect and display IMSI (International Mobile Subscriber Identity) numbers, along with country, brand, and operator information, from cellphones in the vicinity. Developed by Oros42, this project is primarily intended for educational purposes, helping individuals understand the workings of GSM networks and the underlying mobile communication protocols. It emphasizes responsible use, explicitly stating it's not for malicious hacking.

## Installation
To set up IMSI-catcher, you'll need a PC running Gnu/Linux (tested with Debian 10, Ubuntu 20.04+, Kali 2020+), and an SDR receiver such as a USB DVB-T key (RTL2832U), OsmocomBB phone, HackRF, or BladeRF.

First, clone the repository or download the source:
bash
git clone https://github.com/Oros42/IMSI-catcher.git
cd IMSI-catcher

Alternatively:
bash
wget https://github.com/Oros42/IMSI-catcher/archive/master.zip && unzip -q master.zip
cd IMSI-catcher-master


Install the necessary Python dependencies:
bash
sudo apt install python3-numpy python3-scipy python3-scapy

**Important:** Avoid using Python 3.9 due to a ctypes bug.

You have two options for installing `gr-gsm`: directly in your OS or via Docker.

### Install gr-gsm in your OS (recommended)
Install build dependencies:
bash
sudo apt-get install -y \
    cmake \
    autoconf \
    libtool \
    pkg-config \
    build-essential \
    python3-docutils \
    libcppunit-dev \
    swig \
    doxygen \
    liblog4cpp5-dev \
    gnuradio-dev \
    gr-osmosdr \
    libosmocore-dev \
    liborc-0.4-dev \
    swig

Check your GnuRadio version:
bash
gnuradio-config-info -v

Based on your GnuRadio version, clone the appropriate `gr-gsm` branch:
*   If `>= 3.10`:
    bash
git clone -b maint-3.10_with_multiarfcn https://github.com/bkerler/gr-gsm
    
*   If `>= 3.8`:
    bash
git clone -b maint-3.8 https://github.com/velichkov/gr-gsm.git
    
*   If `3.7`:
    bash
git clone https://git.osmocom.org/gr-gsm
    
Then, build and install `gr-gsm`:
bash
cd gr-gsm
mkdir build
cd build
cmake ..
make -j 4
sudo make install
sudo ldconfig
echo 'export PYTHONPATH=/usr/local/lib/python3/dist-packages/:$PYTHONPATH' >> ~/.bashrc


### Importlib vs Imp
For Python 3.1 and newer, `Imp` is replaced by `importlib`. If you encounter issues, install `importlib`:
bash
apt install python3-pip
pip install importlib


### Install gr-gsm with Docker
For a containerized setup:
bash
sudo xhost +local:docker
docker pull atomicpowerman/imsi-catcher
docker run -ti --net=host -e DISPLAY=$DISPLAY --privileged -v /dev/bus/usb:/dev/bus/usb  atomicpowerman/imsi-catcher bash

Run all `grgsm_*` commands inside this Docker container.

## Examples
IMSI-catcher typically uses `grgsm_livemon` to decode GSM signals and `simple_IMSI-catcher.py` to process and display IMSIs.

Open two terminals.

In terminal 1, start the IMSI catcher in sniff mode:
bash
sudo python3 simple_IMSI-catcher.py -s


In terminal 2, start `grgsm_livemon`:
bash
grgsm_livemon

Adjust the frequency in `grgsm_livemon` until you see decoded GSM frames.

### Wireshark Integration
You can also monitor GSM packets using Wireshark:
bash
sudo apt install wireshark
sudo wireshark -k -Y '!icmp && gsmtap' -i lo


### Finding Frequencies
To find active GSM frequencies, use `grgsm_scanner`:
bash
grgsm_scanner

This will output ARFCNs and frequencies. You can then specify a frequency for `grgsm_livemon`:
bash
grgsm_livemon -f 925.4M

For HackRF users, `kalibrate-hackrf` can help find GSM frequencies:
bash
sudo apt-get install automake autoconf libhackrf-dev
git clone https://github.com/scateu/kalibrate-hackrf
cd kalibrate-hackrf/
./bootstrap
./configure
make
sudo make install

Then run:
bash
kal -s GSM900


### Logging Data to MySQL
To save observed IMSI values to a MySQL database:
bash
cp .env.dist .env
nano .env
# set your config
sudo apt install python-decouple python3-mysqldb

Then run the IMSI catcher with the `--mysql` option:
bash
sudo python3 simple_IMSI-catcher.py -s --mysql

Use `db-example.sql` from the repository to create your database schema.

## Why Use IMSI-catcher?
IMSI-catcher offers a unique hands-on approach to understanding the intricacies of GSM networks. For students, researchers, and security enthusiasts, it provides a practical platform to:
*   **Learn GSM Protocols**: Observe real-time GSM traffic and understand how mobile devices communicate with base stations.
*   **Explore SDR Capabilities**: Gain experience with Software Defined Radio hardware and software for signal processing.
*   **Security Research**: Investigate potential vulnerabilities in GSM networks and the methods used for tracking mobile devices.
*   **Educational Tool**: Serve as an excellent educational resource for courses in telecommunications, cybersecurity, and radio frequency engineering.

## Links
*   **Setup of Gr-Gsm**: <a href="https://osmocom.org/projects/gr-gsm/wiki/Installation" target="_blank">Osmocom Gr-Gsm Installation</a> and <a href="https://github.com/velichkov/gr-gsm" target="_blank">velichkov/gr-gsm GitHub</a>
*   **Frequency Information**: <a href="http://www.worldtimezone.com/gsm.html" target="_blank">World Time Zone GSM</a> and <a href="https://fr.wikipedia.org/wiki/Global_System_for_Mobile_Communications" target="_blank">Wikipedia Global System for Mobile Communications</a>
*   **Mobile Network Code**: <a href="https://en.wikipedia.org/wiki/Mobile_Network_Code" target="_blank">Wikipedia Mobile Network Code</a>
*   **Scapy**: <a href="http://secdev.org/projects/scapy/doc/usage.html" target="_blank">Scapy Usage Documentation</a>
*   **IMSI**: <a href="https://fr.wikipedia.org/wiki/IMSI" target="_blank">Wikipedia IMSI</a>
*   **Realtek RTL2832U**: <a href="https://osmocom.org/projects/sdr/wiki/rtl-sdr" target="_blank">Osmocom RTL-SDR</a>, <a href="http://doc.ubuntu-fr.org/rtl2832u" target="_blank">Ubuntu-fr RTL2832U</a> and <a href="http://doc.ubuntu-fr.org/rtl-sdr" target="_blank">Ubuntu-fr RTL-SDR</a>
*   **AskUbuntu gr-gsm 3.10 fix**: <a href="https://askubuntu.com/a/1436119/" target="_blank">AskUbuntu Answer</a>