mirage.libs package

Subpackages

Submodules

mirage.libs.ble module

class mirage.libs.ble.BLEEmitter(interface='hci0')

Bases: mirage.libs.wireless.Emitter

This class is an Emitter for the Bluetooth Low Energy protocol (“ble”).

It can instantiates the following devices :

  • HCI Device (mirage.libs.ble.BLEHCIDevice) [ interface “hciX” (e.g. “hci0”) ]

  • Ubertooth Device (mirage.libs.ble_utils.ubertooth.BLEUbertoothDevice) [ interface “ubertoothX” (e.g. “ubertooth0”) ]

  • BTLEJack Device (mirage.libs.ble_utils.btlejack.BTLEJackDevice) [ interface “microbitX” (e.g. “microbit0”) ]

  • ADB Device (mirage.libs.ble_utils.adb.ADBDevice) [ interface “adbX” (e.g. “adb0”) ]

  • HCIDump Device (mirage.libs.ble_utils.hcidump.BLEHcidumpDevice) [ interface “hcidumpX” (e.g. “hcidump0”) ]

  • PCAP Device (mirage.libs.ble_utils.pcap.BLEPCAPDevice) [ interface “<file>.pcap” (e.g. “pairing.pcap”) ]

convert(packet)

This method converts a Mirage Packet into a raw Packet (e.g. bytes array or scapy frame). It must be overloaded by child classes.

Parameters

packet (mirage.libs.wireless_utils.packets.Packet) – Mirage Packet to convert

Returns

raw representation of a packet

class mirage.libs.ble.BLEHCIDevice(interface)

Bases: mirage.libs.bt.BtHCIDevice

This device allows to communicate with an HCI Device in order to use Bluetooth Low Energy protocol. The corresponding interfaces are : hciX (e.g. “hciX”)

The following capabilities are actually supported :

Capability

Available ?

SCANNING

yes

ADVERTISING

yes

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

yes

RECEIVING_CONNECTION

yes

COMMUNICATING_AS_MASTER

yes

COMMUNICATING_AS_SLAVE

yes

HCI_MONITORING

no

This method sends an encryption request to the current connection established and encrypts the link if possible.

Parameters

  • rand (bytes) – random value

  • ediv (int) – EDIV value

  • ltk (bytes) – Long Term Key

Returns

boolean indicating if the link was successfully encrypted

Return type

bool

Example
>>> device.encryptLink(ltk=bytes.fromhex("000102030405060708090a0b0c0d0e0f")) # Short Term Key, ediv = rand = 0
True

See also

It is possible to encrypt the link using directly the encryption-related packets, such as :

  • mirage.libs.ble_utils.packets.BLELongTermKeyRequest

  • mirage.libs.ble_utils.packets.BLELongTermKeyRequestReply

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.

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.

getMode()

This method returns the current mode used by the HCI Device. Three modes are available and indicates the current state of the device: “NORMAL”, “SCANNING” and “ADVERTISING”

Returns

string indicating the current mode

Return type

str

Example
>>> device.getMode()
'NORMAL'
>>> device.setScan(enable=True)
>>> device.getMode()
'SCANNING'

Note

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

init()

This method initializes the communication with the HCI Device.

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("12:34:56:78:9A:BC",random=True) # set the device's address to 12:34:56:78:9A:BC (random)
[INFO] Changing HCI Device (hci0) Random Address to : 12:34:56:78:9A:BC
[SUCCESS] BD Address successfully modified !
True
>>> device.setAddress("12:34:56:78:9A:BC") # set the device's address to 12:34:56:78:9A:BC (public)
[INFO] Changing HCI Device (hci0) Address to : 12:34:56:78:9A:BC
[SUCCESS] BD Address successfully modified !
True
>>> device2.setAddress("12:34:56:78:9A:BC")
[INFO] Changing HCI Device (hci0) Address to : 12:34:56:78:9A:BC
[ERROR] The vendor has not provided a way to modify the BD Address.
False

Warning

Mirage uses some vendor specific HCI Commands in order to modify the public BD address. If the vendor has not provided a way to modify the BD address, it is not possible to change it (see device2 in the example section).

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) # scanning mode enabled
>>> device.setAdvertising(enable=False) # scanning 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.

setScan(enable=True, passive=False)

This method enables or disables the scanning mode.

Parameters

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

  • passive (bool) – boolean indicating if the scan has to be passive (e.g. no SCAN_REQ)

Example
>>> device.setScan(enable=True, passive=True) # scanning mode enabled in passive mode
>>> device.setScan(enable=False) # scanning mode disabled

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.

