{"id":13540378,"url":"https://github.com/virtualabs/btlejack","last_synced_at":"2025-04-02T07:31:01.842Z","repository":{"id":37561698,"uuid":"143916698","full_name":"virtualabs/btlejack","owner":"virtualabs","description":"Bluetooth Low Energy Swiss-army knife","archived":false,"fork":false,"pushed_at":"2024-08-04T20:31:17.000Z","size":784,"stargazers_count":1977,"open_issues_count":28,"forks_count":200,"subscribers_count":65,"default_branch":"master","last_synced_at":"2025-03-23T18:06:13.577Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/virtualabs.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","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":"2018-08-07T19:13:53.000Z","updated_at":"2025-03-21T21:35:14.000Z","dependencies_parsed_at":"2024-11-03T05:31:29.899Z","dependency_job_id":"a57c5f92-3aec-4a9e-9fdc-7652fd4c534d","html_url":"https://github.com/virtualabs/btlejack","commit_stats":{"total_commits":73,"total_committers":10,"mean_commits":7.3,"dds":"0.23287671232876717","last_synced_commit":"c487859888450f6a33f618180bac5358f104e367"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtualabs%2Fbtlejack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtualabs%2Fbtlejack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtualabs%2Fbtlejack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtualabs%2Fbtlejack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/virtualabs","download_url":"https://codeload.github.com/virtualabs/btlejack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246774355,"owners_count":20831525,"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":[],"created_at":"2024-08-01T09:01:48.134Z","updated_at":"2025-04-02T07:30:56.830Z","avatar_url":"https://github.com/virtualabs.png","language":"Python","readme":"BtleJack: a new Bluetooth Low Energy swiss-army knife\n#####################################################\n\nBtlejack provides everything you need to sniff, jam and hijack Bluetooth Low Energy devices. It relies on one or more `BBC Micro:Bit \u003chttp://microbit.org/\u003e`_. devices running a dedicated firmware. You may also\nwant to use an `Adafruit's Bluefruit LE sniffer \u003chttps://www.adafruit.com/product/2269\u003e`_ or a `nRF51822 Eval Kit \u003chttps://www.waveshare.com/wiki/BLE400\u003e`_, as we added support for these devices.\n\nCurrent version of this tool (2.0) supports BLE 4.x and 5.x. The BLE 5.x support is limited, as it does only support the 1Mbps Uncoded PHY and does not support channel map updates.\n\n\nRequirements\n============\n\nYou need a UNIX based system (for example a Raspberry Pi). If you use the BBC Micro:Bit, you will need one to three Micro:Bit devices (three devices recommended) and for each device one free USB port. The power consumption of a Micro:Bit is rather low, so you can use a single USB port and a passive hub for powering the three recommended units.\n\n**If you connect 3 microbits at the same time on your computer, Btlejack will be able to sniff on every advertising channel and has far more chance to capture the connection request.**\n\nHow to install\n==============\n\nFirst, install the ``btlejack`` Python3 client software with Pip:\n\n::\n\n  $ sudo pip3 install btlejack\n\n\nThen, connect your Micro:Bit device to your computer with a USB cable, mount the associated mass storage device (the mount point must contain **MICROBIT**), and issue the following command:\n\n::\n\n  $ btlejack -i\n\nThis will program every Micro:Bit device connected to your computer, and make\nthem ready to use with Btlejack. It will use the correct firmware version for the current client software, so it is highly recommended to perform this firmware installation procedure each time you update Btlejack.\n\nIf you are using a *Bluefruit LE sniffer* or a *nRF51822 Eval Kit*, then please use an external SWD programmer to flash your device with `this firmware \u003chttps://github.com/virtualabs/btlejack-firmware/raw/master/dist/btlejack-firmware-ble400.hex\u003e`_.\n\nKeep your devices connected and you're all set !\n\n**NOTE** This only works with posix compatible systems.\n\nHow to use Btlejack\n===================\n\nUsing Btlejack is quite easy. Btlejack can:\n\n- use various devices\n- sniff an existing BLE connection\n- sniff new BLE connections\n- jam an existing BLE connection\n- hijack an existing BLE connection\n- export captured packets to various PCAP formats\n\n\nSpecify devices to use\n----------------------\n\nBtlejack normally tries to autodetect and use connected compatible devices (Micro:Bit only for the moment), but since the firmware can be hacked or modified\nto work with other nRF51822-based boards, it provides a specific options to allow compatibility with these devices.\n\nThe ``-d`` option lets you specify one or more devices with Btlejack. Note that this option will disable the automatic detection of devices, and you should\nadd as many devices as you may need:\n\n::\n\n  $ btlejack -d /dev/ttyACM0 -d /dev/ttyACM2 -s\n\n\n\nSniffing an existing connection\n-------------------------------\n\nFirst, find an existing connection to target with ``btlejack``:\n\n::\n\n  $ btlejack -s\n  BtleJack version 1.1\n\n  [i] Enumerating existing connections ...\n  [ - 54 dBm] 0xcd91d517 | pkts: 1\n  [ - 46 dBm] 0xcd91d517 | pkts: 2\n\nThe first value (in dBm) shows the power of the signal, the greater this value is the better the sniffed connection will be.\n\nThe second value (hex) is the associated *access address*, a 32-bit value identifying a link between two bluetooth low energy compatible devices.\n\nThe last value is the number of packets seen with this *access address*. The higher this value is, the more probable the corresponding *access address* is used.\n\nThen, use the `-f` option to follow a specific connection:\n\n::\n\n  $ btlejack -f 0xdda4845e\n  BtleJack version 1.1\n\n  [i] Detected sniffers:\n   \u003e Sniffer #0: fw version 1.1\n\n  [i] Synchronizing with connection 0xdda4845e ...\n  ✓ CRCInit: 0x2a035e\n  ✓ Channel Map = 0x1fffffffff\n  ✓ Hop interval = 39\n  ✓ Hop increment = 15\n  [i] Synchronized, packet capture in progress ...\n  LL Data: 02 07 03 00 04 00 0a 03 00\n  LL Data: 0a 08 04 00 04 00 0b 5a 69 70\n  LL Data: 02 07 03 00 04 00 0a 03 00\n  LL Data: 0a 08 04 00 04 00 0b 5a 69 70\n\n\n**If you are using more than 1 microbit, Btlejack will parallelize some of the sniffing operations in order to speed up the connection parametres recovery !**\n\nSniffing for new connections\n----------------------------\n\nThe  ``-c`` option supported by ``btlejack`` allows you to specify the target BD address, or you may want to use ``any`` to capture any new connection created.\n\n::\n\n  $ btlejack -c any\n  BtleJack version 1.1\n\n  [i] Detected sniffers:\n   \u003e Sniffer #0: version 1.1\n   \u003e Sniffer #1: version 1.1\n  LL Data: 05 22 df b4 6f 95 c5 55 c0 0a f6 99 23 40 1d 7b 2f 0a 9a f4 93 01 12 00 27 00 00 00 d0 07 ff ff ff ff 1f 0b\n  [i] Got CONNECT_REQ packet from 55:c5:95:6f:b4:df to 40:23:99:f6:0a:c0\n   |-- Access Address: 0x0a2f7b1d\n   |-- CRC Init value: 0x93f49a\n   |-- Hop interval: 39\n   |-- Hop increment: 11\n   |-- Channel Map: 1fffffffff\n   |-- Timeout: 20000 ms\n\n  LL Data: 03 09 08 0f 00 00 00 00 00 00 00\n  LL Data: 03 09 08 0f 00 00 00 00 00 00 00\n  LL Data: 0b 06 0c 08 0f 00 09 41\n  LL Data: 03 06 0c 07 1d 00 d3 07\n\nor you may also want to specify the target BD address:\n\n::\n\n  $ btlejack -c 03:e1:f0:00:11:22\n\n\nJamming a connection\n--------------------\n\nOnce a connection identified by its *access address*, you can provide jam it by using the ``-j`` option:\n\n::\n\n  $ btlejack -f 0x129f3244 -j̀\n\n\nHijacking a BLE connection\n--------------------------\n\nBtlejack is also able to hijack an existing connection, use the ``-t`` option to do so. Once hijacked, Btlejack will give you a prompt allowing you to interact with the hijacked device.\n\nFirst, hijack an existing connection:\n\n::\n\n  $ btlejack -f 0x9c68fd30 -t -m 0x1fffffffff\n  BtleJack version 1.1\n\n  [i] Using cached parameters (created on 2018-08-11 01:48:24)\n  [i] Detected sniffers:\n   \u003e Sniffer #0: fw version 1.1\n\n  [i] Synchronizing with connection 0x9c68fd30 ...\n  ✓ CRCInit: 0x81f733\n  ✓ Channel map is provided: 0x1fffffffff\n  ✓ Hop interval = 39\n  ✓ Hop increment = 9\n  [i] Synchronized, hijacking in progress ...\n  [i] Connection successfully hijacked, it is all yours \\o/\n  btlejack\u003e\n\nThen use the following commands to interact with the device:\n- **discover**: performs services and characteristics enumeration, will give you all the information about services and characteristics\n- **write**: write data to a specific value handle\n- **read**: read data from a specific value handle\n- **ll**: sends a raw link-layer packet (for ninjas)\n\n*discover* command\n^^^^^^^^^^^^^^^^^^\n\nThe ``discover`` command will send and receive Bluetooth LE packets and retrieve all the services UUIDs and parameters, as well as characteristics UUIDs and parameters:\n\n::\n\n  btlejack\u003e discover\n  start: 0001 end: 0005\n  start: 0014 end: 001a\n  start: 0028 end: ffff\n   Discovered services:\n  Service UUID: 1801\n   Characteristic UUID: 2a05\n     | handle: 0002\n     | properties: indicate  (20)\n     \\ value handle: 0003\n\n  Service UUID: 1800\n   Characteristic UUID: 2a04\n     | handle: 0019\n     | properties: read  (02)\n     \\ value handle: 001a\n\n   Characteristic UUID: 2a00\n     | handle: 0015\n     | properties: read  (02)\n     \\ value handle: 0016\n\n   Characteristic UUID: 2a01\n     | handle: 0017\n     | properties: read  (02)\n     \\ value handle: 0018\n\n  Service UUID: 1824\n   Characteristic UUID: 2abc\n     | handle: 0029\n     | properties: write indicate  (28)\n     \\ value handle: 002a\n\n*read* command\n^^^^^^^^^^^^^^\n\nThe ``read`` command accepts a single parameter, the value handle corresponding to the characteristic you want to read from:\n\n::\n\n  btlejack\u003e read 0x16\n  read\u003e\u003e 4c 47 20 77 65 62 4f 53 20 54 56\n\n*write* command\n^^^^^^^^^^^^^^^\n\nThe ``write`` command accepts three parameters:\n\n::\n\n  btlejack\u003e write \u003cvalue handle\u003e \u003cdata format\u003e \u003cdata\u003e\n\n\nSupported data formats:\n\n- ``hex``: hex data (i.e. \"414261\")\n- ``str``: text string, may be encapsulated in double quotes\n\n*ll* command\n^^^^^^^^^^^^\n\nThis last command allows you to send Bluetooth Low Energy Link-layer PDUs, in hex form, as specified in Volume 6, Part B, Chapter 2.4.\n\n\nPCAP file export\n----------------\n\nOne interesting feature of Btlejack is the possibility to export the captured data to a PCAP file.\n\nBtlejack supports the following DLT formats:\n\n* DLT_BLUETOOTH_LE_LL_WITH_PHDR (same)\n* DLT_NORDIC_BLE (the one used by Nordic' sniffer)\n* DLT_BLUETOOTH_LE_LL (supported on latest versions of Wireshark)\n\nThe output file may be specified using the `-o` option, while the output format may be specified with the `-x` option. Valid formats values are: `ll_phdr`, `nordic`, or `pcap` (default).\n\n::\n\n  $ btlejack -f 0xac56bc12 -x nordic -o capture.nordic.pcap\n\n\nThe ``ll_phdr`` export type is useful when sniffing an encrypted connection, as it is also supported by `crackle \u003chttps://github.com/mikeryan/crackle\u003e`_. So if you want to sniff and break encrypted connections, this is the way to go.\n\nYou may also need to tell crackle to use a specific cracking strategy, by using the `-s` option:\n\n::\n\n  $ crackle -i some.pcap -s 1\n\n\nConnection cache\n----------------\n\nBtlejack uses a *connection cache* to store some connection-related value in order to speed up\nthings a bit. This connection cache may cause some problems, especially if an access address has\nbeen previously seen.\n\nThis cache can be flushed with the ``-z`` option:\n\n::\n\n  $ btlejack -z\n\nDumping live packets with Wireshark\n-----------------------------------\n\nBtlejack 2.0 introduces a new *-w* option that allows you to specify a FIFO path (existing or not) in order\nto perform packets live analysis:\n\n::\n\n  $ btlejack -c any -w /tmp/blepipe\n\nYou can even use a FIFO and an output file as the same time:\n\n::\n\n  $ btlejack -c any -w /tmp/blepipe -o blepackets.pcap\n\nHint for using btlejack on a Raspberry Pi\n-----------------------------------------\nIf you have previously enabled **virtual ethernet over USB** (RNDIS), e.g. to setup a Raspberry Pi Zero W over USB, you need to disable this again (i.e. remove ``dtoverlay=dwc2`` from boot/config.txt and ``modules-load=dwc2,g_ether`` from boot/cmdline.txt, then ``sudo reboot``), because this would otherwise interfere with the sniffers' USB connections.\n\nBluetooth LE 5 \u0026 5.1 support\n============================\n\nThis version supports Bluetooth Low Energy versions 5 and 5.1 and especially the new *channel selectrion algorithm* introduced\nin version 5 (CSA #2). However, since the hardware used does not support the two new PHYs added from version 5, it will only be\nable to sniff, jam, and maybe hijack connections using the **1Mbps uncoded PHY**.\n\nPlease also note that the current implementation of CSA #2 included in Btlejack does not support channel map updates, for the moment.\n\nSniffing a new BLE 5 connection\n-------------------------------\n\nBtlejack automatically detects the channel selection algorithm used, so you don't have to worry and just capture packets as usual.\n\nSniffing an existing BLE 5 connection\n-------------------------------------\n\nSniffing an existing BLE 5 connection (that uses the 1Mbps uncoded PHY, and only this PHY) is not so difficult. First, you must specify\nthat you want to target a BLE 5 connection, by using the *-5* option. Please note that there is no way to tell if an existing connection\nuses CSA #2 or CSA #1, so you have to try both techniques until one works.\n\n::\n\n  $ btlejack -f 0x11223344 -5\n\nBtlejack will then recover the channel map used and then the hop interval value:\n\n::\n\n  $ btlejack -f 0x11223344 -5\n  [i] Synchronizing with connection 0x11223344 ...\n  ✓ CRCInit: 0x40d64f\n  ✓ Channel Map = 0x1fffffffff\n  ✓ Hop interval = 160\n\nIt will then try to recover this connection PRNG counter value:\n\n::\n\n  $ btlejack -f 0x11223344 -5\n  [i] Synchronizing with connection 0x11223344 ...\n  ✓ CRCInit: 0x40d64f\n  ✓ Channel Map = 0x1fffffffff\n  ✓ Hop interval = 160\n  ✓ CSA2 PRNG counter = 5137\n  [i] Synchronized, packet capture in progress ...\n\nOnce done, Btlejack is synchronized with this connection and will process packets\nas usual.\n\nJamming an existing BLE 5 connection\n-------------------------------------\n\nNothing new here, except that you must specify that you are attacking a BLE 5 connection,\nby using the *-5* option.\n\nPlease note that you can optimize this attack by also specifying the channel map\nand hop interval value to use, by using respectively the *-m* and *-p* flags. Both\nof them MUST be provided, unless it would not work.\n\n\nHijacking an existing BLE 5 connection\n--------------------------------------\n\nI did not manage to hijack a BLE 5 connection at this time, as this attack is\ntime-sensitive. My BLE 5 devices use a latency of 0, thus allowing no delay and\ncausing this attack to fail.\n\nWhen I will get my hands on some legitimate BLE 5 devices, I will improve this.\n","funding_links":[],"categories":["\u003ca name=\"bluetooth_security_tools\"\u003e\u003c/a\u003eBluetooth Security Tools","\u003ca id=\"a2df15c7819a024c2f5c4a7489285597\"\u003e\u003c/a\u003e密罐\u0026\u0026Honeypot","Python","♻️ Projects Using micro:bit as a Dev Board","Uncategorized","Wireless Protocols"],"sub_categories":["Exploit Tools","\u003ca id=\"c5b6762b3dc783a11d72dea648755435\"\u003e\u003c/a\u003e蓝牙\u0026\u0026Bluetooth","🎓 Machine Learning Resources \u0026 Projects","Uncategorized","Bluetooth / BLE"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirtualabs%2Fbtlejack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvirtualabs%2Fbtlejack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirtualabs%2Fbtlejack/lists"}