Omahub
← All plugins
S

USBGuard

by Skymebr

Zero-friction kernel-level USB authorization, BadUSB mitigation, and device manager for Omarchy.

GitHub

Security review

Potentially dangerous behavior detected · 11 findings

Deterministic scan — not a security guarantee

High
Risk level
High
Analyzed commit
ffdf37f
Scanned
1 month ago
  • high persistence omarchy-setup-security-usbguard:162

    Registers scheduled or boot-time system tasks.

    systemctl disable usbguard.service 2>/dev/null || true
  • high persistence omarchy-setup-security-usbguard:351

    Registers scheduled or boot-time system tasks.

    systemctl enable --now usbguard.service
  • high persistence omarchy-setup-security-usbguard:331

    Bundles a systemd unit file.

    [Unit]
  • medium package_manager …/workflows/lint.yml:17

    System package manager operation.

    apt-get install -y shellcheck
  • medium package_manager …/workflows/lint.yml:35

    System-wide Python package installation (not --user).

    pip install ruff mypy
  • medium sudo …/workflows/lint.yml:17

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo apt-get install -y shellcheck
  • low obfuscation test_backend.py:68

    Augments a command with octal/hex escape sequences.

    \x1bName"), "Device Name")
  • Docs external_hosts README.md:148

    Downloads or connects to an external HTTP(S) host.

    git clone https://github.com/Skymebr/omarchy-usbguard.git
  • Docs sudo README.md:206

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo systemctl stop usbguard
  • Docs sudo README.md:207

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo rm -f /etc/usbguard/rules.conf
  • Docs sudo README.md:208

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo systemctl restart usbguard

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
ffdf37f
Reviewed
1 month ago

This is a legitimate USBGuard management plugin that requires sudo to configure system services and policy, which is expected for such a tool. The deterministic findings are mostly documentation (README sudo commands, CI package installs) or expected system operations (systemctl enable/disable, systemd unit). No obfuscated or malicious code was found; the test_backend.py escape sequences are just test data. The plugin performs standard USBGuard operations with proper input sanitization and validation.

  • Requires sudo and modifies system configuration (USBGuard rules, daemon config, systemd services), which is inherent to its purpose but should be reviewed by the user.
  • The setup script writes to /etc/usbguard and enables a systemd service; ensure the user understands the security implications.
  • The plugin grants the desktop user IPC modify permissions on USBGuard, which could allow permanent whitelist changes; this is a trade-off documented in SECURITY.md.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/Skymebr/omarchy-usbguard --enable
System #security

Omarchy USBGuard Hardware Protection

License: MIT Platform: Omarchy / Arch Linux Security: Kernel Level Architecture: Event--Driven

A zero-friction, kernel-level USB device authorization, BadUSB mitigation suite, and native status bar plugin for the Omarchy Linux desktop environment.

<p align="center"> <img src="preview.png" alt="Omarchy USBGuard Screenshot" width="480"> </p> 
  󰌾 1        ┌────────────────────────────────────────────────────────┐
             │  󰌾  USBGuard                                      󰑐   │
             │     1 BLOCKED DEVICE(S)                                │
             │  ────────────────────────────────────────────────────  │
             │  [ 󰕓 Connected (3) ]     [ 󰕥 Whitelist Rules (3) ]     │
             │                                                        │
             │  🚨 SEMICO USB Keyboard                                │
             │     USB Keyboard · ID 28 (1a2c:6004) · Port 3-3        │
             │     [ Allow (Session) ]  [ 󰕥 Trust (Permanent) ] [ 󰅖 ] │
             │                                                        │
             │  ●  Lite-On MediaTek Bluetooth MT7921     [ Internal ] │
             │     Internal Bluetooth Radio · Hardwired               │
             │  ●  HD User Facing (Webcam)               [ Internal ] │
             │     Integrated Webcam · Hardwired                      │
             │  ────────────────────────────────────────────────────  │
             │  󰕥 Hardware Protection Active                          │
             └────────────────────────────────────────────────────────┘

⚡ Quick Install (Omarchy Plugin)

