mirage.libs.wireless_utils package

Submodules

mirage.libs.wireless_utils.callbacks module

class mirage.libs.wireless_utils.callbacks.Callback(event='*', function=None, args=[], kwargs={}, background=True)

Bases: object

This class is an internal representation of a specific callback. It is linked to an event. An event is a string, some examples are represented in the following table:

Event	Description
*	every packet
3	every 3 packets
BLEReadRequest	every BLE Read Request

Some arguments can be passed to the constructor as parameters :

• event : string indicating the event

• function : function to run if the callback is triggered

• args : unnamed arguments of the function

• kwargs : named arguments of the function

• background : boolean indicating if the function is launched in a background thread or in foreground

run(packet)

This method executes the function associated to the callback.

update(packet)

This method allows to update the callback’s internal state by providing the current packet. If the packet received matchs the event defined, the attribute runnable is set to True.

mirage.libs.wireless_utils.device module

class mirage.libs.wireless_utils.device.Device(interface)

Bases: object

This class is used to communicate with a specific hardware component. Every class communicating with a given hardware component must inherits from this class, and implements the following methods :

• init() : this method initializes the communication with the hardware component

• isUp() : this method allows to check if the initialization was successful and if the device is usable

• send(packet) : this method allows to send data (as a raw representation, e.g. bytes array or scapy frame)

• recv() : this method allows to receive data (as a raw representation)

• close() : this method closes the communication with the hardware component

Every device is unique and identified by an interface name : this is a string stored in the interface attribute. Some devices may provide some additional features, such as address configuration, multiple modes, etc. In order to implement this specific behaviours, some additional methods can be implemented in the child classes, and their name may be appended to the class attribute sharedMethods (list of strings). Every shared method will be callable by user using the corresponding Emitter (mirage.libs.wireless.Emitter) and/or the corresponding Receiver (mirage.libs.wireless.Receiver) : they will expose these additional methods thanks to the Proxy design pattern.

Finally, a simple mechanism allows to attach capabilities to a specific Device class : the capabilities are listed in an attribute capabilities (list of strings), filled during the initialization of the Device. From a module, an user can check if the device selected has the right capabilities by calling hasCapabilities on the corresponding Emitter and / or Receiver.

close()

This method closes the device.

classmethod get(interface)

This class method implements the Register device pattern. According to the interface parameter, only one instance of a given specific device will be instanciated if multiple Emitters and/or Receivers tries to access it.

hasCapabilities(*capability)

This method allows to check if the device implements some specific capabilities.

Parameters

*capability (str (multiple)) – capabilities to check

Returns

boolean indicating if the device implements the capabilities provided

Return type

bool

Example

>>> device.capabilities = ["SNIFFING", "INJECTING", "CHANGING_ADDRESS"]
>>> device.hasCapabilities("SNIFFING", "INJECTING")
True
>>> device.hasCapabilities("MAKING_COFFEE")
False

init()

This method initializes the device.

instances = {}

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

publish(event, *args, **kwargs)

This method allows to publish an event. It may be used to call from the device a method implemented on the corresponding Emitters / Receivers, subscribers by default.

Parameters

event (str) – method’s name to call

Example

>>> device.publish("stop")

recv()

This method receives some datas. If no data is available, this method returns None.

Parameters

data – raw representation of the received data

send(data)

This method sends some datas.

Parameters

data – raw representation of the data to send

sharedMethods = ['hasCapabilities']

This class attribute allows to provide some methods’ names in order to make them callable from the corresponding Emitter / Receiver.

subscribe(subscriber)

This method allows to register a subscriber, according to the design pattern named Publish/subscribe. It allows a Device to call a method of the corresponding Emitter / Receiver, subscribers by default.

Parameters

subscriber (Object) – instance of an object subscribing to the device

class mirage.libs.wireless_utils.device.SDRDevice(interface, sdrConfig={}, sdrMode='HALF_DUPLEX')

Bases: mirage.libs.wireless_utils.device.Device

This class is used to communicate with a specific Sofware Defined Radio (SDR) device.

Every device based on a Software Defined Radio must inherit from this class and implements the following methods:

