mirage.libs.bt_utils package

Submodules

mirage.libs.bt_utils.assigned_numbers module

This module contains some data structures used by the upper application layers of Bluetooth and Bluetooth Low Energy, and it provides some helpers in order to easily use them.

class mirage.libs.bt_utils.assigned_numbers.AssignedNumbers

Bases: object

This class provides some helpers to get some specific values used by the Bluetooth and Bluetooth Low Energy protocols.

classmethod getCompanyByNumber(number)

This class method converts a company ID into an human readable name.

Parameters

number (int) – integer indicating the company ID

Returns

name of company

Return type

str

Example
>>> AssignedNumbers.getCompanyByNumber(12)
'Digianswer A/S'
>>> AssignedNumbers.getCompanyByNumber(125)
'Seers Technology Co., Ltd.'
classmethod getNameByNumber(number)

This class method converts an assigned number into the corresponding name.

Parameters

number (int) – assigned number to convert

Returns

name

Return type

str

Example
>>> AssignedNumbers.getNameByNumber(6144)
'Generic Access'
>>> AssignedNumbers.getNameByNumber(6159)
'Battery Service'
classmethod getNameByUTI(uti)

This class method converts an Uniform Type Identifier into the corresponding name.

Parameters

uti (str) – Uniform Type Identifier to convert

Returns

name

Return type

str

Example
>>> AssignedNumbers.getNameByUTI('org.bluetooth.service.generic_access')
'Generic Access'
>>> AssignedNumbers.getNameByUTI('org.bluetooth.service.battery_service')
'Battery Service'
classmethod getNumberByName(name)

This class method converts a name into the corresponding assigned number.

Parameters

name (str) – name to convert

Returns

assigned number

Return type

int

Example
>>> AssignedNumbers.getNumberByName("Generic Access")
6144
>>> AssignedNumbers.getNumberByName("Battery Service")
6159
classmethod getNumberByPermissions(permissions)

This class method converts an human readable list of ATT permissions into an ATT permissions number.

Parameters

permissions (list of str) – human readable list of permissions

Returns

ATT permissions number

Return type

int

Example
>>> AssignedNumbers.getNumberByPermissions(['Write Without Response', 'Broadcast'])
5
>>> AssignedNumbers.getNumberByPermissions(['Broadcast'])
1
>>> AssignedNumbers.getNumberByPermissions(['Write Without Response', 'Read'])
6
classmethod getNumberByUTI(uti)

This class method converts an Uniform Type Identifier into the corresponding assigned number.

Parameters

uti (str) – Uniform Type Identifier to convert

Returns

assigned number

Return type

int

Example
>>> AssignedNumbers.getNumberByUTI('org.bluetooth.service.generic_access')
6144
>>> AssignedNumbers.getNumberByUTI('org.bluetooth.service.battery_service')
6159
classmethod getPermissionsByNumber(number)

This class method converts an ATT permissions number into an human readable list of permissions.

Parameters

number (int) – ATT permissions number

Returns

human readable list of permissions

Return type

list of str

Example
>>> AssignedNumbers.getPermissionsByNumber(5)
['Write Without Response', 'Broadcast']
>>> AssignedNumbers.getPermissionsByNumber(1)
['Broadcast']
>>> AssignedNumbers.getPermissionsByNumber(6)
['Write Without Response', 'Read']
classmethod getStringsbyFlags(flags)

This class method converts some flags contained in BLE Advertisements into a list of human readable strings.

Parameters

flags (str) – flags to convert, separated by “+”

Returns

list of human readable strings

Return type

list of str

Example
>>> AssignedNumbers.getStringsbyFlags("limited_disc_mode+simul_le_br_edr_host")
['LE Limited Discoverable Mode', 'Simultaneous LE and BR/EDR, Host']
classmethod getUTIByName(name)

This class method converts a name into the corresponding Uniform Type Identifier.

Parameters

name (str) – name to convert

Returns

Uniform Type Identifier

Return type

str

Example
>>> AssignedNumbers.getUTIByName("Generic Access")
'org.bluetooth.service.generic_access'
>>> AssignedNumbers.getUTIByName("Battery Service")
'org.bluetooth.service.battery_service'
classmethod getUTIByNumber(number)

