A Wayland/Waybar compatible applet for controlling USBGuard with a GTK4 GUI interface.

• Waybar Integration: Custom module that displays USB device status
• GTK4 GUI: Modern interface for managing USB devices
• Device Control: Allow, block, or reject USB devices
• Policy Management: Generate and edit USBGuard policies
• D-Bus Integration: Communicates with USBGuard daemon via D-Bus
• CLI Tools: Command-line interface for device management
• NixOS Integration: Fully integrated with Nix flakes

• NixOS or Nix package manager
• USBGuard daemon running
• Wayland compositor (for GUI)
• Waybar (optional, for status bar integration)

nix profile install github:shift/usbg

git clone https://github.com/shift/usbg.git cd usbg nix build

If using flakes, add USBG to your flake inputs:

{ inputs = { # ... other inputs usbg.url = "github:shift/usbg"; }; outputs = { self, nixpkgs, usbg, ... }: { nixosConfigurations.yourhost = nixpkgs.lib.nixosSystem { modules = [ usbg.nixosModules.default { services.usbg = { enable = true; waybar.enable = true; systemdUserService = true; }; } # ... other modules ]; }; }; }

For non-flake setups, add the module directly:

{ config, pkgs, ... }: { imports = [ (builtins.fetchTarball "https://github.com/shift/usbg/archive/main.tar.gz") ]; services.usbg = { enable = true; waybar.enable = true; systemdUserService = true; }; }

For Home Manager users (recommended if Waybar is managed via Home Manager):

{ inputs = { # ... other inputs usbg.url = "github:shift/usbg"; }; outputs = { self, nixpkgs, home-manager, usbg, ... }: { homeConfigurations.youruser = home-manager.lib.homeManagerConfiguration { modules = [ usbg.homeManagerModules.default { services.usbg = { enable = true; waybar.enable = true; systemdUserService = true; }; } # ... other modules ]; }; }; }

Note: You'll still need the NixOS module for USBGuard daemon and D-Bus permissions. Use both modules together for full integration.

IMPORTANT: Before running commands, enter the Nix development shell:

nix develop

Or use direnv (recommended):

direnv allow

If you're not in the devShell, you'll need to run commands with:

nix develop -c -- <command>

Launch the graphical interface:

usbg gui

Or simply:

usbg

Add to your Waybar configuration (~/.config/waybar/config):

{ "modules-right": ["custom/usbguard"], "custom/usbguard": { "exec": "usbg waybar --continuous", "return-type": "json", "interval": "once", "tooltip": true, "on-click": "usbg gui" } }

List all USB devices:

usbg list usbg list -v # verbose output

Allow a device:

usbg allow <device-id> usbg allow <device-id> --permanent

Block a device:

usbg block <device-id> usbg block <device-id> --permanent

Generate policy from current devices:

usbg generate-policy usbg generate-policy -o /etc/usbguard/rules.conf

Install the systemd user service for automatic Waybar integration:

mkdir -p ~/.config/systemd/user cp systemd/usbg-waybar.service ~/.config/systemd/user/ systemctl --user enable --now usbg-waybar.service

Configuration file location: ~/.config/usbg/config.json

Default configuration:

{ "waybar": { "update_interval": 2, "show_tooltip": true, "show_notifications": true }, "gui": { "start_minimized": false, "enable_system_tray": true }, "usbguard": { "auto_allow_known": false, "notification_on_block": true } }

Build the project:

nix build

Run checks:

nix flake check

Enter the development shell:

nix develop

The development environment includes:

• Python 3 with PyGObject and dbus-python
• GTK4 and libadwaita
• USBGuard tools
• All necessary build dependencies

Run the application in development mode:

python -m usbg

Ensure USBGuard daemon is running:

systemctl status usbguard

If not running, start it:

sudo systemctl start usbguard sudo systemctl enable usbguard

You may need to configure D-Bus permissions for your user to access USBGuard.

Create /etc/dbus-1/system.d/usbguard.conf:

<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"> <busconfig> <policy user="shift"> <allow send_destination="org.usbguard1"/> </policy> </busconfig>

usbg/ ├── flake.nix # Nix flake configuration ├── pyproject.toml # Python package configuration ├── usbg/ │ ├── __init__.py # Package initialization │ ├── __main__.py # Main entry point │ ├── app.py # GTK4 GUI application │ ├── cli.py # CLI argument parser │ ├── config.py # Configuration management │ ├── dbus_client.py # USBGuard D-Bus interface │ └── waybar.py # Waybar module output └── systemd/ └── usbg-waybar.service # Systemd user service 

• Ensure USBGuard daemon is running: systemctl status usbguard
• Check D-Bus permissions (see D-Bus Permissions section above)
• Verify your user has appropriate PolicyKit permissions

• Make sure you're running a Wayland compositor
• Check GTK4 and libadwaita are available
• Run from Nix devShell: nix develop -c -- usbg gui

• Check the systemd service: systemctl --user status usbg-waybar
• Verify Waybar configuration syntax
• Check logs: journalctl --user -u usbg-waybar

Contributions are welcome! Please ensure:

• Code follows Python conventions
• All changes work within Nix build system
• No binaries are committed to the repository
• Tests are included for new features

MIT License - see LICENSE file for details

• USBGuard - USB device authorization framework
• Waybar - Highly customizable Wayland bar
• GTK4 - GUI toolkit