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

mirage.libs.bt_utils package¶

Submodules¶

mirage.libs.bt_utils.assigned_numbers module¶

mirage.libs.bt_utils.constants module¶

mirage.libs.bt_utils.hciconfig module¶

mirage.libs.bt_utils.packets module¶

mirage.libs.bt_utils.scapy_layers module¶

mirage.libs.bt_utils.scapy_ubertooth_layers module¶

mirage.libs.bt_utils.scapy_vendor_specific module¶

mirage.libs.bt_utils.ubertooth module¶

Module contents¶