1UBERTOOTH-BTLE(1) User Commands UBERTOOTH-BTLE(1)
2
6 ubertooth-btle -- Bluetooth Low Energy (BLE) sniffing and more
7
9 ubertooth-btle -f [-A 37|38|39] [-r output.pcapng]
10
12 ubertooth-btle is a tool for doing Fun Stuff(TM) with BLE. It can do
13 the following things:
14 · Sniff connections
16 · Interfere with connections
18 · Send advertising packets (experimental)
20 Sniffing connections is the most robust feature supported by uber‐
22 tooth-btle. It has two primary modes of operation: follow mode and pro‐
23 miscuous mode.
24 Follow mode is the preferred mode for general use. In this mode, Uber‐
26 tooth will listen on one of three advertising channels waiting for a
27 BLE connection to be established. When a connection is established,
28 Ubertooth will hop along the data channels, passively capturing the
29 data sent between the central and peripheral. After the connection ter‐
30 minates, Ubertooth will return to the advertising channel and wait for
31 another connection.
32 No-follow mode is similar to follow mode, but it only logs advertising
34 packets and will not follow connections as they are established.
35 Promiscuous mode is an experimental mode for sniffing connections after
37 they have already been established. This mode can be used to sniff
38 long-lived connections.
39 When sniffing, Ubertooth can only operate in either follow mode or pro‐
41 miscuous mode, but not both at the same time. If you are unsure which
42 mode to use, use follow mode.
43 By default, Ubertooth will follow any connection it observes. You can
45 limit this to following a specific Bluetooth Address (BD ADDR) using
46 the -t command line flag. For example, the following command will only
47 sniff connections where the central or peripheral's BD ADDR is
48 22:44:66:88:AA:CC:
49 ubertooth-btle -f -t22:44:66:88:AA:CC
51 -t can also take a mask length in CIDR-like notation. Masks can be
53 between 1 and 48 bits long, with a 48 bit mask matching the entire
54 address. Using a /24 mask will filter on just the OUI. For example, to
55 limit sniffing to just TI devices with the OUI 00:1A:7D, use the fol‐
56 lowing:
57 ubertooth-btle -t 00:1A:7D:00:00:00/24
59 Filters persist until they are explicitly cleared or the system
61 restarts (either via ubertooth-util -r or unplug/replug). To clear a
62 filter, use the special filter none. Example:
63 ubertooth-btle -t none
65 When filtering, previous versions of the firmware would still log all
67 advertising packets but only follow connections based on the filter
68 parameters. As of 2018-06-R1, advertising packets that do not match the
69 filter are dropped.
70 In all sniffing modes, Ubertooth can log data to PCAP or PcapNG with a
72 variety of pseudoheaders. The recommended logging format is PcapNG (-r)
73 or PCAP with LE Pseudoheader (-q). For compatibility with crackle (see
74 [USING WITH CRACKLE][]), use PCAP with PPI (-c).
75 Interfering with connections is a feature for causing intentional
77 interference with newly established or long-lived connections. When
78 this attack succeeds, the BLE connection between the central and
79 peripheral will be terminated. Pair the -i or -I flag with -f to inter‐
80 fere with new connections or -p to interfere with long-lived connec‐
81 tions. Note that causing intentional interference may be illegal in
82 your jurisdiction. Check your local laws before using this feature.
83 Finally, ubertooth-btle supports transmitting advertising packets with
85 a specified BD ADDR. This feature, referred to as faux slave mode, is
86 experimental and may not function as intended. Use at your own risk.
87
89 Sniff all connections on advertising channel 38, logging all data to
90 PcapNG:
91 ubertooth-btle -f -A 38 -r log.pcapng
93 Log advertising packets without following connections:
95 ubertooth-btle -n
97 Interfere with connections recovered with promiscuous mode:
99 ubertooth-btle -p -I
101 Send advertising packets using BD ADDR 22:44:66:88:AA:CC:
103 ubertooth-btle -s22:44:66:88:AA:CC
105
107 · -h : Displays help message
108 Major modes:
110 · -f : Follow mode: sniff connections as they are established
112 · -n : No-follow mode: log advertising packets but don't follow
114 connections
115 · -p : Promiscuous mode: sniff already-established connections
117 · -s<BD ADDR> : Inject advertising packets using specified BD
119 ADDR
120 Interference (pair with -f or -p):
122 · -i : Interfere with one connection and return to idle
124 · -I : Interfere continuously with many connections
126 Filtering:
128 · -t<BD ADDR> : Limit connection following and interference in
130 follow mode to the specified BD ADDR
131 Logging:
133 · -r <output.pcapng> : Log to PcapNG (preferred)
135 · -q <output.pcap> : Log to PCAP with DLT_BLUE‐
137 TOOTH_LE_LL_WITH_PHDR
138 · -c <output.pcap> : Log to PCAP with PPI (for compatibility
140 with crackle(1))
141 Miscellaneous:
143 · -A <37|38|39> : Which advertising channel to use in follow
145 mode (default: 37)
146 · -a[address] : Get or set access address in promiscuous mode
148 · -v[01] : Get or set CRC verification (default: 0)
150 · -x<0-32> : Allow n access address violations (default: 32).
152 Filtering occurs on host.
153 Data source:
155 · -U<0-7> : Which Ubertooth to use
157
159 crackle is a tool for cracking the BLE key exchange and decrypting
160 encrypted data. To capture data for use with crackle, sniff connections
161 in follow mode using -f and log data to PCAP/PPI using -c. Example:
162 ubertooth-btle -f -c crack.pcap
164 Refer to crackle documentation for further details.
166
168 crackle(1): ⟨https://github.com/mikeryan/crackle⟩
169
171 ubertooth-btle is Copyright (C) 2012-2018 Mike Ryan. This tool is
172 released under the GPLv2. Refer to COPYING for futher details.
173Project Ubertooth July 2018 UBERTOOTH-BTLE(1)