LOGITacker - Enumerate and test Logitech wireless input devices

项目说明

LOGITacker

README is still under construction

LOGITacker is a hardware tool to enumerate and test of Logitech Wireless Input devices via RF.
In contrast to a tooling, it is designed as stand-alone tool. This means not only the low level RF part,
but also the application part is running on dedicated hardware, which could provides Command Line Interface (CLI)
via USB serial connection.

Keeping hardware from other (not Logitech) out of scope, allowed further optimizations and impro for
low le like RF device discovery.

Additionally support for the following boards was addded:

Nordic nRF52840 Dongle (pca10059)

MakerDiary MDK Dongle

MakerDiary MDK

April Brother Dongle

LOGITacker covers the following Logitech :

MouseJack (plain injection)

forced pairing

C (AES key sniffing from pairing)

C (injection with keys dumped via USB from presentation clickers)

C (injection with keys dumped via USB from Unifying devices)

LOGITacker does currently not cover the following Logitech:

KeyJack

C (Injection without key knowledge, for receivers patched against KeyJack)

*Note: KeyJack and C are covered by mjackit*

LOGITacker can also be used as Hardware Implant (see USBsamurai's Tutorial )

1 feature summary

Discovery of Logitech devices on air (optimized pseudo promiscuous mode)

Device management (store/delete devices from/to flash, auto re-load parameters - like link encryption key - from flash

when a stored device is discovered again)

Passi of discovered devices (sniffing, automatic update of device capabilities based on received RF frames)

Acti of discovered devices (test receiver for additional valid device addresses, test for plain keystroke

injection )

Injection (Inject keystrokes into devices, inject encrypted for devices with known key, bypass alpha

character filter of receivers for newer devices - like R500 presentation clicker)

Scripting (create/store/delete injections scripts on internal flash, auto load a script on boot, auto inject a script

on device discovery, support for DE and US keyboard layout)

CLI (integrated help, tab completion, inline help)

Sniff pairing (AES link encryption keys get stored to flash, encrypted injection and li of keyboard traffic

gets possible)

Device Pairing / forced pairing: a device could be paired to a Unifying dongle in pairing mode or to an

arbitrary RF address (in order to test for the forced pairing presented by Marc Newlin in 2016)

Device management on flash: Discovered devices could be stored/deleted to/from flash persistently. This comes handy if

a device has an AES link encryption key associated. If the dongle is power-cycled and the respecti is discovered
again, the associated data (including the AES key) is restored from flash.

Li: In passi mode, encrypted keyboard RF frames are automatically decrypted if the link

Encryption key is known (could be added manually or obtained from sniffed pairing). This could be combined nicely with
USB pass-thorugh modes.

*experimental* covert channel for air-gap bridging with "keystroke injectable" client agent to deploy the channel

for a Windows host with Logitech receiver (demo with recei into USB cable: )

usable for pure USB keystroke injection (RubberDucky fashion), programming features are still usable

USB pass-through: An USB serial based CLI is not the best choice, when it comes to processing of raw or decrypted RF

data. To circumvent this, LOGITacker supports the following pass-through modes:
- USB keyboard pass-through: If enabled, received RF keyboard frames are forwarded to LOGITacker's USB keyboard
interface. Key presses of the currently sniffed wireless keyboard are ultimately mirrored to the host which has
LOGITacker connected. For encrypted keyboards, the decrypted data is forwarded (in case the AES key is known)
- USB mouse pass-through: Same as keyboard pass-through, but for mouse reports.
- RAW pass-through: Beside the USB serial, USB mouse and USB keyboard interface, LOGITacker provides a raw HID
interface. Passing keyboard reports directly via USB isn't always a good idea (f.e. if you sniff a keyboard and
the user presses ALT+F4). In order to allow further processing raw incoming data could be forwarded to the USB host,
using the raw interface (data format includes: LOGITacker working mode, channel, RSSI, device address, raw payload).

Automation / stand alone use: Beside devices data and scripts, several options could be stored persistently to flash.

Those option allow to control LOGITacker's behavior at boot time. An **example set of persistent options, which could be
used for headless auto-injection** (LOGITacker could be power supplied from a battery) would look like this:
- boot in discovery mode (detect devices on air)
- if a device is discovered, automatically enter injection mode
- in injection mode, load a stored default script and execute the script with default language layout
- if the injection succeeded, return to discovery mode
- enter injection mode not more than 5-times per discovered device

There are still many ToDo's. The whole project is in experimental state.

