mirage.libs.esb_utils package

Submodules

mirage.libs.esb_utils.rfstorm module

class mirage.libs.esb_utils.rfstorm.ESBRFStormDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with a NRF24 Device using the RFStorm firmware from Bastille in order to sniff and inject Enhanced ShockBurst frames. The corresponding interfaces are : rfstormX (e.g. “rfstorm0”)

The following capabilities are actually supported :

Capability

Available ?

INJECTING

yes

SNIFFING_NORMAL

yes

SNIFFING_PROMISCUOUS

yes

SNIFFING_GENERIC_PROMISCUOUS

yes

ACTIVE_SCANNING

yes

Warning

The RFStorm firmware can be used with a crazyRadio PA Dongle or with a Logitech Unifying receiver. The firmware can be found here <https://github.com/BastilleResearch/nrf-research-firmware>.

close()

This method closes the device.

disableAutoAck()

This method disables the autoACK feature (an empty ACK frame will be transmitted every time a frame is received).

Example
>>> device.disableAutoAck()

Note

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

enableAutoAck()

This method enables the autoACK feature (an empty ACK frame will be transmitted every time a frame is received).

Example
>>> device.enableAutoAck()

Note

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

enterGenericPromiscuousMode(prefix=b'', rate=2000, payloadLength=32)

This method allows to put your device into generic promiscuous mode. You can provide multiple parameters such as prefix, rate or payload length.

Parameters

  • prefix (bytes) – bytes indicating the prefix to look for

  • rate (int) – integer indicating the symbol rate to use (possible values: 250, 1000, 2000)

  • payloadLength (int) – maximal length to use

Note

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

enterPromiscuousMode(prefix=b'')

This method allows to put your device into promiscuous mode. You can provide a specific prefix to match using the prefix parameter.

Parameters

prefix (bytes) – bytes indicating the prefix to look for

Note

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

enterSnifferMode(address)

This method allows to put your device into sniffer mode. You have to provide an address to follow.

Parameters

address (str) – address to follow as string (e.g. ‘11:22:33:44:55’)

Note

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

getAddress()

This method returns the address actually in use (sniffer mode only).

Returns

address in use (e.g. ‘11:22:33:44:55’)

Return type

str

Example
>>> device.getAddress()
'11:22:33:44:55'

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 index of the current RFStorm 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.

getMode()

This method returns the current mode in use (RFStorm device can be set in three modes: PROMISCUOUS, GENERIC_PROMISCUOUS, SNIFFER)

Example
>>> device.enterSnifferMode('AA:BB:CC:DD:EE')
>>> device.getMode()
'SNIFFER'

Note

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

init()

This method initializes the device.

isAutoAckEnabled()

This method returns a boolean indicating if the autoACK feature is enabled.

Example
>>> device.isAutoAckEnabled()
False
>>> device.enableAutoAck()
>>> device.isAutoAckEnabled()
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

classmethod resetRFStorm(index=0)
scan(channels=None)

This method allows to launch an active scan in order to find the channel in use by the target device. This method can only be used in sniffer mode.

Parameters

channels (list of int) – list of channels to scan

Returns

boolean indicating if the device has been found

Return type

bool

Example
>>> device.scan([1,2,3])
False
>>> device.scan()
True

Note

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

send(pkt)

This method sends some datas.

Parameters

data – raw representation of the data to send

setAddress(address)

This method changes the address to use (sniffer mode only).

Parameters

address (str) – address to use (e.g. ‘11:22:33:44:55’)

Example
>>> device.setAddress('11:22:33:44:55')

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.

sharedMethods = ['setChannel', 'getChannel', 'getDeviceIndex', 'enterPromiscuousMode', 'enterGenericPromiscuousMode', 'enterSnifferMode', 'getMode', 'getAddress', 'setAddress', 'isAutoAckEnabled', 'enableAutoAck', 'disableAutoAck', 'scan']

