esb_sniff
=========

Presentation
------------
**esb_sniff** passively sniffs Enhanced ShockBurst frames. It works with a `RFStorm Device <devices.html#esb-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
------------------

 * `RFStorm Device <devices.html#esb-rfstorm-device>`_
 * `PCAP Files <devices.html#esb-pcap-files>`_

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 <modules.esb_inject.html>`_ 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 <modules.mouse_visualizer.html>`_ 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:

.. image:: mousevisualizer_example.gif