diff --git a/README.md b/README.md index 996121c..76147fe 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,19 @@ -![Rayhunter Logo - An Orca taking a bite out of a cellular signal bar](https://www.eff.org/files/styles/media_browser_preview/public/banner_library/rayhunter-banner.png) - # Rayhunter - ![Tests](https://github.com/EFForg/rayhunter/actions/workflows/main.yml/badge.svg) -Rayhunter is an IMSI Catcher Catcher for the Orbic mobile hotspot. To learn more, check out the [Rayhunter Book](https://efforg.github.io/rayhunter/). +![Rayhunter Logo - An Orca taking a bite out of a cellular signal bar](https://www.eff.org/files/styles/media_browser_preview/public/banner_library/rayhunter-banner.png) + +Rayhunter is a project for detecting IMSI catchers, also known as cell-site simulators or stingrays. It was first designed to run on a cheap mobile hotspot called the Orbic RC400L, but thanks to community efforts can [support some other devices as well](./supported-devices.md). +It's also designed to be as easy to install and use as possible, regardless of your level of technical skills, and to minimize false positives. + +→ Check out the [installation guide](./installation.md) to get started. + +→ To learn more about the aim of the project, and about IMSI catchers in general, please check out our [introductory blog post](https://www.eff.org/deeplinks/2025/03/meet-rayhunter-new-open-source-tool-eff-detect-cellular-spying). + +→ For discussion, help, or to join the mattermost channel and get involved with the project and community check out the [many ways listed here](./support-feedback-community.md)! + +→ To learn more about the project in general check out the [Rayhunter Book](https://efforg.github.io/rayhunter/). + +**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!* \ No newline at end of file diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md index d9195c2..e87107f 100644 --- a/doc/SUMMARY.md +++ b/doc/SUMMARY.md @@ -13,7 +13,7 @@ - [Re-analyzing recordings](./reanalyzing.md) - [How we analyze a capture](./analyzing-a-capture.md) - [Supported devices](./supported-devices.md) - - [Orbic RC400L](./orbic.md) + - [Orbic/Kajeet RC400L](./orbic.md) - [TP-Link M7350](./tplink-m7350.md) - [TP-Link M7310](./tplink-m7310.md) - [Tmobile TMOHS1](./tmobile-tmohs1.md) diff --git a/doc/analyzing-a-capture.md b/doc/analyzing-a-capture.md index a7e4251..c7a38f7 100644 --- a/doc/analyzing-a-capture.md +++ b/doc/analyzing-a-capture.md @@ -1,3 +1,3 @@ # How we analyze a capture -TODO +Teams of highly trained squirrles. Video coming soon! \ No newline at end of file diff --git a/doc/faq.md b/doc/faq.md index d9e9ed6..edbd06d 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -2,23 +2,23 @@ ### 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! +**It Depends**. Operation of Rayhunter does require the insertion of a SIM card into the device, but that sim card does not have to be actively registered with a service plan. If you want to use the device as a hotspot in addition to a research device, or get [notifications](./configuration.md), an active plan would of course be necessary. - +### How can I test that my device is working? +You can enable the `Test Heuristic` under `Analyzer Heuristic Settings` in the config section on your web dashboard. This will cause an alert to trigger every time your device sees a cell tower, you might need to reboot your device or move around a bit to get this one to trigger, but it will be very noisey once it does. People have also tested it by building IMSI catchers at home, but we don't reccomend that, since it violates FCC regulations and will probably upset your neighbors. -### Help, Rayhunter's line is red! What should I do? +### Help, Rayhunter's line is red/orange/yellow/dotted/dashed! 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! +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 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](https://signal.org/) username [**ElectronicFrontierFoundation.90**](https://signal.me/#eu/HZbPPED5LyMkbTxJsG2PtWc2TXxPUR1OxBMcJGLOPeeCDGPuaTpOi5cfGRY6RrGf) 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](https://ssd.eff.org/module/how-to-use-signal). +If you've received a Rayhunter warning and would like to help us with our research, please send your Rayhunter data captures (Zip file downloaded from the web interface) to us at our [Signal](https://signal.org/) username [**ElectronicFrontierFoundation.90**](https://signal.me/#eu/HZbPPED5LyMkbTxJsG2PtWc2TXxPUR1OxBMcJGLOPeeCDGPuaTpOi5cfGRY6RrGf) 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](https://ssd.eff.org/module/how-to-use-signal). 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. - +If you want to use a non-Verizon SIM card you will probably need an unlocked device. But it's not clear which devices are locked nor how to unlock them, we welcome any experimentation and information regarding the use of unlocked devices. So far most verizon branded orbic devices we have encountered are actually unlocked. ### How do I re-enable USB tethering after installing Rayhunter? diff --git a/doc/heuristics.md b/doc/heuristics.md index e97d0eb..8628337 100644 --- a/doc/heuristics.md +++ b/doc/heuristics.md @@ -4,23 +4,40 @@ Rayhunter includes several analyzers to detect potential IMSI catcher activity. ## Available Analyzers -### IMSI Requested +### IMSI Requested (v3) -This analyser tests whether the eNodeB sends an IMSI Identity Request NAS message. +This analyser tests whether the eNodeB sends an IMSI or IMEI Identity Request NAS message under suspicous . -Mobile network primarily requests IMSI number from mobile device during initial network attachment or when the network cannot identify the mobile device by its temporary identification (TMSI - *Temporary Mobile Subscriber Identity* or GUTI - *Globally Unique Temporary Identifier* in 4G/5G terminology). +Mobile networks primarily request IMSI or IMEI from a mobile device during initial network attachment or when the network cannot identify the mobile device by its temporary identification (TMSI - *Temporary Mobile Subscriber Identity* or GUTI - *Globally Unique Temporary Identifier* in 4G/5G terminology). IMSI request therefore usually happens when you first turn the device on especially after it has been off for a long time. Another possibility is, that you reboot your mobile device and your temporary ID expired. Sometimes temporary identification can expire if you have been in an area where there is absolutely no connection to your service provider or after you left your device on an airplane mode and then reconnect to the network (especially being disconnected for a long time). IMSI could also be requested when you connect to a new network (for instance for roaming), when you swap she SIM card or when your device moves to a new *Tracking Area* or *Location Area* and the network can not map the temporary identification to your device. IMSI number can also be requested after core network reboot. It should also be noted that the network periodically reassigns your device new temporary identification to enhance security and avoid tracking, but in that cases usually does not request IMSI. -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, this could be a sign of IMSI catcher use. +During these events the phone will typically go on to authenticate that the network is legitimate and then establish service with the network it is connected to. + +What we consider suspicious is the following chain of events: + +* Phone connects to a new tower. +* Tower asks for phones identity (IMEI or IMSI.) +* Authentication does *NOT* happen. +* Tower requests phoen to disconnect. + +Looking for this chain of events is much less prone to false positives than naively looking for any time the IMSI/IMEI is sent. We do still sometimes get false positives when users are in an airplane that is coming in for a landing however. This is likely do to having been disconnected for a while and then being over towers that are not able to route to your home network, but we are still researching. + +This is the attack used by commercial IMSI catchers used by law enforcement. + +This heuristic will also alert you if any of the following happen: +* Identity is requested after authentication. +* Identity is requested without your phone connecting to the tower. +* Identity is requested and then authentication doesn't happen shortly thereafter. + +This heuristic will also issue a notification every time your identity is sent to the network under non suspicious circumstances. This is for diagnostic purposes. ### Connection Release/Redirected Carrier 2G Downgrade -This analyser tests if a base station releases your device's connection and redirects your device to a 2G base station. This heuristics is useful, because many commercial IMSI catchers operate in a such way that they downgrade connection to 2G where they can intercept the communication (by performing man-in-the-middle attack). +This analyser tests if a base station releases your device's connection and redirects your device to a 2G base station. This heuristic is useful, because some IMSI catchers may operate in a such way that they downgrade connection to 2G where they can intercept the communication (by performing man-in-the-middle attack). -This heuristic is the most useful in the United States or other countries where there are no more operating 2G base stations. See [Wikipedia page on past 2G networks](https://en.wikipedia.org/wiki/2G#Past_2G_networks) for information about your country. In countries where 2G is still in service (such as most of EU), this heuristics may trigger false positives. In that case you should consider disabling it. However this heuristics has been vastly improved to reduce false positive warnings and new tests in European networks show that false positives are vastly reduced. ### LTE SIB6/7 Downgrade @@ -28,10 +45,12 @@ This analyser tests if LTE base station is broadcasting a SIB type 6 and 7 messa SIB (*System Information Block*) Type 6 and 7 are specific types of broadcast messages sent by the base station (eNodeB in 4G networks) to mobile devices. They contain essential radio-related configuration parameters to help mobile device perform cell reselection. -IMSI catchers exploit the fact that many SIB broadcast messages are not encrypted or authenticated. This allows them to pretend to be a legitimate cell by broadcasting fake system information in order to force mobile devices to downgrade from more secure 4G (LTE) to less secure 2G (GSM) network and then steal IMSI and/or perform man-in-the-middle attack. That is why this is also called a downgrade attack. +This attack exploits the fact that SIB broadcast messages are not encrypted or authenticated. This allows them to pretend to be a legitimate cell by broadcasting fake system information in order to force mobile devices to downgrade from more secure 4G (LTE) to less secure 2G (GSM) network and then steal IMSI and/or perform man-in-the-middle attack. That is why this is also called a downgrade attack. SIB6 is used for cell reselecion to CDMA2000 systems which are not supported by many modern mobile phones, and SIB7 Provides the mobile device with information to perform cell reselection to GSM/EDGE networks. Therefore SIB6 messages are quite rare, while malformed SIB7 messages are much more frequent in practice. +This heuristic is the most useful in the United States or other countries where there are no more operating 2G base stations. See [Wikipedia page on past 2G networks](https://en.wikipedia.org/wiki/2G#Past_2G_networks) for information about your country. In countries where 2G is still in service (such as most of EU), this heuristics may trigger false positives. In that case you should consider disabling it. However this heuristics has been vastly improved to reduce false positive warnings and new tests in European networks show that false positives are vastly reduced. + ### Null Cipher This analyser tests whether the cell suggests using a null cipher (EEA0) in the RRC layer. That means that encryption between your mobile device and base station is turned off. diff --git a/doc/installing-from-release-windows.md b/doc/installing-from-release-windows.md index fbb9477..e93a218 100644 --- a/doc/installing-from-release-windows.md +++ b/doc/installing-from-release-windows.md @@ -14,7 +14,7 @@ Windows support in Rayhunter's installer is a work-in-progress. Depending on the
-[The Windows installer is known to be buggy](https://github.com/EFForg/rayhunter/issues/366). Consider using the [Network-based installer](./orbic.md#the-network-installer). +[The Windows USB installer is known to be buggy](https://github.com/EFForg/rayhunter/issues/366). We strongly reccomend using the [Network-based installer](./orbic.md#the-network-installer).
diff --git a/doc/installing-from-release.md b/doc/installing-from-release.md index 4b64c40..b0a9e2e 100644 --- a/doc/installing-from-release.md +++ b/doc/installing-from-release.md @@ -21,6 +21,7 @@ Make sure you've got one of Rayhunter's [supported devices](./supported-devices. 4. Turn on your device by holding the power button on the front. * For the Orbic, connect the device using a USB-C cable. + * Or connect to the network if using the network based installer, this is especially reccomended on Windows. * For TP-Link, connect to its network using either WiFi or USB Tethering. 5. Run the installer: @@ -32,8 +33,7 @@ Make sure you've got one of Rayhunter's [supported devices](./supported-devices. Then run the installer: ```bash ./installer orbic - # or: ./installer tplink - # or: ./installer wingtech + # or: ./installer [orbic-network|tplink|tmobile|uz801|pinephone|wingtech] ``` The device will restart multiple times over the next few minutes. @@ -44,6 +44,8 @@ Make sure you've got one of Rayhunter's [supported devices](./supported-devices. ## Troubleshooting +* You can test your device by enabling the test heuristic. This will be very noisy and fire an alert every time you see a new tower. Be sure to turn it off when you are done testing. + * 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. ```bash diff --git a/doc/introduction.md b/doc/introduction.md index 8c7c487..b216f00 100644 --- a/doc/introduction.md +++ b/doc/introduction.md @@ -2,11 +2,14 @@ Rayhunter Logo - An Orca taking a bite out of a cellular signal bar -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](./supported-devices.md). - +Rayhunter is a project for detecting IMSI catchers, also known as cell-site simulators or stingrays. It was first designed to run on a cheap mobile hotspot called the Orbic RC400L, but thanks to community efforts can [support some other devices as well](./supported-devices.md). 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](https://www.eff.org/deeplinks/2025/03/meet-rayhunter-new-open-source-tool-eff-detect-cellular-spying). Otherwise, check out the [installation guide](./installation.md) to get started. +→ Check out the [installation guide](./installation.md) to get started. + +→ To learn more about the aim of the project, and about IMSI catchers in general, please check out our [introductory blog post](https://www.eff.org/deeplinks/2025/03/meet-rayhunter-new-open-source-tool-eff-detect-cellular-spying). + +→ For discussion, help, or to join the mattermost channel and get involved with the project and community check out the [many ways listed here](./support-feedback-community.md)! **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. diff --git a/doc/orbic.md b/doc/orbic.md index fbdd1a7..4ca2209 100644 --- a/doc/orbic.md +++ b/doc/orbic.md @@ -1,7 +1,9 @@ -# Orbic RC400L +# Orbic/Kajeet RC400L The Orbic RC400L is an inexpensive LTE modem primarily designed for the US market, and the original device for which Rayhunter is developed. +It is also sometimes sold under the brand Kajeet RC400L. This is the exact same hardware and can be treated the same. + You can buy an Orbic [using bezos bucks](https://www.amazon.com/Orbic-Verizon-Hotspot-Connect-Enabled/dp/B08N3CHC4Y), or on [eBay](https://www.ebay.com/sch/i.html?_nkw=orbic+rc400l). @@ -34,6 +36,8 @@ The drawback is that the device's admin password is required. If you have a Kaje 3. The installer will ask you to log into the admin UI on `localhost:4000`. The password for that is the same as the WiFi password. 4. As soon as you're logged in, the installer will continue and reboot the device. +*note*: On Kajeet devices the default admin password is `$m@rt$p0tc0nf!g`, on most other orbic devices the default admin password is the same as the wifi password. If the password has been changed you can reset it by pressing the button under the back case until the unit restarts. + ## Obtaining a shell After running through the installation procedure, you can obtain a root shell diff --git a/doc/supported-devices.md b/doc/supported-devices.md index f5cf6d0..13b5c26 100644 --- a/doc/supported-devices.md +++ b/doc/supported-devices.md @@ -7,7 +7,7 @@ These devices have been extensively tested by the core developers and are widely | Device | Recommended region | | ------ | ------ | -| [Orbic RC400L](./orbic.md) | Americas | +| [Orbic RC400L](./orbic.md) Sometimes also branded Kajeet RC400L | Americas | | [TP-Link M7350](./tplink-m7350.md) | Africa, Europe, Middle East | The TP-Link M7350 also works in the Americas but is usually more expensive. diff --git a/doc/using-rayhunter.md b/doc/using-rayhunter.md index 1858ca2..12a24b1 100644 --- a/doc/using-rayhunter.md +++ b/doc/using-rayhunter.md @@ -1,6 +1,6 @@ # 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](./faq.md#red) once a potential IMSI catcher has been found, until the device is rebooted or a new recording is started through the web UI. +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 yellow dots, orange dashes, or solid red](./faq.md#red) once a potential IMSI catcher has been found, depending on the severity of the alert, until the device is rebooted or a new recording is started through the web UI. ![Rayhunter_0 5 0](./Rayhunter_0.5.0.png)