mirage.libs.esb_utils.dissectors module

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

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the Logitech Unifying unencrypted 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
>>> LogitechKeystroke(locale="fr",key="a",ctrl=False,gui=False,alt=False,shift=False)
Keystroke(key=a,ctrl=no,alt=no,shift=no,gui=no)
>>> LogitechKeystroke(locale="fr",key="a",ctrl=False,gui=False,alt=False,shift=False).data.hex()
'00140000000000'
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.esb_utils.dissectors.LogitechMousePosition(data=b'', length=- 1, content={}, *args, **kwargs)

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the Logitech Unifying mouse position value. It inherits from Dissector.

The following fields are available in the data structure :

  • x : field indicating x position of the mouse

  • y : field indicating y position of the mouse

Example
>>> LogitechMousePosition(data=bytes.fromhex("feafff"))
MousePosition(x=-2,y=-6)
>>> LogitechMousePosition(data=bytes.fromhex("feafff")).x
-2
>>> LogitechMousePosition(data=bytes.fromhex("feafff")).y
-6
>>> LogitechMousePosition(x=-2,y=-6).data.hex()
'feafff'
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.esb_utils.constants module

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

class mirage.libs.esb_utils.constants.ESBOperationMode

Bases: object

GENERIC_PROMISCUOUS = 2
PROMISCUOUS = 0
SNIFFER = 1

mirage.libs.esb_utils.pcap module

class mirage.libs.esb_utils.pcap.ESBPCAPDevice(interface)

Bases: mirage.libs.wireless_utils.pcapDevice.PCAPDevice

This device allows to communicate with a PCAP file in order to write and read Enhanced ShockBurst packets.

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

  • If the file exists, the ESBPCAPDevice is in read mode, and the corresponding receiver is able to use it as a classic Enhanced ShockBurst sniffer.

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

The following capabilities are actually supported :

Capability

Available ?

INJECTING

yes

SNIFFING_NORMAL

yes

SNIFFING_PROMISCUOUS

yes

SNIFFING_GENERIC_PROMISCUOUS

no

ACTIVE_SCANNING

yes

Warning

This PCAP Device uses the DLT 148.

DLT = 148
SCAPY_LAYER

alias of mirage.libs.esb_utils.scapy_esb_layers.ESB_Hdr

buildPacket(packet, timestamp)

This method is used to encapsulate the packet into a scapy frame (if SCAPY_LAYER is not None).

enterPromiscuousMode(prefix=b'')

This method allows to put your device into promiscuous mode. You can provide a specific prefix to match using the prefix parameter.

Parameters

prefix (bytes) – bytes indicating the prefix to look for

Note

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

enterSnifferMode(address)

This method allows to put your device into sniffer mode. You have to provide an address to follow.

Parameters

address (str) – address to follow as string (e.g. ‘11:22:33:44:55’)

Note

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

generateStream()

This method generates a stream (i.e. a list of packets with the right inter frame spacing) from the PCAP file.

Returns

stream of packets

Return type

list

Example
>>> stream = device.generateStream()
>>> device2.sendp(*stream)

Note

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

getChannel()

This method allows to simulate the getChannel behaviour of a normal sniffer.

Returns

integer indicating an unknown channel (-1)

Return type

int

Example
>>> device.getChannel()
-1

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).

scan(channels)

This method allows to simulate an active scan.

Parameters

channels (list of int) – list of channels to scan

Returns

boolean indicating if the device has been found

Return type

bool

Example
>>> device.scan([1,2,3])
True
>>> device.scan()
True

Note

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

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

setChannel(channel)

This method allows to simulate the setChannel behaviour of a normal sniffer.

Parameters

channel (int) – channel to set

Example
>>> device.getChannel()
-1

Note

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

sharedMethods = ['enterSnifferMode', 'enterPromiscuousMode', 'scan', 'getChannel', 'setChannel', 'getMode', 'generateStream']

mirage.libs.esb_utils.helpers module

This module provides some helpers in order to manipulate Enhanced ShockBurst packets.

mirage.libs.esb_utils.helpers.bits2bytes(bits)

This function converts a sequence of bits (as string) to the corresponding bytes.

Parameters

bits (str) – string indicating a sequence of bits (e.g. “10110011”)

Returns

corresponding bytes

Return type

bytes