2 Installation

2.1 Nordic nRF52840 Dongle (pca10059)

nRF Connect software by Nordic provides a Programmer app, which could be used to flash the firmware from this repository
to a Nordic nRF52840 dongle. After flashing the firmware, the dongle provides 4 new interfaces (USB serial, USB mouse,
USB keyboard and USB HID raw). The serial interface could be accessed using PuTTY or screen on Linux.

Reference: "Terminal Settings" section of nRF5 SDK documentation -

To put the dongle into programming mode (bootloader) push the button labeled RESET. The red LED starts to
"softblink" in red.

The proper file to flash with the Programmer app is build/logitacker_pca10059.hex.

2.2 MakerDiary MDK Dongle (pca10059)

nRF Connect software by Nordic provides a Programmer app, which could be used to flash the firmware from this repository
to a Nordic nRF52840 dongle. After flashing the firmware, the dongle provides 4 new interfaces (USB serial, USB mouse,
USB keyboard and USB HID raw). The serial interface could be accessed using PuTTY or screen on Linux.

Reference: "Terminal Settings" section of nRF5 SDK documentation -

To put the dongle into programming mode (bootloader) follow these steps:

disconnect the dongle from the host

press and hold the button of the dongle

re-connect the dongle to the host without releasing the button

the red LED of the dongle should "softblink" to indicate bootloader mode

The proper file to flash with the Programmer app is build/logitacker_mdk_dongle.hex.

2.3 MakerDiary MDK

Thanks to DAPLink support flashing this board is really easy:

1) Connect the board to the host
2) Push the button labeled "IF BOOT / RST"
3) A mass storage with label "DAPLINK" should be detected and mounted to the host.
4) Copy the build/logitacker_mdk.hex file to the DAPLINK .
5) Wait till the green LED stops flashing, and the "DAPLINK" is re-mounted.
6) Push the "IF BOOT / RST" button again, in order to boot the LOGITacker firmware.

2.4 April Brother nRF52840 Dongle

The April Brother dongle provides a removable dri accepts uf2 file to program the dongle.

To program the dongle follow these steps:

disconnect the dongle from the host

double-click button on the dongle (through the tiny hole)

copy logitacker_apr-dongle.uf2 to the removable drive 'NRF52BOOT'

the dongle will restart

remove the dongle from host

reinsert dongle to host

The proper file to flash with the Programmer app is build/logitacker_aprdongle.uf2.

After flashing the firmware, the dongle provides 4 new interfaces (USB serial, USB mouse,
USB keyboard and USB HID raw). The serial interface could be accessed using PuTTY or screen on Linux.

Reference: "Terminal Settings" section of nRF5 SDK documentation -

2.4.1 Remark on LED issues of aprbrother dongle

The aprbrother dongle has LED issues, which are not caused by LOGITacker. See here for reference:

2.4.2 Remark on bootloader

Once LOGITacker has been flashed, double-tapping the hardware button does not start the bootloader anymore (UF2 flash mode).

1) In order to get back to the bootloader, unplug the dongle
2) Press and hold the hardware button (use something which fits the small hole)
3) Re-plug the dongle with the button still pressed
4) The blue LED should "soft blink", this indicates that the dongle is in bootloader mode again
5) Copy the intended UF2 firmware image to the named 'NRF52BOOT' to flash a new firmware

3 Basic usage concepts

LOGITacker exposes four USB devices:

USB CDC ACM (serial port) - this port has a console connected and is used for CLI interaction

USB mouse - used to optionally forward mouse reports (captured from RF) to the host

USB keyboard - used to optionally forward keyboard reports (captured from RF, decrypted if applicable) to the host

USB HID raw - used to optionally forward raw RF frames for further processing (usage as additional control interface planned)

LOGITacker provides an interactive CLI interface which could be accessed using the USB CDC ACM serial port.

For details, see "Terminal Settings" section of nRF5 SDK documentation -