sharedMethods = ['getConnections', 'switchConnection', 'getCurrentConnection', 'getCurrentConnectionMode', 'getAddressByHandle', 'getCurrentHandle', 'isConnected', 'setScan', 'setAdvertising', 'setAdvertisingParameters', 'setScanningParameters', 'getAddress', 'setAddress', 'getMode', 'getAddressMode', 'getManufacturer', 'isAddressChangeable', 'encryptLink', 'updateConnectionParameters']
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.

class mirage.libs.ble.BLEReceiver(interface='hci0')

Bases: mirage.libs.wireless.Receiver

This class is a Receiver for the Bluetooth Low Energy protocol (“ble”).

It can instantiates the following devices :

  • HCI Device (mirage.libs.ble.BLEHCIDevice) [ interface “hciX” (e.g. “hci0”) ]

  • Ubertooth Device (mirage.libs.ble_utils.ubertooth.BLEUbertoothDevice) [ interface “ubertoothX” (e.g. “ubertooth0”) ]

  • BTLEJack Device (mirage.libs.ble_utils.btlejack.BTLEJackDevice) [ interface “microbitX” (e.g. “microbit0”) ]

  • ADB Device (mirage.libs.ble_utils.adb.ADBDevice) [ interface “adbX” (e.g. “adb0”) ]

  • HCIDump Device (mirage.libs.ble_utils.hcidump.BLEHcidumpDevice) [ interface “hcidumpX” (e.g. “hcidump0”) ]

  • PCAP Device (mirage.libs.ble_utils.pcap.BLEPCAPDevice) [ interface “<file>.pcap” (e.g. “pairing.pcap”) ]

convert(packet)

This method converts a raw Packet (e.g. bytes array or scapy frame) into a Mirage Packet. It must be overloaded by child classes.

Parameters

data – raw representation of a packet

Returns

Mirage packet

Return type

mirage.libs.wireless_utils.packets.Packet

stop()

Stops the Receiver and the associated device

mirage.libs.bt module

class mirage.libs.bt.BluetoothEmitter(interface='hci0')

Bases: mirage.libs.wireless.Emitter

This class is an Emitter for the Bluetooth protocol (“bt”).

It can instantiates the following devices :

  • HCI Device (mirage.libs.bt.BtHCIDevice)

convert(p)

This method converts a Mirage Packet into a raw Packet (e.g. bytes array or scapy frame). It must be overloaded by child classes.

Parameters

packet (mirage.libs.wireless_utils.packets.Packet) – Mirage Packet to convert

Returns

raw representation of a packet

class mirage.libs.bt.BluetoothReceiver(interface='hci0')

Bases: mirage.libs.wireless.Receiver

This class is a Receiver for the Bluetooth protocol (“bt”).

It can instantiates the following devices :

  • HCI Device (mirage.libs.bt.BtHCIDevice)

convert(packet)

This method converts a raw Packet (e.g. bytes array or scapy frame) into a Mirage Packet. It must be overloaded by child classes.

Parameters

data – raw representation of a packet

Returns

Mirage packet

Return type

mirage.libs.wireless_utils.packets.Packet

stop()

Stops the Receiver and the associated device

class mirage.libs.bt.BtHCIDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

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

getAddress()

This method returns the actual BD address of the HCI 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.

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 / 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'},{'handle':73, 'address':'11:22:33:44:55:66'}]

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.send(HCI_Hdr()/HCI_Command_Hdr()/HCI_Cmd_Disconnect())
>>> device.getCurrentConnection()
None

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.

getLocalName()

This method returns the local name of the HCI Device.

Returns

name

Return type

str

Example
>>> device.getLocalName()
'toto'

Note

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

getManufacturer()

This method returns the human readable name of the manufacturer of the HCI Device.

Returns

manufacturer’s name

Return type

str

Example
>>> device.getManufacturer()
'Realtek Semiconductor Corporation'

Note

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

init()

This method initializes the communication with the HCI Device.

isAddressChangeable()

This method returns a boolean indicating if the manufacturer of the HCI Device provides some packets allowing to change the BD address.

Returns

boolean indicating if the BD address can be changed

Return type

bool

Example
>>> device.isAddressChangeable()
True
>>> device2.isAddressChangeable()
False

Note

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

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 allows to receive raw HCI packets from the HCI device.

send(data)

This method allows to send raw HCI packet to the HCI device.

setAddress(address)

This method allows to change the BD address (if it is possible).

Parameters

address (str) – new BD address

Returns

boolean indicating if the operation was successful

Return type

bool

Example
>>> device.getAddress()
'1A:2B:3C:4D:5E:6F'
>>> device.setAddress('11:22:33:44:55:66')
[INFO] Changing HCI Device (hci0) Address to : 11:22:33:44:55:66
[SUCCESS] BD Address successfully modified !
True
>>> device.getAddress()
'11:22:33:44:55:66'