This class method converts an assigned number into the corresponding Uniform Type Identifier.

Parameters

number (int) – assigned number to convert

Returns

Uniform Type Identifier

Return type

str

Example
>>> AssignedNumbers.getUTIByNumber(6144)
'org.bluetooth.service.generic_access'
>>> AssignedNumbers.getUTIByNumber(6159)
'org.bluetooth.service.battery_service'
class mirage.libs.bt_utils.assigned_numbers.PairingMethods

Bases: object

This class provides some helpers in order to manipulate the Security Manager protocol.

JUST_WORKS = 1
NUMERIC_COMPARISON = 3
PASSKEY_ENTRY = 2
classmethod getPairingMethod(secureConnections=False, initiatorInputOutputCapability='NoInputNoOutput', responderInputOutputCapability='NoInputNoOutput')

This method allows to select the right pairing method according to the initiator and responder Input Output Capability.

Parameters
  • secureConnections (bool) – boolean indicating if the secure connections are in use

  • initiatorInputOutputCapability (str) – string indicating the initiator Input Output Capability

  • responderInputOutputCapability – string indicating the responder Input Output Capability

Returns

integer indicating the pairing method selected

Return type

int

Note

The possible values for InputOutputCapability parameters are :

  • “DisplayOnly”

  • “DisplayYesNo”

  • “KeyboardOnly”

  • “NoInputNoOutput”

  • “KeyboardDisplay”

Example
>>> PairingMethods.getPairingMethod(
... secureConnections=False,
... initiatorInputOutputCapability="NoInputNoOutput",
... responderInputOutputCapability="NoInputNoOutput")
1
>>> PairingMethods.getPairingMethod(
... secureConnections=True,
... initiatorInputOutputCapability="DisplayOnly",
... responderInputOutputCapability="KeyboardOnly")
2

mirage.libs.bt_utils.constants module

This module contains some constants that are used by the Bluetooth stack.

mirage.libs.bt_utils.hciconfig module

class mirage.libs.bt_utils.hciconfig.HCIConfig

Bases: object

This class allows to easily configure an HCI Interface.

static down(index)

This class method stops an HCI interface. Its role is equivalent to the following command : hciconfig hci<index> down

Parameters

index (integer) – index of the HCI interface to stop

Example
>>> HCIConfig.down(0)
static reset(index)

This class method resets an HCI interface. Its role is equivalent to the following command : hciconfig hci<index> reset

Parameters

index (integer) – index of the HCI interface to reset

Example
>>> HCIConfig.reset(0)
static up(index)

This class method starts an HCI interface. Its role is equivalent to the following command : hciconfig hci<index> up

Parameters

index (integer) – index of the HCI interface to start

Example
>>> HCIConfig.up(0)

mirage.libs.bt_utils.packets module

class mirage.libs.bt_utils.packets.BluetoothAcceptConnectionRequest(address='', role='slave')

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Bluetooth Accept Connection Request

Parameters
  • address (str) – string indicating the target BD address (format : “XX:XX:XX:XX:XX:XX”)

  • role (str) – string indicating the role of device (“master”,”slave”)

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.bt_utils.packets.BluetoothConnect(address='', packetType=52248, pageScanRepetitionMode='R1', clockOffset=0, allowRoleSwitch='allowed')

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Bluetooth Connect

Parameters
  • address (str) – string indicating the target BD address (format : “XX:XX:XX:XX:XX:XX”)

  • packetType (int) – integer indicating the type of packets

  • pageScanRepetitionMode (str) – string indicating the page Scan Repetition mode (“R0”,”R1” or “R2”)

  • clockOffset (int) – integer indicating the clock offset

  • allowRoleSwitch (str) – string indicating if a role switch is allowed during the connection (“allowed”, “disallowed”)

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.bt_utils.packets.BluetoothConnectResponse(dstMac='00:00:00:00:00:00', srcMac='00:00:00:00:00:00', success=True, linkType=0, encryptionMode=False)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Bluetooth Connect Response