In addition to PuTTY, the terminal muxer screen could be used as an alternative, like this screen /de 115200
(/de has to be replaced with the proper device file, representing LOGITacker's USB serial interface).
**In contrast to PuTTY, the screen tool seems not to support tra BACKSPACE to CTRL + H. Because of this CTRL + H
has to be pressed to get BACKSPACE functionality**

*Note: Makerdiary MDK exposes two USB serial ports (one belonging to CMSIS-DAP). Be sure to connect to the correct
port, which runs the CLI. The other port only outputs log messages*

3.1 LOGITacker's modes of operation

discover: Used to find Logitech wireless devices on air aka. pseudo-promiscuous mode (default mode)

passi: Receives all RX traffic of the selected device address (optained in discover mode or added manually).

This is basically sniffing, but device information is updated based on recei (f.e. if plain keyboard reports
are received, the device is flagged to allow plain keystroke injection)

acti: Actively transmits frames for a discovered device address, in order to test if plain keystroke injection

is possible (no false positives, but detection doesn't work for devices like presentation clickers). Additionally
acti "talks" to the receiver of a discovered device to find out other accessible RF addresses. This means
if a mouse is discovered, acti could possibly find an input RF address for a keyboard connected to the same
receiver. If this keyboard address is to plain injection, this would be detected, too (even if the actual
keyboard is not in range).
in range.

inject: This mode is used to inject keystrokes to a Logitech receiver for a gi address. If the respective

device is stored along with a link encryption key (obtained by sniffing of pairing or manually added), keystrokes are
injected with proper encryption. If no key is stored for the device or the device supports plain keys, keystrokes are
injected unencrypted.

script: Not an actual mode, but a subset of commands used to edit, load and store scripts used in injection mode.

pair: This mode has two submodes:

- pair sniff: used to sniff device pairings (C)
- pair device: used to pair a new device to a receiver in pairing mode (or for a dedicated RF address if the
respecti is to "forced pairing")

3.2 Distinguish between data is stored in LOGITacker's RAM (session data) and data stored on flash (persistent)

devices: Discovered devices are stored in RAM only. They could be persistently stored to flash with the devices storage save <address>

command and restored with devices storage load <address> command. Stored devices could be listed with devices storage list.
Storing devices comes in handy, if the device data has a link encryption key associated. Devices for which the pairing
has been sniffed, are automatically stored to flash by default. If a device is discovered on air the first time and
associated device data is stored on flash, it gets reloaded automatically. This means once a encryption key for a device
is obtained, it always is present and ready to use, even if LOGITacker has been power-cycled.

scripts: Only a single (injection) script could be active at a given time. Of course scripts could be stored to

flash with script store "scriptname" and restored with script load "scriptname". Stored scripts could be listed with
script list. To show the content of the currently active the following command is used: script show

options: Options drive the behavior of LOGITacker. If done right, they could be used to fully automate it. Anyways,

changes to options NEVER ARE PERSISTENT, unless the options store command is run. Although being less con, this
is to reduce flash write&erase cycles (flash could not be written endlessly). Keep this in mind: options always have to
be stored manually, in order to persist a reboot of LOGITacker.

In case, saving of scripts or options to flash fails with
LOGITACKER_SCRIPT_ENGINE: failed to write first task for script storage or <warning> LOGITACKER_OPTIONS: failed to find Flash Data Storage record for global options: 2
the flash store is corrupted and has to be rewritten.
Issue erase_flash and reconnect the dongle afterwards.

3.3 Scripting

Entering script to the CLI shows the sub-commands of the script command group. There are two kinds of commands:

Commands to edit the currently acti and commands to manage scripts on flash storage.

The keyboard language layout to use (at time of this writing US and DE are supported), could be selected with
options inject language de or options inject language us. Keep in mind, that in order to persist the language
setting options store has to be issued.

The commands directly usable within a scripts are:

string: Presses keys which should output the gi (according to selected language layout)

altstring: Instead of pressing the key for the respecti, a ALT-NUMPAD combination is pressed, which

should produce the respecti. In contrast to the string command, this is language layout independent.
The shortcoming: This only works on Microsoft Operating Systems, but not on all input dialogs.

delay: This command delays script execution by the gi of milliseconds.

press: This command interprets the gi as key combination and tries to create a keyboard report which

presses the given keys simultaneously. Key-arguments usable in press command are listed below:

Here is a usage example, showing how to bring up a script which utilizes ALT+NUMPAD input, in order to bypass the key
blacklisting of a Logitech R500 (does not allow keys A to Z and GUI + r) on a Windows 7 host:

To list the script run script show

Below some notes on the script, as the approach applies in other scenarios, too :

As GUI + r is filtered by R500 (or results in GUI without the pressed r) only the start dialog could be opened on
the targeted Windows 7 host (not the run dialog). The start dialog accepts no characters created based on ALT+NUMPAD
combination (on Windows 10 it does so). In order to compensate for this, a help dialog is opened using GUI+F1. This
dialog allows input based on NUMPAD combos, thus cmd.exe could be typed out using the altstring command. In order
to use NUMPAD based key combinations, of course, NUMLOCK has to be turned on. This is why the first command of the script
presses the NUMLOCK key. Even if NUMLOCK was already enabled, a second run of the whole script would succeed.
The next commands:

CTRL+A marks the whole "cmd.exe" string

CTRL+X cuts the "cmd.exe" string (clipboard)

ALT+F4 close the opened help dialog

GUI opens the start dialog

CTRL+V pastes the "cmd.exe" string from clipboard (as it can't be entered it directly using )

RETURN execute cmd.exe

the "calc.exe" string is, again, entered using ALT+NUMPAD combinations, as the cmd.exe console supports this

RETURN execute calc.exe

The script could now be stored to flash, for later use with script store "calc_win7". Stored scripts could be checked
like this:

Next a simplified for Windows 10 could be created and stored:

First current script has to be cleared with script clear. Afterwards, a new script could be created.

Again, the script should be stored with script store "calc_win10". The command script list should show bot scripts,
now.

The Windows 7 script could be re-loaded using script load like shown below:

*Note: all commands shown so far, support tab completition.*

In order to load, for example, the Windows 7 script on every boot of LOGITacker, the respecti has to be changed
and stored persistently, like this:

After re-plugging LOGITacker and opening the CLI again (power cycle / reboot), the "calc_win7" script should already be
loaded. This could be checked with script show.

For Logitech devices to plain keystroke injection (see MouseJack research for details), the script could
directly be used. For encrypted devices, like Logitech R500 or Logitech SPOTLIGHT presentation clickers, the new script
can not be injected, without knowing the encryption key. This is issue is covered in the next section.

3.4 Encrypted injection

In order to execute the example scripts agains an encrypted Logitech device, the decryption key has to be obtained.
There are two class of , allow stealing those keys:

1) Sniff the pairing (or re-pairing) of the device to obtain the key (C)
2) USB based key extraction from Logitech receivers using a Texas Instruments chip (C, C)

As the details for C / C aren't released, yet, the key should be obtained using by sniffing
the device pairing. The scripts of the last section have been built to target wireless presentation clickers, like R500
or SPOTLIGHT. When those devices ship, they are already paired to the receiver. This is less of an issue, as an
undocumented pairing mode could be triggered, anyways.

The following video shows the concept:

The pre-release of munifying could be found here:

The only thing which has to be done to capture a pairing with LOGITacker and derive the link encryption key according to
C, is to issue the following command: pair sniff run

LOGITacker starts flashing the red LED. Once a receiver - which is set to pairing mode - is in range, the LED starts
flashing blue. If a pairing is captured successfully, the device and associated key are not only stored in LOGITacker's
RAM, but they are automatically stored to flash.

In order to unpair and re-pair the device to the receiver, the munifying tool is used. Re-pairing of the device is
done, while LOGITacker is running in pair sniff mode.

The command ./munifying unpair lists devices currently paired to the receiver and ask for a device to unpair.
To set the receiver back to pairing mode and re-pair the device, munifying has to be called with ./munifying pair.

Below is the example output of munifying for unpairing a R500 presenation clicker from its receiver and initiating
pairing mode again.

Once the receiver is in pairing mode, the red-flashing LED of LOGITacker should turn to a blue-flashing LED.
For Unifying devices, the device which should be paired has to be turned off and on again. For presentation clickers
R500 / SPOTLIGHT the two buttons used to put the clicker into Bluetooth mode have to pressed and hold.

If nothing has gone wrong, LOGITacker has captured the device address and encryption key. Afterwards, LOGITacker
changes back from "pair sniff" mode to "passi" mode (default behavior).

Here's some example output of a successful key capture:

When pressing keys on the - now paired - device,
LOGITacker should not only print the encrypted reports, but a decrypted , too (in passi mode).

Here's an example for the key "RIGHT":

Additionally, the device should be listed in red with the remarks "encrypted, key ḱnown":

Now e is set, for encrypted injection (LOGITackers script engine automatically encrypts keyboard RF reports
for devices with known key).

In order to inject the "calc_win7" script (which should already be loaded), two steps are needed:

1) Select the injection target (tab completition a)
2) Execute the injection