Note

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

setLocalName(name)

This method changes the local name of the HCI Device.

Parameters

name (str) – new name

Example
>>> device.setLocalName("toto")

Note

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

sharedMethods = ['getConnections', 'switchConnection', 'getCurrentConnection', 'getAddressByHandle', 'getCurrentHandle', 'isConnected', 'setLocalName', 'getLocalName', 'getAddress', 'setAddress', 'getManufacturer', 'isAddressChangeable']
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.wifi module

class mirage.libs.wifi.WifiDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with a WiFi Device. The corresponding interfaces are : wlanX (e.g. “wlanX”)

The following capabilities are actually supported :

Capability

Available ?

SCANNING

yes

MONITORING

yes

COMMUNICATING_AS_ACCESS_POINT

yes

COMMUNICATING_AS_STATION

yes

JAMMING

no
down()

This method allows to set down the interface corresponding to the current device.

Returns

boolean indicating if the operation is successful

Return type

bool

getAddress()

This method allows to get the MAC address currently in use by the device.

Returns

string indicating the MAC address currently in ues

Return type

str

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

Note

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

getChannel()

This method allows to get the channel currently in use by the corresponding Device.

Returns

channel currently in use

Return type

int

Example
>>> device.getChannel()
11

Note

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

getFrequency()

This method allows to get the frequency currently in use by the corresponding Device.

Returns

frequency currently in use (in Hz)

Return type

int

Example
>>> device.getFrequency()
2462000000

Note

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

getMode()

This method allows to get the mode currently in use.

Existing modes:

  • ‘Auto’

  • ‘Ad-Hoc’

  • ‘Managed’

  • ‘Master’

  • ‘Repeat’

  • ‘Second’

  • ‘Monitor’

  • ‘Unknown/bug’

Returns

string indicating the mode in use

Return type

str

Example
>>> device.getMode()
'Auto'
>>> device.setMode("Monitor")
>>> device.getMode()
'Monitor'

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

listen(callback=None)

This method replaces the recv method, in order to reuse scapy’s receiver optimization. It’s the reason why the _task method will also be redefined in mirage.libs.wifi.WifiReceiver.

Parameters

callback (function) – reception callback

send(data)

This method sends some datas.

Parameters

data – raw representation of the data to send

setChannel(channel)

This method allows to set the channel to use by the corresponding Device.

Parameters

channel (int) – channel to use

Returns

boolean indicating if the channel change operation is successful

Return type

bool

Example
>>> device.setChannel(11)
True

Note

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

setFrequency(frequency)

This method allows to set the frequency to use by the corresponding Device.

Parameters

frequency (int) – frequency to use (in Hz)

Returns

boolean indicating if the frequency change operation is successful

Return type

bool

Example
>>> device.setFrequency(2462000000)
True

Note

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

setMode(mode)

This method allows to set the mode currently in use.

Existing modes:

  • ‘Auto’

  • ‘Ad-Hoc’

  • ‘Managed’

  • ‘Master’

  • ‘Repeat’

  • ‘Second’

  • ‘Monitor’

  • ‘Unknown/bug’

Parameters

mode (str) – string indicating the mode to use

Returns

boolean indicating if the operation was successful

Return type

bool

Example
>>> device.getMode()
'Auto'
>>> device.setMode("Monitor")
>>> device.getMode()
'Monitor'

Note

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

setMonitorMode(enable=True)

This method allows to switch on or off the monitor mode.

Parameters

enable (bool) – boolean indicating if the monitor mode should be enabled or disabled.

Example
>>> device.getMode()
'Managed'
>>> device.setMonitorMode(enable=True)
>>> device.getMode()
'Monitor'

Note

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

sharedMethods = ['setChannel', 'getChannel', 'getFrequency', 'setFrequency', 'setMonitorMode', 'getAddress', 'getMode', 'setMode']
up()

This method allows to set up the interface corresponding to the current device.

Returns

boolean indicating if the operation is successful

Return type

bool

class mirage.libs.wifi.WifiEmitter(interface='wlp2s0')

Bases: mirage.libs.wireless.Emitter

convert(packet)

This method converts a Mirage Packet into a raw Packet (e.g. bytes array or scapy frame). It must be overloaded by child classes.

Parameters

packet (mirage.libs.wireless_utils.packets.Packet) – Mirage Packet to convert

Returns

raw representation of a packet

class mirage.libs.wifi.WifiReceiver(interface='wlp2s0', monitorMode=True)

Bases: mirage.libs.wireless.Receiver

convert(packet)

This method converts a raw Packet (e.g. bytes array or scapy frame) into a Mirage Packet. It must be overloaded by child classes.

Parameters

data – raw representation of a packet

Returns

Mirage packet

Return type