• buildReceivePipeline(interface) : this method allows to build the receive pipeline

• buildTransmitPieline(interface) : this method allows to build the transmit pipeline

• setExperimentalDemodulator(enable) (optional) : this optional method allow to modify the receive pipeline to use an experimental demodulator (if any)

Keep in mind that the child class must also implements the methods of a classic Device.

SDR_PARAMETERS = {'BANDWIDTH': (['source', 'sink'], 'setBandwidth', <class 'int'>), 'EXPERIMENTAL_DEMODULATOR': (['device'], 'setExperimentalDemodulator', <function booleanArg>), 'FREQUENCY': (['source', 'sink'], 'setFrequency', <class 'int'>), 'GAIN': (['source'], 'setGain', <class 'int'>), 'LNA_GAIN': (['source'], 'setLNAGain', <class 'int'>), 'SAMPLE_RATE': (['source', 'sink'], 'setSampleRate', <class 'int'>), 'TX_GAIN': (['sink'], 'setTXGain', <class 'int'>)}

applySDRConfig()

This method applies the SDR-related configuration.

buildReceivePipeline(interface)

This method allows to build the receive pipeline of the current device.

Parameters

interface (str) – string indicating the interface to use

Returns

receive pipeline instance

Return type

SDRPipeline

buildTransmitPipeline(interface)

This method allows to build the transmit pipeline of the current device.

Parameters

interface (str) – string indicating the interface to use

Returns

transmit pipeline instance

Return type

SDRPipeline

close()

This method closes the device.

updateSDRConfig(sdrConfig)

This method updates the SDR-related configuration. The supported parameters are:

• GAIN: Receive (RX) Gain (integer value)

• TX_GAIN: Tranmit (TX) Gain (integer value)

• LNA_GAIN: Low Noise Amplifier (LNA) Gain (integer value)

• FREQUENCY: Frequency (integer value)

• BANDWIDTH: Bandwidth (integer value)

• SAMPLE_RATE: Sample Rate (integer value)

• EXPERIMENTAL_DEMODULATOR: Use the experimental demodulator if available (boolean value)

Parameters

sdrConfig (dict) – dictionary describing the SDR parameters name and their value as string

mirage.libs.wireless_utils.packetQueue module

class mirage.libs.wireless_utils.packetQueue.PacketQueue(waitEmpty=False, autoStart=True)

Bases: object

This class implements a Packet (mirage.libs.wireless_utils.packets.Packet) queue, and provides an API to manipulate it.

The Emitter class (mirage.libs.wireless.Emitter) and the Receiver class (mirage.libs.wireless.Receiver) inherit from it. The private method _task implements a watchdog, allowing to put or get some packets in the queue and manipulate them. This watchdog is called continuously thanks to a Stoppable Thread (mirage.libs.wireless_utils.packetQueue.StoppableThread).

Some parameters may be passed to the constructor :

• waitEmpty : it indicates if the queue should wait for an empty queue before stopping

• autoStart : it indicates if the queue shoud start immediatly after the instanciation of the class

clear()

isBusy()

This method indicates if the queue contains some datas.

Returns

boolean indicating if the queue contains some datas

Return type

bool

isDeviceUp()

This method allow to check if the Device (mirage.libs.wireless_utils.device.Device) linked to this Packet Queue is up and running.

isEmpty()

This method indicates if the queue is empty.

Returns

boolean indicating if the queue is empty

Return type

bool

restart()

This method restarts the associated stoppable thread.

start()

This method starts the associated stoppable thread in order to continuously call the watchdog function (_task).

stop()

This method stops the associated stoppable thread.

class mirage.libs.wireless_utils.packetQueue.StoppableThread(target=None)

Bases: threading.Thread

This class is just a simplistic implementation of a stoppable thread. The target parameter allows to provide a specific function to run continuously in background. If the stop method is called, the thread is interrupted.

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

stop()

This method stops the thread.

mirage.libs.wireless_utils.packets module

class mirage.libs.wireless_utils.packets.AdditionalInformations

Bases: object

toString()

