📡 Modmobmap

🎯 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

🛠️ Supported Hardware

📱 Mobile Devices (Rooted Required)

📻 SDR Devices (via gr-osmosdr & UHD)

🚀 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

# 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