mirage.libs.mosart_utils package

Submodules

mirage.libs.mosart_utils.rfstorm module

class mirage.libs.mosart_utils.rfstorm.MosartRFStormDevice(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 Mosart frames. The corresponding interfaces are : rfstormX (e.g. “rfstorm0”)

The following capabilities are actually supported :

Capability

Available ?

SNIFFING_NORMAL

yes

SNIFFING_PROMISCUOUS

yes

INJECTING

yes

INJECTING_SYNC

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.

disableDonglePackets()

This method enables the reception of dongle packets.

Example
>>> device.disableDonglePackets()

Note

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

disableSync()

This method disables the synchronization mode. The frames transmitted by a Mosart mouse or keyboard are synchronized with the synchronization packets transmitted by the dongle. If the synchronization mode is enabled, every transmitted frame will be synchronized using these packets. If the synchronization mode is disabled, every transmitted frame will be sent as soon as possible.

Example
>>> device.enableSync()

Note

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

enableDonglePackets()

This method enables the reception of dongle packets.

Example
>>> device.enableDonglePackets()

Note

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

enableSync()

This method enables the synchronization mode. The frames transmitted by a Mosart mouse or keyboard are synchronized with the synchronization packets transmitted by the dongle. If the synchronization mode is enabled, every transmitted frame will be synchronized using these packets. If the synchronization mode is disabled, every transmitted frame will be sent as soon as possible.

Example
>>> device.enableSync()

Note

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

enterPromiscuousMode()

This method allows to put your device into promiscuous mode.

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

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

Return type

str

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

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, SNIFFER)

Returns

current mode in use

Return type

str

Example
>>> device.enterSnifferMode('AA:BB:CC:DD')
>>> 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.

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

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

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', 'enterSnifferMode', 'getAddress', 'setAddress', 'getMode', 'enableDonglePackets', 'disableDonglePackets', 'enableSync', 'disableSync']

mirage.libs.mosart_utils.dissectors module

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

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the Mosart keystroke payload. It inherits from Dissector.

The following fields are available in the data structure :
  • hidCode : integer indicating the hid code of the key

  • modifiers : integer indicating the modifiers code of the key

Example
>>> MosartKeystroke(hidCode=5,modifiers=0).data.hex()
'812d'
>>> MosartKeystroke(data=bytes.fromhex("812d")).hidCode
5
>>> MosartKeystroke(data=bytes.fromhex("812d")).modifiers
0
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.mosart_utils.constants module

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

class mirage.libs.mosart_utils.constants.MosartOperationMode

Bases: object

PROMISCUOUS = 0
SNIFFER = 1

mirage.libs.mosart_utils.pcap module

class mirage.libs.mosart_utils.pcap.MosartPCAPDevice(interface)

Bases: mirage.libs.wireless_utils.pcapDevice.PCAPDevice

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

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

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

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

The following capabilities are actually supported :

Capability

Available ?

SNIFFING_NORMAL

yes

SNIFFING_PROMISCUOUS

yes

INJECTING

yes

INJECTING_SYNC

no

Warning

This PCAP Device uses the DLT 149.

DLT = 149
SCAPY_LAYER

alias of mirage.libs.mosart_utils.scapy_mosart_layers.Mosart_Hdr

buildPacket(packet, timestamp)

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

disableDonglePackets()

This method enables the reception of dongle packets.

Example
>>> device.disableDonglePackets()

Note

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

enableDonglePackets()

This method enables the reception of dongle packets.

Example
>>> device.enableDonglePackets()

Note

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

enterPromiscuousMode()

This method allows to put your device into promiscuous mode.

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

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

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', 'disableDonglePackets', 'enableDonglePackets', 'getChannel', 'setChannel', 'getMode', 'generateStream']

mirage.libs.mosart_utils.helpers module

mirage.libs.mosart_utils.helpers.addressToInteger(address)

This function converts a string indicating the address of a Mosart device to its raw value (as integer).

Parameters

address (str) – string to convert (format: ‘11:22:33:44’)

Example
>>> hex(addressToInteger('11:22:33:44'))
'0x11223344'
mirage.libs.mosart_utils.helpers.crc(data)

This function returns the CRC of a Mosart payload.

Parameters

data (bytes) – bytes of the payload

mirage.libs.mosart_utils.helpers.integerToAddress(integer)

This function converts a Mosart address to a printable string.

Parameters

integer – address to convert

Example
>>> integerToAddress(0x11223344)
'11:22:33:44'

mirage.libs.mosart_utils.keyboard_codes module

class mirage.libs.mosart_utils.keyboard_codes.MosartKeyboardCodes

Bases: object

This class allows to convert the Mosart keyboard codes to the corresponding HID code and modifiers.

Warning

These values have been collected empirically. As a result, the corresponding mapping may contains some mistakes or missing data.

classmethod getHIDCodeFromMosartKeyboardCode(code)
classmethod getMosartKeyboardCodeFromHIDCode(hidCode, modifiers)

This method returns the Mosart keybaord