mirage.libs.wireless_utils.packets.Packet

mirage.libs.esb module

class mirage.libs.esb.ESBEmitter(interface='rfstorm0')

Bases: mirage.libs.wireless.Emitter

This class is an Emitter for the Enhanced ShockBurst protocol (“esb”).

It can instantiates the following devices :

  • RFStorm Device (mirage.libs.esb_utils.rfstorm.ESBRFStormDevice) [ interface “rfstormX” (e.g. “rfstormX”) ]

  • PCAP Device (mirage.libs.esb_utils.pcap.ESBPCAPDevice) [ interface “<file>.pcap” (e.g. “capture.pcap”) ]

convert(packet)

This method converts a Mirage Packet into a raw Packet (e.g. bytes array or scapy frame). It must be overloaded by child classes.

Parameters

packet (mirage.libs.wireless_utils.packets.Packet) – Mirage Packet to convert

Returns

raw representation of a packet

class mirage.libs.esb.ESBReceiver(interface='rfstorm0')

Bases: mirage.libs.wireless.Receiver

This class is a Receiver for the Enhanced ShockBurst protocol (“esb”).

It can instantiates the following devices :

  • RFStorm Device (mirage.libs.esb_utils.rfstorm.ESBRFStormDevice) [ interface “rfstormX” (e.g. “rfstormX”) ]

  • PCAP Device (mirage.libs.esb_utils.pcap.ESBPCAPDevice) [ interface “<file>.pcap” (e.g. “capture.pcap”) ]

convert(packet)

This method converts a raw Packet (e.g. bytes array or scapy frame) into a Mirage Packet. It must be overloaded by child classes.

Parameters

data – raw representation of a packet

Returns

Mirage packet

Return type

mirage.libs.wireless_utils.packets.Packet

mirage.libs.mosart module

class mirage.libs.mosart.MosartEmitter(interface='rfstorm0')

Bases: mirage.libs.wireless.Emitter

convert(packet)

This method converts a Mirage Packet into a raw Packet (e.g. bytes array or scapy frame). It must be overloaded by child classes.

Parameters

packet (mirage.libs.wireless_utils.packets.Packet) – Mirage Packet to convert

Returns

raw representation of a packet

class mirage.libs.mosart.MosartReceiver(interface='rfstorm0')

Bases: mirage.libs.wireless.Receiver

convert(packet)

This method converts a raw Packet (e.g. bytes array or scapy frame) into a Mirage Packet. It must be overloaded by child classes.

Parameters

data – raw representation of a packet

Returns

Mirage packet

Return type

mirage.libs.wireless_utils.packets.Packet

mirage.libs.zigbee module

class mirage.libs.zigbee.ZigbeeEmitter(interface)

Bases: mirage.libs.wireless.Emitter

convert(packet)

This method converts a Mirage Packet into a raw Packet (e.g. bytes array or scapy frame). It must be overloaded by child classes.

Parameters

packet (mirage.libs.wireless_utils.packets.Packet) – Mirage Packet to convert

Returns

raw representation of a packet

class mirage.libs.zigbee.ZigbeeReceiver(interface)

Bases: mirage.libs.wireless.Receiver

convert(packet)

This method converts a raw Packet (e.g. bytes array or scapy frame) into a Mirage Packet. It must be overloaded by child classes.

Parameters

data – raw representation of a packet

Returns

Mirage packet

Return type

mirage.libs.wireless_utils.packets.Packet

mirage.libs.ir module

class mirage.libs.ir.IREmitter(interface='irma0')

Bases: mirage.libs.wireless.Emitter

convert(p)

This method converts a Mirage Packet into a raw Packet (e.g. bytes array or scapy frame). It must be overloaded by child classes.

Parameters

packet (mirage.libs.wireless_utils.packets.Packet) – Mirage Packet to convert

Returns

raw representation of a packet

class mirage.libs.ir.IRReceiver(interface='irma0')

Bases: mirage.libs.wireless.Receiver

convert(packet)

This method converts a raw Packet (e.g. bytes array or scapy frame) into a Mirage Packet. It must be overloaded by child classes.

Parameters

data – raw representation of a packet

Returns

Mirage packet

Return type

mirage.libs.wireless_utils.packets.Packet

mirage.libs.io module

class mirage.libs.io.MiceVisualizer(datas=[], outputFile='mice.gif', lineColor='tab:blue', leftClickColor='tab:red', rightClickColor='tab:purple', showStart=False)

Bases: object

This class allows to import some mouse movement and click data in order to generate a graphical view of the mouse behaviour. It requires to provide a list of dictionary containing the following fields:

  • x: x coordinate of the velocity vector

  • y: y coordinate of the velocity vector

  • leftClick: boolean indicating if the left button is pressed

  • rightClick: boolean indicating if the right button is pressed