omarchy plugin add https://github.com/Skymebr/omarchy-usbguard.git --enable --yes

Features

  • Native Status Bar Widget (Panel.qml): Integrated Quickshell icon with dynamic security states (󰕓 Safe, 󰌾 Blocked with count badge, 󰕤 BadUSB Threat).
  • Zero-Friction Authorization: One-click Allow (Session), Trust (Permanent), Reject, and Block actions.
  • Visual Whitelist Manager: Inspect active permanent rules and revoke trusted devices with a single click (󰅖).
  • High-Speed Hardware Resolution (backend.py): Sub-15ms Linux hwdata and sysfs bulk scanner resolving official vendor and product names.
  • Active BadUSB Mitigation: Heuristic detection for composite storage + keystroke/network injection attacks.
  • Anti-Lockout Baseline: Automatic preservation of onboard motherboard hardware (webcam, bluetooth, keyboard/touchpad).

Threat Model and Protection Scope

Linux systems by default automatically probe, enumerate, and bind kernel drivers to any USB device connected to a physical port. This creates distinct attack surfaces that omarchy-usbguard actively mitigates:

  1. BadUSB / Keystroke Injection Attacks (HID Spoofing): Malicious microcontrollers (e.g., Rubber Ducky, MalDuino) disguised as standard mass storage drives or charging cables that register as high-speed keyboards to execute arbitrary shell commands.
  2. Rogue Network Interfaces: Composite USB devices that advertise CDC/Ethernet or RNDIS interfaces to hijack local network routes and perform DHCP/DNS spoofing.
  3. Firmware Descriptor Exploits: Malicious USB descriptors designed to trigger kernel heap/buffer overflows in legacy USB class drivers prior to user login.

Architecture and Execution Flow

[ Physical USB Connection ]
            │
            ▼
[ Linux Kernel USB Core ] ─── (authorized = 0)
            │
            ▼
[ usbguard-daemon (IPC) ]
            │
            ▼ (via native -e event hook)
[ omarchy-usbguard-event ]
            │
    ├── 1. Interface Class Inspection (Storage 08h, HID 03h, Net 02h)
    ├── 2. BadUSB Composite Detection (Storage + HID combo inspection)
    ├── 3. Attacker String Sanitization (C0 strip, dash removal, length cap)
    ├── 4. Hardware Name Resolution (lsusb / hwdata lookup)
    └── 5. Dynamic Hash Replace ID Generation (SHA-256 slice)
            │
            ▼
[ Quickshell Desktop Notification (omarchy-notification-send) ]
            │
            ├── Right-Click: Dismiss (Keep blocked)
            └── Left-Click: Open Selection Modal (omarchy-menu-select)
                     │
                     ├── Allow for this session only (usbguard allow-device <id>)
                     ├── Trust permanently (usbguard allow-device <id> -p)
                     ├── Reject device (usbguard reject-device <id>)
                     └── Keep blocked (usbguard block-device <id>)

Key Technical Implementations

1. Interface-Driven Classification (Anti-Spoofing)

Device categorization is performed strictly via 2-digit hexadecimal USB interface class codes (08: for Mass Storage, 03:01:01 for Boot Keyboard, 03:01:02 for Boot Mouse, 02:/0a: for CDC Network, 01: for Audio, 0e:/10: for Video, e0: for Wireless/Bluetooth). Firmware-provided device strings (iProduct) are treated as untrusted and never used for security classification.

2. BadUSB Composite Inspection

If a single physical device descriptor advertises both Mass Storage (08:) and Human Interface Device (03:) interfaces, the event processor flags it as a high-risk BadUSB candidate, escalating notification urgency and prompting the user with an explicit security warning.

3. Native Event Hook (usbguard watch -e)

Eliminates brittle multiline stdout terminal scraping. The watcher runs usbguard watch -w -e omarchy-usbguard-event, receiving structured environment variables (USBGUARD_DEVICE_ID, USBGUARD_DEVICE_EVENT, USBGUARD_DEVICE_TARGET, USBGUARD_DEVICE_RULE) directly from the IPC bus.