Parameters
  • dstMac (str) – string indicating the destination BD address (format : “XX:XX:XX:XX:XX:XX”)

  • srcMac (str) – string indicating the source BD address (format : “XX:XX:XX:XX:XX:XX”)

  • success (bool) – boolean indicating if the connection is successful

  • linkType (int) – integer indicating the link type (0x01 : ACL connection)

  • encryptionMode (bool) – boolean indicating if the encryption is enabled

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.bt_utils.packets.BluetoothConnectionRequest(address='', classOfDevice=0)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Bluetooth Connection Request

Parameters
  • address (str) – string indicating the target BD address (format : “XX:XX:XX:XX:XX:XX”)

  • classOfDevice (int) – integer indicating the class of device

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.bt_utils.packets.BluetoothInquiry(lap=3378078, inquiryLength=5, numResponses=0)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Inquiry

Parameters
  • lap (int) – integer indicating the lap

  • inquiryLength (int) – integer indicating the inquiry length

  • numResponses (int) – integer indicating the number of responses

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.bt_utils.packets.BluetoothInquiryComplete(status=0)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Inquiry Complete

Parameters

status (int) – integer indicating the status of the inquiry scan

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.bt_utils.packets.BluetoothInquiryScanResult(address='', numResponses=0, classOfDevice=0, rssi=0, data=b'')

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Inquiry Scan Result

Parameters
  • address (str) – string indicating the target BD address (format : “XX:XX:XX:XX:XX:XX”)

  • numResponses (int) – integer indicating the number of responses

  • classOfDevice (int) – integer indicating the class of device

  • rssi (int) – integer indicating the Received Signal Strength Indication

  • data (bytes) – array of bytes indicating the data attached to this scan result

getRawDatas()

This method allows to get raw datas as bytes (not as scapy frame)

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.bt_utils.packets.BluetoothL2CAPConfigurationRequest(dcid=64, flags=0, data='', connectionHandle=-1)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - L2CAP Configuration Request

Parameters
  • dcid (str) – integer indicating the Destination Channel Identifier

  • flags (int) – integer indicating the flags

  • data (bytes) – array of bytes indicating the data included in the request

  • connectionHandle (int) – integer indicating the connection handle

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.bt_utils.packets.BluetoothL2CAPConfigurationResponse(scid=64, flags=0, result=0, data='', connectionHandle=-1)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - L2CAP Configuration Response

Parameters
  • scid (str) – integer indicating the Source Channel Identifier

  • flags (int) – integer indicating the flags

  • data (bytes) – array of bytes indicating the data included in the request

  • result (int) – integer indicating the result of the response (0 : success)

  • connectionHandle (int) – integer indicating the connection handle

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.bt_utils.packets.BluetoothL2CAPConnectionRequest(psm=None, protocol=None, scid=64, connectionHandle=-1)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - L2CAP Connection Request

Parameters
  • psm (int) – integer indicating the Protocol Service Multiplexer (1 : SDP, 3 : RFCOMM, 4 : telephony control)

  • protocol (str) – string indicating the protocol (“SDP”, “RFCOMM”, “telephony control”)

  • scid (int) – integer indicating the Source Channel Identifier

  • connectionHandle (int) – integer indicating the connection handle

Note

This class implements an automatic behaviour in order to select the right protocol :
  • If PSM is provided, the protocol field is set according to its value

  • If PSM is not provided, the protocol field is used to choose the protocol and the PSM field is set to the right value

  • If PSM and protocol are not provided, the SDP protocol is automatically selected

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.bt_utils.packets.BluetoothL2CAPConnectionResponse(result=0, status=0, dcid=64, scid=64, connectionHandle=-1)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - L2CAP Connection Response

Parameters
  • result (int) – integer indicating the result of the response (0 : success)

  • dcid (str) – integer indicating the Destination Channel Identifier

  • scid (int) – integer indicating the Source Channel Identifier

  • connectionHandle (int) – integer indicating the connection handle

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.bt_utils.packets.BluetoothL2CAPInformationRequest(type=0, data=b'', connectionHandle=-1)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - L2CAP Information Request

Parameters
  • type (int) – integer indicating the type of information request (1: CL_MTU, 2: FEAT_MASK)

  • data (bytes) – array of bytes indicating the data included in the request

  • connectionHandle (int) – integer indicating the connection handle

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.bt_utils.packets.BluetoothL2CAPInformationResponse(type=0, result=0, data=b'', connectionHandle=-1)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - L2CAP Information Response