Example
>>> bits2bytes('00000001000000100000001111111111')
b'ÿ'
>>> bits2bytes('010000010100001001000011')
b'ABC'
mirage.libs.esb_utils.helpers.bitwiseXor(a, b)

This function returns the result of a bitwise XOR operation applied to two sequences of bits (a and b);

Parameters

  • a (str) – string indicating a sequence of bits (e.g. “10101010”)

  • b (str) – string indicating a sequence of bits (e.g. “10101010”)

Returns

result of the XOR operation

Return type

str

Example
>>> bitwiseXor('11001111','10101010')
'01100101'
>>> bitwiseXor('11111111','00101010')
'11010101'
>>> bitwiseXor('11111111','11001100')
'00110011'
mirage.libs.esb_utils.helpers.bytes2bits(data)

This function converts bytes to the corresponding bits sequence (as string).

Parameters

data (bytes) – bytes to convert

Returns

corresponding bits sequence

Return type

str

Example
>>> bytes2bits(b"ÿ")
'00000001000000100000001111111111'
>>> bytes2bits(b"ABC")
'010000010100001001000011'
mirage.libs.esb_utils.helpers.calcCrc(packet)

This function calculates the CRC of an Enhanced Shockburst packet.

Parameters

packet (bytes) – raw bytes of packet (without CRC and preamble)

Returns

calculated CRC

Return type

bytes

Example
>>> calcCrc(bytes.fromhex('e846f92fa429006100007f57ff80004900')).hex()
'9ed4'
mirage.libs.esb_utils.helpers.calcCrcByte(crc, byte, bits)

This function calculates the temporary value generated by an iteration of CRC calculation.

Parameters

  • crc (bytes) – previous temporary value of CRC

  • byte (bytes) – byte to use in the current iteration

  • bits (int) – number of bits of the byte to take into account in the calculation

mirage.libs.esb_utils.helpers.channelToFrequency(channel)

This function converts an Enhanced ShockBurst channel to the corresponding frequency.

Parameters

channel (int) – ESB channel to convert

Returns

corresponding frequency (MHz)

Return type

int

Example
>>> channelToFrequency(37)
2437
>>> channelToFrequency(8)
2408
mirage.libs.esb_utils.helpers.frequencyToChannel(frequency)

This function converts a frequency to the corresponding Enhanced ShockBurst channel.

Parameters

frequency (int) – frequency to convert (MHz)

Returns

channel associated to the provided frequency

Return type

int

Example
>>> frequencyToChannel(2420)
20
>>> frequencyToChannel(2402)
02

mirage.libs.esb_utils.packets module

class mirage.libs.esb_utils.packets.ESBAckResponsePacket(address='00:00:00:00:00', payload=b'')

Bases: mirage.libs.esb_utils.packets.ESBPacket

Mirage Enhanced ShockBurst Packet - ACK Response

Parameters

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – bytes indicating the ACK payload’s value (e.g. b”4”)

class mirage.libs.esb_utils.packets.ESBLogitechEncryptedKeystrokePacket(payload=None, address='00:00:00:00:00', hidData=b'\x00\x04\x00\x00\x00\x00\x00', aesCounter=0, unknown=0)

Bases: mirage.libs.esb_utils.packets.ESBPacket

Mirage Enhanced ShockBurst Packet - Logitech Encrypted Keystroke Packet

Parameters

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – bytes indicating the payload’s value (e.g. b””)

  • hidData (bytes) – value of HID data in use

  • aesCounter (int) – value of AES counter

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.esb_utils.packets.ESBLogitechKeepAlivePacket(payload=None, address='00:00:00:00:00', timeout=1200)

Bases: mirage.libs.esb_utils.packets.ESBPacket

Mirage Enhanced ShockBurst Packet - Logitech Keep Alive Packet

Parameters

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – bytes indicating the payload’s value (e.g. b””)

  • timeout (int) – value of provided timeout

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.esb_utils.packets.ESBLogitechMousePacket(address='00:00:00:00:00', payload=None, button='', buttonMask=0, move=None, x=0, y=0)

Bases: mirage.libs.esb_utils.packets.ESBPacket

