📡 Modmobmap

Mobile Network Intelligence & Mapping Tool

Retrieve comprehensive information on 2G/3G/4G/and soon 5G cellular networks with minimal equipment

Features • Installation • Quick Start • Documentation • Docker

🎯 Overview

Modmobmap is a comprehensive cellular network reconnaissance tool designed for security researchers, RF engineers, and penetration testers. Originally presented at BeeRump 2018, it combines multiple techniques to map and analyze mobile networks using both commercial smartphones and Software-Defined Radio (SDR) devices.

🔥 Key Features

📱 Smartphone-Based Scanning

Samsung Galaxy devices (S3-S20)
ServiceMode interface support
XGold modem compatibility
Real-time cell information

📻 SDR Integration

GNU Radio GSM scanning
srsRAN LTE/NB-IoT support
Multi-band analysis
Passive reconnaissance

🌐 Network Coverage

2G/GSM networks
3G/UMTS systems
4G/LTE cells
NB-IoT detection

💾 Data Management

JSON export format
Real-time logging
Cell database
Operator caching

🛠️ Supported Hardware

📱 Mobile Devices (Rooted Required)

✅ Tested & Confirmed

Samsung Galaxy S3 (via xgoldmon)
Samsung Galaxy S4 (GT-I9500)
Samsung Galaxy S5
Samsung Galaxy Note 2 (LTE version)
Samsung Galaxy S20
Samsung Galaxy Nexus (GT-I9250, rooted)
Samsung Galaxy S2 (GT-I9100)

💡 Note: All devices must be rooted. For non-rooted devices, manual DFR technique required.

📻 SDR Devices (via gr-osmosdr & UHD)

🎛️ Compatible SDR Hardware

Device	Driver	GSM	LTE	Notes
RTL-SDR	rtlsdr/soapy	✅	✅	Budget option
HackRF One	hackrf	✅	✅	Wide frequency range
BladeRF	bladerf	✅	✅	High performance
USRP (all models)	uhd	✅	✅	Professional grade
ANTSDR E200	uhd	✅	✅	Requires proper UHD setup
AirSpy	airspy	✅	❌	GSM only
SDRplay RSP	sdrplay	✅	❌	GSM only
FunCube Dongle	fcd	✅	❌	GSM only

🚀 Installation

Prerequisites

# Core dependencies
- Python 3.x
- Android SDK (for ADB)
- GNU Radio 3.10+ with gr-gsm
- Valid/invalid SIM card (for IMSI)

🐧 Ubuntu 24.04 Quick Install

# Clone repository with submodules
git clone --recursive https://github.com/FlUxIuS/modmobmap.git
cd modmobmap

# Run automated installation script
sudo ./install_all-Ubuntu_24.04.sh

# Update submodules (if needed)
git submodule update --init --recursive --remote

🔧 Manual Installation

Click to expand manual installation steps

# 1. Install Python dependencies
pip3 install -r requirements.txt

# 2. Install Android SDK
# Download from: https://developer.android.com/studio/#downloads
export ANDROID_SDK_ROOT=/path/to/android-sdk

# 3. Install GNU Radio & gr-gsm
sudo apt-get install gnuradio gr-gsm

# 4. Build srsRAN (for LTE scanning)
cd thirdparty/srsLTE
mkdir build && cd build
cmake ../
make -j$(nproc)
sudo make install

🎯 Quick Start

🔰 Basic Scanning (Smartphone)

# Auto-detect operators and scan all available networks
sudo python3 modmobmap.py

# Specify Android SDK location (if not in default path)
sudo python3 modmobmap.py -s /opt/Android/sdk

Expected Output:

=> Requesting a list of MCC/MNC. Please wait, it may take a while...
Found 2 operator(s)
{'20810': 'F SFR', '20820': 'F-Bouygues Telecom'}

[+] New cell detected [CellID/PCI-DL_freq (4XXX-81)]
 Network type=2G
 PLMN=208-10
 ARFCN=81

[+] New cell detected [CellID/PCI-DL_freq (3XX-6300)]
 Network type=4G
 PLMN=208-10
 Band=20
 Downlink EARFCN=6300

⚡ Speed Up Scanning (Cached Operators)

Create cache/operators.json:

{
    "20801": "Orange",
    "20810": "F SFR",
    "20815": "Free",
    "20820": "F-Bouygues Telecom"
}

Run with cache:

sudo python3 modmobmap.py -o

🎯 Target Specific Operators

# Focus on Orange (MCC/MNC: 20801)
sudo python3 modmobmap.py -n 20801

# Multiple operators
sudo python3 modmobmap.py -n 20801,20810,20815

📚 MCC/MNC Lookup: Wikipedia Mobile Country Codes

📖 Usage Examples

🔵 Method 1: ServiceMode (Samsung Devices)

The default and most straightforward method:

sudo python3 modmobmap.py -m servicemode

🟢 Method 2: XGoldmon (XGold Modems)

For devices with XGold chipsets (S3, S4, Nexus):

Terminal 1 - Start xgoldmon:

cd /path/to/xgoldmon
sudo ./xgoldmon -t s3 -m /dev/ttyACM1
# Creates celllog.fifo

Terminal 2 - Run Modmobmap:

sudo python3 modmobmap.py \
    -f /path/to/xgoldmon/celllog.fifo \
    -m xgoldmod \
    -a /dev/ttyACM0 \
    -o

🟡 Method 3: GSM Scanning (SDR - gr-gsm)

Scan GSM bands with Software-Defined Radio:

# RTL-SDR scanning GSM-R and GSM900
python3 modmobmap.py -m grgsm -b GSM-R,GSM900 -g rtlsdr