This is done with the following commands (RF address of the device is only an example):

Once the script has finished execution, LOGITacker changes back from "injection" mode to "discover" mode.
This behavior could be changed using the following command:

3.5 Ea encrypted devices (keyboards)

The process for ea follows the same steps as described for the "encrypted injection".

The link encryption key for a device has either to be added manually (could be extracted from receivers with unrestricted
of munifying, once released) or to be obtained from sniffing of device pairing.

As pointed out in the previous chapter, passi automatically decrypts received key reports for devices with known
key. Reading the keys from the CLI output isn't really con. To o this, LOGITacker allows forwarding of
decrypted or plain keyboard and mouse frames sniffed in passi mode to its USB interface. The reports are
translated to proper USB HID reports. Thus, the input is ultimately mirrored to the USB host which has LOGITacker
connected.

The respecti could be enabled with the following commands:

The result should look like in the following video, where the sniffed input of a encrypted keyboard is mirrored to
LOGITacker's USB host:

The video additionally shows, that for Unifying device the re-pairing could be initiated using the Unifying software, in
order to sniff the link encryption key. For presentation clickers, this could currently only be achieved with munifying.

**WARNING: In current , no filter could be applied on USB forwarded input. E entered with the sniffed
keyboard is directly forwarded to the USB keyboard interface of LOGITacker.**