4. Input Sanitization

Firmware strings (iProduct, iSerial) are sanitized before being passed to desktop notification APIs:

  • Strips ASCII control characters (\x00-\x1f\x7f).
  • Collapses sequential whitespace.
  • Removes leading hyphens to prevent CLI argument injection (e.g. --exec).
  • Enforces bounded string length limits.

5. Hardware Hash Validation and Dynamic Notification IDs

  • ID Recycling Protection: omarchy-usbguard-allow validates the target device ID and its SHA-256 descriptor hash against the live daemon device table before applying allow/reject commands.
  • Notification Collision Prevention: Generates unique notification replace IDs derived from the hardware descriptor hash, ensuring concurrent USB insertions do not overwrite one another.

6. Anti-Lockout Baseline Setup

  • Automatically injects allow with-connect-type "hardwired" at the top of the ruleset to ensure internal webcams, onboard Bluetooth radios, and fingerprint readers are never locked out.
  • Configures PresentDevicePolicy=keep in /etc/usbguard/usbguard-daemon.conf to prevent active hardware drops during daemon restarts.

Installation

Method 1: Native Omarchy Shell Plugin (Recommended)

Install and enable the status bar widget and popup panel directly via the Omarchy CLI:

omarchy plugin add https://github.com/Skymebr/omarchy-usbguard.git --enable --yes

Then run the one-time hardware baseline setup wizard:

omarchy-setup-security-usbguard

Method 2: Manual Clone & Setup

Clone the repository and run the setup wizard:

git clone https://github.com/Skymebr/omarchy-usbguard.git
cd omarchy-usbguard
./omarchy-setup-security-usbguard

Installation Flags

Flag Description
-y, --yes Skip the interactive confirmation prompt (useful for automated scripts).
--regenerate-policy Rebuild /etc/usbguard/rules.conf from currently attached hardware, saving a timestamped backup.
--user <username> Explicitly specify the non-root user authorized for IPC access.
--remove Perform a complete, clean rollback and uninstall.

Component Reference

File Purpose
manifest.json Omarchy Shell plugin manifest defining bar widget and settings schema.
Panel.qml Quickshell bar widget and interactive control panel flyout.
backend.py High-speed hardware name resolver, BadUSB inspector, and JSON formatter.
omarchy-setup-security-usbguard Installation wizard, policy generator, and rollback manager.
omarchy-setup-usbguard Compatibility symlink mapping to setup wizard.
omarchy-usbguard-watch Background systemd service wrapper invoking event delegation.
omarchy-usbguard-event Structured event handler executing classification, sanitization, and desktop notifications.
omarchy-usbguard-prompt Interactive Quickshell menu interface (omarchy-menu-select).
omarchy-usbguard-allow Hash-validated authorization execution helper.
omarchy-usbguard-manage Zero-friction trusted device revocation and whitelist manager.

Policy Management and Rollback

Rebuilding Policy for New Hardware

When permanently attaching new desktop peripherals (e.g., a new docking station or external keyboard):

omarchy-setup-security-usbguard --regenerate-policy

Clean Uninstallation

To cleanly disable USBGuard, remove systemd units, restore configuration backups, and purge installed binaries:

omarchy-setup-security-usbguard --remove

Emergency Recovery (Troubleshooting)

If you accidentally misconfigure rules or boot into a locked session without working keyboard/mouse input:

  1. Switch to a TTY (Ctrl + Alt + F3) or boot into rescue mode.
  2. Stop the daemon and restore your previous policy backup: 
    sudo systemctl stop usbguard
sudo cp /etc/usbguard/rules.conf.bak.* /etc/usbguard/rules.conf 2>/dev/null || sudo rm -f /etc/usbguard/rules.conf
sudo systemctl restart usbguard
  3. To disable USBGuard entirely from the console: 
    omarchy-setup-security-usbguard --remove

Security Policy

For vulnerability reporting guidelines, see SECURITY.md.

License

This project is licensed under the terms of the MIT License.