mirage.libs.ble_utils package¶

Submodules¶

mirage.libs.ble_utils.adb module¶

class mirage.libs.ble_utils.adb.ADBDevice(interface)¶

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with an Android Device using adb in order to monitor Bluetooth Low Energy HCI packets.

The corresponding interfaces are : adbX (e.g. “adb0”)

The following capabilities are actually supported :

Capability	Available ?
SCANNING	no
ADVERTISING	no
SNIFFING_ADVERTISEMENTS	no
SNIFFING_NEW_CONNECTION	no
SNIFFING_EXISTING_CONNECTION	no
JAMMING_CONNECTIONS	no
JAMMING_ADVERTISEMENTS	no
HIJACKING_MASTER	no
HIJACKING_SLAVE	no
INJECTING	no
MITMING_EXISTING_CONNECTION	no
INITIATING_CONNECTION	no
RECEIVING_CONNECTION	no
COMMUNICATING_AS_MASTER	no
COMMUNICATING_AS_SLAVE	no
HCI_MONITORING	yes

Warning

You must install a recent version of adb in order to monitor a smartphone.
The full path to the binary adb should be present in the PATH environment variable.
You should enable the Developper mode, USB Debugging and Bluetooth logging on your smartphone.

If you don’t know how to configure your smartphone, please follow the instructions presented here.

close()¶: This method closes the device.

classmethod findADBDevices(index=None)¶

This class method allows to find a specific ADB device, by providing the device’s index. If no index is provided, it returns a list of every devices found. If no device has been found, None is returned.

Parameters

index (int) – device’s index

Returns

string indicating the device

Return type

str

Example

>>> ADBDevice.findADBDevices(0)
'3e95c5e'
>>> ADBDevice.findADBDevices()
['3e95c5e','3e95c5f']

getAddressByHandle(handle)¶

This method returns the BD address associated to the provided connection handle if a corresponding connection is established. If no connection uses this handle, it returns None.

Parameters

handle (int) – connection handle

Returns

address of the corresponding connection

Return type

str

Example

>>> device.getAddressByHandle(72)
'AA:BB:CC:DD:EE:FF'
>>> device.getAddressByHandle(4)
None

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getConnections()¶

This method returns a list of couple (connection handle / BD address) representing the connections actually established. A connection is described by a dictionary containing an handle and a BD address : {"handle":72, "address":'AA:BB:CC:DD:EE:FF'}

Returns

list of connections established

Return type

list of dict

Example

>>> device.getConnections()
[{'handle':72, 'address':'AA:BB:CC:DD:EE:FF'}]

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnection()¶

This method returns the BD address associated to the current connection. If no connection is established, it returns None.

Returns

address of the current connection

Return type

str

Example

>>> device.getCurrentConnection()
'AA:BB:CC:DD:EE:FF'
>>> device.getCurrentConnection()
None

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnectionMode()¶

This method returns the connection mode (“public” or “random”) of the currently established connection.

Returns

connection mode of the current connection (“public” or “random”)

Return type

str

Example

>>> device.getCurrentConnectionMode()
'public'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentHandle()¶

This method returns the connection Handle actually in use. If no connection is established, its value is equal to -1.

Returns: connection Handle
Return type: int

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()¶

This method returns the index of the current ADB device.

Returns

device’s index

Return type

int

Example

>>> device.getDeviceIndex()
0

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSerial()¶

This method returns the serial number of the smartphone.

Returns

serial number

Return type

str

Example

>>> device.getSerial()
'3e95c5e'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSnoopFileLocation()¶

This method returns the snoop file location on the smartphone.

Returns

snoop file location

Return type

str

Example

>>> device.getSnoopFileLocation()
'/sdcard/btsnoop_hci.log'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSnoopFileSize()¶

This method returns the snoop file size on the smartphone.

Returns

snoop file size

Return type

int

Example

>>> device.getSnoopFileSize()
8927994

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()¶: This method initializes the device.

isConnected()¶

This method returns a boolean indicating if a connection is actually established.

Returns

boolean indicating if a connection is established

Return type

bool

Example

>>> device.isConnected()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()¶

This method allows to check if the device is initialized and available for use.

Returns: boolean indicating if the device is up
Return type: bool

recv()¶

This method receives some datas. If no data is available, this method returns None.

Parameters: data – raw representation of the received data

sharedMethods = ['getConnections', 'switchConnection', 'getCurrentConnection', 'getAddressByHandle', 'getCurrentHandle', 'getCurrentConnectionMode', 'isConnected', 'getSnoopFileLocation', 'getSnoopFileSize', 'getSerial', 'getDeviceIndex']¶

classmethod startADBDaemon()¶

This class method starts the ADB daemon server.

Returns

boolean indicating if the ADB server was successfully launched

Return type

bool

Example

>>> ADBDevice.startADBDaemon()
True

classmethod stopADBDaemon()¶

This class method stops the ADB daemon server.

Returns

boolean indicating if the ADB server was successfully stopped

Return type

bool

Example

>>> ADBDevice.stopADBDaemon()
True

switchConnection(address)¶

This method allows to switch the current connection to another connection established by providing the associated BD address.

Parameters

address (str) – BD Address of the new current connection

Returns

boolean indicating if the operation was successful

Return type

bool

Example

>>> device.getCurrentConnection()
'AA:BB:CC:DD:EE:FF'
>>> device.switchConnection('11:22:33:44:55:66')
>>> device.getCurrentConnection()
'11:22:33:44:55:66'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.hcidump module¶

class mirage.libs.ble_utils.hcidump.BLEHcidumpDevice(interface)¶

Bases: mirage.libs.wireless_utils.device.Device

This device allows to monitor an HCI interface using hcidump.

The corresponding interfaces are : hcidumpX (e.g. “hcidump0” for monitoring the interface “hci0”).

The following capabilities are actually supported :

Capability	Available ?
SCANNING	no
ADVERTISING	no
SNIFFING_ADVERTISEMENTS	no
SNIFFING_NEW_CONNECTION	no
SNIFFING_EXISTING_CONNECTION	no
JAMMING_CONNECTIONS	no
JAMMING_ADVERTISEMENTS	no
HIJACKING_MASTER	no
HIJACKING_SLAVE	no
INJECTING	no
MITMING_EXISTING_CONNECTION	no
INITIATING_CONNECTION	no
RECEIVING_CONNECTION	no
COMMUNICATING_AS_MASTER	no
COMMUNICATING_AS_SLAVE	no
HCI_MONITORING	yes

Warning

You must install a recent version of hcidump in order to monitor an HCI device.
The full path to the binary hcidump should be present in the PATH environment variable.

close()¶: This method closes the device.

getAddressByHandle(handle)¶

This method returns the BD address associated to the provided connection handle if a corresponding connection is established. If no connection uses this handle, it returns None.

Parameters

handle (int) – connection handle

Returns

address of the corresponding connection

Return type

str

Example

>>> device.getAddressByHandle(72)
'AA:BB:CC:DD:EE:FF'
>>> device.getAddressByHandle(4)
None

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getConnections()¶

This method returns a list of couple (connection handle / BD address) representing the connections actually established. A connection is described by a dictionary containing an handle and a BD address : {"handle":72, "address":'AA:BB:CC:DD:EE:FF'}

Returns

list of connections established

Return type

list of dict

Example

>>> device.getConnections()
[{'handle':72, 'address':'AA:BB:CC:DD:EE:FF'}]

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnection()¶

This method returns the BD address associated to the current connection. If no connection is established, it returns None.

Returns

address of the current connection

Return type

str

Example

>>> device.getCurrentConnection()
'AA:BB:CC:DD:EE:FF'
>>> device.getCurrentConnection()
None

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnectionMode()¶

This method returns the connection mode (“public” or “random”) of the currently established connection.

Returns

connection mode of the current connection (“public” or “random”)

Return type

str

Example

>>> device.getCurrentConnectionMode()
'public'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentHandle()¶

This method returns the connection Handle actually in use. If no connection is established, its value is equal to -1.

Returns: connection Handle
Return type: int

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()¶

This method returns the index of the current HCIDump device.

Returns

device’s index

Return type

int

Example

>>> device.getDeviceIndex()
0

getHCIInterface()¶

This method returns the HCI Interface monitored by this HCIDump device.

Returns

monitored HCI interface

Return type

str

Example

>>> device.getHCIInterface()
'hci0'

init()¶: This method initializes the device.

isConnected()¶

This method returns a boolean indicating if a connection is actually established.

Returns

boolean indicating if a connection is established

Return type

bool

Example

>>> device.isConnected()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()¶

This method allows to check if the device is initialized and available for use.

Returns: boolean indicating if the device is up
Return type: bool

recv()¶

This method receives some datas. If no data is available, this method returns None.

Parameters: data – raw representation of the received data

sharedMethods = ['getConnections', 'switchConnection', 'getCurrentConnection', 'getCurrentConnectionMode', 'getAddressByHandle', 'getCurrentHandle', 'isConnected', 'getHCIInterface', 'getDeviceIndex']¶

switchConnection(address)¶

This method allows to switch the current connection to another connection established by providing the associated BD address.

Parameters

address (str) – BD Address of the new current connection

Returns

boolean indicating if the operation was successful

Return type

bool

Example

>>> device.getCurrentConnection()
'AA:BB:CC:DD:EE:FF'
>>> device.switchConnection('11:22:33:44:55:66')
>>> device.getCurrentConnection()
'11:22:33:44:55:66'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.pcap module¶

class mirage.libs.ble_utils.pcap.BLEPCAPDevice(interface)¶

Bases: mirage.libs.wireless_utils.pcapDevice.PCAPDevice

This device allows to communicate with a PCAP file in order to write and read Bluetooth Low Energy packets.

The corresponding interfaces are : <filename>.pcap (e.g. “out.pcap”)

If the file exists, the BLEPCAPDevice is in read mode, and the corresponding receiver is able to use it as a classic Bluetooth Low Energy sniffer.

If the file doesn’t exist, the BLEPCAPDevice is in write mode, and the corresponding emitter is able to write packets in the file.

The following capabilities are actually supported :

Capability	Available ?
SCANNING	no
ADVERTISING	no
SNIFFING_ADVERTISEMENTS	yes
SNIFFING_NEW_CONNECTION	yes
SNIFFING_EXISTING_CONNECTION	no
JAMMING_CONNECTIONS	no
JAMMING_ADVERTISEMENTS	no
HIJACKING_MASTER	no
HIJACKING_SLAVE	no
INJECTING	no
MITMING_EXISTING_CONNECTION	no
INITIATING_CONNECTION	no
RECEIVING_CONNECTION	no
COMMUNICATING_AS_MASTER	no
COMMUNICATING_AS_SLAVE	no
HCI_MONITORING	no

Warning

This PCAP Device uses the DLT 256, and can be used to read or write some Link Layer packets. It is not compatible with a PCAP file containing HCI frames.

DLT = 256¶

SCAPY_LAYER¶: alias of scapy.layers.bluetooth4LE.BTLE_RF

buildPacket(packet, timestamp)¶: This method is used to encapsulate the packet into a scapy frame (if SCAPY_LAYER is not None).

getAccessAddress()¶

This method returns the access address actually in use.

Returns

access address

Return type

int

Example

>>> hex(device.getAccessAddress())
'0xe5e296e9'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannelMap()¶

This method returns the Channel Map actually in use.

Returns

Channel Map

Return type

int

Example

>>> hex(device.getChannelMap())
'0x1fffffffff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCrcInit()¶

This method returns the CRCInit actually in use.

Returns

CRCInit

Return type

int

Example

>>> hex(device.getCrcInit())
'0x0bd54a'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopIncrement()¶

This method returns the Hop Increment actually in use.

Returns

Hop Increment

Return type

int

Example

>>> device.getHopIncrement()
11

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopInterval()¶

This method returns the Hop Interval actually in use.

Returns

Hop Interval

Return type

int

Example

>>> device.getHopInterval()
36

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()¶: This method initializes the PCAP file, by checking the header (if the Device is in reading mode) or by adding the header (if the Device is in writing mode).

isSynchronized()¶

This method indicates if the sniffer is actually synchronized with a connection.

Returns

boolean indicating if the sniffer is synchronized

Return type

bool

Example

>>> device.isSynchronized()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

recv()¶: This method gets the packets from the PCAP file asynchronously.

send(packet)¶

This method writes a packet synchronously into the PCAP file.

Parameters: packet (bytes or scapy frame (if SCAPY_LAYER is not None)) – packet to write

sharedMethods = ['sniffNewConnections', 'sniffAdvertisements', 'getAccessAddress', 'getCrcInit', 'getChannelMap', 'getHopInterval', 'getHopIncrement', 'isSynchronized', 'getMode']¶