Mirage Enhanced ShockBurst Packet - Logitech Mouse Packet

Parameters

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – bytes indicating the payload’s value (e.g. b””)

  • button (str) – string indicating the selected button (e.g. ‘left’,’right’,’center’ or ‘’ if no button is pressed)

  • buttonMask – integer indicating the selected button (0: ‘’, 1: ‘left’, 2: ‘right’, 4: ‘center’)

  • move (bytes) – 3 bytes indicating the movement of the mouse

  • x (int) – indicates the X position of the mouse

  • y (int) – indicates the Y position of the mouse

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.esb_utils.packets.ESBLogitechMultimediaKeyPressPacket(payload=None, address='00:00:00:00:00', hidData=b'\x00\x04\x00\x00\x00\x00\x00')

Bases: mirage.libs.esb_utils.packets.ESBPacket

Mirage Enhanced ShockBurst Packet - Logitech Multimedia Key Press Packet

Parameters

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – bytes indicating the payload’s value (e.g. b””)

  • hidData (bytes) – value of HID data in use

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.esb_utils.packets.ESBLogitechMultimediaKeyReleasePacket(payload=None, address='00:00:00:00:00')

Bases: mirage.libs.esb_utils.packets.ESBPacket

Mirage Enhanced ShockBurst Packet - Logitech Multimedia Key Release Packet

Parameters

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – bytes indicating the payload’s value (e.g. b””)

  • hidData (bytes) – value of HID data in use

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.esb_utils.packets.ESBLogitechSetTimeoutPacket(payload=None, address='00:00:00:00:00', timeout=1200)

Bases: mirage.libs.esb_utils.packets.ESBPacket

Mirage Enhanced ShockBurst Packet - Logitech Hello / Set Timeout Packet

Parameters

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – bytes indicating the payload’s value (e.g. b””)

  • timeout (int) – value of provided timeout

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.esb_utils.packets.ESBLogitechUnencryptedKeyPressPacket(payload=None, address='00:00:00:00:00', key='', ctrl=False, shift=False, gui=False, alt=False, locale='fr', hidData=None)

Bases: mirage.libs.esb_utils.packets.ESBPacket

Mirage Enhanced ShockBurst Packet - Logitech Unencrypted Key Press Packet

Parameters

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – bytes indicating the payload’s value (e.g. b””)

  • hidData (bytes) – value of HID data in use

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.esb_utils.packets.ESBLogitechUnencryptedKeyReleasePacket(payload=None, address='00:00:00:00:00')

Bases: mirage.libs.esb_utils.packets.ESBPacket

Mirage Enhanced ShockBurst Packet - Logitech Unencrypted Key Release Packet

Parameters

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – bytes indicating the payload’s value (e.g. b””)

  • hidData (bytes) – value of HID data in use

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.esb_utils.packets.ESBPacket(protocol=None, address='00:00:00:00:00', payload=None)

Bases: mirage.libs.wireless_utils.packets.Packet

Mirage Enhanced ShockBurst Packet

Parameters

  • protocol (str) – string indicating the applicative protocol in use

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – payload of the 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.esb_utils.packets.ESBPingRequestPacket(address='00:00:00:00:00', payload=b'\x0f\x0f\x0f\x0f')

Bases: mirage.libs.esb_utils.packets.ESBPacket

Mirage Enhanced ShockBurst Packet - Ping Request

Parameters

  • address (str) – address of the emitter of the frame (e.g. ‘11:22:33:44:55’)

  • payload (bytes) – bytes indicating the payload’s value (e.g. b””)

class mirage.libs.esb_utils.packets.ESBSniffingParameters(channel=None, frequency=None)

Bases: mirage.libs.wireless_utils.packets.AdditionalInformations

This class allows to attach some sniffer’s data to a Enhanced ShockBurst Packet, such as channel. If the frequency is provided, the corresponding channel is automatically calculated.

Parameters

  • channel (int) – channel of the received packet

  • frequency (float) – frequency of the received packet

toString()

mirage.libs.esb_utils.scapy_esb_layers module

This module contains some scapy definitions for Enhanced ShockBurst packets.