3.6 Format description for RF reports forwarded to raw USB HID interface

t.b.d.

3.7 Headless use / Automation

t.b.d.

Demo:

4 Other video usage examples (Twitter)

Note: The have been created throughout de and command syntax has likely changed (and will change).
Please use tab completion and CLI inline help. All examples are included in current firmware.

4.1 Discover a device

Video:

Note: Discovery, especially of presentation clickers, has been impro this test video.

4.2 Sniff pairing and ea for an encrypted keyboard

Video:

To sniff a pairing attempt use pai sniff run. Successfully devices (and keys) of successfully sniffed pairing are
stored to flash automatically. The options pair-sniff command subset could be used to alter this behavior.

The options store command could be used to persistently store options changed at runtime (new option survi
after storing).

If not done automatically after successful pair-sniffing, the respecti has to be sniffed using
passi AA:BB:CC:DD:EE:FF, where AA:BB:CC:DD:EE:FF has to be replaced by the device address obtained during
pair sniff (a via tab complete).

In order to forward (decrypted) keyboard RF frames to the USB keyboard interface, like shown in the video, the
respecti has to be enabled with options passi pass-through-keyboard on.

4.3 Inject keystrokes (encrypted device)

Video:

The video utilizes "pair-sniffing" to obtain the device link encryption key. This, of course, isn't needed for unencrypted
devices (f.e. presentation clickers like R400, R700, R800).

The injection mode uses encrypted injection for devices with known AES key and falls back to plain injection if no
key is known or the device isn't encrypted.

In order to create, store and delete scripts use the script sub-command set (again inline help and tab complete).

In order to start a injection enter injection mode for a specific device with inject target AA:BB:CC:DD:EE where
AA:BB:CC:DD:EE has to be replaced by the respecti address (tab complete if already discovered).

To execute the injection, issue inject execute.

The behavior after injection depends on the setting of options inject onsuccess and options inject onfail.
If LOGITacker is configured to lea mode it has to be entered again, using inject target AA:BB:CC:DD:EE, in
order to do further injections.

The current injection script could be stored to flash with script store "scriptname".
It is not allowed to o stored scripts (same name). In order to do so, the respecti has to be deleted
first, with script remove "scriptname".

Stored scripts could be listed with script list.

The current script could be printed with script show.

To set a script as default script on boot (could be used for auto-injection), the following option has to be altered:
options inject default-script "scriptname". To persist the new default-script option don't forget to run options store.

4.4 Using altstring feature in scripts (enter characters using ALT+NUMPAD on Windows targets)

Video demo 1 (Mouse MX Anywhere 2S):

Video demo 2 (encrypted presentation clicker R500):

5 DISCLAIMER

LOGITacker should be used for authorized testing and/or educational purposes only.
The only exception is using it against devices or a network, owned by yourself.

I take no responsibility for the abuse of LOGITacker or any information given in
the related documents.

I DO NOT GRANT PERMISSIONS TO USE LOGITacker TO BREAK THE LAW.

As LOGITacker is no production tool, it is likely that bugs occur.
I disclaim any warranty for LOGITacker, it is provided "as is".

项目信息

开发语言：C

Star 数：745

技术要点

该项目属于漏洞知识库方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Enumerate and test Logitech wireless input devices for vulnerabilities with a nRF52840 radio dongle.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。