sniffAdvertisements(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the advertisement sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Warning

The channel parameter is not used by this method, and is present in order to provide the same API as BTLEJack and Ubertooth devices. However, the address field can be used in order to filter the advertisements frames.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffNewConnections(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the new connections sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffNewConnections()
>>> device.sniffNewConnections(channel=38)
>>> device.sniffNewConnections(address="1A:2B:3C:4D:5E:6F")

Warning

Actually, the address and channel arguments are not used by this method. They are present in order to provide the same API as BTLEJack and Ubertooth devices.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.btlejack module¶

class mirage.libs.ble_utils.btlejack.BTLEJackDevice(interface)¶

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with a BTLEJack Device in order to sniff Bluetooth Low Energy protocol. The corresponding interfaces are : microbitX (e.g. “microbit0”)

The following capabilities are actually supported :

Capability	Available ?
SCANNING	yes
ADVERTISING	no
SNIFFING_ADVERTISEMENTS	yes
SNIFFING_NEW_CONNECTION	yes
SNIFFING_EXISTING_CONNECTION	yes
JAMMING_CONNECTIONS	yes
JAMMING_ADVERTISEMENTS	yes
HIJACKING_MASTER	yes
HIJACKING_SLAVE	no
INJECTING	no
MITMING_EXISTING_CONNECTION	no
INITIATING_CONNECTION	no
RECEIVING_CONNECTION	no
COMMUNICATING_AS_MASTER	yes
COMMUNICATING_AS_SLAVE	no
HCI_MONITORING	no

close()¶: This method closes the device.

disableAdvertisementsJamming()¶

classmethod findMicrobits(index=None)¶

This class method allows to find a specific BTLEJack device, by providing the device’s index. If no index is provided, it returns a list of every devices found. If no device has been found, None is returned.

Parameters

index (int) – device’s index

Returns

string indicating the device

Return type

str

Example

>>> BTLEJackDevice.findMicrobits(0)
'/dev/ttyACM0'
>>> BTLEJackDevice.findMicrobits()
['/dev/ttyACM0','/dev/ttyACM1']

getAccessAddress()¶

This method returns the access address actually in use.

Returns

access address

Return type

int

Example

>>> hex(device.getAccessAddress())
'0xe5e296e9'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()¶

This method returns the channel actually in use.

Returns

channel in use

Return type

int

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannelMap()¶

This method returns the Channel Map actually in use.

Returns

Channel Map

Return type

int

Example

>>> hex(device.getChannelMap())
'0x1fffffffff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getConnections()¶

This method returns a list of couple (connection handle / address) representing the connections actually established. A connection is described by a dictionary containing an handle and an access address : {"handle":1, "address":"0x12345678"}

Returns

list of connections established

Return type

list of dict

Example

>>> device.getConnections()
[{'handle':1, 'address':'0x12345678'}]

Warning

The connection handle is always 1, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCrcInit()¶

This method returns the CRCInit actually in use.

Returns

CRCInit

Return type

int

Example

>>> hex(device.getCrcInit())
'0x0bd54a'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnection()¶

This method returns the access address associated to the current connection. If no connection is established, it returns None.

Returns

access address of the current connection

Return type

str

Example

>>> device.getCurrentConnection()
'0x12345678'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentHandle()¶

This method returns the connection Handle actually in use. If no connection is established, its value is equal to -1.

Returns: connection Handle
Return type: int

Warning

This method always returns 1, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()¶

This method returns the index of the current BTLEJack device.

Returns

device’s index

Return type

int

Example

>>> device.getDeviceIndex()
0

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getFirmwareVersion()¶

This method returns the firmware version of the current BTLEJack device.

Returns

firmware version as a tuple of (major, minor)

Return type

tuple of (int,int)

Example

>>> device.getFirmwareVersion()
(3,14)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopIncrement()¶

This method returns the Hop Increment actually in use.

Returns

Hop Increment

Return type

int

Example

>>> device.getHopIncrement()
11

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopInterval()¶

This method returns the Hop Interval actually in use.

Returns

Hop Interval

Return type

int

Example

>>> device.getHopInterval()
36

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()¶: This method initializes the device.

isConnected()¶

This method returns a boolean indicating if a connection is actually established and hijacked.

Returns

boolean indicating if a connection is established and hijacked

Return type

bool

Example

>>> device.isConnected()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isSynchronized()¶

This method indicates if the sniffer is actually synchronized with a connection.

Returns

boolean indicating if the sniffer is synchronized

Return type

bool

Example

>>> device.isSynchronized()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()¶

This method allows to check if the device is initialized and available for use.

Returns: boolean indicating if the device is up
Return type: bool

jamAdvertisements(pattern=b'', offset=0, channel=37)¶

This method reactively jams advertisements according to the specified pattern, offset and channel provided.

Parameters

pattern (bytes) – pattern contained in payload indicating that the packet must be jammed
offset (int) – offset indicating the position of pattern in the payload
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> target = "1A:2B:3C:4D:5E:6F"
>>> pattern = bytes.fromhex(target.replace(":",""))[::-1]
>>> device.jamAdvertisements(pattern=pattern,offset=2,channel=39) # jam the advertisements transmitted by 1A:2B:3C:4D:5E:6F on channel 39

Warning

This method requires the custom Mirage Firmware in order to jam advertisements.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

recv()¶

This method receives some datas. If no data is available, this method returns None.

Parameters: data – raw representation of the received data

restartSniffingMode()¶

This method restarts the sniffing mode.

Example

>>> device.restartSniffingMode()

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

send(packet)¶

This method sends some datas.

Parameters: data – raw representation of the data to send

setAccessAddress(accessAddress)¶

This method sets the access address to use.

Parameters

accessAddress (int) – new access address

Example

>>> device.setAccessAddress(0xe5e296e9)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setCRCChecking(enable=True)¶

This method enables CRC Checking.

Parameters

enable (bool) – boolean indicating if CRC Checking must be enabled

Example

>>> device.setCRCChecking(enable=True) # CRC Checking enabled
>>> device.setCRCChecking(enable=False) # CRC Checking disabled

Warning

BTLEJack calculates the CRC directly in the firmware, so this command is ignored. It is present in order to provide a similar API to Ubertooth.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setChannel(channel=37)¶

This method changes the channel actually in use by the provided channel.

Parameters

channel (int) – new channel

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setHijacking(enable=True)¶

This method allows to enable or disable the hijacking mode.

Parameters

enable (bool) – boolean indicating if the hijacking mode must be enabled or disabled

Example

>>> device.setHijacking(enable=True) # hijacking mode enabled
>>> device.setHijacking(enable=False) # hijacking mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setJamming(enable=True)¶

This method allows to enable or disable the jamming mode.

Parameters

enable (bool) – boolean indicating if the jamming mode must be enabled or disabled

Example

>>> device.setJamming(enable=True) # jamming mode enabled
>>> device.setJamming(enable=False) # jamming mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScan(enable=True)¶

This method enables or disables the scanning mode. It allows to change the channel according to the scan interval parameter.

Parameters

enable (bool) – boolean indicating if the scanning mode must be enabled

Example

>>> device.setScan(enable=True) # scanning mode enabled
>>> device.setScan(enable=False) # scanning mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanInterval(seconds=1)¶

This method allows to provide the scan interval (in second).

Parameters

seconds (float) – number of seconds to wait between two channels

Example

>>> device.setScanInterval(seconds=1)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setSweepingMode(enable=True, sequence=[37, 38, 39])¶

This method allows to enable or disable the Sweeping mode. It allows to provide a subset of advertising channels to monitor sequentially.

Parameters

enable (bool) – boolean indicating if the Sweeping mode is enabled.
sequence (list of int) – sequence of channels to use

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['getFirmwareVersion', 'getDeviceIndex', 'setCRCChecking', 'setChannel', 'getChannel', 'sniffNewConnections', 'sniffExistingConnections', 'sniffAdvertisements', 'jamAdvertisements', 'disableAdvertisementsJamming', 'setSweepingMode', 'setScan', 'setScanInterval', 'getConnections', 'switchConnection', 'getCurrentConnection', 'getCurrentHandle', 'isConnected', 'isSynchronized', 'getAccessAddress', 'getCrcInit', 'getChannelMap', 'getHopInterval', 'getHopIncrement', 'setJamming', 'setHijacking']¶

sniffAdvertisements(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the advertisement sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Warning

This method requires the custom Mirage Firmware in order to sniff advertisements.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffExistingConnections(accessAddress=None, crcInit=None, channelMap=None)¶

This method starts the existing connections sniffing mode.

Parameters

accessAddress – selected Access Address - if not provided, the parameter is recovered
crcInit (int) – selected CRCInit - if not provided, the parameter is recovered
channelMap (int) – selected Channel Map - if not provided, the parameter is recovered

Example

>>> device.sniffExistingConnections()
>>> device.sniffExistingConnections(accessAddress=0xe5e296e9)
>>> device.sniffExistingConnections(accessAddress=0xe5e296e9, crcInit=0x0bd54a)
>>> device.sniffExistingConnections(accessAddress=0xe5e296e9, crcInit=0x0bd54a, channelMap=0x1fffffffff)

Warning

If no access address is provided, BTLEJack tries to get multiple candidate access addresses and select the most probable address.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffNewConnections(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the new connections sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffNewConnections()
>>> device.sniffNewConnections(channel=38)
>>> device.sniffNewConnections(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

switchConnection(address)¶: This method is provided in order to provide the same API as an HCI Device, it actually has no effects.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.ubertooth module¶

class mirage.libs.ble_utils.ubertooth.BLEUbertoothDevice(interface)¶

Bases: mirage.libs.bt_utils.ubertooth.BtUbertoothDevice

This device allows to communicate with an Ubertooth Device in order to sniff Bluetooth Low Energy protocol. The corresponding interfaces are : ubertoothX (e.g. “ubertooth0”)

The following capabilities are actually supported :

Capability	Available ?
SCANNING	yes
ADVERTISING	no
SNIFFING_ADVERTISEMENTS	yes
SNIFFING_NEW_CONNECTION	yes
SNIFFING_EXISTING_CONNECTION	yes
JAMMING_CONNECTIONS	yes
JAMMING_ADVERTISEMENTS	no
HIJACKING_MASTER	no
HIJACKING_SLAVE	no
INJECTING	no
MITMING_EXISTING_CONNECTION	no
INITIATING_CONNECTION	no
RECEIVING_CONNECTION	no
COMMUNICATING_AS_MASTER	no
COMMUNICATING_AS_SLAVE	no
HCI_MONITORING	no

getAccessAddress()¶

This method returns the access address actually in use.

Returns

access address

Return type

int

Example

>>> hex(device.getAccessAddress())
'0xe5e296e9'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()¶

This method returns the channel actually in use.

Returns

channel in use

Return type

int

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannelMap()¶

This method returns the Channel Map actually in use.

Returns

Channel Map

Return type

int

Example

>>> hex(device.getChannelMap())
'0x1fffffffff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCrcInit()¶

This method returns the CRCInit actually in use.

Returns

CRCInit

Return type

int

Example

>>> hex(device.getCrcInit())
'0x0bd54a'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopIncrement()¶

This method returns the Hop Increment actually in use.

Returns

Hop Increment

Return type

int

Example

>>> device.getHopIncrement()
11

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopInterval()¶

This method returns the Hop Interval actually in use.

Returns

Hop Interval

Return type

int

Example

>>> device.getHopInterval()
36

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getMode()¶

This method returns the mode actually in use in the current Ubertooth Device (“Bt” or “BLE”)

Returns

string indicating the mode

Return type

str

Example

>>> device.getMode()
"BLE"

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSerial()¶

This method allows to get the device’s serial number.

Returns

device’s serial number

Return type

str

Example

>>> device.getSerial()
'1160010b201835ae6d474553-79e1ff0b'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()¶: This method initializes the device.

isSynchronized()¶

This method indicates if the sniffer is actually synchronized with a connection.

Returns

boolean indicating if the sniffer is synchronized

Return type

bool

Example

>>> device.isSynchronized()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

recv()¶

This method receives some datas. If no data is available, this method returns None.

Parameters: data – raw representation of the received data

restartSniffingMode()¶

This method restarts the sniffing mode.

Example

>>> device.restartSniffingMode()

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setCRCChecking(enable=True)¶

This method enables CRC Checking.

Parameters

enable (bool) – boolean indicating if CRC Checking must be enabled

Example

>>> device.setCRCChecking(enable=True) # CRC Checking enabled
>>> device.setCRCChecking(enable=False) # CRC Checking disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setChannel(channel=37)¶

This method changes the channel actually in use by the provided channel.

Parameters

channel (int) – new channel

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setJamming(enable=True)¶

This method allows to enable or disable the jamming mode.

Parameters

enable (bool) – boolean indicating if the jamming mode must be enabled or disabled

Example

>>> device.setJamming(enable=True) # jamming mode enabled
>>> device.setJamming(enable=False) # jamming mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScan(enable=True)¶

This method enables or disables the scanning mode. It allows to change the channel according to the scan interval parameter.

Parameters

enable (bool) – boolean indicating if the scanning mode must be enabled

Example

>>> device.setScan(enable=True) # scanning mode enabled
>>> device.setScan(enable=False) # scanning mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanInterval(seconds=1)¶

This method allows to provide the scan interval (in second).

Parameters

seconds (float) – number of seconds to wait between two channels

Example

>>> device.setScanInterval(seconds=1)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setSweepingMode(enable=True, sequence=[37, 38, 39])¶

This method allows to enable or disable the Sweeping mode. It allows to provide a subset of advertising channels to monitor sequentially.

Parameters

enable (bool) – boolean indicating if the Sweeping mode is enabled.
sequence (list of int) – sequence of channels to use

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['getFirmwareVersion', 'getDeviceIndex', 'getMode', 'getSerial', 'setChannel', 'setCRCChecking', 'setScanInterval', 'setScan', 'setJamming', 'isSynchronized', 'getChannel', 'getAccessAddress', 'getCrcInit', 'getChannelMap', 'getHopInterval', 'getHopIncrement', 'setSweepingMode', 'sniffNewConnections', 'sniffExistingConnections', 'sniffAdvertisements']¶

sniffAdvertisements(address='00:00:00:00:00:00', channel=None)¶

This method starts the advertisement sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffExistingConnections(accessAddress=None, crcInit=None, channelMap=None)¶

This method starts the existing connections sniffing mode.

Parameters

accessAddress – selected Access Address - if not provided, the parameter is recovered
crcInit (int) – selected CRCInit - if not provided, the parameter is recovered
channelMap (int) – selected Channel Map - if not provided, the parameter is recovered

Example

>>> device.sniffExistingConnections()
>>> device.sniffExistingConnections(accessAddress=0xe5e296e9)
>>> device.sniffAdvertisements(accessAddress=0xe5e296e9, crcInit=0x0bd54a)
>>> device.sniffAdvertisements(accessAddress=0xe5e296e9, crcInit=0x0bd54a, channelMap=0x1fffffffff)

Warning

Please note the following warnings :

Ubertooth is actually not able to set CRC Init value and uses a full Channel Map (0x1fffffffff). This parameters are provided in order to provide the same API for Ubertooth and BTLEJack devices.

If no access address is provided, Ubertooth tries to get multiple candidate access addresses and select the most probable address

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffNewConnections(address='00:00:00:00:00:00', channel=None)¶

This method starts the new connections sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffNewConnections()
>>> device.sniffNewConnections(channel=38)
>>> device.sniffNewConnections(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

stop()¶

mirage.libs.ble_utils.nrfsniffer module¶

class mirage.libs.ble_utils.nrfsniffer.NRFSnifferDevice(interface)¶

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with a NRFSniffer Device in order to sniff Bluetooth Low Energy protocol. The corresponding interfaces are : nrfsnifferX (e.g. “nrfsniffer0”)

The following capabilities are actually supported :

Capability	Available ?
SCANNING	yes
ADVERTISING	no
SNIFFING_ADVERTISEMENTS	yes
SNIFFING_NEW_CONNECTION	yes
SNIFFING_EXISTING_CONNECTION	no
JAMMING_CONNECTIONS	no
JAMMING_ADVERTISEMENTS	no
HIJACKING_MASTER	no
HIJACKING_SLAVE	no
INJECTING	no
MITMING_EXISTING_CONNECTION	no
INITIATING_CONNECTION	no
RECEIVING_CONNECTION	no
COMMUNICATING_AS_MASTER	no
COMMUNICATING_AS_SLAVE	no
HCI_MONITORING	no

close()¶: This method closes the device.

classmethod findNRFSniffers(index=None)¶

This class method allows to find a specific NRFSniffer device, by providing the device’s index. If no index is provided, it returns a list of every devices found. If no device has been found, None is returned.

Parameters

index (int) – device’s index

Returns

string indicating the device

Return type

str

Example

>>> NRFSnifferDevice.findNRFSniffers(0)
'/dev/ttyACM0'
>>> NRFSnifferDevice.findNRFSniffers()
['/dev/ttyACM0','/dev/ttyACM1']

getAccessAddress()¶

This method returns the access address actually in use.

Returns

access address

Return type

int

Example

>>> hex(device.getAccessAddress())
'0xe5e296e9'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()¶

This method returns the channel actually in use.

Returns

channel in use

Return type

int

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannelMap()¶

This method returns the Channel Map actually in use.

Returns

Channel Map

Return type

int

Example

>>> hex(device.getChannelMap())
'0x1fffffffff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCrcInit()¶

This method returns the CRCInit actually in use.

Returns

CRCInit

Return type

int

Example

>>> hex(device.getCrcInit())
'0x0bd54a'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()¶

This method returns the index of the current NRFSniffer device.

Returns

device’s index

Return type

int

Example

>>> device.getDeviceIndex()
0

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getFirmwareVersion()¶

This method returns the firmware version of the current NRFSniffer device.

Returns

firmware version

Return type

int

Example

>>> device.getFirmwareVersion()
1111

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopIncrement()¶

This method returns the Hop Increment actually in use.

Returns

Hop Increment

Return type

int

Example

>>> device.getHopIncrement()
11

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopInterval()¶

This method returns the Hop Interval actually in use.

Returns

Hop Interval

Return type

int

Example

>>> device.getHopInterval()
36

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()¶: This method initializes the device.

isSynchronized()¶

This method indicates if the sniffer is actually synchronized with a connection.

Returns

boolean indicating if the sniffer is synchronized

Return type

bool

Example

>>> device.isSynchronized()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()¶

This method allows to check if the device is initialized and available for use.

Returns: boolean indicating if the device is up
Return type: bool

recv()¶

This method receives some datas. If no data is available, this method returns None.

Parameters: data – raw representation of the received data

restartSniffingMode()¶

This method restarts the sniffing mode.

Example

>>> device.restartSniffingMode()

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setCRCChecking(enable=True)¶

This method enables CRC Checking.

Parameters

enable (bool) – boolean indicating if CRC Checking must be enabled

Example

>>> device.setCRCChecking(enable=True) # CRC Checking enabled
>>> device.setCRCChecking(enable=False) # CRC Checking disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setChannel(channel=37)¶

This method changes the channel actually in use by the provided channel.

Parameters

channel (int) – new channel

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScan(enable=True)¶

This method enables or disables the scanning mode. It allows to change the channel dynamically.

Parameters

enable (bool) – boolean indicating if the scanning mode must be enabled

Example

>>> device.setScan(enable=True) # scanning mode enabled
>>> device.setScan(enable=False) # scanning mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanInterval(seconds=1)¶

This method allows to provide the scan interval (in second).

Parameters

seconds (float) – number of seconds to wait between two channels

Example

>>> device.setScanInterval(seconds=1)

Warning

Scan interval cannot be modified on a NRF Sniffer actually. This method is provided in order to expose the same API used by other supported sniffers.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setSweepingMode(enable=True, sequence=[37, 38, 39])¶

This method allows to enable or disable the Sweeping mode. It allows to provide a subset of advertising channels to monitor sequentially.

Parameters

enable (bool) – boolean indicating if the Sweeping mode is enabled.
sequence (list of int) – sequence of channels to use

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['getFirmwareVersion', 'getDeviceIndex', 'setCRCChecking', 'setChannel', 'getChannel', 'sniffNewConnections', 'sniffAdvertisements', 'setSweepingMode', 'setScan', 'setScanInterval', 'isSynchronized', 'getAccessAddress', 'getCrcInit', 'getChannelMap', 'getHopInterval', 'getHopIncrement']¶

sniffAdvertisements(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the advertisement sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffNewConnections(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the new connections sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffNewConnections()
>>> device.sniffNewConnections(channel=38)
>>> device.sniffNewConnections(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.sniffle module¶

class mirage.libs.ble_utils.sniffle.SniffleDevice(interface)¶

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with a Sniffle Device in order to sniff Bluetooth Low Energy protocol. The corresponding interfaces are : sniffleX (e.g. “sniffle0”)

The following capabilities are actually supported :

Capability	Available ?
SCANNING	yes
ADVERTISING	yes
SNIFFING_ADVERTISEMENTS	yes
SNIFFING_NEW_CONNECTION	yes
SNIFFING_EXISTING_CONNECTION	no
JAMMING_CONNECTIONS	no
JAMMING_ADVERTISEMENTS	no
INJECTING	no
MITMING_EXISTING_CONNECTION	no
HIJACKING_MASTER	no
HIJACKING_SLAVE	no
INITIATING_CONNECTION	yes
RECEIVING_CONNECTION	no
COMMUNICATING_AS_MASTER	yes
COMMUNICATING_AS_SLAVE	no
HCI_MONITORING	no

close()¶: This method closes the device.

classmethod findSniffleSniffers(index=None)¶

This class method allows to find a specific Sniffle device, by providing the device’s index. If no index is provided, it returns a list of every devices found. If no device has been found, None is returned.

Parameters

index (int) – device’s index

Returns

string indicating the device

Return type

str

Example

>>> NRFSnifferDevice.findSniffleSniffers(0)
'/dev/ttyACM0'
>>> NRFSnifferDevice.findSniffleSniffers()
['/dev/ttyACM0','/dev/ttyACM1']

getAccessAddress()¶

This method returns the access address actually in use.

Returns

access address

Return type

int

Example

>>> hex(device.getAccessAddress())
'0xe5e296e9'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getAddress()¶

This method returns the actual BD address of the device.

Returns

str indicating the BD address

Return type

str

Example

>>> device.getAddress()
'1A:2B:3C:4D:5E:6F'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getAddressMode()¶

This method returns the address mode currently in use.

Returns

address mode (“public” or “random”)

Return type

str

Example

>>> device.getAddressMode()
'public'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()¶

This method returns the channel actually in use.

Returns

channel in use

Return type

int

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannelMap()¶

This method returns the Channel Map actually in use.

Returns

Channel Map

Return type

int

Example

>>> hex(device.getChannelMap())
'0x1fffffffff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getConnections()¶

This method returns a list of couple (connection handle / address) representing the connections actually established. A connection is described by a dictionary containing an handle and an access address : {"handle":1, "address":"0x12345678"}

Returns

list of connections established

Return type

list of dict

Example

>>> device.getConnections()
[{'handle':1, 'address':'0x12345678'}]

Warning

The connection handle is always 1, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCrcInit()¶

This method returns the CRCInit actually in use.

Returns

CRCInit

Return type

int

Example

>>> hex(device.getCrcInit())
'0x0bd54a'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnection()¶

This method returns the access address associated to the current connection. If no connection is established, it returns None.

Returns

access address of the current connection

Return type

str

Example

>>> device.getCurrentConnection()
'0x12345678'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentHandle()¶

This method returns the connection Handle actually in use. If no connection is established, its value is equal to -1.

Returns: connection Handle
Return type: int

Warning

This method always returns 1, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()¶

This method returns the index of the current Sniffle device.

Returns

device’s index

Return type

int

Example

>>> device.getDeviceIndex()
0

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getFirmwareVersion()¶

This method returns the firmware version of the current Sniffle device.

Returns

firmware version

Return type

int

Example

>>> device.getFirmwareVersion()
(1,5)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopIncrement()¶

This method returns the Hop Increment actually in use.

Returns

Hop Increment

Return type

int

Example

>>> device.getHopIncrement()
11

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopInterval()¶

This method returns the Hop Interval actually in use.

Returns

Hop Interval

Return type

int

Example

>>> device.getHopInterval()
36

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()¶: This method initializes the device.

isConnected()¶

This method returns a boolean indicating if the device is connected.

Returns

boolean indicating if the device is connected

Return type

bool

Example

>>> device.isConnected()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isSynchronized()¶

This method indicates if the sniffer is actually synchronized with a connection.

Returns

boolean indicating if the sniffer is synchronized

Return type

bool

Example

>>> device.isSynchronized()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()¶

This method allows to check if the device is initialized and available for use.

Returns: boolean indicating if the device is up
Return type: bool

recv()¶

This method receives some datas. If no data is available, this method returns None.

Parameters: data – raw representation of the received data

send(pkt)¶

This method sends some datas.

Parameters: data – raw representation of the data to send

setAddress(address, random=False)¶

This method allows to modify the BD address and the BD address type of the device, if it is possible.

Parameters

address (str) – new BD address
random (bool) – boolean indicating if the address is random

Returns

boolean indicating if the operation was successful

Return type

bool

Example

>>> device.setAddress("11:22:33:44:55:66")
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setAdvertising(enable=True)¶

This method enables or disables the advertising mode.

Parameters

enable (bool) – boolean indicating if the advertising mode must be enabled

Example

>>> device.setAdvertising(enable=True) # advertising mode enabled
>>> device.setAdvertising(enable=False) # advertising mode disabled

Warning

Please note that if no advertising and scanning data has been provided before this function call, nothing will be advertised. You have to set the scanning Parameters and the advertising Parameters before calling this method.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setAdvertisingParameters(type='ADV_IND', destAddr='00:00:00:00:00:00', data=b'', intervalMin=200, intervalMax=210, daType='public', oaType='public')¶

This method sets advertising parameters according to the data provided. It will mainly be used by ADV_IND-like packets.

Parameters

type (str) – type of advertisement (available values : “ADV_IND”, “ADV_DIRECT_IND”, “ADV_SCAN_IND”, “ADV_NONCONN_IND”, “ADV_DIRECT_IND_LOW”)
destAddress (str) – destination address (it will be used if needed)
data (bytes) – data included in the payload
intervalMin (int) – minimal interval
intervalMax (int) – maximal interval
daType (str) – string indicating the destination address type (“public” or “random”)
oaType – string indicating the origin address type (“public” or “random”)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setCRCChecking(enable=True)¶

This method enables CRC Checking.

Parameters

enable (bool) – boolean indicating if CRC Checking must be enabled

Example

>>> device.setCRCChecking(enable=True) # CRC Checking enabled
>>> device.setCRCChecking(enable=False) # CRC Checking disabled

Warning

Sniffle calculates the CRC directly in the firmware, so this command is ignored. It is present in order to provide a similar API to Ubertooth.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setChannel(channel=37)¶

This method changes the channel actually in use by the provided channel.

Parameters

channel (int) – new channel

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScan(enable=True)¶

This method enables or disables the scanning mode. It allows to change the channel according to the scan interval parameter.

Parameters

enable (bool) – boolean indicating if the scanning mode must be enabled

Example

>>> device.setScan(enable=True) # scanning mode enabled
>>> device.setScan(enable=False) # scanning mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanInterval(seconds=1)¶

This method allows to provide the scan interval (in second).

Parameters

seconds (float) – number of seconds to wait between two channels

Example

>>> device.setScanInterval(seconds=1)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanningParameters(data=b'')¶

This method sets scanning parameters according to the data provided. It will mainly be used by SCAN_RESP packets.

Parameters: data (bytes) – data to use in SCAN_RESP

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setSweepingMode(enable=True, sequence=[37, 38, 39])¶

This method allows to enable or disable the Sweeping mode. It allows to provide a subset of advertising channels to monitor sequentially.

Parameters

enable (bool) – boolean indicating if the Sweeping mode is enabled.
sequence (list of int) – sequence of channels to use

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['getFirmwareVersion', 'getDeviceIndex', 'setCRCChecking', 'setChannel', 'getChannel', 'getConnections', 'switchConnection', 'getCurrentConnection', 'getCurrentHandle', 'isConnected', 'updateConnectionParameters', 'setAddress', 'getAddress', 'setAdvertising', 'setAdvertisingParameters', 'setScanningParameters', 'sniffNewConnections', 'sniffAdvertisements', 'setSweepingMode', 'setScan', 'setScanInterval', 'isSynchronized', 'getAccessAddress', 'getCrcInit', 'getChannelMap', 'getHopInterval', 'getHopIncrement']¶

sniffAdvertisements(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the advertisement sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffNewConnections(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the new connections sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffNewConnections()
>>> device.sniffNewConnections(channel=38)
>>> device.sniffNewConnections(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

switchConnection(address)¶: This method is provided in order to provide the same API as an HCI Device, it actually has no effects.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

updateConnectionParameters(minInterval=0, maxInterval=0, latency=0, timeout=0, minCe=0, maxCe=65535)¶

This method allows to update connection parameters according to the data provided. It will mainly be used if an incoming BLEConnectionParameterUpdateRequest is received.

Parameters

minInterval (int) – minimal interval
maxInterval (int) – maximal interval
latency (int) – connection latency
timeout (int) – connection timeout
minCe (int) – minimum connection event length
maxCe (int) – maximum connection event length

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.butterfly module¶

class mirage.libs.ble_utils.butterfly.BLEButterflyDevice(interface)¶

Bases: mirage.libs.wireless_utils.butterfly.ButterflyDevice

This device allows to communicate with a ButteRFly Device in order to interact with Bluetooth Low Energy protocol. The corresponding interfaces are : butterflyX (e.g. “butterfly0”)

The following capabilities are actually supported :

Capability	Available ?
SCANNING	yes
ADVERTISING	no
SNIFFING_ADVERTISEMENTS	yes
SNIFFING_NEW_CONNECTION	yes
SNIFFING_EXISTING_CONNECTION	no
JAMMING_CONNECTIONS	no
JAMMING_ADVERTISEMENTS	no
INJECTING	yes
MITMING_EXISTING_CONNECTION	yes
HIJACKING_MASTER	yes
HIJACKING_SLAVE	yes
INITIATING_CONNECTION	no
RECEIVING_CONNECTION	no
COMMUNICATING_AS_MASTER	no
COMMUNICATING_AS_SLAVE	no
HCI_MONITORING	no

attachSubDevice(subDevice, identifier)¶

This method allows to attach a given subdevice to the current ButteRFly device.

Parameters

subDevice (BLEButterflySubdevice) – sub device instance
identifier (str) – string indicating if the subdevice communicates as a Master (“master”) or as a Slave (“slave”)

Note

This method is called directly by the subdevice, it is not intended to be used directly.

close()¶: This method closes the device.

detachSubDevice(identifier)¶

This method allows to detach a given subdevice.

Parameters: identifier (str) – string indicating the subdevice to detach (“master” or “slave”)

Note

This method is called directly by the subdevice, it is not intended to be used directly.

disableController()¶: This method disables the current controller.

enableController()¶: This method enables the current controller.

classmethod get(interface)¶: This class method implements the Register device pattern. According to the interface parameter, only one instance of a given specific device will be instanciated if multiple Emitters and/or Receivers tries to access it.

getAccessAddress()¶

This method returns the access address actually in use.

Returns

access address

Return type

int

Example

>>> hex(device.getAccessAddress())
'0xe5e296e9'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()¶

This method returns the channel actually in use.

Returns

channel in use

Return type

int

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannelMap()¶

This method returns the Channel Map actually in use.

Returns

Channel Map

Return type

int

Example

>>> hex(device.getChannelMap())
'0x1fffffffff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getConnections()¶

This method returns a list of couple (connection handle / address) representing the connections actually established. A connection is described by a dictionary containing an handle and an access address : {"handle":1, "address":"0x12345678"}

Returns

list of connections established

Return type

list of dict

Example

>>> device.getConnections()
[{'handle':1, 'address':'0x12345678'}]

Warning

The connection handle is always 1, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getController()¶

This method returns the controller used by the current Butterfly device.

Returns

controller in use

Return type

str

Example

>>> device.getController()
'BLE'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCrcInit()¶

This method returns the CRCInit actually in use.

Returns

CRCInit

Return type

int

Example

>>> hex(device.getCrcInit())
'0x0bd54a'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnection()¶

This method returns the access address associated to the current connection. If no connection is established, it returns None.

Returns

access address of the current connection

Return type

str

Example

>>> device.getCurrentConnection()
'0x12345678'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentHandle()¶

This method returns the connection Handle actually in use. If no connection is established, its value is equal to -1.

Returns: connection Handle
Return type: int

Warning

This method always returns 1, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()¶

This method returns the index of the current Butterfly device.

Returns

device’s index

Return type

int

Example

>>> device.getDeviceIndex()
0

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getFirmwareVersion()¶

This method returns the firmware version of the current Butterfly device.

Returns

firmware version as a tuple of (major, minor)

Return type

tuple of (int,int)

Example

>>> device.getFirmwareVersion()
(1,0)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopIncrement()¶

This method returns the Hop Increment actually in use.

Returns

Hop Increment

Return type

int

Example

>>> device.getHopIncrement()
11

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopInterval()¶

This method returns the Hop Interval actually in use.

Returns

Hop Interval

Return type

int

Example

>>> device.getHopInterval()
36

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSubInterfaces()¶

This method returns the interfaces of the available subdevices.

Returns

a tuple of strings linked to the available interfaces

Return type

(str,str)

Example

>>> device.getSubInterfaces()

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

hasCapabilities(*capability)¶

This method allows to check if the device implements some specific capabilities.

Parameters

*capability (str (multiple)) – capabilities to check

Returns

boolean indicating if the device implements the capabilities provided

Return type

bool

Example

>>> device.capabilities = ["SNIFFING", "INJECTING", "CHANGING_ADDRESS"]
>>> device.hasCapabilities("SNIFFING", "INJECTING")
True
>>> device.hasCapabilities("MAKING_COFFEE")
False

init()¶: This method initializes the device.

instances = {}¶

isConnected()¶

This method returns a boolean indicating if a connection is actually established.

Returns

boolean indicating if a connection is established

Return type

bool

Example

>>> device.isConnected()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isSynchronized()¶

This method indicates if the sniffer is actually synchronized with a connection.

Returns

boolean indicating if the sniffer is synchronized

Return type

bool

Example

>>> device.isSynchronized()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()¶

This method allows to check if the device is initialized and available for use.

Returns: boolean indicating if the device is up
Return type: bool

publish(event, *args, **kwargs)¶

This method allows to publish an event. It may be used to call from the device a method implemented on the corresponding Emitters / Receivers, subscribers by default.

Parameters

event (str) – method’s name to call

Example

>>> device.publish("stop")

recv()¶

This method receives some datas. If no data is available, this method returns None.

Parameters: data – raw representation of the received data

restartSniffingMode()¶

This method restarts the sniffing mode.

Example

>>> device.restartSniffingMode()

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

selectController(controller)¶

send(pkt)¶

This method sends some datas.

Parameters: data – raw representation of the data to send

setAccessAddress(accessAddress)¶

This method sets the access address to use.

Parameters

accessAddress (int) – new access address

Example

>>> device.setAccessAddress(0xe5e296e9)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setChannel(channel=37)¶

This method changes the channel actually in use by the provided channel.

Parameters

channel (int) – new channel

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setHijacking(target='master', enable=True)¶

This method allows to enable or disable the hijacking mode.

Parameters

target – target role to hijack (“master” for master hijacking, “slave” for slave hijacking)
enable (bool) – boolean indicating if the hijacking mode must be enabled or disabled

Example

>>> device.setHijacking(target="master",enable=True) # master hijacking mode enabled
>>> device.setHijacking(target="master",enable=False) # master hijacking mode disabled
>>> device.setHijacking(target="slave",enable=True) # slave hijacking mode enabled
>>> device.setHijacking(target="slave",enable=False) # slave hijacking mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setMitm(enable=True)¶

This method performs a Man-in-the-Middle attack targeting an established connection..

Parameters

enable (bool) – boolean indicating if the mitm mode must be enabled or disabled

Example

>>> device.setMitm(enable=True) # mitm mode enabled
>>> device.setMitm(enable=False) # mitm mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScan(enable=True)¶

This method enables or disables the scanning mode. It allows to change the channel according to the scan interval parameter.

Parameters

enable (bool) – boolean indicating if the scanning mode must be enabled

Example

>>> device.setScan(enable=True) # scanning mode enabled
>>> device.setScan(enable=False) # scanning mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanInterval(seconds=1)¶

This method allows to provide the scan interval (in second).

Parameters

seconds (float) – number of seconds to wait between two channels

Example

>>> device.setScanInterval(seconds=1)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['getFirmwareVersion', 'getDeviceIndex', 'getController', 'sniffNewConnections', 'isSynchronized', 'sniffAdvertisements', 'getAccessAddress', 'getCrcInit', 'getChannelMap', 'getHopInterval', 'getHopIncrement', 'setChannel', 'getChannel', 'setScan', 'setScanInterval', 'attachSubDevice', 'detachSubDevice', 'setMitm', 'setHijacking', 'getSubInterfaces', 'getConnections', 'switchConnection', 'getCurrentConnection', 'isConnected']¶

sniffAdvertisements(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the advertisement sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffNewConnections(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the new connections sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffNewConnections()
>>> device.sniffNewConnections(channel=38)
>>> device.sniffNewConnections(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

subscribe(subscriber)¶

This method allows to register a subscriber, according to the design pattern named Publish/subscribe. It allows a Device to call a method of the corresponding Emitter / Receiver, subscribers by default.

Parameters: subscriber (Object) – instance of an object subscribing to the device

switchConnection(address)¶: This method is provided in order to provide the same API as an HCI Device, it actually has no effects.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

class mirage.libs.ble_utils.butterfly.BLEButterflySubdevice(interface)¶

Bases: mirage.libs.wireless_utils.device.Device

This (sub)device allows to interact with one specific role (Master or Slave) of a BLE connection when an InjectaBLE complex attack is performed using ButteRFly Device. It is directly related to the approach used by ButteRFly firmware when an attack is performed. Indeed, some of the experimental InjectaBLE attacks (especially MiTM) makes use of a “trick” allowing to use only one physical ButteRFly Device to interact with the two roles involved in the targeted connection simultaneously. The attacker injects a CONNECTION_UPDATE_IND packet including carefully chosen WinOffset and WinSize fields allowing to desynchronize the legitimate Master and Slave without altering the other channel hopping parameters. Then, the attacker synchronises with the two legitimate roles, and the two connections follow the same channel hopping pattern with a simple time offset. As a consequence, only one physical device is needed to perform this attack.

However, Mirage’s ble_mitm module requires two separate devices, according to the existing Man-in-the-Middle strategies (GATTacker and BTLEJuice). As a consequence, this subdevice mimick the behaviour of a normal device from the module’s perspective, but acts as a software proxy to interact with the ButteRFly device. This subdevice can’t be used directly, it will be automatically instantiated by the ButteRFly Device when an attack is performed.

The corresponding interfaces are : butterflyX:subY (e.g. “butterfly0:sub0” mimicks a master and “butterfly0:sub1” mimicks a slave)

The following capabilities are supported :

Capability	Available ?
COMMUNICATING_AS_MASTER	yes (if Y == 0)
COMMUNICATING_AS_SLAVE	yes (if Y == 1)

close()¶: This method closes the device.

classmethod get(interface)¶: This class method implements the Register device pattern. According to the interface parameter, only one instance of a given specific device will be instanciated if multiple Emitters and/or Receivers tries to access it.

getConnections()¶

This method returns a list of couple (connection handle / address) representing the connections actually established. A connection is described by a dictionary containing an handle and an access address : {"handle":1, "address":"0x12345678"}

Returns

list of connections established

Return type

list of dict

Example

>>> device.getConnections()
[{'handle':1, 'address':'0x12345678'}]

Warning

The connection handle is always 1, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnection()¶

This method returns the access address associated to the current connection. If no connection is established, it returns None.

Returns

access address of the current connection

Return type

str

Example

>>> device.getCurrentConnection()
'0x12345678'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentHandle()¶

This method returns the connection Handle actually in use. If no connection is established, its value is equal to -1.

Returns: connection Handle
Return type: int

Warning

This method always returns 1, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

hasCapabilities(*capability)¶

This method allows to check if the device implements some specific capabilities.

Parameters

*capability (str (multiple)) – capabilities to check

Returns

boolean indicating if the device implements the capabilities provided

Return type

bool

Example

>>> device.capabilities = ["SNIFFING", "INJECTING", "CHANGING_ADDRESS"]
>>> device.hasCapabilities("SNIFFING", "INJECTING")
True
>>> device.hasCapabilities("MAKING_COFFEE")
False

init()¶: This method initializes the device.

instances = {}¶

isConnected()¶

This method returns a boolean indicating if a connection is actually established and hijacked.

Returns

boolean indicating if a connection is established and hijacked

Return type

bool

Example

>>> device.isConnected()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()¶

This method allows to check if the device is initialized and available for use.

Returns: boolean indicating if the device is up
Return type: bool

publish(event, *args, **kwargs)¶

This method allows to publish an event. It may be used to call from the device a method implemented on the corresponding Emitters / Receivers, subscribers by default.

Parameters

event (str) – method’s name to call

Example

>>> device.publish("stop")

recv()¶

This method receives some datas. If no data is available, this method returns None.

Parameters: data – raw representation of the received data

send(packet)¶

This method sends some datas.

Parameters: data – raw representation of the data to send

sharedMethods = ['isConnected', 'getCurrentHandle', 'getConnections', 'getCurrentConnection', 'switchConnection']¶

subscribe(subscriber)¶

This method allows to register a subscriber, according to the design pattern named Publish/subscribe. It allows a Device to call a method of the corresponding Emitter / Receiver, subscribers by default.

Parameters: subscriber (Object) – instance of an object subscribing to the device

switchConnection(address)¶: This method is provided in order to provide the same API as an HCI Device, it actually has no effects.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.hackrf module¶

class mirage.libs.ble_utils.hackrf.BLEHackRFDevice(interface)¶

Bases: mirage.libs.wireless_utils.device.SDRDevice

This device allows to communicate with a HackRF Device in order to interact with Bluetooth Low Energy protocol. HackRF support is experimental, the demodulator is slow and it can only deal with advertisements.

The corresponding interfaces are : hackrfX (e.g. “hackrf0”)

The following capabilities are actually supported :

Capability	Available ?
SCANNING	yes
ADVERTISING	yes
SNIFFING_ADVERTISEMENTS	yes
SNIFFING_NEW_CONNECTION	no
SNIFFING_EXISTING_CONNECTION	no
JAMMING_CONNECTIONS	no
JAMMING_ADVERTISEMENTS	no
INJECTING	no
MITMING_EXISTING_CONNECTION	no
HIJACKING_MASTER	no
HIJACKING_SLAVE	no
INITIATING_CONNECTION	no
RECEIVING_CONNECTION	no
COMMUNICATING_AS_MASTER	no
COMMUNICATING_AS_SLAVE	no
HCI_MONITORING	no

SDR_PARAMETERS = {'BANDWIDTH': (['source', 'sink'], 'setBandwidth', <class 'int'>), 'EXPERIMENTAL_DEMODULATOR': (['device'], 'setExperimentalDemodulator', <function booleanArg>), 'FREQUENCY': (['source', 'sink'], 'setFrequency', <class 'int'>), 'GAIN': (['source'], 'setGain', <class 'int'>), 'LNA_GAIN': (['source'], 'setLNAGain', <class 'int'>), 'SAMPLE_RATE': (['source', 'sink'], 'setSampleRate', <class 'int'>), 'TX_GAIN': (['sink'], 'setTXGain', <class 'int'>)}¶

applySDRConfig()¶: This method applies the SDR-related configuration.

buildReceivePipeline(interface)¶

This method allows to build the receive pipeline of the current device.

Parameters: interface (str) – string indicating the interface to use
Returns: receive pipeline instance
Return type: SDRPipeline

buildTransmitPipeline(interface)¶

This method allows to build the transmit pipeline of the current device.

Parameters: interface (str) – string indicating the interface to use
Returns: transmit pipeline instance
Return type: SDRPipeline

close()¶: This method closes the device.

classmethod get(interface)¶: This class method implements the Register device pattern. According to the interface parameter, only one instance of a given specific device will be instanciated if multiple Emitters and/or Receivers tries to access it.

getAPIVersion()¶

This method returns the API version of the HackRF library.

Returns

API version as a tuple of (major, minor)

Return type

tuple of (int,int)

Example

>>> device.getAPIVersion()
(1, 4)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getAddress()¶

This method returns the actual BD address of the device.

Returns

str indicating the BD address

Return type

str

Example

>>> device.getAddress()
'1A:2B:3C:4D:5E:6F'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getBoardID()¶

This method returns the board identifier of the current HackRF.

Returns

board identifier

Return type

int

Example

>>> device.getBoardID()
2

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getBoardName()¶

This method returns the board name of the current HackRF.

Returns

board name

Return type

str

Example

>>> device.getBoardName()
'HackRF One'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()¶

This method returns the channel actually in use.

Returns

channel in use

Return type

int

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()¶

This method returns the device index of the current HackRF.

Returns

device index

Return type

int

Example

>>> device.getDeviceIndex()
0

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getFirmwareVersion()¶

This method returns the firmware version of the current HackRF device.

Returns

firmware version

Return type

str

Example

>>> device.getFirmwareVersion()
'git-a9945ff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSerial()¶

This method returns the serial number of the current HackRF device.

Returns

serial number

Return type

str

Example

>>> device.getSerialNumber()
'0000000000000000a06063c8234e925f'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

hasCapabilities(*capability)¶

This method allows to check if the device implements some specific capabilities.

Parameters

*capability (str (multiple)) – capabilities to check

Returns

boolean indicating if the device implements the capabilities provided

Return type

bool

Example

>>> device.capabilities = ["SNIFFING", "INJECTING", "CHANGING_ADDRESS"]
>>> device.hasCapabilities("SNIFFING", "INJECTING")
True
>>> device.hasCapabilities("MAKING_COFFEE")
False

init()¶: This method initializes the device.

instances = {}¶

isConnected()¶

This method returns a boolean indicating if the device is connected.

Returns: boolean indicating if the device is connected
Return type: bool

Warning

This method always returns False, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()¶

This method allows to check if the device is initialized and available for use.

Returns: boolean indicating if the device is up
Return type: bool

publish(event, *args, **kwargs)¶

This method allows to publish an event. It may be used to call from the device a method implemented on the corresponding Emitters / Receivers, subscribers by default.

Parameters

event (str) – method’s name to call

Example

>>> device.publish("stop")

recv()¶

This method receives some datas. If no data is available, this method returns None.

Parameters: data – raw representation of the received data

send(packet)¶

This method sends some datas.

Parameters: data – raw representation of the data to send

setAddress(address, random=False)¶

This method allows to modify the BD address and the BD address type of the device, if it is possible.

Parameters

address (str) – new BD address
random (bool) – boolean indicating if the address is random

Returns

boolean indicating if the operation was successful

Return type

bool

Example

>>> hackrfDevice.setAddress("11:22:33:44:55:66")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setAdvertising(enable=True)¶

This method enables or disables the advertising mode.

Parameters

enable (bool) – boolean indicating if the advertising mode must be enabled

Example

>>> device.setAdvertising(enable=True) # advertising mode enabled
>>> device.setAdvertising(enable=False) # advertising mode disabled

Warning

Please note that if no advertising and scanning data has been provided before this function call, nothing will be advertised. You have to set the scanning Parameters and the advertising Parameters before calling this method.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setAdvertisingParameters(type='ADV_IND', destAddr='00:00:00:00:00:00', data=b'', intervalMin=200, intervalMax=210, daType='public', oaType='public')¶

This method sets advertising parameters according to the data provided. It will mainly be used by ADV_IND-like packets.

Parameters

type (str) – type of advertisement (available values : “ADV_IND”, “ADV_DIRECT_IND”, “ADV_SCAN_IND”, “ADV_NONCONN_IND”, “ADV_DIRECT_IND_LOW”)
destAddress (str) – destination address (it will be used if needed)
data (bytes) – data included in the payload
intervalMin (int) – minimal interval
intervalMax (int) – maximal interval
daType (str) – string indicating the destination address type (“public” or “random”)
oaType – string indicating the origin address type (“public” or “random”)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setChannel(channel)¶

This method changes the channel actually in use by the provided channel.

Parameters

channel (int) – new channel

Example

>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setExperimentalDemodulator(enable=True)¶

setScan(enable=True)¶

This method enables or disables the scanning mode. It allows to change the channel according to the scan interval parameter.

Parameters

enable (bool) – boolean indicating if the scanning mode must be enabled

Example

>>> device.setScan(enable=True) # scanning mode enabled
>>> device.setScan(enable=False) # scanning mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanInterval(seconds=1)¶

This method allows to provide the scan interval (in second).

Parameters

seconds (float) – number of seconds to wait between two channels

Example

>>> device.setScanInterval(seconds=1)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanningParameters(data)¶

This method sets scanning parameters according to the data provided. It will mainly be used by SCAN_RESP packets.

Parameters: data (bytes) – data to use in SCAN_RESP

Warning

This method does nothing, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['getChannel', 'setChannel', 'isConnected', 'setAddress', 'getAddress', 'sniffAdvertisements', 'setAdvertising', 'setAdvertisingParameters', 'setScanningParameters', 'setScan', 'setScanInterval', 'getMode', 'getFirmwareVersion', 'getSerial', 'getAPIVersion', 'getDeviceIndex', 'getBoardName', 'getBoardID']¶

sniffAdvertisements(address='FF:FF:FF:FF:FF:FF', channel=None)¶

This method starts the advertisement sniffing mode.

Parameters

address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)
channel (int) – selected channel - if not provided, channel 37 is selected

Example

>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

subscribe(subscriber)¶

This method allows to register a subscriber, according to the design pattern named Publish/subscribe. It allows a Device to call a method of the corresponding Emitter / Receiver, subscribers by default.

Parameters: subscriber (Object) – instance of an object subscribing to the device

updateSDRConfig(sdrConfig)¶

This method updates the SDR-related configuration. The supported parameters are:

GAIN: Receive (RX) Gain (integer value)
TX_GAIN: Tranmit (TX) Gain (integer value)
LNA_GAIN: Low Noise Amplifier (LNA) Gain (integer value)
FREQUENCY: Frequency (integer value)
BANDWIDTH: Bandwidth (integer value)
SAMPLE_RATE: Sample Rate (integer value)
EXPERIMENTAL_DEMODULATOR: Use the experimental demodulator if available (boolean value)

Parameters: sdrConfig (dict) – dictionary describing the SDR parameters name and their value as string

mirage.libs.ble_utils.decoders module¶

class mirage.libs.ble_utils.decoders.BLEDecoder(samplesPerSymbol=1, samplesBefore=60, samplesAfter=60, crcChecking=True, channel=37, crcInit=5592405)¶

Bases: mirage.libs.common.sdr.decoders.SDRDecoder

Software Defined Radio decoder for Bluetooth Low Energy protocol.

decode(demodulatedData, iqSamples)¶

This method implements the BLE decoding process and transforms a binary string into a BLE packet.

Parameters

demodulatedData (str) – data to decode
iqSamples (list of complex) – IQ samples corresponding with the demodulated data

Returns

tuple composed of the decoded data and the correspond IQ samples

Return type

(bytes, list of complex)

setCRCChecking(enable=True)¶

This method enables CRC checking.

Parameters

enable (bool) – indicates if the CRC checking should be enabled or disabled

Example

>>> decoder.setCRCChecking(True)

setChannel(channel)¶

This method sets the channel used by the dewhitening algorithm.

Parameters

channel (int) – channel to use

Example

>>> decoder.setChannel(37)

mirage.libs.ble_utils.encoders module¶

class mirage.libs.ble_utils.encoders.BLEEncoder(channel=37, crcInit=5592405)¶

Bases: mirage.libs.common.sdr.encoders.SDREncoder

Software Defined Radio encoder for Bluetooth Low Energy protocol.

encode(data)¶

This method implements the encoding process and transforms a sequence of bytes into a binary string.

Parameters: data (bytes) – data to encode
Returns: binary string
Return type: str

setChannel(channel)¶

This method sets the channel used by the dewhitening algorithm.

Parameters

channel (int) – channel to use

Example

>>> decoder.setChannel(37)

mirage.libs.ble_utils.crypto module¶

class mirage.libs.ble_utils.crypto.BLECrypto¶

Bases: object

This class provides some cryptographic functions used by the Security Manager.

Note

The temporaryKeys class attribute is used in order to precalculate the possible temporary keys. It allows to avoid some time consuming calculations during the cracking process.

classmethod c1(key, rand, payloadRequest, payloadResponse, initiatorAddressType, initiatorAddress, responderAddressType, responderAddress)¶

This class method implements the confirm value generation function \(C1\)

Parameters

key (bytes) – encryption key
rand (bytes) – random value
payloadRequest (bytes) – request’s payload
payloadResponse (bytes) – response’s payload
initiatorAddressType (bytes) – initiator address type (format : b”" if type is public or b”” if it is random)
initiatorAddress (str) – initiator address (format : “A1:B2:C3:D4:E5:F6”)
responderAddressType (bytes) – responder address type (format : b”" if type is public or b”” if it is random)
responderAddress (str) – responder address (format : “A1:B2:C3:D4:E5:F6”)

Returns

generated confirm value

Return type

bytes

See also

This function is described in Bluetooth Core Specification, [Vol 3] Part H, Section 2.2.3.

classmethod c1m1(key, confirm, payloadRequest, payloadResponse, initiatorAddressType, initiatorAddress, responderAddressType, responderAddress)¶

This class method implements the inverse function \(C1_{-1}\) of the confirm value generation function \(C1\)

Parameters

key (bytes) – encryption key
confirm (bytes) – confirm value
payloadRequest (bytes) – request’s payload
payloadResponse (bytes) – response’s payload
initiatorAddressType (bytes) – initiator address type (format : b”" if type is public or b”” if it is random)
initiatorAddress (str) – initiator address (format : “A1:B2:C3:D4:E5:F6”)
responderAddressType (bytes) – responder address type (format : b”" if type is public or b”” if it is random)
responderAddress (str) – responder address (format : “A1:B2:C3:D4:E5:F6”)

Returns

corresponding random value

Return type

bytes

See also

This function is described in Bluetooth Core Specification, [Vol 3] Part H, Section 2.2.3.

classmethod crackTemporaryKey(r, preq, pres, iat, initiatorAddress, rat, responderAddress, confirm)¶

This class method allows to crack a temporary key, according to multiple parameters extracted during the pairing process. It returns the corresponding PIN code.

Parameters

r (bytes) – random value
preq (bytes) – pairing request’s payload
pres (bytes) – pairing response’s payload
iat (bytes) – initiator address type
initiatorAddress (str) – initiator address (format : “1A:2B:3C:4D:5E:6F”)
rat (bytes) – responder address type
responderAddress (str) – responder address (format : “1A:2B:3C:4D:5E:6F”)
confirm (bytes) – confirm value

Returns

corresponding PIN code

Return type

int

Example

>>> random = bytes.fromhex("abb692ebfd4601f4aad3aea40f7da5fc")[::-1]
>>> pairingRequest = bytes.fromhex("01030005100001")[::-1]
>>> pairingResponse = bytes.fromhex("02000005100001")[::-1]
>>> initiatorAddress = "08:3E:8E:E1:0B:3E"
>>> initiatorAddressType = b""
>>> responderAddress = "78:C5:E5:6E:DD:E8"
>>> responderAddressType = b""
>>> confirm = bytes.fromhex("febb983ed78020e13d685bc8418d2c5d")[::-1]
>>> BLECrypto.crackTemporaryKey(random,pairingRequest,pairingResponse, initiatorAddressType,initiatorAddress,responderAddressType,responderAddress,confirm)
0

Warning

This method uses multi processes in order to optimize the time consumption of the required operation.

classmethod e(key, plaintext)¶

This class method implements the security function \(E\)

Parameters

key (bytes) – encryption key
plaintext (bytes) – plain text data

Returns

encrypted data

Return type

bytes

See also

This function is described in Bluetooth Core Specification, [Vol 3] Part H, Section 2.2.1.

classmethod em1(key, ciphertext)¶

This class method implements the inverse function \(E_{-1}\) of the security function \(E\)

Parameters

key (bytes) – encryption key
ciphertext (bytes) – encrypted data

Returns

decrypted data

Return type

bytes

See also

This function is described in Bluetooth Core Specification, [Vol 3] Part H, Section 2.2.1.

classmethod generateRandom(size=16)¶

This class method allows to easily generate a random value, according to the size (number of bytes) provided.

Parameters

size (int) – number of bytes of the random value

Returns

random list of bytes

Return type

bytes

Example

>>> BLECrypto.generateRandom().hex()
'd05c872faaef8bc959b801e4c30c0afa'
>>> BLECrypto.generateRandom(3).hex()
'e7bbc9'

classmethod s1(key, randMaster, randSlave)¶

This class method implements the key generation function \(S1\)

Parameters

key (bytes) – encryption key
randMaster (bytes) – master’s random value
randSlave (bytes) – slave’s random value

Returns

generated key

Return type

bytes

See also

This function is described in Bluetooth Core Specification, [Vol 3] Part H, Section 2.2.4.

classmethod xor128(a1, b1)¶

This class method implements the XOR operation applied to 128 bits bytes strings.

Parameters

a1 (bytes) – first value
b1 (bytes) – second value

Returns

result

Return type

bytes

class mirage.libs.ble_utils.crypto.BLELinkLayerCrypto(ltk)¶

Bases: object

This class provides an API allowing to manipulate the Link Layer Cryptographic functions used by Bluetooth Low Energy.

Warning

This class is used by the receiver BLEReceiver (mirage.libs.ble.BLEReceiver) and should not be used directly by an user.

decrypt(payload, masterToSlave=True)¶

This method decrypts the provided payload, according to the direction provided.

Parameters

payload (bytes) – payload to decrypt
masterToSlave (bool) – boolean indicating if the direction is “master to slave”

Returns

tuple composed of (two first bytes of the payload + decrypted payload, boolean indicating if the message’s integrity is valid)

Return type

tuple of (bytes,bool)

displayDetails()¶: This method displays a chart indicating the session keys’ diversifier, the initializations vectors and the session key. If some values have not been provided or calculated, it displays an error message.

encrypt(payload, masterToSlave=True)¶

This method encrypts the provided payload, according to the direction provided.

Parameters

payload (bytes) – payload to encrypt
masterToSlave (bool) – boolean indicating if the direction is “master to slave”

Returns

first two bytes of the payload + ciphertext + message integrity check

Return type

bytes

generateIv()¶: This method generates the initialization vector according to the provided master’s and slave’s IV.

generateNonce(masterToSlave)¶

This method generates a nonce.

Parameters: masterToSlave (bool) – boolean indicating if the direction is “master to slave”
Returns: generated nonce
Return type: bytes

generateSessionKey()¶: This method generates the session key according to the calculted session key diversifier and initialization vector.

generateSkd()¶: This method generates the session key diversifier according to the provided master’s and slave’s diversifier.

classmethod getInstance()¶

This class method returns the singleton’s instance of the current class.

Returns: instance of this class
Return type: BLELinkLayerCrypto

incrementMasterCounter()¶: This method increments the master’s counter.

incrementSlaveCounter()¶: This method increments the slave’s counter.

classmethod provideLTK(ltk)¶

This class method initializes a singleton’s instance of the current class. It allows to provide a Long Term Key.

Parameters: ltk (bytes) – Long Term Key

setMasterValues(skd, iv)¶

This method allows to provide the session key diversifier and the initialization vector from Master.

Parameters

skd (bytes) – session key diversifier
iv (bytes) – initialization vector

setSlaveValues(skd, iv)¶

This method allows to provide the session key diversifier and the initialization vector from Slave.

Parameters

skd (bytes) – session key diversifier
iv (bytes) – initialization vector

tryToDecrypt(payload)¶

This function tries to decrypt a payload. It tries to guess the direction (master to slave or slave to master) and the right counters’ values.

Parameters: payload (bytes) – payload to decrypt
Returns: tuple composed of (decrypted payload, boolean indicating if the operation was successful)
Return type: tuple of (bytes,bool)

Note

If the operation fails, the decrypted payload field of the tuple is replaced by None

mirage.libs.ble_utils.att_server module¶

class mirage.libs.ble_utils.att_server.ATT_Attribute(handle=None, value=None, type=None, permissions=None)¶

Bases: object

This class describes an ATT attribute. An ATT attribute is composed of four main fields :

handle : ATT handle (it can be described as the index of an attribute of an ATT Database)

value : binary value linked to this attribute

type : UUID (12 bits or 128 bits) indicating the type of attribute, such as a Device Name or a Characteristic Declaration.

permissions : flag indicating the access permissions attached to this attribute, such as readable or writeable.

It overloads the method __str__ in order to provide a pretty representation.

class mirage.libs.ble_utils.att_server.ATT_Database¶

Bases: object

This class describes an ATT Database. It acts as a classic Database, and offer multiple primitives in order to manipulate the attributes. The internal representation is just a list containing some ATT_Attribute.

findByTypeValue(start, end, type, value)¶

This method allows to read a set of groups of attributes according to the handles, type and value provided.

Parameters

start (int) – start handle
end (int) – end handle
type (int or str) – type of attributes
value (bytes) – value of attributes

Returns

list of attributes (represented as a dictionary of two fields : attributeHandle and endGroupHandle)

Return type

list of dict

findInformation(start, end)¶

This method allows to get a set of attributes’ types according to the handles provided.

Parameters

start (int) – start handle
end (int) – end handle

Returns

list of attributes’ types (represented as a dictionary of two fields : attributeHandle and type)

Return type

list of dict

Example

>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=2, value=b"", type="Secondary Service",permissions=["Read"])
>>> db.setAttribute(handle=3, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=4, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=5, value=b"", type="Secondary Service",permissions=["Read"])
>>> db.findInformation(2,5)
[{'attributeHandle': 2, 'type': b'('}, {'attributeHandle': 3, 'type': b'('}, {'attributeHandle': 4, 'type': b'('}, {'attributeHandle': 5, 'type': b'('}]
>>> db.findInformation(1,3)
[{'attributeHandle': 1, 'type': b'('}, {'attributeHandle': 2, 'type': b'('}, {'attributeHandle': 3, 'type': b'('}]

getNextHandle()¶

This method returns the next free handle.

Returns

next free handle

Return type

int

Example

>>> db.getNextHandle()
25

read(handle)¶

This method allows to read the value of a given attribute according to the provided handle.

Parameters

handle (int) – handle of the attribute

Returns

tuple composed of a boolean indicating if the attribute exists, another one indicating if it is readable and the value if possible

Return type

tuple of (bool,bool,bytes)

Example

>>> db = ATT_Database()
>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=2, value=b"*", type=0x2803,permissions=b"")
>>> db.read(1)
(True, True, b'')
>>> db.read(2)
(True, False, None)
>>> db.read(3)
(False, False, None)

readByGroupType(start, end, type)¶

This method allows to read a set of groups of attributes according to the handles and type provided.

Parameters

start (int) – start handle
end (int) – end handle
type (int or str) – type of attributes

Returns

list of attributes (represented as a dictionary of three fields : attributeHandle,*endGroupHandle* and value)

Return type

list of dict

readByType(start, end, type)¶

This method allows to read a set of attributes according to the handles and type provided.

Parameters

start (int) – start handle
end (int) – end handle
type (int or str) – type of attributes

Returns

list of attributes (represented as a dictionary of two fields : attributeHandle and value)

Return type

list of dict

Example

>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=2, value=b"", type="Secondary Service",permissions=["Read"])
>>> db.setAttribute(handle=3, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=4, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=5, value=b"", type="Secondary Service",permissions=["Read"])
>>> db.readByType(start=1,end=3,type="Primary Service")
[{'attributeHandle': 1, 'value': b''}, {'attributeHandle': 3, 'value': b''}]
>>> db.readByType(start=2,end=5,type=0x2801)
[{'attributeHandle': 2, 'value': b''}, {'attributeHandle': 5, 'value': b''}]

setAttribute(handle=None, value=None, type=None, permissions=None)¶

This method allows to add or modify an ATT attribute in the ATT Database.

Parameters

handle (int) – handle of the attribute
value (bytes) – value of the attribute
type (int or str) – type of the attribute
permissions (int or list of str) – permissions of the attribute

Example

>>> db = ATT_Database()
>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=2, value=b"*", type=0x2803,permissions=b"")
>>> db.show()
┌Attributes────────┬────────────────────────────────────────────┬────────────────────────────────────────┐
│ Attribute Handle │ Attribute Type                             │ Attribute Value                        │
├──────────────────┼────────────────────────────────────────────┼────────────────────────────────────────┤
│ 0x0001           │ Primary Service                            │ 0018                                   │
│ 0x0002           │ Characteristic Declaration                 │ 020300002a                             │
└──────────────────┴────────────────────────────────────────────┴────────────────────────────────────────┘
>>> db.setAttribute(handle=1,value=b"",type="Primary Service",permissions=["Read"])
>>> db.show()
┌Attributes────────┬────────────────────────────────────────────┬────────────────────────────────────────┐
│ Attribute Handle │ Attribute Type                             │ Attribute Value                        │
├──────────────────┼────────────────────────────────────────────┼────────────────────────────────────────┤
│ 0x0001           │ Primary Service                            │ 0118                                   │
│ 0x0002           │ Characteristic Declaration                 │ 020300002a                             │
└──────────────────┴────────────────────────────────────────────┴────────────────────────────────────────┘

show()¶: This method displays a chart to present the ATT level vision of the attributes included in the Database.

showCharacteristics(startHandle, endHandle, title='Characteristics')¶

This method displays the GATT characteristics described as attributes included in the Database and provide a mechanism to only select the characteristics between two handles (it is mainly used in order to print the characteristics included in a Service).

Parameters

startHandle (int) – first ATT handle
endHandle (int) – last ATT handle
title (str) – Title of the chart

showGATT()¶: This method displays a chart to present the GATT level vision of the attributes included in the Database.

showServices()¶: This method displays the GATT services described as attributes included in the Database.

write(handle, value)¶

This method allows to write a new value in a given attribute according to the provided handle.

Parameters

handle (int) – handle of the attribute
value (bytes) – new value to write

Returns

tuple composed of a boolean indicating if the attribute exists and another one indicating if it is writeable

Return type

tuple of (bool,bool)

Example

>>> db = ATT_Database()
>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=2, value=b"*", type=0x2803,permissions=b"")
>>> db.write(handle=1,value=b"")
(True, False)
>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read","Write"])
>>> db.write(handle=1,value=b"")
(True, True)
>>> db.read(1)
(True, True, b'')

class mirage.libs.ble_utils.att_server.ATT_Server(database=None, mtu=23)¶

Bases: object

This class is a partial implementation of an ATT Server. The methods provided describe the corresponding requests, and the return value describe the response.

This class uses the ATT_Database class in order to represent the data structure.

addAttribute(handle=None, value=None, type=None, permissions=None)¶

This method allows to add a new attribute to the ATT Server’s database.

Parameters

handle (int) – handle of the attribute
value (bytes) – value of the attribute
type (int or str) – type of the attribute
permissions (int or list of str) – permissions of the attribute

findInformation(start, end)¶

This method implements the Find Information Request.

Parameters

start (int) – start handle included in the Find Information Request
end (int) – end handle included in the Find Information Request

Returns

tuple

Return type

tuple of (bool,list of dict)

Note

The returned tuple is composed of two main fields :

success : this field is a boolean indicating if the request was successful or not

body : this field is the response’s body (list of dict - see output of ATT_Database.findInformation) if the request was successful or an error code (int) if the request was not successful

read(handle)¶

This method implements the Read Request.

Parameters: handle (int) – handle included in the Read Request
Returns: tuple
Return type: tuple of (bool,bytes or int)

Note

The returned tuple is composed of two main fields :

success : this field is a boolean indicating if the request was successful or not

body : this field is the response’s body (array of bytes) if the request was successful or the error code (integer) if the request was not successful

readBlob(handle, offset)¶

This method implements the Read Blob Request.

Parameters: handle (int) – handle included in the Read Blob Request
Returns: tuple
Return type: tuple of (bool,bytes or int)

Note

The returned tuple is composed of two main fields :

success : this field is a boolean indicating if the request was successful or not

body : this field is the response’s body (array of bytes) if the request was successful or the error code (integer) if the request was not successful

readByGroupType(start, end, type)¶

This method implements the Read By Group Type Request.

Parameters

start (int) – start handle included in the Read By Group Type Request
end (int) – end handle included in the Read By Group Type Request
type (bytes or int) – type included in the Read By Group Type Request

Returns

tuple

Return type

tuple of (bool,list of dict)

Note

The returned tuple is composed of two main fields :

success : this field is a boolean indicating if the request was successful or not

body : this field is the response’s body (list of dict - see output of ATT_Database.readByGroupType) if the request was successful or an error code (int) if the request was not successful

readByType(start, end, type)¶

This method implements the Read By Type Request.

Parameters

start (int) – start handle included in the Read By Type Request
end (int) – end handle included in the Read By Type Request
type (bytes or int) – type included in the Read By Type Request

Returns

tuple

Return type

tuple of (bool,list of dict)

Note

The returned tuple is composed of two main fields :

success : this field is a boolean indicating if the request was successful or not

body : this field is the response’s body (list of dict - see output of ATT_Database.readByType) if the request was successful or an error code (int) if the request was not successful

setMtu(mtu)¶

This method allows to set a new MTU Value.

Parameters

mtu (int) – value of Maximum Transfer Unit

Example

>>> server = ATT_Server()
>>> server.setMtu(48)

writeCommand(handle, value)¶

This method implements the Write Command.

Parameters

handle (int) – handle included in the Write Command
value (bytes) – value included in the Write Command

Returns

tuple

Return type

tuple of (bool,None)

Note

The returned tuple is composed of two main fields :

success : this field is a boolean indicating if the request was successful or not

body : this field is the response’s body (None)

writeRequest(handle, value)¶

This method implements the Write Request.

Parameters

handle (int) – handle included in the Write Request
value (bytes) – value included in the Write Request

Returns

tuple

Return type

tuple of (bool,int)

Note

The returned tuple is composed of two main fields :

success : this field is a boolean indicating if the request was successful or not

body : this field is the error code (int) if the request was not successful

class mirage.libs.ble_utils.att_server.GATT_Server(database=None, mtu=23)¶

Bases: mirage.libs.ble_utils.att_server.ATT_Server

This class inherits from ATT_Server, and provides some GATT level methods in order to easily manipulate GATT layer.

addCharacteristic(uuid, value=b'', declarationHandle=None, valueHandle=None, permissions=['Read', 'Write'])¶

This method allows to easily add a new characteristic.

Parameters

uuid (bytes) – uuid associated to the characteristic
value (bytes) – value of the characteristic
declarationHandle (int) – declaration handle of the characteristic
valueHandle (int) – value handle of the characteristic
permissions (list of str) – permissions associated to the characteristic

Note

If no declaration handle is provided, the characteristic declaration is stored as the next available handle. If no value handle is provided, the characteristic value is stored as declaration handle + 1 If no permissions are provided, the characteristic value is stored with “Read” & “Write” permission.

addDescriptor(uuid, value=b'', handle=None, permissions=['Read', 'Write', 'Notify'])¶

This method allows to easily add a new descriptor.

Parameters

uuid (bytes) – uuid associated to the descriptor
value (bytes) – value of the descriptor
handle (int) – handle of the descriptor

Note

If no handle is provided, the descriptor is stored as the next available handle. If no permissions are provided, the descriptor is stored with “Read”,”Write” and “Notify” permission.

addPrimaryService(uuid, handle=None, permissions=['Read'])¶

This method allows to easily add a new primary service.

Parameters

uuid (bytes) – value stored in the service (associated UUID)
handle (int) – start handle of the service
permissions (list of str) – permissions associated to the service

Note

If no handle is provided, the service is stored as the next available handle. If no permissions are provided, the service is stored with “Read” permission.

addSecondaryService(uuid, handle=None, permissions=['Read'])¶

This method allows to easily add a new secondary service.

Parameters

uuid (bytes) – value stored in the service (associated UUID)
handle (int) – start handle of the service
permissions (list of str) – permissions associated to the service

Note

If no handle is provided, the service is stored as the next available handle. If no permissions are provided, the service is stored with “Read” permission.

mirage.libs.ble_utils.dissectors module¶

class mirage.libs.ble_utils.dissectors.AuthReqFlag(data=b'', length=- 1, content={}, *args, **kwargs)¶

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the Authentication Request Flag (Security Manager). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :

bonding field : boolean indicating if bonding is required
mitm field : boolean indicating if MiTM protection is required
secureConnections field : boolean indicating if a secure connection is required
keypress field : boolean indicating if the keypress mode is required
ct2 field : boolean indicating if ct2 is required

Example

>>> AuthReqFlag(bonding=True, mitm=True).data.hex()
'05'
>>> AuthReqFlag(data=data=bytes.fromhex("05"))
AuthReq Flag(0x5,bonding:yes|mitm:yes|secureConnections:no|keypress:no|ct2:no)

build()¶

This method converts the raw bytes to the corresponding data structure.

Example

>>> dissector.build()

dissect()¶

This method converts the data structure to the corresponding raw bytes.

Example

>>> dissector.dissect()

class mirage.libs.ble_utils.dissectors.CharacteristicDeclaration(data=b'', length=- 1, content={}, *args, **kwargs)¶

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the characteristic declarations (GATT). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :

UUID field : characteristic’s UUID (see also the following dissector : UUID)
permissions field : characteristic’s Permissions Flag (see also the following dissector : PermissionsFlag)
valueHandle field : characteristic’s value handle

Example

>>> CharacteristicDeclaration(data=bytes.fromhex('2a00000302'))
Characteristic Declaration( UUID=UUID(128bits:00002a00-0000-1000-8000-00805f9b34fb, 16bits:0x2a00, name:Device Name ) , valueHandle=0x3 , permissionsFlag=Flag(Read))
>>> CharacteristicDeclaration(data=bytes.fromhex('2a00000302')).UUID
UUID(128bits:00002a00-0000-1000-8000-00805f9b34fb, 16bits:0x2a00, name:Device Name )
>>> CharacteristicDeclaration(data=bytes.fromhex('2a00000302')).valueHandle
3
>>> CharacteristicDeclaration(data=bytes.fromhex('2a00000302')).permissionsFlag
Flag(Read)
>>> CharacteristicDeclaration(UUID=UUID(name="Device Name"),valueHandle=0x0003,permissionsFlag=PermissionsFlag(permissions=["Read"])).data.hex()
'2a00000302'

build()¶

This method converts the raw bytes to the corresponding data structure.

Example

>>> dissector.build()

dissect()¶

This method converts the data structure to the corresponding raw bytes.

Example

>>> dissector.dissect()

class mirage.libs.ble_utils.dissectors.CharacteristicDescriptor(data=b'', length=- 1, content={}, *args, **kwargs)¶

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the characteristic descriptors (GATT). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :

UUID field : descriptor’s UUID (see also the following dissector : UUID)

Example

>>> CharacteristicDescriptor(data=bytes.fromhex("2901"))
Characteristic Descriptor( UUID=UUID(128bits:00002901-0000-1000-8000-00805f9b34fb, 16bits:0x2901, name:Characteristic User Description ) )
>>> CharacteristicDescriptor(UUID=UUID(UUID16=0x2901)).data.hex()
'2901'

build()¶

This method converts the raw bytes to the corresponding data structure.

Example

>>> dissector.build()

dissect()¶

This method converts the data structure to the corresponding raw bytes.

Example

>>> dissector.dissect()

class mirage.libs.ble_utils.dissectors.HIDoverGATTKeystroke(data=b'', length=- 1, content={}, *args, **kwargs)¶

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the HID over GATT keystroke payload. It inherits from Dissector.

The following fields are available in the data structure :

locale : string indicating the locale (language layout)
key : string indicating the key
ctrl : boolean indicating if the Ctrl key is pressed
alt : boolean indicating if the Alt key is pressed
super : boolean indicating if the Super key is pressed
shift : boolean indicating if the Shift key is pressed

Example

>>> HIDoverGATTKeystroke(locale="fr",key="a",ctrl=False,gui=False,alt=False,shift=False)
Keystroke(key=a,ctrl=no,alt=no,shift=no,gui=no)
>>> HIDoverGATTKeystroke(locale="fr",key="a",ctrl=False,gui=False,alt=False,shift=False).data.hex()
'0000140000000000'

build()¶

This method converts the raw bytes to the corresponding data structure.

Example

>>> dissector.build()

dissect()¶

This method converts the data structure to the corresponding raw bytes.

Example

>>> dissector.dissect()

class mirage.libs.ble_utils.dissectors.InputOutputCapability(data=b'', length=- 1, content={}, *args, **kwargs)¶

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the Input Output Capability (Security Manager). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :

display field : boolean indicating if the device provides a display output
yesno field : boolean indicating if the device has yes/no input
keyboard field : boolean indicating if the device has a keyboard input

Example

>>> InputOutputCapability(display=True, yesno=False, keyboard=True).data.hex()
'04'
>>> InputOutputCapability(data=data=bytes.fromhex("04"))
Input Output Capability(0x4,keyboard:yes|yesno:no|display:yes)

build()¶

This method converts the raw bytes to the corresponding data structure.

Example

>>> dissector.build()

dissect()¶

This method converts the data structure to the corresponding raw bytes.

Example

>>> dissector.dissect()

class mirage.libs.ble_utils.dissectors.KeyDistributionFlag(data=b'', length=- 1, content={}, *args, **kwargs)¶

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the Key Distribution Flag (Security Manager). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :

encKey field : boolean indicating if an encryption key is required (LTK + Ediv + RAND)
idKey field : boolean indicating if an identification key is required (IRK + BD_Addr + BD_Addr mode)
signKey field : boolean indicating if a signing key is required (CSRK)
linkKey field : boolean indicating if a link key is required

Example

>>> KeyDistributionFlag(idKey=True,encKey=True).data.hex()
'03'
>>> KeyDistributionFlag(data=bytes.fromhex("03"))
Key Distribution Flag(0x3,encKey:yes|idKey:yes|signKey:no|linkKey:no)

build()¶

This method converts the raw bytes to the corresponding data structure.

Example

>>> dissector.build()

dissect()¶

This method converts the data structure to the corresponding raw bytes.

Example

>>> dissector.dissect()

class mirage.libs.ble_utils.dissectors.PermissionsFlag(data=b'', length=- 1, content={}, *args, **kwargs)¶

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the permissions flag (ATT/GATT). It inherits from Dissector.

The following fields are available in the data structure :

permissions : field indicating permissions as a list of strings (ex : [‘Write Without Response’, ‘Read’])

The following permissions can be used :

“Extended Properties”
“Authenticated Signed Writes”
“Indicate”
“Notify”
“Write”
“Write Without Response”
“Read”
“Broadcast”

Example

>>> dissector=PermissionsFlag(permissions=["Write", "Read"])
>>> dissector.data.hex()
'0a'
>>> dissector2=PermissionsFlag(data=bytes.fromhex("0a"))
>>> dissector2.permissions
['Write', 'Read']
>>> for permission in dissector2:
...     print(permission)
...
Write
Read
>>> dissector2.permissions += ["Write Without Response"]
>>> dissector2.data.hex()
'0e'
>>> dissector.data = bytes.fromhex("0e")
>>> dissector.dissect()
>>> dissector.permissions
['Write', 'Write Without Response', 'Read']

build()¶

This method converts the raw bytes to the corresponding data structure.

Example

>>> dissector.build()

dissect()¶

This method converts the data structure to the corresponding raw bytes.

Example

>>> dissector.dissect()

class mirage.libs.ble_utils.dissectors.Service(data=b'', length=- 1, content={}, *args, **kwargs)¶

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the services (GATT). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :

UUID field : descriptor’s UUID (see also the following dissector : UUID)

Example

>>> Service(data=bytes.fromhex("1800"))
Service( UUID=UUID(128bits:00001800-0000-1000-8000-00805f9b34fb, 16bits:0x1800, name:Generic Access ) )
>>> Service(data=bytes.fromhex("1800")).UUID
UUID(128bits:00001800-0000-1000-8000-00805f9b34fb, 16bits:0x1800, name:Generic Access )
>>> Service(UUID=UUID(UUID16=0x1800)).data.hex()
'1800'

build()¶

This method converts the raw bytes to the corresponding data structure.

Example

>>> dissector.build()

dissect()¶

This method converts the data structure to the corresponding raw bytes.

Example

>>> dissector.dissect()

class mirage.libs.ble_utils.dissectors.UUID(data=b'', length=- 1, content={}, *args, **kwargs)¶

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class inherits from Dissector, and allows to quicky and easily use UUID (Universally Unique IDentifier). It provides a way to convert them into their multiple forms.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :

UUID16 field : UUID (16 bits)
UUID128 field : UUID (128 bits)
name field : name

Example

>>> UUID(name="Generic Access").data.hex()
'1800'
>>> UUID(data=bytes.fromhex('1800')).name
'Generic Access'
>>> UUID(data=bytes.fromhex('1800')).UUID16
6144
>>> UUID(data=bytes.fromhex('1800')).UUID128.hex()
'0000180000001000800000805f9b34fb'
>>> UUID(data=bytes.fromhex('1801'))
UUID(128bits:00001801-0000-1000-8000-00805f9b34fb, 16bits:0x1801, name:Generic Attribute )

build()¶

This method converts the raw bytes to the corresponding data structure.

Example

>>> dissector.build()

dissect()¶

This method converts the data structure to the corresponding raw bytes.

Example

>>> dissector.dissect()

mirage.libs.ble_utils.helpers module¶

This module provides some helpers in order to manipulate Bluetooth Low Energy link layer packets.

mirage.libs.ble_utils.helpers.channelToFrequency(channel)¶

This function converts a BLE channel to the corresponding frequency.

Parameters

channel (int) – BLE channel to convert

Returns

corresponding frequency (MHz)

Return type

int

Example

>>> channelToFrequency(37)
2402
>>> channelToFrequency(8)
2420

mirage.libs.ble_utils.helpers.crc24(data, length, init=5592405)¶

This function calculates the 24 bits CRC corresponding to the data provided.

Parameters

data (bytes) – packet’s payload
length (int) – length of data
init (int) – initialization value

Returns

24 bits crc value

Return type

bytes

Example

>>> data=bytes.fromhex("0215110006000461ca0ce41b1e430559ac74e382667051")
>>> crc24(data=data,length=len(data)).hex()
'545d96'

mirage.libs.ble_utils.helpers.dewhiten(data, channel)¶

This function allows to dewhiten a given raw data according to the channel value.

Parameters

data (bytes) – raw data to dewhiten
channel (int) – channel number

Returns

dewhitened data

Return type

bytes

mirage.libs.ble_utils.helpers.frequencyToChannel(frequency)¶

This function converts a frequency to the corresponding BLE channel.

Parameters

frequency (int) – frequency to convert (MHz)

Returns

channel associated to the provided frequency

Return type

int

Example

>>> frequencyToChannel(2420)
8
>>> frequencyToChannel(2402)
37

mirage.libs.ble_utils.helpers.isAccessAddressValid(aa)¶

This function checks if the provided access address is valid.

Parameters

aa (int) – access address to validate

Returns

boolean indicating if the access address provided is valid

Return type

bool

Example

>>> isAccessAddressValid(0x870ac713)
True
>>> isAccessAddressValid(0xcc0bcc1a)
False

mirage.libs.ble_utils.helpers.rssiToDbm(rssi)¶

This function converts a RSSI (Received Signal Strength Indication) to a value in Dbm.

Parameters

rssi (int) – rssi to convert

Returns

corresponding value in Dbm

Return type

float

Example

>>> rssiToDbm(12)
-45.0
>>> rssiToDbm(30)
-28.8

mirage.libs.ble_utils.packets module¶

class mirage.libs.ble_utils.packets.BLEAdvDirectInd(srcAddr='00:00:00:00:00:00', srcAddrType='public', dstAddr='00:00:00:00:00:00', dstAddrType='public')¶

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - ADV_DIRECT_IND

Parameters

srcAddr (str) – BD address of the emitter
dstAddr (str) – BD address of the receiver

Note

This class inherits from BLEAdvertisement.

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEAdvInd(addr='00:00:00:00:00:00', addrType='public', data=b'')¶

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - ADV_IND

Parameters

addr (str) – BD address of the emitter
data (bytes) – bytes indicating the data included in the Advertisement packet

Note

This class inherits from BLEAdvertisement.

class mirage.libs.ble_utils.packets.BLEAdvNonConnInd¶

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - ADV_NONCONN_IND

Note

This class inherits from BLEAdvertisement.

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEAdvScanInd¶

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - ADV_SCAN_IND

Note

This class inherits from BLEAdvertisement.

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEAdvertisement(addr='00:00:00:00:00:00', type='ADV_IND', addrType='public', data=b'', intervalMin=200, intervalMax=210)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Advertisement

Parameters

addr (str) – BD address of the emitter
type (str) – type of Advertisement (“ADV_IND”, “ADV_NONCONN_IND” …)
addrType (str) – type of BD address used by the emitter (“public” or “random”)
data (bytes) – bytes indicating the data included in the Advertisement packet
intervalMin (int) – minimal interval of advertisement
intervalMax (int) – maximal interval of advertisement

Note

Some other classes inherits from this class, allowing to adapt the content of the Packet.

getRawDatas()¶

This method returns the raw data : indeed, some devices provides a scapy representation in the data field, and this method can be used to convert it into a list of bytes.

Example

>>> device.getRawDatas()
b' [...]

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEConnect(dstAddr='00:00:00:00:00:00', srcAddr='00:00:00:00:00:00', type='public', initiatorType='public')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Connect

Parameters

dstAddr (str) – destination BD Address (format: 1A:22:33:44:55:66)
srcAddr (str) – source BD Address (format: 1A:22:33:44:55:66)
type (str) – string indicating if the responder’s address is in public (“public”) or random (“random”) mode.
initiatorType (str) – string indicating if the initiator’s address is in public (“public”) or random (“random”) mode.

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEConnectRequest(srcAddr='00:00:00:00:00:00', dstAddr='00:00:00:00:00:00', srcAddrType='public', dstAddrType='public', accessAddress=2391391958, crcInit=0, winSize=0, winOffset=0, hopInterval=0, latency=0, timeout=0, channelMap=0, SCA=0, hopIncrement=0, data=None)¶

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - SCAN_RSP

Parameters

srcAddr (str) – BD address of the emitter
dstAddr (str) – BD address of the receiver
srcAddrType (str) – type of BD address used by the emitter (“public” or “random”)
dstAddrType (str) – type of BD address used by the receiver (“public” or “random”)
accessAddress (int) – access address associated to the connection
crcInit (int) – CRCInit associated to the connection
winSize (int) – window’s size associated to the connection
winOffset (int) – window’s offset associated to the connection
hopInterval (int) – Hop Interval associated to the connection
latency (int) – latency associated to the connection
timeout (int) – timeout associated to the connection
channelMap (int) – channel Map associated to the connection
SCA (int) – SCA associated to the connection
hopIncrement (int) – Hop increment associated to the connection
data (bytes) – data associated to this advertisement packet

Note

This class inherits from BLEAdvertisement.

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEConnectResponse(dstAddr='00:00:00:00:00:00', srcAddr='00:00:00:00:00:00', type='public', success=True, role='', interval=0)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Connect Response

Parameters

dstAddr (str) – destination BD Address (format: 1A:22:33:44:55:66)
srcAddr (str) – source BD Address (format: 1A:22:33:44:55:66)
type (str) – string indicating if the responder’s address is in public (“public”) or random (“random”) mode.
success (bool) – boolean indicating if the operation was successful
role (str) – string indicating the role (“master” or “slave”) of the initiator
interval (int) – integer indicating the interval

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEConnectionCancel¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Connection Cancel

class mirage.libs.ble_utils.packets.BLEConnectionParameterUpdateRequest(l2capCmdId=0, minInterval=0, maxInterval=0, slaveLatency=0, timeoutMult=0, connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Connection Parameter Update Request

Parameters

l2capCmdId (int) – L2CAP Command Identifier
timeoutMult (int) – timeout Multiplier
slaveLatency (int) – slave Latency
minInterval (int) – minimal Interval
maxInterval (int) – maximal Interval
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEConnectionParameterUpdateRequest(timeoutMult=65535, minInterval=65535, maxInterval=65535, slaveLatency=0))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEConnectionParameterUpdateResponse(l2capCmdId=0, moveResult=0, connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Connection Parameter Update Response

Parameters

l2capCmdId (int) – L2CAP Command Identifier
moveResult (int) – move Result
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEConnectionParameterUpdateResponse(moveResult=0))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEControlPDU(type=None, data=b'')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Control PDU

Parameters

type (str) – string indicating the type of control PDU (“LL_ENC_REQ”, “LL_ENC_RESP” …)
data (bytes) – data associated to the Packet

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEDisconnect(connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Disconnect

Parameters: connectionHandle (int) – connection handle associated to the connection to terminate

class mirage.libs.ble_utils.packets.BLEEmptyPDU¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Empty PDU

class mirage.libs.ble_utils.packets.BLEEncryptedPacket(connectionHandle=- 1, data=b'')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Encrypted Packet This class is an abstraction : it provides a way to solve the problems linked to the encryption. In Mirage, an encrypted packet is just another Mirage Packet, allowing to manipulate it easily.

Parameters

connectionHandle (int) – connection handle of the connection actually established.
data (bytes) – encrypted datas associated to the Packet

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEEncryptionInformation(connectionHandle=- 1, ltk=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Encryption Information

Parameters

connectionHandle (int) – connection handle associated to the connection
ltk (bytes) – Long Term Key

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEErrorResponse(request=0, handle=0, ecode=0, connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Error Request

Parameters

request (int) – Request opcode
handle (int) – ATT handle linked to the error
ecode (int) – error code
connectionHandle (int) – connection handle associated to the connection

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEExchangeMTURequest(mtu=0, connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Exchange MTU Request

Parameters

mtu (float) – float indicating the Maximum transmission unit
connectionHandle – connection handle of the connection actually established.

class mirage.libs.ble_utils.packets.BLEExchangeMTUResponse(mtu=0, connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Exchange MTU Response

Parameters

mtu (float) – float indicating the Maximum transmission unit
connectionHandle – connection handle of the connection actually established.

class mirage.libs.ble_utils.packets.BLEFindByTypeValueRequest(startHandle=0, endHandle=65535, uuid=0, data=b'', connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Find By Type Value Request

Parameters

startHandle (int) – lowest ATT handle included in the request
endHandle (int) – highest ATT handle included in the request
uuid (int) – 2 octet UUID to find
data (bytes) – Attribute value to find
connectionHandle (int) – connection handle associated to the connection

class mirage.libs.ble_utils.packets.BLEFindByTypeValueResponse(handles=[], connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Find By Type Value Response

Parameters

handles (list) – list indicating the handles contained in the Information Response
connectionHandle (int) – connection handle associated to the connection

class mirage.libs.ble_utils.packets.BLEFindInformationRequest(startHandle=0, endHandle=65535, connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Find Information Request

Parameters

startHandle (int) – lowest ATT handle included in the request
endHandle (int) – highest ATT handle included in the request
connectionHandle (int) – connection handle associated to the connection

class mirage.libs.ble_utils.packets.BLEFindInformationResponse(format=0, data=b'', attributes=[], connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Find Information Response

Parameters

data (bytes) – data included in the Information Response
attributes (list of dict) – list indicating the ATT attributes contained in the Information Response
format (int) – integer indicating the format of the response (0x1 : short UUID (16 bits), 0x2 : long UUID (128bits))
connectionHandle (int) – connection handle associated to the connection

Example

>>> BLEFindInformationResponse(data=bytes.fromhex('0f000229')).attributes
[{'attributeHandle': 15, 'type': b')'}]
>>> BLEFindInformationResponse(attributes=[{'attributeHandle': 15, 'type': b')'}]).data.hex()
'0f000229'

Note

Please note the following behaviour :

If only the data is provided, the attributes list is automatically generated (thanks to the decode method.)
If the attributes are provided, the corresponding data is automatically generated (thanks to the build method)

An attribute is described as a dictionary composed of two fields :

attributeHandle : indicating the handle of the corresponding ATT attribute
type : indicating the UUID (type of the ATT attribute)

Example : {"attributeHandle":0x0001, "type":type}

build()¶: This method generates the data from the attributes list.

decode()¶: This method generates the attributes list from the data.

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEHandleValueConfirmation(connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Handle Value Confirmation

Parameters

connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEHandleValueConfirmation())

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEHandleValueIndication(handle=0, value=b'', connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Handle Value Indication

Parameters

handle (int) – ATT value handle indicating the attribute linked to the indication
value (bytes) – new value to notify
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEHandleValueIndication(handle=0x0021, value=b""))
>>> emitter.sendp(ble.BLEHandleValueIndication(handle=0x0021, value=b""))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEHandleValueNotification(handle=0, value=b'', connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Handle Value Notification

Parameters

handle (int) – ATT value handle indicating the attribute linked to the notification
value (bytes) – new value to notify
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEHandleValueNotification(handle=0x0021, value=b""))
>>> emitter.sendp(ble.BLEHandleValueNotification(handle=0x0021, value=b""))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEIdentityAddressInformation(connectionHandle=- 1, type='public', address='00:00:00:00:00:00')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Identity Address Information

Parameters

connectionHandle (int) – connection handle associated to the connection
type (str) – string indicating if the associated BD address is random (“random”) or public (“public”)
address (str) – string indicating the BD address

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEIdentityInformation(connectionHandle=- 1, irk=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Identity Information

Parameters

connectionHandle (int) – connection handle associated to the connection
irk (bytes) – Identity Resolving Key

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLELongTermKeyRequest(connectionHandle=- 1, rand=b'\x00\x00\x00\x00\x00\x00\x00\x00', ediv=0, ltk=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Long Term Key Request

Parameters

rand (bytes) – random value associated to this Long Term Key
ediv (integer) – EDIV value associated to this Long Term Key
ltk (bytes) – Long Term Key
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLELongTermKeyRequest(ltk=bytes.fromhex("000102030405060708090a0b0c0d0e0f"))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLELongTermKeyRequestReply(connectionHandle=- 1, positive=False, ltk=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Long Term Key Request Reply

Parameters

positive (bool) – boolean indicating if the LTK Request was accepted (positive=True) or rejected (positive=False)
ltk (bytes) – Long Term Key
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLELongTermKeyRequestReply(ltk=bytes.fromhex("000102030405060708090a0b0c0d0e0f"), positive=True))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEMasterIdentification(connectionHandle=- 1, ediv=0, rand=b'\x00\x00\x00\x00\x00\x00\x00\x00')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Encryption Information

Parameters

connectionHandle (int) – connection handle associated to the connection
rand (bytes) – random value associated to the Long Term Key
ediv (integer) – EDIV value associated to the Long Term Key

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEPacket¶

Bases: mirage.libs.wireless_utils.packets.Packet

Mirage Bluetooth Low Energy Packet

class mirage.libs.ble_utils.packets.BLEPairingConfirm(connectionHandle=- 1, confirm=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Pairing Confirm

Parameters

connectionHandle (int) – connection handle associated to the connection
confirm (bytes) – confirmation value

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEPairingFailed(connectionHandle=- 1, reason=0)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Pairing Failed

Parameters

connectionHandle (int) – connection handle associated to the connection
reason (int) – integer indicating the reason of failure

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEPairingRandom(connectionHandle=- 1, random=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Pairing Random

Parameters

connectionHandle (int) – connection handle associated to the connection
random (bytes) – random value

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEPairingRequest(connectionHandle=- 1, outOfBand=False, inputOutputCapability=0, maxKeySize=16, authentication=b'\x00', initiatorKeyDistribution=b'\x00', responderKeyDistribution=b'\x00', payload=b'')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Pairing Request

Parameters

connectionHandle (int) – connection handle associated to the connection
outOfBand (bool) – boolean indicating if out of band is available
inputOutputCapability (int) – integer indicating the input output capability of Central
maxKeySize (int) – integer indicating the maximum key size
authentication (bytes) – flags indicating the authentication parameters requested
initiatorKeyDistribution (bytes) – bytes indicating the initiator key distribution
responderKeyDistribution (bytes) – bytes indicating the responder key distribution
payload (bytes) – bytes indicating the payload of request

Note

Some dissectors are provided in order to fill the fields included in this packet :

mirage.libs.ble_utils.dissectors.AuthReqFlag : authentication field

mirage.libs.ble_utils.dissectors.InputOutputCapability : input output capability field

mirage.libs.ble_utils.dissectors.KeyDistributionFlag : initiatorKeyDistribution and responderKeyDistribution fields

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEPairingResponse(connectionHandle=- 1, outOfBand=0, inputOutputCapability=0, maxKeySize=16, authentication=0, initiatorKeyDistribution=0, responderKeyDistribution=0, payload=b'')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Pairing Response

Parameters

connectionHandle (int) – connection handle associated to the connection
outOfBand (bool) – boolean indicating if out of band is available
inputOutputCapability (int) – integer indicating the input output capability of Peripheral
maxKeySize (int) – integer indicating the maximum key size
authentication (bytes) – flags indicating the authentication parameters requested
initiatorKeyDistribution (bytes) – bytes indicating the initiator key distribution
responderKeyDistribution (bytes) – bytes indicating the responder key distribution
payload (bytes) – bytes indicating the payload of response

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadBlobRequest(handle=0, offset=0, connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read Blob Request

Parameters

handle (int) – ATT value handle indicating the attribute linked to the request
offset (int) – offset of the value to read
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEReadBlobRequest(handle=0x0021, offset=26))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadBlobResponse(value=b'', connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read Blob Response

Parameters

value (bytes) – ATT value
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEReadBlobResponse(value=bytes.fromhex("01020304")))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadByGroupTypeRequest(startHandle=0, endHandle=65535, uuid=0, connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read By Group Type Request

Parameters

startHandle (int) – lowest ATT handle included in the request
endHandle (int) – highest ATT handle included in the request
uuid (int) – UUID indicating a given type
connectionHandle (int) – connection handle associated to the connection

class mirage.libs.ble_utils.packets.BLEReadByGroupTypeResponse(length=6, data=b'', attributes=[], connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read By Group Type Response

Parameters

data (bytes) – data included in the Read By Group Type Response
attributes (list of dict) – list indicating the ATT group type of attributes contained in the Read By Group Type Response
length (int) – integer indicating the length (in number of bytes) corresponding to one range of attributes providing the same value
connectionHandle (int) – connection handle associated to the connection

Example

>>> BLEReadByGroupTypeResponse(data=bytes.fromhex('01000b0000180c000f00011810001e000a18')).attributes
[{'attributeHandle': 1, 'endGroupHandle': 11, 'value': b''}, {'attributeHandle': 12, 'endGroupHandle': 15, 'value': b''}, {'attributeHandle': 16, 'endGroupHandle': 30, 'value': b''}]
>>> BLEReadByGroupTypeResponse(attributes=[{'attributeHandle': 1, 'endGroupHandle': 11, 'value': b''},{'attributeHandle': 12, 'endGroupHandle': 15, 'value': b''}, {'attributeHandle': 16, 'endGroupHandle': 30, 'value':b'\n'}]).data.hex()
'01000b0000180c000f00011810001e000a18'

Note

Please note the following behaviour :

If only the data is provided, the group type list is automatically generated (thanks to the decode method.)

If the attributes are provided, the corresponding data is automatically generated (thanks to the build method)

A group type of attribute is described as a dictionary composed of three fields :

attributeHandle : indicating the lowest handle of the corresponding ATT group type

value : indicating the value of the ATT attribute

endGroupHandle : indicating the highest handle of the corresponding ATT group type

Example : {'attributeHandle': 1, 'endGroupHandle': 11, 'value': b'\'}

build()¶

decode()¶

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadByTypeRequest(startHandle=0, endHandle=65535, uuid=0, connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read By Type Request

Parameters

startHandle (int) – lowest ATT handle included in the request
endHandle (int) – highest ATT handle included in the request
uuid (int) – UUID indicating a given type
connectionHandle (int) – connection handle associated to the connection

class mirage.libs.ble_utils.packets.BLEReadByTypeResponse(data=b'', attributes=[], connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read By Type Response

Parameters

data (bytes) – data included in the Read By Type Response
attributes (list of dict) – list indicating the attributes contained in the Read By Type Response
connectionHandle (int) – connection handle associated to the connection

Example

>>> BLEReadByTypeResponse(data=bytes.fromhex("152900102a0018d3dd5ce93dd08951403448f4ffb3a8")).attributes
[{'attributeHandle': 41, 'value': b'*ÓÝ\é=ÐQ@4Hôÿ³¨'}]
>>> BLEReadByTypeResponse(attributes=[{'attributeHandle': 41, 'value': b'*ÓÝ\é=ÐQ@4Hôÿ³¨'}]).data.hex()
'152900102a0018d3dd5ce93dd08951403448f4ffb3a8'

Note

Please note the following behaviour :

If only the data is provided, the list of attributes is automatically generated (thanks to the decode method.)

If the attributes are provided, the corresponding data is automatically generated (thanks to the build method)

An attribute is described as a dictionary composed of two fields :

attributeHandle : indicating the handle of the ATT attribute

value : indicating the value of the ATT attribute

Example : {'attributeHandle': 1, 'value': b'\'}

build()¶

decode()¶

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadRequest(handle=0, connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read Request

Parameters

handle (int) – ATT handle indicating the attribute to read
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEReadRequest(handle=0x0021))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadResponse(value=b'', connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read Response

Parameters

value (bytes) – value read and transmitted to Central
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEReadResponse(value=b"ª»ÌÝ"))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEScanRequest(srcAddr='00:00:00:00:00:00', srcAddrType='public', dstAddr='00:00:00:00:00:00', dstAddrType='public')¶

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - SCAN_REQ

Parameters

srcAddr (str) – BD address of the emitter
dstAddr (str) – BD address of the receiver

Note

This class inherits from BLEAdvertisement.

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEScanResponse(addr='00:00:00:00:00:00', addrType='public', data=b'')¶

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - SCAN_RSP

Parameters

srcAddr (str) – BD address of the emitter
data (bytes) – bytes indicating the data included in the Advertisement packet

Note

This class inherits from BLEAdvertisement.

class mirage.libs.ble_utils.packets.BLESecurityRequest(connectionHandle=- 1, authentication=b'\x00')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Security Request

Parameters

connectionHandle (int) – connection handle associated to the connection
authentication (bytes) – flags indicating the authentication parameters requested

Note

Some dissectors are provided in order to fill the fields included in this packet :

mirage.libs.ble_utils.dissectors.AuthReqFlag : authentication field

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLESigningInformation(connectionHandle=- 1, csrk=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Signing Information

Parameters

connectionHandle (int) – connection handle associated to the connection
csrk (bytes) – Connection Signature Resolving Key

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLESniffingParameters(rssi=None, rssi_min=0, rssi_max=0, rssi_avg=0, rssi_count=0, clk_100ns=0, clkn_high=0, direction=None, channel=None, frequency=None, rawPacket=None)¶

Bases: mirage.libs.wireless_utils.packets.AdditionalInformations

This class allows to attach some sniffer’s data to a Mirage BLE Packet, such as RSSI or channel. If the frequency is provided, the corresponding channel is automatically calculated.

Parameters

rssi (float) – Received Signal Strength Indication
rssi_min (float) – Received Signal Strength Indication (min. value)
rssi_max (float) – Received Signal Strength Indication (max. value)
rssi_avg (float) – Received Signal Strength Indication (average value)
clk_high (float) – clock’s value (high)
clk_100ns – clock’s value (100ns)
direction (str) – direction of the packet (“master->slave” or “slave->master”)
channel (int) – channel of the received packet
frequency (float) – frequency of the received packet

toString()¶

class mirage.libs.ble_utils.packets.BLEWriteCommand(handle=0, value=b'', connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Write Command

Parameters

handle (int) – ATT value handle indicating the attribute to write
value (bytes) – new value to write
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEWriteCommand(handle=0x0021, value=b""))

Note

This Packet is similar to BLEWriteRequest but it doesn’t need a Write Response

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEWriteRequest(handle=0, value=b'', connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Write Request

Parameters

handle (int) – ATT value handle indicating the attribute to write
value (bytes) – new value to write
connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEWriteRequest(handle=0x0021, value=b""))

toString()¶

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :

<< name >> if no additional informations are linked to this packet
[ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEWriteResponse(connectionHandle=- 1)¶

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Write Response

Parameters

connectionHandle (int) – connection handle associated to the connection

Example

>>> emitter.sendp(ble.BLEWriteResponse()) # note : the connectionHandle is not provided because its value is direcly modified by the Device

mirage.libs.ble_utils.scapy_hci_layers module¶

This module contains some scapy definitions for communicating with an Sniffle device.

mirage.libs.ble_utils.scapy_hci_layers module¶

This module contains some scapy definitions for communicating with an HCI device.

mirage.libs.ble_utils.scapy_btlejack_layers module¶

This module contains some scapy definitions for communicating with a BTLEJack device.

mirage.libs.ble_utils.scapy_link_layers module¶

This module contains some scapy definitions of Link Layer Bluetooth Low Energy packets.