An extremely simple CLI tool that was created to diagnose and further understand an issue in DriverKit causing kIOHIDOptionsTypeSeizeDevice to behave incorrectly when used in DriverKit system extensions.

Overview

IOKitHIDKeyboardTester

This tool is NOT useful to, or intended for general users.

IOKitHIDKeyboardTester is an extremely simple (one-file!) CLI tool that was created to diagnose and further understand an issue in DriverKit causing kIOHIDOptionsTypeSeizeDevice to behave incorrectly when used in DriverKit system extensions.

Aside from that, it can also be used as example/reference code for any developers who also wish to implement and use IOHIDManagerRegisterInputValueCallback, IOHIDManagerSetDeviceMatchingMultiple, and other related functions of IOKit/IOHIDManager.


The aforementioned DriverKit issue was breaking global hotkey functionality in applications such as Discord (example on Twitter) when DriverKit system extensions such as Karabiner-Elements (see my GitHub issue #2895) were installed on a system.

I actively use both of these products, which is how I noticed the bug in the first place (Discord uses the IOKit/IOHIDManager functions mentioned above for its global hotkey functionality, which I discovered by running nm -um "${HOME}/Library/Application Support/$DISCORD_VARIANT_HERE/$VERSION_NUMBER_HERE/modules/discord_utils/discord_utils.node").

Also of note is that this issue affects some macOS built-in hotkey-related functionality too, such as the "Press the Option key five times to toggle Mouse Keys" feature that many use to quickly toggle locking their MacBook's built-in trackpad.

For more information, please refer to my writeup regarding this issue.


IMPORTANT — PLEASE READ THIS, IF NOTHING ELSE

Please be aware that this tool prints out keyboard scancodes directly to standard output which correspond to your keystrokes!

Please do not leave it running and/or type anything sensitive while using the tool, and remember to completely clear your Terminal scrollback when you are done using the tool and have copied any relevant output you may want!

The entire source code is very simple and exists entirely in just one file, so please do your due diligence and read through the code, making sure that you fully understand what it does and doesn't do before compiling and running it!


Building

Xcode: Press the "Run" button.

CLI: xcodebuild -configuration Release or simply just make. (※ The latter actually just calls xcodebuild for you.)


I've already authorised Accessibility/TCC permissions (or it simply does not show up at all), but it still keeps asking me in a loop…

If you're running from Xcode…

Please uncheck and recheck the existing IOKitHIDKeyboardTester entry from your Accessibility/TCC permissions list, then run the tool again.

This occurs because the Xcode project is set to use ad-hoc signing, which results in the code signature changing every time a new binary is built. This invalidates the old Accessibility/TCC authorisation that was given for a previously-signed binary.

If you want to fix this behaviour for your own development builds, simply change the project's codesigning team to your own Apple Developer Team ID.

※ Note: On some older versions of Xcode (such as 9.4.1), you may have to grant Accessibility/TCC permissions to Xcode itself, similar to the Terminal instructions below.

If you're running from a compiled binary via a Terminal instance…

Please grant your Terminal application the Accessibility/TCC authorisation. This applies to both Apple's Terminal.app and any third-party applications like it, such as iTerm2.

Manually adding the IOKitHIDKeyboardTester binary to the list will not work.


License

Licensed under the MIT License.

You might also like...
Swift-cli - Example of building command-line tools in Swift
Swift-cli - Example of building command-line tools in Swift

swift-cli Example of building command-line tools in Swift Step 1: Create CLI wit

ConcurrentTest - Swift macOS CLI example on how to NOT do concurrent coding
ConcurrentTest - Swift macOS CLI example on how to NOT do concurrent coding

Swift Concurrent Test Open the .xcodeproj file in Xcode, and try running it seve

A CLI utility to check or uncheck Open Using Rosetta preference for Apple Silicon macs.
A CLI utility to check or uncheck Open Using Rosetta preference for Apple Silicon macs.

SetArchPrefForURL A CLI utility to "check" or "uncheck" "Open Using Rosetta" preference for Apple Silicon macs. Usage: SetArchPrefForURL path-to-the-

A CLI to Alcatraz, the Xcode package manager.
A CLI to Alcatraz, the Xcode package manager.

Azkaban This project is deprecated in favor of Editor Extensions support in Xcode 8+. A CLI to Alcatraz, the Xcode package manager. Usage Install a pl

A way to build TUI apps with a layout system and API that's similar to SwiftUI.

terminal-ui A way to build TUI apps with a layout system and API that's similar to SwiftUI. We reimplemented parts of the SwiftUI layout system in the

🕳 A simple command line tool to punch hole to reduce disk usage on APFS volume for such as a raw disk image.

HolePunch NAME holepunch -- A simple command line tool to punch hole to reduce disk usage on APFS volume for such as a raw disk image. SYNOPSIS holepu

ipatool is a command line tool that allows you to search for iOS apps on the App Store and download a copy of the app package, known as an ipa file.
ipatool is a command line tool that allows you to search for iOS apps on the App Store and download a copy of the app package, known as an ipa file.

ipatool is a command line tool that allows you to search for iOS apps on the App Store and download a copy of the app package, known as an ipa file.

iOS command-line tool that allows searching and downloading ipa files from the iOS App Store

ipatool for iOS This is a port of Majd Alfhaily's ipatool adapted to run on iOS Build / Installation To build this, make sure you have AppSync install

The best command-line tool to install and switch between multiple versions of Xcode.
The best command-line tool to install and switch between multiple versions of Xcode.

The best command-line tool to install and switch between multiple versions of Xcode.

Owner
Karen/あけみ
Karen/あけみ
A command-line tool to generate a JSON-list of all used SPM-dependencies of an Xcode-project.

SwiftPackageList A command-line tool to generate a JSON-list of all used SPM-dependencies of an Xcode-project. This includes all the Package.resolved

Felix Herrmann 14 Jan 8, 2023
Guaka - Smart and beautiful POSIX compliant CLI framework for Swift.

Guaka - Smart and beautiful POSIX compliant CLI framework for Swift. It helps you create modern and familiar CLI apps in the vein of widely used proje

Omar Abdelhafith 1.1k Dec 24, 2022
A library and CLI Utility to manage NVRAM Stuff, written in Swift.

NVRAMKit A Library and CLI Utility to manage NVRAM Stuff, written in Swift. Library Adding Library to Project Simply add this line to the dependencies

Serena 7 Sep 25, 2022
A silly CLI for replacing macosx.internal SDK settings in .xcodeproj files with macosx

fix-macos-internal-sdk A silly CLI for replacing macosx.internal SDK settings in .xcodeproj files with macosx.

Keith Smiley 14 Dec 6, 2022
A CLI too powered by Swift to provision environments using an up.toml manifest file

tuist-up tuist up was originally a Tuist built-in command to provision environments by reading the requirements in a manifest file Setup.swift. Althou

Tuist 5 Mar 31, 2022
A starting point to create CLI utilities with swift

cli tuist template A starting point to create CLI utilities with swift Installation Just create a Tuist folder and a Templates folder inside it. Creat

humdrum 6 May 3, 2022
A Tuist Template to quickly create CLI apps in Swift

macOS CLI Template Motivation I'm writing more and more Swift CLI apps these days. And as I solve more problems with this litte tools, I find that I'm

Diego Freniche 21 Dec 28, 2022
A cli program written in swift (with async/await) that removes the unnecessary parts of xcframeworks.

xctrim A cli program written in swift (with async/await) that removes the unnecessary parts of xcframeworks. Usecase Say you downloaded firebase sdk a

Mustafa Yusuf 32 Jul 18, 2022
Phiole - Allow to write or read from standards stream or files for script or CLI application

No longer maintained! Phiole - Φole Simple object to wrap three NSFileHandle: 'output', 'error' to write and 'input' to read There is of course a defa

Eric Marchand 8 Sep 10, 2018
Snpm - Snippet Manager CLI With Swift

Snippet Manager CLI Usage foo@bar:~$ snpm --help OVERVIEW: Utill for searching s

Gleb Zavyalov 5 Jan 5, 2023