The execution of this component may take a few minutes if the provided data is big. It produces an animated GIF file.

Parameters

  • datas (list of dict) – list of dictionnary containing the mouse movements and clicks.

  • outputFile (str) – string indicating the output filename (animated GIF format)

  • lineColor (str) – string indicating the line color (default: blue)

  • leftClickColor (str) – string indicating the left click color (default: red)

  • rightClickColor (str) – string indicating the right click color (default: purple)

  • showStart (bool) – boolean indicating if the first movement (from the point (0,0) to the first provided coordinates) should be displayed

visualize()

This method generates the output GIF file, according to the provided parameters.

class mirage.libs.io.VerbosityLevels(value)

Bases: enum.IntEnum

This class provide an enumeration of available verbosity levels :

  • NONE prints no message at all

  • NO_INFO_AND_WARNING prints only failure and success messages

  • NO_INFO prints only failure, success and warning messages

  • ALL prints every type of messages

ALL = 3
NONE = 0
NO_INFO = 2
NO_INFO_AND_WARNING = 1
mirage.libs.io.ask(prompt, default='', final=': ')

This function allows to ask the user to provide an information as a string. It is possible to provide a default value, that will be used if the user provide nothing. It is also possible to change the final character to customize this user interaction function.

Parameters

  • prompt (str) – message to display before the entry field

  • default (str) – default value

  • final (str) – final character

Returns

string provided by the user

Return type

str

Example
>>> io.ask("Enter your age",default=25,final=": ")
[QUESTION] Enter your age [25] : 26
'26'
mirage.libs.io.banner()

This function returns the banner.

Returns

banner of Mirage

Return type

str

mirage.libs.io.chart(columnsName, content, title='')

This function displays a table containing multiple informations provided by the user. He can provide a header name for each column thanks to columnsName, and content allows him to provide the data. He can also provide an (optional) title, by using the title parameters.

Parameters

  • columnsName (list of str) – list of strings indicating the header name for every columns

  • content (list of (list of str)) – matrix of data to include in the table

Example
>>> io.chart(["A","B","A xor B"],[
...                               ["False","False","False"],
...                               ["True","False","True"],
...                               ["False", "True", "True"],
...                               ["True", "True", "False"]
...                              ],title="XOR Table")
┌XOR Table──────┬─────────┐
│ A     │ B     │ A xor B │
├───────┼───────┼─────────┤
│ False │ False │ False   │
│ True  │ False │ True    │
│ False │ True  │ True    │
│ True  │ True  │ False   │
└───────┴───────┴─────────┘
mirage.libs.io.colorCode(selectedColor)

This function returns the right color code according to the color string provided.

Parameters

selectedColor (str) – string describing a color (“red”, “purple”, “cyan”, “blue”, “yellow”, “green” or “white”)

Returns

string containing the right color code

Return type

str

mirage.libs.io.colorize(message, color)

This function returns the message with a specific color code, allowing to print colored messages.

Parameters

  • message (str) – string to color

  • color (str) – string describing a color (“red”, “purple”, “cyan”, “blue”, “yellow”, “green” or “white”)

Returns

string containing the right color code and the message

Return type

str

mirage.libs.io.displayPacket(packet)

This function displays a packet as an information message.

Parameters

packet (mirage.libs.wireless_utils.packets.Packet) – packet to display

mirage.libs.io.enterPinCode(message='Enter pin code: ', maxLength=6)

This function asks the user to enter a PIN code, and checks if the provided answer is valid.

Parameters

  • message (str) – message to display

  • maxLength (int) – maximum length of the PIN code

Return pinCode

string provided by the user, composed of digits

Return type

str

mirage.libs.io.fail(message)

This function displays a failure message.

Parameters

message (str) – message to display

mirage.libs.io.info(message)

This function displays an information message.

Parameters

message (str) – message to display

mirage.libs.io.progress(count, total=100, suffix='')

This function displays a progress bar. This bar is not automatically filled, the user has to call progress with the right values multiple times.

Parameters

  • count (int) – number describing the value of the progress bar

  • total (int) – number describing the maximal value of the progress bar

Returns

boolean indicating if the progressbar is not full (it returns True if the progressbar is not full and False if it is full)

Example
>>> io.progress(0, total=100, suffix="youpi")
True__________________________________________________________) youpi
>>> io.progress(20, total=100, suffix="youpi")
True))))))))))________________________________________________) youpi
>>> io.progress(65, total=100, suffix="youpi")
True)))))))))))))))))))))))))))))))))))))_____________________) youpi
>>> io.progress(95, total=100, suffix="youpi")
True)))))))))))))))))))))))))))))))))))))))))))))))))))))))___) youpi
>>> io.progress(100, total=100, suffix="Done")
()))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))) Done
False
mirage.libs.io.success(message)