class mirage.libs.wireless_utils.packets.Packet(packet=None, additionalInformations=None)

Bases: object

This class represents an abstract representation of a packet. It can be overloaded in order to implements the relevant packets for a given technology.

By default, three attributes are included in a Packet :

• name : it indicates the name of the packet

• packet : it contains the raw representation of the packet (e.g. a bytes array or a scapy frame)

• additionalInformations : it contains some external informations about a packet (e.g. frequency, timestamp …)

show()

This method allows to display 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.wireless_utils.packets.WaitPacket(time=0.0)

Bases: mirage.libs.wireless_utils.packets.Packet

This class represents a fake packet, allowing to force the Emitter to wait for a given specific time. It can be used if some timing constraints are needed for a given transmission.

The time attribute indicates the waiting time needed.

Example

>>> packet = WaitPacket(time=1.0)
>>> emitter.sendp(firstPacket,packet,lastPacket) # the emitter sends firstPacket, waits for one second and sends lastPacket

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.wireless_utils.butterfly module

class mirage.libs.wireless_utils.butterfly.ButterflyDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with a ButteRFly Device in order to sniff BLE, Zigbee or ESB. The corresponding interfaces are : butterflyX (e.g. “butterfly0”)

close()

This method closes the device.

disableController()

This method disables the current controller.

enableController()

This method enables the current controller.

getController()

This method returns the controller used by the current Butterfly device.

Returns

controller in use

Return type

str

Example

>>> device.getController()
'BLE'

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

getFirmwareVersion()

This method returns the firmware version of the current Butterfly device.

Returns

firmware version as a tuple of (major, minor)

Return type

tuple of (int,int)

Example

>>> device.getFirmwareVersion()
(1,0)

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

selectController(controller)

sharedMethods = ['getFirmwareVersion', 'getDeviceIndex', 'getController']

mirage.libs.wireless_utils.pcapDevice module

class mirage.libs.wireless_utils.pcapDevice.PCAPDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

This class provides an easy way to implement a PCAP writer or reader as a Mirage Device.

• If the provided interface is an existing file, the PCAPDevice is set in “reading mode”.

• If the provided interface is a non existing file, the PCAPDevice is set in “writing mode”.

Every child classes of PCAPDevice should provide :

• the DLT class attribute, defining the DLT of the PCAP file

• the SCAPY_LAYER class attribute (optional), defining a scapy layer automatically used to encapsulate the packets

The send and recv methods uses the timestamp in order to write and read the pcap “in real time”. The putPacket, getPacket and getAllPackets methods allow to manipulate directly the packets without taking into account the timestamp values.

DLT = 0

SCAPY_LAYER = None

buildPacket(packet, timestamp)

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

close()

This method closes the device.

getAllPackets()

This method gets all packets stored in the PCAP file asynchronously and returns them.

Returns

list of packets (tuple of (timestamp, packet))

Return type

list of tuple of (timestamp, packet)

getMode()

This method returns the mode used by this PCAP Device.

Returns

current mode (“read” or “write”)

Return type

str

Example

>>> device.getMode()
'read'

Note

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

getPacket()

This method reads a packet asynchronously from the PCAP file and returns it to the user.

Returns

tuple composed of a boolean indicating if the packet exists and a tuple of (timestamp, packet)

Return type

tuple of (bool,tuple of (float,bytes))

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

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

openFile()

putPacket(data, timestamp=None)

This method writes a packet asynchronously into the PCAP file.

Parameters

• data (bytes or scapy frame (if SCAPY_LAYER is not None)) – packet to write

• timestamp (float) – timestamp of the packet (optional)

Returns

boolean indicating if the operation was successful

Return type

bool

recv()

This method gets the packets from the PCAP file asynchronously.

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

sharedMethods = ['putPacket', 'getPacket', 'getAllPackets', 'startReading', 'stopReading', 'getMode']

startReading()

This method starts the reading mode.

stopReading()

This method stops the reading mode.

mirage.libs.wireless_utils.scapy_butterfly_layers module

This module contains some scapy definitions for communicating with a ButteRFly device.

Module contents