# BladeRF scanning multiple bands
python3 modmobmap.py -m grgsm -b GSM850,GSM900,DCS1800 -g bladerf

# HackRF with custom gain
python3 modmobmap.py -m grgsm -b GSM900 -g "driver=hackrf,gain=40"

Available GSM Bands:

GSM850 (824-849 MHz)
GSM-R (876-880 MHz, Railway)
GSM900 (890-915 MHz)
DCS1800 (1710-1785 MHz)
PCS1900 (1850-1910 MHz)

🔴 Method 4: LTE Scanning (SDR - srsRAN)

Scan LTE cells using srsRAN:

# USRP scanning LTE Band 28
python3 modmobmap.py -m srslte_pss -b 28 -g 'driver=usrp'

# BladeRF scanning Band 7
python3 modmobmap.py -m srslte_pss -b 7 -g 'driver=bladerf'

# RTL-SDR via Soapy (specify device ID!)
python3 modmobmap.py -m srslte_pss -b 20 -g 'soapy:id=1'

# Multiple bands
python3 modmobmap.py -m srslte_pss -b 3,7,20,28 -g 'driver=usrp'

🟣 Method 5: NB-IoT Scanning

Detect Narrowband IoT cells:

sudo python3 modmobmap.py -m srslte_npss -b 20 -g 'soapy:id=1'

🔍 Finding Your SDR Device

List Soapy Devices

SoapySDRUtil --find

Example Output:

Found device 0
  driver = rtlsdr
  label = Generic RTL2832U OEM :: 00000001
  serial = 00000001

Found device 1
  driver = bladerf
  label = BladeRF #0 [bd7fffbf..d5958b06]
  serial = bd7fffbf8efb4de4ba08d94bd5958b06

List UHD Devices

uhd_find_devices

💾 Data Export

Results are automatically saved when you stop the scan (Ctrl+C):

[+] Cells save as cells_1595446203.json

JSON Output Format

{
  "3XX-6300": {
    "PLMN": "208-10",
    "band": 20,
    "bandwidth": "10MHz",
    "eARFCN": 6300,
    "PCI": "3XX",
    "TAC": "XXXX",
    "type": "4G"
  }
}

🐳 Docker Deployment

Pre-built Image (Recommended)

# Pull latest image
docker pull penthertz/modmobmap:latest_with_e200

# Run with device access
docker run -it --privileged \
  -v /dev/bus/usb:/dev/bus/usb \
  penthertz/modmobmap:latest_with_e200 \
  python3 modmobmap.py -m grgsm -b GSM900 -g rtlsdr

Build Your Own

# Clone and build
git clone --recursive https://github.com/FlUxIuS/modmobmap.git
cd modmobmap
docker build -t modmobmap:local .

# Run
docker run -it --privileged -v /dev:/dev modmobmap:local

🔐 Security Note: --privileged flag required for USB/hardware access

📊 Command Reference

python3 modmobmap.py [OPTIONS]

Required Options:
  -m, --module MODULE       Scanning module: servicemode|xgoldmod|grgsm|srslte_pss|srslte_npss
  
Optional Parameters:
  -n, --networks NETWORKS   Target MCC/MNC codes (comma-separated)
  -o, --cached_operator     Use cached operators for faster scanning
  -s, --sdk PATH           Android SDK path (default: auto-detect)
  -a, --at DEVICE          AT serial device (e.g., /dev/ttyUSB0)
  -f, --file FILE          FIFO file for xgoldmon integration
  -b, --bands BANDS        Frequency bands to scan (SDR modes)
  -g, --args ARGS          SDR device arguments (driver, gain, etc.)

Examples:
  # Basic smartphone scan
  sudo python3 modmobmap.py
  
  # GSM scan with RTL-SDR
  python3 modmobmap.py -m grgsm -b GSM900 -g rtlsdr
  
  # LTE scan targeting Band 7
  python3 modmobmap.py -m srslte_pss -b 7 -g 'driver=usrp'
  
  # Cached operators, specific network
  sudo python3 modmobmap.py -n 20810 -o

🤝 Contributing

We welcome contributions! Here's how you can help:

🐛 Bug Reports: Open an issue with details
🔧 Device Support: Add parsers for new phones
📡 SDR Engines: Integrate new hardware/software
📚 Documentation: Improve guides and examples

📞 Support & Community

🐦 Twitter: @Penthertz
🌐 Website: penthertz.com

📜 License

----------------------------------------------------------------------------
"THE BEER-WARE LICENSE" (Revision 42):
<sebastien.dudek(@)penthertz.com> wrote this file. As long as you retain 
this notice you can do whatever you want with this stuff. If we meet some 
day, and you think this stuff is worth it, you can buy me a beer in return.
                                                            FlUxIuS ;)
----------------------------------------------------------------------------

🙏 Acknowledgments

Original presentation: BeeRump 2018
gr-gsm by Piotr Krysik
srsRAN by Software Radio Systems
xgoldmon by 2b-as

Made with ☕ & 📡 by the Penthertz Team

⭐ Star us on GitHub if this project helped you!

Name		Name	Last commit message	Last commit date
Latest commit History 108 Commits
cache		cache
core		core
engines		engines
samples		samples
thirdparty		thirdparty
utils		utils
.gitmodules		.gitmodules
README.md		README.md
__init__.py		__init__.py
install_all-Ubuntu_24.04.sh		install_all-Ubuntu_24.04.sh
modmobmap.py		modmobmap.py
requirements.txt		requirements.txt

PentHertz/Modmobmap

Folders and files

Latest commit

History

Repository files navigation