Parameters
  • type (int) – integer indicating the type of information response (1: CL_MTU, 2: FEAT_MASK)

  • result (int) – integer indicating the result of the response (0 : success)

  • data (bytes) – array of bytes indicating the data included in the response

  • connectionHandle (int) – integer indicating the connection handle

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.bt_utils.packets.BluetoothMaxSlotChange(maxNumberOfSlots=0)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Max Slot Change

Parameters

maxNumberOfSlots (int) – integer indicating the maximum number of slots

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.bt_utils.packets.BluetoothPacket

Bases: mirage.libs.wireless_utils.packets.Packet

Mirage Bluetooth Packet

class mirage.libs.bt_utils.packets.BluetoothRejectConnectionRequest(address='', reason=0)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Bluetooth Reject Connection Request

Parameters
  • address (str) – string indicating the target BD address (format : “XX:XX:XX:XX:XX:XX”)

  • reason (int) – error code (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.bt_utils.packets.BluetoothRemoteNameRequest(pageScanRepetitionMode='R2', address='00:00:00:00:00:00')

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Remote Name Request

Parameters
  • address (str) – string indicating the target BD address (format : “XX:XX:XX:XX:XX:XX”)

  • pageScanRepetitionMode (str) – string indicating the page Scan Repetition mode (“R0”,”R1” or “R2”)

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.bt_utils.packets.BluetoothRemoteNameResponse(remoteName='', success=False, address='00:00:00:00:00:00')

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Remote Name Response

Parameters
  • remoteName (str) – string indicating the remote name of the device

  • success (bool) – boolean indicating if the remote name request was successful

  • address (str) – string indicating the target BD address (format : “XX:XX:XX:XX:XX:XX”)

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.bt_utils.packets.BluetoothWriteExtendedInquiryResponse(fecRequired=False, data=b'')

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Write Extended Inquiry Response

Parameters
  • fecRequired (bool) – boolean indicating if the Forward Error Correction is required

  • data (bytes) – data collected during the inquiry scan

class mirage.libs.bt_utils.packets.BluetoothWriteScanEnable(discoverable=False, connectable=False, scanEnable=None)

Bases: mirage.libs.bt_utils.packets.BluetoothPacket

Mirage Bluetooth Packet - Write Scan Enable

Parameters
  • discoverable (bool) – boolean indicating if the device is discoverable

  • connectable (bool) – boolean indicating if the device is connectable

  • scanEnable (bool) – boolean indicating if the scan is enabled

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

mirage.libs.bt_utils.scapy_layers module

This module contains some scapy definitions for Bluetooth protocol. Some of them have been recently included in the latest scapy development version, these changes will be taken into account soon.

mirage.libs.bt_utils.scapy_ubertooth_layers module

This module contains some scapy definitions for communicating with an Ubertooth device.

mirage.libs.bt_utils.scapy_vendor_specific module

This module contains some scapy definitions defining some vendor specific HCI packets in order to change the BD Address.

mirage.libs.bt_utils.ubertooth module

class mirage.libs.bt_utils.ubertooth.BtUbertoothDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

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

Warning

Please note that this implementation is actually incomplete in order to sniff the Bluetooth protocol. Actually, it can only be used in Bluetooth Low Energy mode (mirage.libs.ble_utils.ubertooth.BLEUbertoothDevice)

close()

This method closes the device.

getDeviceIndex()

This method returns the index of the current Ubertooth device.

Returns

device’s index

Return type

int

Example
>>> device.getDeviceIndex()
0
getFirmwareVersion()

This method returns the firmware version in use in the current Ubertooth device.

Returns

firmware version

Return type

str

Example
>>> device.getFirmwareVersion()
'1.6'
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()
"Bt"
init()

This method initializes the device.

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

classmethod resetUbertooth(index=0)

This class method allows to reset the Ubertooth, by providing the device’s index.

Parameters

index (int) – device’s index

Returns

boolean indicating if the reset operation was successful

Return type

bool

Example
>>> BtUbertoothDevice.resetUbertooth(0)
True

Module contents