This function displays a success message.

Parameters

message (str) – message to display

mirage.libs.io.warning(message)

This function displays a warning message.

Parameters

message (str) – message to display

mirage.libs.utils module

mirage.libs.utils.addTask(function, name='', args=[], kwargs={})

This function allows to quickly add a new background task.

Parameters

  • function (function) – function to add as a background task

  • name (str) – name of the background task

  • args (list) – list of unnamed arguments

  • kwargs (dict) – dictionary of named arguments

Returns

real name of the task (may be suffixed / see core.taskManager.addTask)

Return type

str

Example

>>> def f(name):
>>>     print("Hello, "+name)
>>> fTask = utils.addTask(f,args=["user"])

See also

core.taskManager.addTask

mirage.libs.utils.addressArg(arg)

This function converts the provided string into an address.

Parameters

arg (str) – string to convert

Returns

corresponding address

Return type

str

Example
>>> utils.addressArg("0a:0b:0c:0d:0e:0f")
'0A:0B:0C:0D:0E:0F'
mirage.libs.utils.booleanArg(arg)

This function converts the provided string into a boolean.

Parameters

arg (str) – string to convert

Returns

corresponding boolean

Return type

bool

Example
>>> utils.booleanArg("yes")
True
>>> utils.booleanArg("no")
False
>>> utils.booleanArg("true")
True
>>> utils.booleanArg("false")
False
mirage.libs.utils.exitMirage()

This function exits Mirage.

mirage.libs.utils.generateModulesDictionary(moduleDir, moduleUserDir)

This function generates a dictionary of Mirage modules, by including files stored in moduleDir and moduleUserDir.

Parameters

  • moduleDir (str) – path of Mirage’s modules directory

  • moduleUserDir (str) – path of Mirage’s user modules directory

Returns

dictionary of Mirage’s modules

Return type

dict of str: module

mirage.libs.utils.generateScenariosDictionary(scenariosDir, scenariosUserDir)

This function generates a dictionary of Mirage scenarios, by including files stored in scenariosDir and scenariosUserDir.

Parameters

  • scenariosDir (str) – path of Mirage’s scenarios directory

  • scenariosUserDir (str) – path of Mirage’s user scenarios directory

Returns

dictionary of Mirage’s scenarios

Return type

dict of str: module

mirage.libs.utils.getHomeDir()

This function returns the path of the home directory.

Returns

path of the home directory

Return type

str

Example

>>> print(utils.getHomeDir())
mirage.libs.utils.getRandomAddress()

This function generates and returns a random address.

Returns

random address

Return type

str

Example
>>> utils.getRandomAddress()
'A1:96:8D:2F:9A:66'
>>> utils.getRandomAddress()
'9F:CD:E3:50:61:66'
>>> utils.getRandomAddress()
'E6:99:B7:42:32:95'
mirage.libs.utils.getTempDir()

This function returns the path of the temporary directory.

Returns

path of the temporary directory

Return type

str

Example

>>> print(utils.getTempDir())
mirage.libs.utils.initializeHomeDir()

This function initializes Mirage’s home directory. It creates the following files and directories under user’s home directory :

/home/user
        |_.mirage
                |_ modules (modules user directory)
                |_ scenarios (scenarios user directory)
                |_ mirage.cfg (configuration file)

It returns the path of Mirage’s home directory (e.g. “/home/user/.mirage”)

Returns

path of Mirage’s home directory

Return type

str

mirage.libs.utils.integerArg(arg)

This function converts the provided string into an integer.

Parameters

arg (str) – string to convert

Returns

corresponding integer

Return type

int

Example
>>> utils.integerArg("12")
12
>>> utils.integerArg("0x1234")
4660
mirage.libs.utils.isHexadecimal(theString)

This function checks if the provided string is an hexadecimal number.

Parameters

theString (str) – string to check

Returns

boolean indicating if the provided string is an hexadecimal number

Return type

bool

mirage.libs.utils.isNumber(theString)

This function checks if the provided string is a number.

Parameters

theString (str) – string to check

Returns

boolean indicating if the provided string is a number

Return type

bool

mirage.libs.utils.isPrintable(theString)

This function checks if the provided string is composed of printable characters.

Parameters

theString (str) – string to check

Returns

boolean indicating if the provided string is printable

Return type

bool

mirage.libs.utils.isRoot()

This function checks if the framework has been launched as root.

Returns

boolean indicating if the framework has been launched as root

Return type

bool

mirage.libs.utils.listArg(arg)

This function converts the provided string into a list of strings (splitted by “,”).

Parameters

arg (str) – string to convert

Returns

corresponding list of strings

