Skip to content

Commit ed2fce5

Browse files
author
Arndt Haßel-Kurz
committed
initial
0 parents  commit ed2fce5

11 files changed

Lines changed: 732 additions & 0 deletions

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.DS_Store
2+
*.log

‎ACKNOWLEDGMENTS.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Acknowledgments
2+
3+
Hackboard is built on [Karabiner Elements](https://karabiner-elements.pqrs.org/), created and maintained by [Fumihiko Takayama](https://github.com/tekezo) (pqrs.org). Karabiner Elements is the foundation that makes Hackboard possible — years of careful, reliable engineering that the entire macOS keyboard community depends on.
4+
5+
Hackboard ships a modified fork called Hb-Karabiner-Elements. The core key-event engine, the DriverKit virtual HID driver, and the security architecture are inherited from upstream. Our modifications add custom functionality and a visual interface on top — the foundation is his work.
6+
7+
If you appreciate what Hackboard does, please consider [supporting Karabiner Elements directly](https://karabiner-elements.pqrs.org/docs/pricing/).

‎LICENSE‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
© 2026 Farbe Software UG (haftungsbeschränkt). All rights reserved.
2+
3+
Use is subject to the Hackboard Terms of Service: https://github.com/farbe-software/hackboard/blob/main/TERMS.md

‎PRIVACY.md‎

Lines changed: 248 additions & 0 deletions
Large diffs are not rendered by default.

‎README.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Hackboard
2+
3+
![macOS 13+](https://img.shields.io/badge/macOS-13%2B-blue?style=flat-square)
4+
![Karabiner-Elements](https://img.shields.io/badge/Karabiner--Elements-15.0.0-green?style=flat-square)
5+
6+
Hackboard is a macOS app enabling layered keymaps (based on the hold-tap paradigm) to trigger actions more efficiently and ergonomically with your keyboard. **Hold a key, tap another, map it to an action - that's a keymap.**
7+
8+
**Examples**:
9+
10+
| Sequence | Action |
11+
|---|---|
12+
| `Hold ⌘` → `Hold A` → `Tap T` | Open Terminal |
13+
| `Hold ⌘` → `Hold A` → `Hold S` → `Tap M` | Open Maps in Safari |
14+
| `Hold F` → `Tap J, K, L, ;` | Arrow Keys |
15+
| `Hold F` → `Tap Space` | Enter |
16+
| `Hold ⌘` → `Hold T` → `Tap E` | Type your_email@example.com |
17+
18+
19+
Hackboard bundles Hb-Karabiner-Elements, a fork of [Karabiner-Elements](https://karabiner-elements.pqrs.org/) by [Fumihiko Takayama](https://github.com/tekezo) — without his years of work, this wouldn't exist. [Support his work](https://karabiner-elements.pqrs.org/docs/pricing/). Inspired by [Max Stoiber's sublayer concept](https://github.com/mxstbr/karabiner). Fully compatible with your existing Karabiner config, currently pinned to version 15.0.0.
20+
21+
<img src="./demo_recording.gif" width="50%" />
22+
23+
<img src="./demo_image.jpeg" />
24+
25+
## Beta
26+
27+
Pre-launch users obtain a free lifetime license by submitting feedback through the app (provide email!). A generous free tier and a fair lifetime license will exist after launch.
28+
29+
## Get Started
30+
31+
1. [Download Latest GitHub Release](https://github.com/farbe-software/hackboard/releases/latest/download/Hackboard.dmg)
32+
2. **Hb-Karabiner-Elements** starts automatically after install — grant the macOS permissions it requests (Input Monitoring, virtual HID driver).
33+
3. **Start Hackboard** — it asks for access to the folder containing `karabiner.json` via a system folder picker.
34+
4. Hackboard loads an example configuration - try it, change it and hack away!
35+
36+
> [!IMPORTANT]
37+
> **Switching from Karabiner-Elements?** Uninstall it first and ensure your `karabiner.json` is compatible with Karabiner-Elements 15.0.0.
38+
> - If there are problems with permissions, try deactivating and reactivating them.
39+
> - Your existing `karabiner.json` rules remain unaffected and will continue to work. If any of them conflict with your Hackboard keymaps, the Hackboard keymaps take priority.
40+
41+
## Uninstall
42+
43+
A full uninstall can be triggered from the Hackboard settings page or through the Hb-Karabiner-Elements UI. Either option removes both applications. A restart is required to complete the uninstallation.
44+
45+
## Feedback & Issues
46+
47+
Found a bug or have a suggestion? [Open an issue](https://github.com/farbe-software/hackboard/issues) on this repository.
48+
49+
## Legal
50+
51+
By downloading and using Hackboard, you agree to the [Terms of Service](TERMS.md) and acknowledge the [Privacy Policy](PRIVACY.md).

‎SECURITY.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Hackboard - Security Information
2+
3+
Thank you for helping us keep Hackboard secure.
4+
5+
## Scope & Definition
6+
7+
This document covers:
8+
- **Hackboard.app**
9+
- **Hb-Karabiner-Elements** (the bundled Karabiner fork)
10+
11+
Both are referred to in union as 'Hackboard'.
12+
13+
## Permissions
14+
15+
Hackboard customizes keyboard input at the system level. This requires privileges:
16+
17+
- **Input Monitoring** — Hb-Karabiner-Elements sees all keyboard input system-wide. This is how key remapping works; no keystroke data is stored or transmitted.
18+
- **Virtual HID driver** — A signed DriverKit extension (from pqrs, the Karabiner maintainer) creates a virtual keyboard that delivers remapped input to macOS.
19+
- **Root background service** — `karabiner_grabber` runs with root privileges to access low-level input devices. This is standard for keyboard customization tools on macOS and inherited unchanged from Karabiner Elements.
20+
- **Shell commands** — Keymaps can trigger shell commands that run as your user account. You author all configurations yourself; Hackboard does not support importing third-party configs.
21+
22+
23+
## Security Model
24+
25+
**Local-first.** Hackboard operates entirely on your machine. All keyboard input is processed locally by Karabiner's virtual keyboard driver — no keystrokes, usage patterns, or personal data are intentionally transmitted from your machine. All configurations are created and modified by you alone; Hackboard does not include functionality to import third-party configurations. You carry full control and responsibility for your setup.
26+
27+
**Inherited security architecture.** Hb-Karabiner-Elements does not modify the Karabiner Elements security model. The root-privileged core service, virtual HID driver restrictions, and closed-process design are inherited unchanged from upstream. For details, see the [Karabiner Elements security documentation](https://karabiner-elements.pqrs.org/docs/help/advanced-topics/security/).
28+
29+
**File access.** Hackboard.app requests access to the folder containing `karabiner.json` via a macOS system folder picker. It uses security-scoped bookmarks to remember this access across launches, and cannot read or write files outside the granted folder without explicit user consent.
30+
31+
**Minimal network activity.** Hackboard's only network communication:
32+
- **Update checks** — When automatic update checks are enabled, Sparkle periodically fetches a small XML file from this repository to check for new versions. You can also check for updates manually via the menu. Your IP address is transmitted to GitHub Pages as part of the request.
33+
- **Crash reports** — When crash reporting is enabled in Settings, crash data is sent to Sentry if the app encounters an error. Crash reports may incidentally contain technical identifiers; personally identifiable information is not intentionally collected (`sendDefaultPii: false`). See [Privacy Policy](PRIVACY.md) for details.
34+
35+
## Inherent Risks
36+
37+
Keyboard customization at Hackboard's depth involves risks that are inseparable from the technology:
38+
39+
- **Elevated system privileges** — Root-level processes (`karabiner_grabber`, `Karabiner-VirtualHIDDevice-Daemon`, `karabiner_session_monitor`) run with system access to intercept keyboard input at the hardware level.
40+
- **Shell command execution** — Keymaps can trigger arbitrary shell commands. Maliciously or inadvertantly configured commands can perform harmful actions.
41+
- **Unexpected keyboard behavior** — Misconfigured keymaps may cause keys to produce unintended input, stop responding, or behave erratically.
42+
- **Software conflicts** — Other software that modifies keyboard input may conflict with Hackboard. Hackboard cannot coexist with a separate Karabiner-Elements installation.
43+
44+
Hackboard actively mitigates each of these risks through its security architecture, configuration validation, and command safety filtering.
45+
46+
### Installed System Components
47+
48+
The bulk of the system-level footprint comes from Hb-Karabiner-Elements.
49+
50+
**Hackboard app:**
51+
52+
| Component | Location |
53+
|-----------|----------|
54+
| Hackboard.app | /Applications/ |
55+
| User preferences and state | ~/Library/Application Support/com.farbe.hackboard/ |
56+
| `hb_keymaps.json` (keymap config) | ~/Library/Application Support/com.farbe.hackboard/ |
57+
58+
**Hb-Karabiner-Elements** (all components below originate from the Karabiner-Elements open-source project):
59+
60+
*Applications:*
61+
62+
| Component | Location |
63+
|-----------|----------|
64+
| Hb-Karabiner-Elements.app | /Applications/ |
65+
| Karabiner-EventViewer.app | /Applications/ |
66+
| Karabiner-Menu.app | /Library/Application Support/org.pqrs/ |
67+
| Karabiner-NotificationWindow.app | /Library/Application Support/org.pqrs/ |
68+
| Karabiner-MultitouchExtension.app | /Library/Application Support/org.pqrs/ |
69+
70+
*Root-level services (LaunchDaemons):*
71+
72+
| Service | Purpose |
73+
|---------|---------|
74+
| `karabiner_grabber` | Low-level keyboard event capture (runs as root) |
75+
| `Karabiner-VirtualHIDDevice-Daemon` | Virtual HID device management (runs as root) |
76+
77+
*User-level services (LaunchAgents):*
78+
79+
| Service | Purpose |
80+
|---------|---------|
81+
| `karabiner_console_user_server` | IPC server, shell command execution |
82+
| `karabiner_session_monitor` | Session state monitoring (setuid root) |
83+
| `karabiner_grabber` (user agent) | User-level event capture |
84+
| `Karabiner-Menu` | Menu bar UI |
85+
| `Karabiner-NotificationWindow` | System notifications |
86+
| `Karabiner-MultitouchExtension` | Trackpad event support |
87+
88+
*Other:*
89+
90+
| Component | Details |
91+
|-----------|---------|
92+
| DriverKit extension | Karabiner-DriverKit-VirtualHIDDevice (user-space virtual HID driver, signed by pqrs) |
93+
| setuid binary | `karabiner_session_monitor` (4755) — required for `CGSessionCopyCurrentDictionary` |
94+
| Configuration | `~/.config/karabiner/karabiner.json` (permissions 0600) |
95+
96+
**Uninstall:** The bundled uninstaller removes all system components listed above. User configuration (`karabiner.json`, Hackboard preferences) is preserved for manual deletion.
97+
98+
99+
100+
## Reporting a Vulnerability
101+
102+
If you discover a security vulnerability in Hackboard or Hb-Karabiner-Elements, please report it responsibly.
103+
104+
**Email:** [contact@hackboard.app](mailto:contact@hackboard.app)
105+
106+
Please include:
107+
- A description of the vulnerability and its potential impact
108+
- Steps to reproduce, if possible
109+
- The version of Hackboard and macOS you are using
110+
- If the vulnerability extends to upstream Karabiner-Elements, consider reporting there as well.
111+
112+
We will acknowledge your report within 7 days and work with you to understand and address the issue. Please do not disclose the vulnerability publicly until we have had a reasonable opportunity to fix it. For information on how we handle your personal data, see our [Privacy Policy](PRIVACY.md).
113+

0 commit comments

Comments
 (0)