Rayhunter

Rayhunter is a project for detecting IMSI catchers, also known as cell-site simulators or stingrays. It's designed to run on a cheap mobile hotspot called the Orbic RC400L, but thanks to community efforts can support some other devices as well.
It's also designed to be as easy to install and use as possible, regardless of your level of technical skills. This guide should provide you all you need to acquire a compatible device, install Rayhunter, and start catching IMSI catchers.
To learn more about the aim of the project, and about IMSI catchers in general, please check out our introductory blog post. Otherwise, check out the installation guide to get started.
LEGAL DISCLAIMER: Use this program at your own risk. We believe running this program does not currently violate any laws or regulations in the United States. However, we are not responsible for civil or criminal liability resulting from the use of this software. If you are located outside of the US please consult with an attorney in your country to help you assess the legal risks of running this program.
Good Hunting!
Installing Rayhunter
So, you've got one of the supported devices, and are ready to start catching IMSI catchers. You have two options for installing Rayhunter:
Installing from the latest release
Make sure you've got one of Rayhunter's supported devices. These instructions have only been tested on macOS and Ubuntu 24.04. If they fail, you will need to install Rayhunter from source.
-
Download the latest
rayhunter-vX.X.X-PLATFORM.zip
from the Rayhunter releases page for your platform:- for Linux on x64 architecture:
linux-x64
- for Linux on ARM64 architecture:
linux-aarch64
- for MacOS on Intel (old macbooks) architecture:
macos-intel
- for MacOS on ARM (M1/M2 etc.) architecture:
macos-arm
- for Windows:
windows-x86_64
- for Linux on x64 architecture:
-
Decompress the
rayhunter-vX.X.X-PLATFORM.zip
archive. Open the terminal and navigate to the folder. (Be sure to replace X.X.X with the correct version number!)unzip ~/Downloads/rayhunter-vX.X.X-PLATFORM.zip cd ~/Downloads/rayhunter-vX.X.X-PLATFORM
-
Turn on your device by holding the power button on the front.
- For the Orbic, connect the device using a USB-C cable.
- For TP-Link, connect to its network using either WiFi or USB Tethering.
-
Run the installer:
# On MacOS, you must first remove the quarantine bit xattr -d com.apple.quarantine installer
Then run the installer:
./installer orbic # or: ./installer tplink # or: ./installer wingtech
The device will restart multiple times over the next few minutes.
You will know it is done when you see terminal output that says
Testing Rayhunter... done
-
Rayhunter should now be running! You can verify this by viewing Rayhunter's web UI. You should also see a green line flash along the top of top the display on the device.
Troubleshooting
- On MacOS if you encounter an error that says "No Orbic device found," it may because you have the "Allow accessories to connect" security setting set to "Ask for approval." You may need to temporarily change it to "Always" for the script to run. Make sure to change it back to a more secure setting when you're done.
./installer --help
./installer util --help
Installing from the latest release (Windows)
Windows support in Rayhunter's installer is a work-in-progress. Depending on the device, the installation instructions differ.
TP-Link
- Connect the device via WiFi or USB Tethering -- you should be able to view the TP-Link admin page on http://192.168.0.1.
- Download the latest release (must be at least 0.3.0) for windows-x86_64, and unpack the zipfile.
- Open PowerShell or CMD in that extracted folder, the installer:
./installer tplink
- Follow the instructions on the screen, if there are any.
Orbic
-
Connect the device to your computer using the provided USB cable.
-
Install the Zadig WinUSB driver installer.
-
Open Zadig, click options->show all devices
-
Select 'RNDIS (Interface 0)'
-
Click 'install driver' and wait for it to finish.
-
Download the latest
rayhunter-vX.X.X-windows-x86_64.zip
from the Rayhunter releases page. The version you download will have numbers instead of X -
Unzip
rayhunter-vX.X.X-windows-x86_64
. -
Open a powershell terminal by pressing Win+R and typing
powershell
and hitting enter. -
Type
cd ~\Downloads\rayhunter-v<x.x.x>-windows-x86_64
(Replace <x.x.x> with the Rayhunter version you just unzipped) and hit enter. -
Run the install script:
.\installer.exe orbic
and hit enter.- The device will restart multiple times over the next few minutes.
- You will know it is done when you see terminal output that says
checking for rayhunter server...success!
-
Rayhunter should now be running! You can verify this by following the instructions below to view the web UI. You should also see a green line flash along the top of top the display on the device.
Installing from source
Building Rayhunter from source, either for development or because the install script doesn't work on your system, involves a number of external dependencies. Unless you need to do this, we recommend you use our compiled builds.
- Install nodejs/npm, which is required to build Rayhunter's web UI
- Make sure to build the site with
cd bin/web && npm install && npm run build
before building Rayhunter. If you're working directly on the frontend,npm run dev
will allow you to test a local frontend with hot-reloading (usehttp://localhost:5173
instead ofhttp://localhost:8080
).
- Make sure to build the site with
- Install ADB on your computer using the instructions above, and make sure it's in your terminal's PATH
- Install
curl
on your computer to run the install scripts. It is not needed to build binaries.
Install Rust targets
Install Rust the usual way. Then,
- install the cross-compilation target for the device Rayhunter will run on:
rustup target add armv7-unknown-linux-musleabihf
- install the statically compiled target for your host machine to build the binary installer
serial
.
# check which toolchain you have installed by default with
rustup show
# now install the correct variant for your host platform, one of:
rustup target add x86_64-unknown-linux-musl
rustup target add aarch64-unknown-linux-musl
rustup target add aarch64-apple-darwin
rustup target add x86_64-apple-darwin
rustup target add x86_64-pc-windows-gnu
Now you can root your device and install Rayhunter by running:
cargo build --bin rayhunter-daemon --target armv7-unknown-linux-musleabihf --profile firmware --no-default-features --features orbic
cargo build --bin rootshell --target armv7-unknown-linux-musleabihf --profile firmware
cargo run --bin installer orbic
If you're on Windows or can't run the install scripts
- Root your device on Windows using the instructions here: https://xdaforums.com/t/resetting-verizon-orbic-speed-rc400l-firmware-flash-kajeet.4334899/#post-87855183
- Build the web UI using
cd bin/web && npm install && npm run build
- Push the scripts in
scripts/
to/etc/init.d
on device and make a directory called/data/rayhunter
usingadb shell
(and sshell for your root shell if you followed the steps above) - You also need to copy
config.toml.example
to/data/rayhunter/config.toml
- Then run
./make.sh
, which will build the binary, push it over adb, and restart the device. Once it's restarted, Rayhunter should be running!
Updating Rayhunter
Great news: if you've successfully installed Rayhunter, you already know how to update it! Our update process is identical to the installation process: simply repeat the steps for installing Rayhunter via a release or from source.
Configuration
Rayhunter can be configured by editing /data/rayhunter/config.toml
on the device. You can obtain a shell on orbic and tplink and edit the file manually. In future versions the web UI will allow you to edit the config as well.
View the default configuration file on GitHub.
Uninstalling
Orbic
To uninstall Rayhunter, power on your Orbic device and connect to it via USB. Then, start a rootshell on it by running adb shell
, followed by rootshell
.
Once in a rootshell, run:
echo 3 > /usrdata/mode.cfg
rm -rf /data/rayhunter /etc/init.d/rayhunter-daemon /bin/rootshell.sh
reboot
Your device is now Rayhunter-free, and should no longer be in a rooted ADB-enabled mode.
TPLink
- Run
./installer util tplink-start-telnet
- Telnet into the device
telnet 192.168.0.1
rm /data/rayhunter /etc/init.d/rayhunter_daemon
update-rc.d rayhunter_daemon remove
- (hardware revision v4.0+ only) In
Settings > NAT Settings > Port Triggers
in TP-Link's admin UI, remove any leftover port triggers.
Using Rayhunter
Once installed, Rayhunter will run automatically whenever your device is running. You'll see a green line on top of the device's display to indicate that it's running and recording. The line will turn red once a potential IMSI catcher has been found, until the device is rebooted or a new recording is started through the web UI.
It also serves a web UI that provides some basic controls, such as being able to start/stop recordings, download captures, delete captures, and view heuristic analyses of captures.
The web UI
You can access this UI in one of two ways:
-
Connect over WiFi: Connect your phone/laptop to your device's WiFi network and visit http://192.168.1.1:8080 (orbic) or http://192.168.0.1:8080 (tplink).
Click past your browser warning you about the connection not being secure, Rayhunter doesn't have HTTPS yet.
On the Orbic, you can find the WiFi network password by going to the Orbic's menu > 2.4 GHz WIFI Info > Enter > find the 8-character password next to the lock 🔒 icon. On the TP-Link, you can find the WiFi network password by going to the TP-Link's menu > Advanced > Wireless > Basic Settings.
-
Connect over USB (Orbic): Connect your device to your laptop via USB. Run
adb forward tcp:8080 tcp:8080
, then visit http://localhost:8080.- For this you will need to install the Android Debug Bridge (ADB) on your computer, you can copy the version that was downloaded inside the
releases/platform-tools/
folder to somewhere else in your path or you can install it manually. - You can find instructions for doing so on your platform here, (don't worry about instructions for installing it on a phone/device yet).
- On MacOS, the easiest way to install ADB is with Homebrew: First install Homebrew, then run
brew install android-platform-tools
.
- For this you will need to install the Android Debug Bridge (ADB) on your computer, you can copy the version that was downloaded inside the
-
Connect over USB (TP-Link): Plug in the TP-Link and use USB tethering to establish a network connection. ADB support can be enabled on the device, but the installer won't do it for you.
Key shortcuts
As of 0.3.3, you can start a new recording by double-tapping the power button. Any current recording will be stopped and a new recording will be started, resetting the red line as well.
This feature is disabled by default since 0.4.0 and needs to be enabled through configuration.
Heuristics
Rayhunter includes several analyzers to detect potential IMSI catcher activity. These can be enabled and disabled in your config.toml file.
Available Analyzers
- IMSI Requested: Tests whether the eNodeB sends an IMSI Identity Request NAS message. This can sometimes happen under normal circumstances when the network doesn't already have a TMSI (Temporary Mobile Subscriber ID or GUTI in 5G terminology) for your device. This most often happens when you first turn the device on, especially after it has been off for a long time or if you are in an area where ther is absolutely no connection to your service provider. This can also happen if you leave your device on while on an airplane and it suddenly connects to a new tower after being disconnected for a long time. However, if you get this warning at a time when you have been steadily connected to towers and the device has been on for a while it can be treated as suspcious.
- Connection Release/Redirected Carrier 2G Downgrade: Tests if a cell releases our connection and redirects us to a 2G cell. This heuristic only makes sense in the US or other countries where there are no more operating 2G base stations. Users in contries where 2G is still in service (such as most of EU) may want to disable it. See https://en.wikipedia.org/wiki/2G#Past_2G_networks for information about your country.
- LTE SIB6/7 Downgrade: Tests for LTE cells broadcasting a SIB type 6 and 7 which include 2G/3G frequencies with higher priorities
- Null Cipher: Tests whether the cell suggests using a null cipher (EEA0).
How we analyze a capture
TODO
Supported devices
Be sure to check your location's supported frequencies against a device page before obtaining a device.
1. Recommended devices
These devices have been extensively tested by the core developers and are widely used. Use one of these devices if you can.
Device | Recommended region |
---|---|
Orbic RC400L | Americas |
TP-Link M7350 | Africa, Europe, Middle East |
The TP-Link M7350 also works in the Americas but is usually more expensive.
Derivative work of this file by Maximillian Dörrbecker licensed CC BY-SA 2.5
2. Functional devices
Rayhunter is confirmed to work on these devices.
Device | Recommended region |
---|---|
Wingtech CT2MHS01 | Americas |
TP-Link M7310 | Africa, Europe, Middle East |
Adding new devices
Rayhunter was built and tested primarily on the Orbic RC400L mobile hotspot, but the community has been working hard at adding support for other devices. Theoretically, if a device runs a Qualcomm modem and exposes a /dev/diag
interface, Rayhunter may work on it.
If you have a device in mind which you'd like Rayhunter to support, please open a discussion on our Github!
Orbic RC400L
The Orbic RC400L is an inexpensive LTE modem primarily designed for the US market, and the original device for which Rayhunter is developed.
You can buy an Orbic using bezos bucks, or on eBay.
Please check whether the Orbic works in your country, and whether the Orbic RC400L supports the right frequency bands for your purpose before buying.
Supported Bands
Frequency | Band |
---|---|
5G (wideband,midband,nationwide) | n260/n261, n77, n2/5/48/66 |
4G | 2/4/5/12/13/48/66 |
Global & Roaming | n257/n78 |
Wifi 2.4Ghz | b/g/n |
Wifi 5Ghz | a/ac/ax |
Wifi 6 | 🮱 |
Obtaining a shell
After running through the installation procedure, you can obtain a root shell
by running adb shell
or ./installer util shell
. Then, inside of that shell
you can run /bin/rootshell
to obtain "fakeroot."
TP-Link M7350
Supported in Rayhunter since version 0.3.0.
The TP-Link M7350 supports many more frequency bands than Orbic and therefore works in Europe and also in some Asian and African countries.
Hardware versions
The TP-Link comes in many different hardware versions. Support for installation varies:
1.0
,2.0
: Not supported, devs are not able to obtain a device3.0
,3.2
,5.0
,5.2
,7.0
,8.0
: Tested, no known issues since 0.3.0.6.2
: One user reported it is working, not tested4.0
: Manual firmware downgrade required (issue)9.0
: Working since 0.3.2.
TP-Link versions newer than 3.0
have cyan packaging and a color display. Version 3.0
has a one-bit display and white packaging.
You can find the exact hardware version of each device under the battery or next to the barcode on the outer packaging, for example V3.0
or V5.2
.
When filing bug reports, particularly with the installer, please always specify the exact hardware version.
You can get your TP-Link M7350 from:
- First check for used offers on local sites, sometimes it's much cheaper there.
- Geizhals price comparison
- Ebay
Installation & Usage
Follow the release installation guide. Substitute ./installer orbic
for ./installer tplink
in other documentation. The Rayhunter UI will be available at http://192.168.0.1:8080.
Obtaining a shell
Unlike on Orbic, the installer will not enable ADB. Instead, you can obtain a root shell with the following command:
./installer util tplink-start-telnet
telnet 192.168.0.1
Display states
If your device has a color display, Rayhunter will show the same red/green/white line at the top of the display as it does on Orbic, each color meaning "warning"/"recording"/"paused" respectively. See Using Rayhunter.
If your device has a one-bit (black-and-white) display, Rayhunter will instead show an emoji to indicate status:
!
means "warning (potential IMSI catcher)":)
(smiling) means "recording":
(face with no mouth) means "paused"
Power-saving mode/sleep
By default the device will go to sleep after N minutes of no devices being connected. In that mode it will also turn off connections to cell phone towers. In order for Rayhunter to record continuously, you have to turn off this sleep mode in TP-Link's admin panel (go to Advanced - Power Saving) or keep e.g. your phone connectd on the TP-Link's WiFi.
Port triggers
On hardware revisions starting with v4.0, the installer will modify settings to
add two port triggers. You can look at Settings > NAT Settings > Port Triggers
in TP-Link's admin UI to see them.
- One port trigger "rayhunter-root" to launch the telnet shell. This is only needed for installation, and can be removed after upgrade. You can reinstall it using
./installer util tplink-start-telnet
. - One port trigger "rayhunter-daemon" to auto-start Rayhunter on boot. If you remove this, Rayhunter will have to be started manually from shell.
Other links
For more information on the device and instructions on how to install Rayhunter without an installer (i.e. manually), please see rayhunter-tplink-m7350
TP-Link M7310
Supported in Rayhunter since version 0.4.0.
The TP-Link M7310 works similarly to the M7350 and is
essentially an older, more expensive version of it. The installation procedure
is identical, ./installer tplink
.
Hardware version v1.0 has been successfully tested, later versions may work as well.
Wingtech CT2MHS01
Supported in Rayhunter since version 0.4.0.
The Wingtech CT2MHS01 hotspot is a Qualcomm mdm9650-based device with a screen available for US$15-35. This device is often used as a base platform for white labeled versions like the T-Mobile TMOHS1. AT&T branded versions of the hotspot seem to be the most abundant.
Supported bands
There are likely variants of the device for all three ITU regions.
According to FCC ID 2APXW-CT2MHS01 Test Report No. I20N02441-RF-LTE, the ITU Region 2 American version of the device supports the following LTE bands:
Band | Frequency |
---|---|
2 | 1900 MHz (PCS) |
5 | 850 MHz (CLR) |
12 | 700 MHz (LSMH) |
14 | 700 MHz (USMH) |
30 | 2300 MHz (WCS) |
66 | 1700 MHz (E-AWS) |
Note that Band 5 (850 MHz, CLR) is suitable for roaming in ITU regions 2 and 3.
Hardware
Wingtechs are abundant on ebay and can also be found on Amazon:
- https://www.ebay.com/itm/135205906535
- https://www.ebay.com/itm/126987839936
- https://www.ebay.com/itm/127147132518
- https://www.amazon.com/AT-Turbo-Hotspot-256-Black/dp/B09YWLXVWT
Installing
Connect to the Wingtech's network over wifi or usb tethering, then run the installer:
./installer wingtech --admin-password 12345678 # replace with your own password
Obtaining a shell
Even when Rayhunter is running, for security reasons the Wingtech will not have telnet or adb enabled during normal operation.
Use either command below to enable telnet or adb access:
./installer util wingtech-start-telnet --admin-password 12345678
telnet 192.168.1.1
./installer util wingtech-start-adb --admin-password 12345678
adb shell
Developing
The device has a framebuffer-driven screen at /dev/fb0 that behaves
similarly to the Orbic RC400L, although the userspace program
displaygui
refreshes the screen significantly more often than on the
Orbic. This causes the green line on the screen to subtly flicker and
only be displayed during some frames. Subsequent work to fully control
the display without removing the OEM interface is desired.
Rayhunter has been tested on:
WT_INNER_VERSION=SW_Q89323AA1_V057_M10_CRICKET_USR_MP
WT_PRODUCTION_VERSION=CT2MHS01_0.04.55
WT_HARDWARE_VERSION=89323_1_20
Please consider sharing the contents of your device's /etc/wt_version file here.
Support, Feedback, and Community
If you're using Rayhunter (or trying to), we'd love to hear from you! Check out one of the following forums for contacting the Rayhunter developers and community:
- If you've received a Rayhunter warning and would like to help us with our research, please send your Rayhunter data captures (QMDL and PCAP logs) to us at our Signal username ElectronicFrontierFoundation.90 with the following information: capture date, capture location, device, device model, and Rayhunter version. If you're unfamiliar with Signal, feel free to check out our Security Self Defense guide on it.
- If you're having issues installing or using Rayhunter, please open an issue on our Github repo.
- If you'd like to propose a feature, heuristic, or device for Rayhunter, start a discussion in our Github repo
- For anything else, join us in the
#rayhunter
or#rayhunter-developers
channel of EFF's Mattermost instance to chat!
Frequently Asked Questions
Do I need an active SIM card to use Rayhunter?
It Depends. Operation of Rayhunter does require the insertion of a SIM card into the device, but whether that SIM card has to be currently active for our tests to work is still under investigation. If you want to use the device as a hotspot in addition to a research device an active plan would of course be necessary, however we have not done enough testing yet to know whether an active subscription is required for detection. If you want to test the device with an inactive SIM card, we would certainly be interested in seeing any data you collect, and especially any runs that trigger an alert!
Help, Rayhunter's line is red! What should I do?
Unfortunately, the circumstances that might lead to a positive cell site simulator (CSS) signal are quite varied, so we don't have a universal recommendation for how to deal with the a positive signal. Depending on your circumstances and threat model, you may want to turn off your phone until you are out of the area (or put it on airplane mode) and tell your friends to do the same!
If you've received a Rayhunter warning and would like to help us with our research, please send your Rayhunter data captures (QMDL and PCAP logs) to us at our Signal username ElectronicFrontierFoundation.90 with the following information: capture date, capture location, device, device model, and Rayhunter version. If you're unfamiliar with Signal, feel free to check out our Security Self Defense guide on it.
Please note that this file may contain sensitive information such as your IMSI and the unique IDs of cell towers you were near which could be used to ascertain your location at the time.
Should I get a locked or unlocked orbic device? What is the difference?
If you want to use a non-Verizon SIM card you will probably need an unlocked device. But it's not clear how locked the locked devices are nor how to unlock them, we welcome any experimentation and information regarding the use of unlocked devices.
How do I re-enable USB tethering after installing Rayhunter?
Make sure USB tethering is also enabled in the Orbic's UI, and then run the following commands:
installer util shell "echo 9 > /usrdata/mode.cfg"
installer util shell reboot
To disable tethering again:
installer util shell "echo 3 > /usrdata/mode.cfg"
installer util shell reboot
See /data/usb/boot_hsusb_composition
for a list of USB modes and Android USB gadget settings.