{"id":13638476,"url":"https://github.com/SysSec-KAIST/LTESniffer","last_synced_at":"2025-04-19T18:30:44.749Z","repository":{"id":154770470,"uuid":"626771649","full_name":"SysSec-KAIST/LTESniffer","owner":"SysSec-KAIST","description":" An Open-source LTE Downlink/Uplink Eavesdropper","archived":false,"fork":false,"pushed_at":"2024-10-23T16:48:32.000Z","size":29208,"stargazers_count":1901,"open_issues_count":18,"forks_count":193,"subscribers_count":33,"default_branch":"main","last_synced_at":"2025-04-11T21:48:40.969Z","etag":null,"topics":["cellular","lte","sdr","sniffer","wireless"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SysSec-KAIST.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-12T06:08:49.000Z","updated_at":"2025-04-11T10:21:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"ed97c45b-57e3-4caf-8d83-78e369189c2c","html_url":"https://github.com/SysSec-KAIST/LTESniffer","commit_stats":{"total_commits":42,"total_committers":3,"mean_commits":14.0,"dds":"0.33333333333333337","last_synced_commit":"a694803082017ac2b349e6b113940e8b9ba2fe5b"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SysSec-KAIST%2FLTESniffer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SysSec-KAIST%2FLTESniffer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SysSec-KAIST%2FLTESniffer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SysSec-KAIST%2FLTESniffer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SysSec-KAIST","download_url":"https://codeload.github.com/SysSec-KAIST/LTESniffer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249764714,"owners_count":21322287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cellular","lte","sdr","sniffer","wireless"],"created_at":"2024-08-02T01:00:46.485Z","updated_at":"2025-04-19T18:30:44.740Z","avatar_url":"https://github.com/SysSec-KAIST.png","language":"C++","funding_links":[],"categories":["C++","Wireless Protocols","UE","🛠️ Software \u0026 Tools","📡 BVLOS Communications"],"sub_categories":["Cellular (GSM/LTE/5G)","Diagnostics, Monitor mode","Analysis Tools","Cellular Analysis \u0026 Tampering Tools"],"readme":"\n# LTESniffer - An Open-source LTE Downlink/Uplink Eavesdropper\n\n**LTESniffer** is An Open-source LTE Downlink/Uplink Eavesdropper \n\nIt first decodes the Physical Downlink Control Channel (PDCCH) to obtain the Downlink Control Informations (DCIs) and Radio Network Temporary Identifiers (RNTIs) of all active users. Using decoded DCIs and RNTIs, LTESniffer further decodes the Physical Downlink Shared Channel (PDSCH) and Physical Uplink Shared Channel (PUSCH) to retrieve uplink and downlink data traffic.\n\nLTESniffer supports an API with three functions for security applications and research. Many LTE security research assumes\na passive sniffer that can capture privacy-related packets on the air. However, non of the current open-source sniffers satisfy their requirements as they cannot decode protocol packets in PDSCH and PUSCH. We developed a proof-of-concept security API that supports three tasks that were proposed by previous works: 1) Identity mapping, 2) IMSI collecting, and 3) Capability profiling.\n\nPlease refer to our [paper][paper] for more details.\n\n## LTESniffer in layman's terms\nLTESniffer is a tool that can capture the LTE wireless messages that are sent between a cell tower and smartphones connected to it. LTESniffer supports capturing the messages in both directions, from the tower to the smartphones, and from the smartphones back to the cell tower.\n\nLTESniffer **CANNOT DECRYPT** encrypted messages between the cell tower and smartphones. It can be used for analyzing unencrypted parts of the communication between the cell tower and smartphones. For example, for encrypted messages, it can allow the user to analyze unencrypted parts, such as headers in MAC and physical layers. However, those messages sent in plaintext can be completely analyzable. For example, the broadcast messages sent by the cell tower, or the messages at the beginning of the connection are completely visible.\n\n## Ethical Consideration\n\nThe main purpose of LTESniffer is to support security and analysis research on the cellular network. Due to the collection of uplink-downlink user data, any use of LTESniffer must follow the local regulations on sniffing the LTE traffic. We are not responsible for any illegal purposes such as intentionally collecting user privacy-related information.\n\n## Features\n### New Update v2.1.0\n- Supports recording IQ raw data of subframes to file. Please refer to `LTESniffer-record-subframe` branch and its [README][capture-readme] for more details.\n- Supports offline decoding using recorded files ([README][capture-readme]).\n- Enable API in the downlink mode (only apply for identity collecting and mapping API)\n### New Update v2.0.0\n- Supports two USRP B-series for uplink sniffing mode. Please refer to `LTESniffer-multi-usrp` branch and its [README][multi-readme] for more details.\n- Fixed some bugs.\n\nLTESniffer is implemented on top of [FALCON][falcon] with the help of [srsRAN][srsran] library. LTESniffer supports:\n- Real-time decoding LTE uplink-downlink control-data channels: PDCCH, PDSCH, PUSCH\n- LTE Advanced and LTE Advanced Pro, up to 256QAM in both uplink and downlink\n- DCI formats: 0, 1A, 1, 1B, 1C, 2, 2A, 2B\n- Transmission modes: 1, 2, 3, 4\n- FDD only\n- Maximum 20 MHz base station. \n- Automatically detect maximum UL/DL modulation schemes of smartphones (64QAM/256QAM on DL and 16QAM/64QAM/256QAM on UL)\n- Automatically detect physical layer configuration per UE.\n- LTE Security API: RNTI-TMSI mapping, IMSI collecting, UECapability Profiling.\n\n## Hardware and Software Requirement\n### OS Requirement\nCurrently, LTESniffer works stably on Ubuntu 18.04/20.04/22.04.\n\n### Hardware Requirement\nAchieving real-time decoding of LTE traffic requires a high-performance CPU with multiple physical cores, especially during peak hours when the base station has many active users. LTESniffer successfully achieved real-time decoding when deployed on an Intel i7-9700K PC, decoding traffic from a base station with 150 active users.\n\n**The following hardware is recommended**\n- Intel i7 CPU with at least 8 physical cores\n- At least 16Gb RAM\n- 256 Gb SSD storage\n### SDR\nLTESniffer requires different SDR for its uplink and downlink sniffing modes.\n\nTo sniff only downlink traffic from the base station, LTESniffer is compatible with most SDRs that are supported by the srsRAN library (for example, USRP or BladeRF). \nThe SDR should be connected to the PC via a USB 3.0 port. Additionally, it should be equipped with two RX antennas to decode downlink messages in transmission modes 3 and 4. \nIf your SDR only has one RX antenna, LTESniffer will only decode downlink messages in transmission mode 1. Note that GPSDO is optional for downlink sniffing; it will help improve synchronization but is not mandatory.\n\nOn the other hand, to sniff uplink traffic from smartphones to base stations, LTESniffer needs to listen to two different frequencies (Uplink and Downlink) concurrently. To solve this problem, LTESniffer supports two options:\n- Using a single USRP X310. USRP X310 has two Local Oscillators (LOs) for 2 RX channels, which can turn each RX channel to a distinct Uplink/Downlink frequency. Similar to Downlink Sniffing, GPSDO is optional for this option. To use this option, please refer to the `main` branch of LTESniffer.\n- Using 2 USRP B-Series. LTESniffer utilizes 2 USRP B-series (B210/B200) for uplink and downlink separately. It achieves synchronization between 2 USRPs by using GPSDO for clock source and time reference. GPSDO is mandatory for this option. To use this option, please refer to the `LTESniffer-multi-usrp` branch of LTESniffer and its [README][multi-readme].\n\n## Installation\n**Important note: To avoid unexpected errors, please follow the following steps on Ubuntu 18.04/20.04/22.04.**\n\n**Dependencies**\n- **Important dependency**: [UHD][uhd] library version \u003e= 4.0 must be installed in advance (recommend building from source). The following steps can be used on Ubuntu 18.04. Refer to UHD Manual for full installation guidance. \n\nUHD dependencies:\n```bash\nsudo apt update\nsudo apt-get install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool \\\ng++ git inetutils-tools libboost-all-dev libncurses5 libncurses5-dev libusb-1.0-0 libusb-1.0-0-dev \\\nlibusb-dev python3-dev python3-mako python3-numpy python3-requests python3-scipy python3-setuptools \\\npython3-ruamel.yaml\n```\nClone and build UHD from source (make sure that the current branch is higher than 4.0)\n```bash\ngit clone https://github.com/EttusResearch/uhd.git\ncd \u003cuhd-repo-path\u003e/host\nmkdir build\ncd build\ncmake ../\nmake -j 4\nmake test\nsudo make install\nsudo ldconfig\n```\nDownload firmwares for USRPs:\n```bash\nsudo uhd_images_downloader\n```\nWe use a [10Gb card](https://www.ettus.com/all-products/10gige-kit/) to connect USRP X310 to PC, refer to UHD Manual [[1]](https://files.ettus.com/manual/page_usrp_x3x0.html), [[2]](https://files.ettus.com/manual/page_usrp_x3x0_config.html) to configure USRP X310 and 10Gb card interface. For USRP B210, it should be connected to PC via a USB 3.0 port.\n\nTest the connection and firmware (for USRP X310 only):\n```bash\nsudo sysctl -w net.core.rmem_max=33554432\nsudo sysctl -w net.core.wmem_max=33554432\nsudo ifconfig \u003c10Gb card interface\u003e mtu 9000\nsudo uhd_usrp_probe\n```\n\n- srsRAN dependencies:\n```bash\nsudo apt-get install build-essential git cmake libfftw3-dev libmbedtls-dev libboost-program-options-dev libconfig++-dev libsctp-dev\n```\n\n- LTESniffer dependencies:\n```bash\nsudo apt-get install libglib2.0-dev libudev-dev libcurl4-gnutls-dev libboost-all-dev qtdeclarative5-dev libqt5charts5-dev\n```\n\n**Build LTESniffer from source:**\n```bash\ngit clone https://github.com/SysSec-KAIST/LTESniffer.git\ncd LTESniffer\nmkdir build\ncd build\ncmake ../\nmake -j 4 (use 4 threads)\n```\n## Usage\nLTESniffer has 3 main functions: \n- Sniffing LTE downlink traffic from the base station\n- Sniffing LTE uplink traffic from smartphones\n- Security API\n\nAfter building from source, ``LTESniffer`` is located in ``\u003cbuild-dir\u003e/src/LTESniffer``\n\nNote that before using LTESniffer on the commercial, one should have to check the local regulations on sniffing LTE traffic, as we explained in the **Ethical Consideration**.\n\nTo figure out the base station and Uplink-Downlink band the test smartphone is connected to, install [Cellular-Z][app] app on the test smartphone (the app only supports Android). It will show the cell ID and Uplink-Downlink band/frequency to which the test smartphone is connected. Make sure that LTESniffer also connects to the same cell and frequency.\n### General downlink sniffing\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"png/dl_mode_png.png\" alt=\"LTESniffer Downlink Mode\"\u003e\n\u003c/p\u003e\n\n```bash\nsudo ./\u003cbuild-dir\u003e/src/LTESniffer -A 2 -W \u003cnumber of threads\u003e -f \u003cDL Freq\u003e -C -m 0\nexample: sudo ./src/LTESniffer -A 2 -W 4 -f 1840e6 -C -m 0\n-A: number of antennas\n-W: number of threads\n-f: downlink frequency\n-C: turn on cell search\n-m: sniffer mode, 0 for downlink sniffing and 1 for uplink sniffing\n```\nNote: to run ``LTESniffer`` with USRP B210 in the downlink mode, add option ``-a \"num_recv_frames=512\" `` to the command line.\nThis option extends the receiving buffer for USRP B210 to achieve better synchronization.\n\n```bash\nsudo ./\u003cbuild-dir\u003e/src/LTESniffer -A 2 -W \u003cnumber of threads\u003e -f \u003cDL Freq\u003e -C -m 0 -a \"num_recv_frames=512\"\nexample: sudo ./src/LTESniffer -A 2 -W 4 -f 1840e6 -C -m 0 -a \"num_recv_frames=512\"\n```\n\n### General uplink sniffing\nNote: In the uplink sniffing mode, the test smartphones should be located nearby the sniffer, because the uplink signal power from UE is significantly weaker compared to the downlink signal from the base station.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"png/ul_mode_png.png\" alt=\"LTESniffer Uplink Mode\"\u003e\n\u003c/p\u003e\n\n```bash\nsudo ./\u003cbuild-dir\u003e/src/LTESniffer -A 2 -W \u003cnumber of threads\u003e -f \u003cDL Freq\u003e -u \u003cUL Freq\u003e -C -m 1\nexample: sudo ./src/LTESniffer -A 2 -W 4 -f 1840e6 -u 1745e6 -C -m 1\n-u: uplink frequency\n```\n\n### Security API\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"png/api_png.png\" alt=\"LTESniffer API Mode\"\u003e\n\u003c/p\u003e\n\n```bash\nsudo ./\u003cbuild-dir\u003e/src/LTESniffer -A 2 -W \u003cnumber of threads\u003e -f \u003cDL Freq\u003e -u \u003cUL Freq\u003e -C -m 1 -z 3\nexample: sudo ./src/LTESniffer -A 2 -W 4 -f 1840e6 -u 1745e6 -C -m 1 -z 3\n-z: 3 for turnning on 3 functions of sniffer, which are identity mapping, IMSI collecting, and UECapability profiling.\n    2 for UECapability profiling\n    1 for IMSI collecting\n    0 for identity mapping\n```\n### Specify a base station\n\nLTESniffer can sniff on a specific base station by using options ``-I \u003cPhycial Cell ID (PCI)\u003e -p \u003cnumber of Physical Resource Block (PRB)\u003e``. In this case, LTESniffer does not do the cell search but connects directly to the specified cell.\n```bash\nsudo ./\u003cbuild-dir\u003e/src/LTESniffer -A 2 -W \u003cnumber of threads\u003e -f \u003cDL Freq\u003e -I \u003cPCI\u003e -p \u003cPRB\u003e -m 0\nsudo ./\u003cbuild-dir\u003e/src/LTESniffer -A 2 -W \u003cnumber of threads\u003e -f \u003cDL Freq\u003e -u \u003cUL Freq\u003e -I \u003cPCI\u003e -p \u003cPRB\u003e -m 1\nexample: sudo ./src/LTESniffer -A 2 -W 4 -f 1840e6 -u 1745e6 -I 379 -p 100 -m 1\n```\nThe debug mode can be enabled by using option ``-d``. In this case, the debug messages will be printed on the terminal.\n\n### Output of LTESniffer\n\nLTESniffer provides pcap files in the output. The pcap file can be opened by WireShark for further analysis and packet trace.\nThe name of downlink pcap file: ``sniffer_dl_mode.pcap``, uplink pcap file: ``sniffer_ul_mode.pcap``, and API pcap file: ``api_collector.pcap``.\nThe pcap files are located in the same directory ``LTESniffer`` has been executed.\nTo enable the WireShark to analyze the decoded packets correctly, please refer to the WireShark configuration guide [here][pcap]. There are also some examples of pcap files in the link.\\\n**Note:** The uplink pcap file contains both uplink and downlink messages. On the WireShark, use this filter to monitor only uplink messages: ``mac-lte.direction == 0``; or this filter to monitor only downlink messages: ``mac-lte.direction == 1``.\n\n## Application Note\n### Distance for uplink sniffing\nThe effective range for sniffing uplink is limited in LTESniffer due to the capability of the RF front-end of the hardware (i.e. SDR). The uplink signal power from UE is significantly weaker compared to the downlink signal because UE is a handheld device that optimizes battery usage, while the eNB uses sufficient power to cover a large area. To successfully capture the uplink traffic, LTESniffer can increase the strength of the signal power by i) being physically close to the UE, or ii) improving the signal reception capability with specialized hardware, such as a directional antenna, dedicated RF front-end, and signal amplifier.\n### The information displayed on the terminal\n**Downlink Sniffing Mode** \n\n``Processed 1000/1000 subframes``: Number of subframes was processed by LTESniffer last 1 second. There are 1000 LTE subframes per second by design. \\\n``RNTI``: Radio Network Temporary Identifier of UEs. \\\n``Table``: The maximum modulation scheme that is used by smartphones in downlink. LTESniffer supports up to 256QAM in the downlink. Refer to our [paper][paper] for more details. \\\n``Active``: Number of detected messages of RNTIs. \\\n``Success``: Number of successfully decoded messages over number of detected messages (``Active``). \\\n``New TX, ReTX, HARQ, Normal``: Statistic of new messages and retransmitted messages. This function is in development. \\\n``W_MIMO, W_pinfor, Other``: Number of messages with wrong radio configuration, only for debugging. \n\n**Uplink Sniffing Mode** \n\n``Max Mod``: The maximum modulation scheme that is used by smartphones in uplink. It can be 16/64/256QAM depending on the support of smartphones and the configuration of the network. Refer to our [paper][paper] for more details. \\\n``SNR``: Signal-to-noise ratio (dB). Low SNR means the uplink signal quality from the smartphone is bad. One possible reason is the smartphone is far from the sniffer. \\\n``DL-UL_delay``: The average of time delay between downlink signal from the base station and uplink signal from the smartphone. \\\n``Other Info``: Information only for debugging. \n\n**API Mode** \n\n``Detected Identity``: The name of detected identity. \\\n``Value``: The value of detected identity. \\\n``From Message``: The name of the message that contains the detected identity. \n\n\u003c!-- ## FAQ\n**Q:** Is it possible to capture and see the phone call content using LTESniffer? \\\n**A:** No. LTE traffic including phone call traffic is encrypted, so you cannot use LTESniffer to know the content of phone calls of someone. Moreover, it is important to note that sniffing phone calls in the commercial network is illegal in most countries. --\u003e\n## Credits\nWe sincerely appreciate the [FALCON][falcon] and [SRS team][srsran] for making their great softwares available.\n\n## Contributor\nSpecial thanks to all the contributors who helped us to fix bugs and improve LTESniffer\n\n1. [cellular777][cellular77]\n2. [Cemaxecuter][Cemaxecuter]\n3. [Ksk190809][Ksk190809]\n\n## BibTex\nPlease refer to our [paper][paper] for more details.\n\n```bibtex\n@inproceedings{hoang:ltesniffer,\n  title = {{LTESniffer: An Open-source LTE Downlink/Uplink Eavesdropper}},\n  author = {Hoang, Dinh Tuan and Park, CheolJun and Son, Mincheol and Oh, Taekkyung and Bae, Sangwook and Ahn, Junho and Oh, BeomSeok and Kim, Yongdae},\n  booktitle = {16th ACM Conference on Security and Privacy in Wireless and Mobile Networks (WiSec '23)},\n  year = {2023}\n}\n```\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=SysSec-KAIST/LTESniffer\u0026type=Date)](https://star-history.com/#SysSec-KAIST/LTESniffer\u0026Date)\n\n## FAQ\n\n\u003c!-- **Q:** What kind of SDRs I can use to run LTESniffer? \\\n**A:** To sniff only downlink traffic from the base station, LTESniffer works well with USRP B210 with 2 RX antennas.\nTo sniff the uplink traffic, LTESniffer requires USRP X310 with 2 daughterboards. There are two reasons for this. First, sniffing the uplink traffic requires precise time synchronization between uplink and downlink subframes, which can be simply achieved by using two daughterboards with the same clock source from a single motherboard of USRP X310. Second, the \"srsran_rf_set_rx_freq\" function used by LTESniffer seems to only support the USRP X310 with 2 daughterboards for simultaneous reception of signals at two different frequencies. --\u003e\n\n**Q:** Is it mandatory to use GPSDO with the USRP in order to run LTESniffer? \\\n**A:** GPSDO is useful for more stable synchronization. However, for downlink sniffing mode, LTESniffer still can synchronize with the LTE signal to decode the packets without GPSDO. For uplink sniffing mode, GPSDO is only required when using 2 USRP B-series, as it is the time and clock reference sources for synchrozation between uplink and downlink channels. Another uplink SDR option, using a single USRP X310, does not require GPSDO.\n\n**Q:** For downlink traffic, can I use a cheaper SDR? \\\n**A:** Technically, any SDRs supported by srsRAN library such as Blade RF can be used to run LTESniffer in the downlink sniffing mode. However, we only tested the downlink sniffing function of LTESniffer with USRP B210 and X310. \n\n**Q:** Is it illegal to use LTESniffer to sniff the LTE traffic? \\\n**A:** You should have to check the local regulations on sniffing (unencrypted) LTE traffic. Another way to test LTESniffer is setting up a personal LTE network by using [srsRAN][srsran] - an open-source LTE implementation in a Faraday cage. \n\n**Q:** Can LTESniffer be used to view the content of messages between two users? \\\n**A:** One can see only the \"unencrypted\" part of the messages. Note that the air traffic between the base station and users is mostly encrypted.\n\n**Q:** Is there any device identity exposed in plaintext in the LTE network? \\\n**A:** Yes, literature shows that there are multiple identities exposed, such as TMSI, GUTI, IMSI, and RNTI. Please refer to the academic literature for more details. e.g. [Watching the Watchers: Practical Video Identification Attack in LTE Networks][watching]\n\n[falcon]: https://github.com/falkenber9/falcon\n[srsran]: https://github.com/srsran/srsRAN_4G\n[uhd]:    https://github.com/EttusResearch/uhd\n[paper]:  https://syssec.kaist.ac.kr/pub/2023/wisec2023_tuan.pdf\n[pcap]:   pcap_file_example/README.md\n[app]:    https://apkpure.com/cellular-z/make.more.r2d2.cellular_z\n[watching]: https://syssec.kaist.ac.kr/pub/2022/sec22summer_bae.pdf\n[multi-readme]: https://github.com/SysSec-KAIST/LTESniffer/tree/LTESniffer-multi-usrp\n[capture-readme]: https://github.com/SysSec-KAIST/LTESniffer/tree/LTESniffer-record-subframe\n[cellular77]: https://github.com/cellular777\n[Cemaxecuter]: https://www.youtube.com/@cemaxecuter7783\n[Ksk190809]: https://github.com/Ksk190809","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSysSec-KAIST%2FLTESniffer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSysSec-KAIST%2FLTESniffer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSysSec-KAIST%2FLTESniffer/lists"}