Return type

list of str

Example
>>> utils.listArg("one,two,three")
["one","two","three"]
mirage.libs.utils.loadModule(name)

This function allows to load a module according to its name.

Parameters

name (str) – name of the module to load

Returns

instance of the loaded module

Return type

core.module.Module

Example

>>> module = utils.loadModule("ble_info")
>>> module["INTERFACE"] = "hci0"
>>> module.run()

See also

core.loader.load

mirage.libs.utils.now()

This function returns the current timestamp.

Returns

current timestamp

Return type

float

mirage.libs.utils.restartTask(name)

This function allows to restart a background task.

Parameters

name (str) – real name of the task to restart

Example

>>> utils.restartTask(fTask)

See also

core.taskManager.restartTask

mirage.libs.utils.startTask(name)

This function allows to start a background task.

Parameters

name (str) – real name of the task to start

Example

>>> utils.startTask(fTask)

See also

core.taskManager.startTask

mirage.libs.utils.stopAllSubprocesses()

This function stops all subprocesses of Mirage.

mirage.libs.utils.stopAllTasks()

This function allows to stop all the background tasks.

Example

>>> utils.stopAllTasks()

See also

core.taskManager.stopAllTasks

mirage.libs.utils.stopTask(name)

This function allows to stop a background task.

Parameters

name (str) – real name of the task to stop

Example

>>> utils.stopTask(fTask)

See also

core.taskManager.stopTask

mirage.libs.utils.wait(seconds=1, minutes=0, hours=0)

This function allows to wait for a given amount of time, provided by user.

Parameters

  • seconds (float) – seconds to wait

  • minutes (int) – minutes to wait

  • hours (int) – hours to wait

mirage.libs.wireless module

class mirage.libs.wireless.Emitter(interface, packetType=<class 'mirage.libs.wireless_utils.packets.Packet'>, deviceType=<class 'mirage.libs.wireless_utils.device.Device'>)

Bases: mirage.libs.wireless_utils.packetQueue.PacketQueue

This class allows an user to communicate with a device in order to send data. Indeed, Mirage provides no direct access to the device component from the modules : the hardware components are manipulated thanks to the Emitter class and the Receiver class. Emitters’ classes for a given technology inherits from this class. The packet are manipulated as an abstract representation in Emitters and Receivers (mirage.libs.wireless_utils.packets.Packet) and as a raw representation in Device (e.g. bytes array or scapy frame). That’s why an Emitter must implement the following method :

  • convert(self,packet) : this method converts a Mirage Packet into its raw representation

The constructor of an Emitter needs three parameters :

  • interface : indicating the interface to use to instantiate the device, generally it will be provided by the user

  • packetType : indicating the child class of Packet for the technology implemented by the Emitter

  • deviceType : indicating the child class of Device to instanciate

A _task method is implemented by default. It gets a Mirage Packet from the queue, calls the convert method on it and calls the send method of a Device on the result. If you want to customize this behaviour, you can overload this method.

convert(packet)

This method converts a Mirage Packet into a raw Packet (e.g. bytes array or scapy frame). It must be overloaded by child classes.

Parameters

packet (mirage.libs.wireless_utils.packets.Packet) – Mirage Packet to convert

Returns

raw representation of a packet

convertMiragePacketToRaw(data)

This method is an alias for the convert method of an emitter.

Parameters

data – raw representation of a packet

Returns

Mirage packet

Return type

mirage.libs.wireless_utils.packets.Packet

isTransmitting()

This method indicates if the Emitter is actually transmitting.

Returns

boolean indicating if the Emitter is actually transmitting

Return type

bool

Example
>>> emitter.isTransmitting()
True
send(*packets)

This method allows to send a Mirage Packet.

Parameters

*packets (mirage.libs.wireless_utils.packets.Packet (multiple)) – packets to send

Example
>>> emitter.send(packet1, packet2, packet3)
>>> emitter.send(packet1)
sendp(*packets)

This method is an alias for send.

Parameters

*packets (mirage.libs.wireless_utils.packets.Packet (multiple)) – packets to send

Example
>>> emitter.sendp(packet1, packet2, packet3)
>>> emitter.sendp(packet1)
stop()

Stops the Emitter and the associated device

updateSDRConfig(sdrConfig)

This method updates the SDR configuration if the corresponding device is an SDR Device.

class mirage.libs.wireless.Receiver(interface, packetType=<class 'mirage.libs.wireless_utils.packets.Packet'>, deviceType=<class 'mirage.libs.wireless_utils.device.Device'>)

Bases: mirage.libs.wireless_utils.packetQueue.PacketQueue

This class allows an user to communicate with a device in order to receive data. Indeed, Mirage provides no direct access to the device component from the modules : the hardware components are manipulated thanks to the Emitter class and the Receiver class. Receivers’ classes for a given technology inherits from this class.