mosartKeyboardCodes = {8: [72, 0], 12: [0, 16], 14: [0, 1], 15: [62, 0], 16: [20, 0], 17: [43, 0], 18: [4, 0], 19: [41, 0], 20: [29, 0], 21: [139, 0], 22: [53, 0], 23: [30, 0], 24: [26, 0], 25: [57, 0], 26: [22, 0], 27: [100, 0], 28: [27, 0], 29: [138, 0], 30: [58, 0], 31: [31, 0], 32: [8, 0], 33: [60, 0], 34: [7, 0], 35: [61, 0], 36: [6, 0], 37: [136, 0], 38: [59, 0], 39: [32, 0], 40: [21, 0], 41: [23, 0], 42: [9, 0], 43: [10, 0], 44: [25, 0], 45: [5, 0], 46: [34, 0], 47: [33, 0], 48: [24, 0], 49: [28, 0], 50: [13, 0], 51: [11, 0], 52: [16, 0], 53: [17, 0], 54: [35, 0], 55: [36, 0], 56: [12, 0], 57: [48, 0], 58: [14, 0], 59: [63, 0], 60: [54, 0], 61: [135, 0], 62: [46, 0], 63: [37, 0], 64: [18, 0], 65: [64, 0], 66: [15, 0], 68: [55, 0], 69: [101, 0], 70: [65, 0], 71: [38, 0], 72: [19, 0], 73: [47, 0], 74: [51, 0], 75: [52, 0], 76: [50, 0], 77: [56, 0], 78: [45, 0], 79: [39, 0], 80: [71, 0], 83: [0, 4], 85: [0, 64], 87: [70, 0], 88: [137, 0], 89: [42, 0], 90: [49, 0], 91: [68, 0], 92: [40, 0], 93: [69, 0], 94: [66, 0], 95: [67, 0], 96: [95, 0], 97: [92, 0], 98: [89, 0], 99: [44, 0], 100: [83, 0], 101: [81, 0], 102: [76, 0], 104: [96, 0], 105: [93, 0], 106: [90, 0], 107: [98, 0], 108: [84, 0], 109: [79, 0], 110: [73, 0], 112: [97, 0], 113: [94, 0], 114: [91, 0], 115: [99, 0], 116: [85, 0], 117: [86, 0], 118: [75, 0], 119: [78, 0], 120: [87, 0], 121: [133, 0], 122: [88, 0], 123: [82, 0], 125: [80, 0], 126: [74, 0], 127: [77, 0], 129: [0, 2], 130: [0, 32], 137: [0, 8], 144: [145, 0], 146: [0, 128], 151: [144, 0], 152: [98, 0], 153: [98, 0], 154: [0, 9], 155: [0, 8], 156: [0, 9], 157: [0, 8], 158: [0, 4]}

mirage.libs.mosart_utils.packets module

class mirage.libs.mosart_utils.packets.MosartDonglePacket(address=None, payload=None)

Bases: mirage.libs.mosart_utils.packets.MosartPacket

Mirage Mosart Packet - Dongle Sync / Acknowledgment

Parameters
  • address (str) – string indicating the address of the transmitter (format: ‘11:22:33:44’)

  • payload (bytes) – payload of 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.mosart_utils.packets.MosartKeyboardKeystrokePacket(sequenceNumber=0, address=None, payload=None, code=None, stateCode=None, state=None, hidCode=None, modifiers=None)

Bases: mirage.libs.mosart_utils.packets.MosartPacket

Mirage Mosart Packet - Keyboard Keystroke

Parameters
  • address (str) – string indicating the address of the transmitter (format: ‘11:22:33:44’)

  • sequenceNumber (int) – sequence number of the packet

  • payload (bytes) – payload of the packet

  • code (int) – Mosart code indicating the selected key

  • stateCode (int) – Mosart code indicating the state of the selected key

  • state (str) – string indicating the state of the selected button (“pressed”, “released”, “unknown”)

  • hidCode (int) – HID code of the selected key

  • modifiers (int) – HID modifiers of the selected 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.mosart_utils.packets.MosartMouseClickPacket(sequenceNumber=0, address=None, payload=None, code=None, stateCode=None, state=None, button='')

Bases: mirage.libs.mosart_utils.packets.MosartPacket

Mirage Mosart Packet - Mouse Click

Parameters
  • address (str) – string indicating the address of the transmitter (format: ‘11:22:33:44’)

  • sequenceNumber (int) – sequence number of the packet

  • payload (bytes) – payload of the packet

  • code (int) – Mosart code indicating the selected button

  • stateCode (int) – Mosart code indicating the state of the selected button

  • state (str) – string indicating the state of the selected button (“pressed”, “released”, “unknown”)

  • button (str) – string indicating the selected button (“right”, “left”, “middle”)

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.mosart_utils.packets.MosartMouseMovementPacket(sequenceNumber=0, address=None, payload=None, x1=0, x2=0, y1=0, y2=0)

Bases: mirage.libs.mosart_utils.packets.MosartPacket

Mirage Mosart Packet - Mouse Movement

Parameters
  • address (str) – string indicating the address of the transmitter (format: ‘11:22:33:44’)

  • sequenceNumber (int) – sequence number of the packet

  • payload (bytes) – payload of the packet

  • x1 (int) – X coordinate of the velocity vector (first)

  • x2 (int) – X coordinate of the velocity vector (second)

  • y1 (int) – Y coordinate of the velocity vector (first)

  • y2 (int) – Y coordinate of the velocity vector (second)

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.mosart_utils.packets.MosartPacket(address='00:00:00:00', sequenceNumber=0, deviceType=None, payload=None)

Bases: mirage.libs.wireless_utils.packets.Packet

Mirage Mosart Packet

Parameters
  • address (str) – string indicating the address of the transmitter (format: ‘11:22:33:44’)

  • sequenceNumber (int) – sequence number of the packet

  • deviceType (str) – string indicating the device type of the packet (“keyboard”, “mouse” or “dongle”)

  • payload (bytes) – payload of 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.mosart_utils.packets.MosartSniffingParameters(channel=None)

Bases: mirage.libs.wireless_utils.packets.AdditionalInformations

This class allows to attach some sniffer’s data to a Mirage Mosart Packet, such as channel.

Parameters

channel (int) – channel of the received packet

toString()

mirage.libs.mosart_utils.scapy_mosart_layers module

This module contains some scapy definitions for Mosart packets.