The packet are manipulated as an abstract representation in Emitters and Receivers (mirage.libs.wireless_utils.packets.Packet) and as a raw representation in Device (e.g. bytes array or scapy frame). That’s why a Receiver must implement the following method :

  • convert(self,packet) : this method converts a raw representation of a packet into a Mirage Packet

The constructor of a Receiver needs three parameters :

  • interface : indicating the interface to use to instantiate the device, generally it will be provided by the user

  • packetType : indicating the child class of Packet for the technology implemented by the Emitter

  • deviceType : indicating the child class of Device to instanciate

A _task method is implemented by default. It calls the recv method of a Device, converts the result (if it is not None) to a Mirage Packet and adds it to the queue. If you want to customize this behaviour, you can overload this method.

clean()

This method removes every Mirage Packets stored in the queue.

Example
>>> receiver.clean()
convert(data)

This method converts a raw Packet (e.g. bytes array or scapy frame) into a Mirage Packet. It must be overloaded by child classes.

Parameters

data – raw representation of a packet

Returns

Mirage packet

Return type

mirage.libs.wireless_utils.packets.Packet

convertRawToMiragePacket(data)

This method is an alias for the convert method of a receiver.

Parameters

data – raw representation of a packet

Returns

Mirage packet

Return type

mirage.libs.wireless_utils.packets.Packet

isReceiving()

This method indicates if the Receiver is actually receiving.

Returns

boolean indicating if the Receiver is actually receiving

Return type

bool

Example
>>> receiver.isReceiving()
True
listenCallbacks()

Starts the foreground callbacks execution loop.

Example
>>> receiver.listenCallbacks()
next(timeout=None)

This method returns the next Mirage Packet stored in the queue.

Parameters

timeout (float) – time (in seconds) before the method fails

Example
>>> packet = receiver.next(timeout=1.0)
onEvent(event='*', callback=None, args=[], kwargs={}, background=True)

This function allows to attach a callback, triggered when some specific Mirage Packets are received. It is linked to an event, which is a string indicating when should the callback be called. Three formats exists describing an event :

  • * : indicating “the callback is called every times a packet is received”

  • n : indicating “the callback is called every times n packets have been received”

  • packetType : indicating “the callback is called every times a packet of type ‘packetType’ is received”

Some examples are represented in the following table:

Event

Description

*

every packet

3

every 3 packets

BLEReadRequest

every BLE Read Request

The function callback is called with the following format : callback(packet,*args,**kwargs) A callback can be run in the associated background thread (by default) or in foreground by using the methods listenCallbacks and stopListeningCallbacks.

Parameters

  • event (str) – string describing the associated event

  • callback (function) – function to call when the associated event is triggered

  • args (list) – unnamed arguments to provide to the function

  • kwargs (dict) – named arguments to provide to the function

  • background (bool) – boolean indicating if the callback is run in background or in foreground

Example
>>> def show(packet):
...     packet.show()
>>> receiver.onEvent("*", callback=show)
>>> def onReadRequest(packet,username):
...     io.info("Hello "+username+", I have an incoming Read Request for you : "+str(packet))
>>> receiver.onEvent("BLEReadRequest",callback=onReadRequest, args=["Romain"])
receive(nb=1, loop=False, timeout=None)

This method provide a generator allowing to iterate on the incoming Mirage Packets.

Parameters

  • nb (int) – number of packets to receive in the iterator

  • loop (bool) – boolean indicating if the packets must be continuously received

  • timeout (float) – time (in seconds) before a reception fails

Returns

generator of Mirage Packets (mirage.libs.wireless_utils.packets.Packet)

Example
>>> for packet in receiver.receive(nb=5):
...     packet.show()
<< Packet >>
<< Packet >>
<< Packet >>
<< Packet >>
<< Packet >>
>>> for packet in receiver.receive(loop=True, timeout=1.0):
...     if packet is not None:
...             packet.show()
...     else:
...             io.info("Timeout !")
[INFO] Timeout !
<< Packet >>
[INFO] Timeout !
[INFO] Timeout !
<< Packet >>
[...]
removeCallbacks()

Remove the callbacks attached to the Receiver.

skip(timeout=None)

This method skips the next Mirage Packet stored in the queue.

Parameters

timeout (float) – time (in seconds) before the method fails

Example
>>> receiver.skip(timeout=1.0)
stop()

Stops the Receiver and the associated device

stopListeningCallbacks()

Stops the foreground callbacks execution loop.

Example
>>> receiver.stopListeningCallbacks()
updateSDRConfig(sdrConfig)

This method updates the SDR configuration if the corresponding device is an SDR Device.