usbguard-gui 0.3.1__tar.gz

usbguard_gui-0.3.1/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /home/dgunchev/github/gunchev/usbguard_gui/ log --oneline -3)",
+      "Read(//home/dgunchev/github/gunchev/**)",
+      "Bash(uv sync:*)",
+      "Bash(uv run:*)",
+      "Bash(git -C /home/dgunchev/github/gunchev/usbguard_gui/ status)",
+      "Bash(git:*)",
+      "Bash(make:*)",
+      "Bash(uv pip:*)",
+      "Bash(uv add:*)",
+      "Bash(ls *.py release*)",
+      "Bash(grep -E \"\\\\.\\(toml|cfg|ini|txt\\)$\")",
+      "Bash(xargs ls:*)",
+      "Bash(rpm -ql python3-gobject-base)",
+      "Bash(python3:*)",
+      "Bash(wc:*)",
+      "Bash(python:*)"
+    ]
+  }
+}

usbguard_gui-0.3.1/.copr/Makefile

@@ -0,0 +1,8 @@
+export TOP:=$(shell dirname "$(abspath $(lastword $(MAKEFILE_LIST)))")
+outdir ?= dist
+
+.PHONY: srpm
+srpm:
+	dnf -y install uv python3 python3-build python3-hatchling
+	$(MAKE) -C $(TOP)/.. srpm
+	if test -n "$(outdir)"; then cp -a $(TOP)/../dist/*.src.rpm "$(outdir)"; fi

usbguard_gui-0.3.1/.editorconfig

@@ -0,0 +1,22 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+max_line_length = 120
+
+[*.{cfg,ini,py,rst,toml,txt}]
+indent_style = space
+indent_size = 4
+
+[*.{htm,html,js,json,md,xml,yaml,yml}]
+indent_style = space
+indent_size = 2
+
+[{Makefile,*.go}]
+indent_style = tab

usbguard_gui-0.3.1/.github/workflows/makefile.yml

@@ -0,0 +1,23 @@
+name: Makefile CI
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Run tox (py310–py314) on Fedora
+      run: |
+        sudo apt-get update && sudo apt-get install -y podman
+        podman run --rm -v "$PWD:/work" -w "/work" quay.io/fedora/fedora:latest bash -c '
+          dnf -y install uv python3 python3.10 python3.11 python3.12 python3.13 make gcc fedora-packager python3-devel python3-cairo cairo-gobject-devel cairo-devel libglvnd-glx libglvnd-egl
+          UV_PYTHON_DOWNLOADS=never QT_QPA_PLATFORM=offscreen uv run tox
+        '

usbguard_gui-0.3.1/.gitignore

@@ -0,0 +1,31 @@
+/dist/
+/build/
+/htmlcov/
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.eggs/
+.tox/
+.pytest_cache/
+.coverage
+*.py,cover
+site.py
+__pypackages__/
+
+# uv
+/.venv/
+/uv.lock
+
+# Local wheels cache
+/whl_local/
+
+# Packaging
+/*.spec
+/VERSION
+
+# Editor
+/.idea/
+/.vscode/
+*.swp
+*~

usbguard_gui-0.3.1/AGENTS.md

@@ -0,0 +1,176 @@
+# AGENTS.md
+
+Instructions for agentic coding agents working in this repository.
+
+## Project Overview
+
+KDE/Qt system tray GUI for USBGuard — responds to USB device insertions with Allow, Block, or Reject actions.
+
+- **Language**: Python >= 3.10
+- **UI Framework**: PyQt6
+- **IPC**: D-Bus (via dbus-fast)
+- **Layout**: src-layout (sources in `src/usbguard_gui/`)
+
+## Build & Run Commands
+
+### Using uv (recommended)
+
+```bash
+uv run usbguard_gui                                 # run the app
+uv run python -m usbguard_gui                       # alternative entry point
+uv run pytest                                       # run all tests
+uv run pytest tests/test_file.py                    # run single test file
+uv run pytest -k test_name                          # run single test by name
+uv run pytest -v --cov . --cov-report=term-missing  # coverage
+uv run ruff check src/ tests/                       # lint
+uv run autopep8 --in-place --recursive src/ tests/  # format
+uv run tox                                          # test across Python versions
+```
+
+### Using Make
+
+```bash
+make test          # run all tests (uv run pytest -v)
+make check         # lint + test
+make lint          # ruff check + autopep8 format check
+make format        # auto-format with autopep8
+make coverage      # test with coverage report
+make build         # build wheel package
+make clean         # clean build artifacts
+make run           # sync dev deps and run app
+```
+
+## Code Style Guidelines
+
+### Formatting
+
+- **Line length**: 120 characters maximum
+- **Indentation**: 4 spaces for Python files
+- **Line endings**: LF
+- **Formatter**: autopep8
+- **Charset**: UTF-8
+- **Trailing whitespace**: trimmed
+- **Final newline**: required
+- See `.editorconfig` for additional editor-specific settings
+
+### Linter/Formatter Configuration (pyproject.toml)
+
+```toml
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "UP", "B", "SIM", "RUF"]
+
+[tool.autopep8]
+max_line_length = 120
+```
+
+### Imports
+
+- Always use `from __future__ import annotations` for postponed annotations
+- Group imports in order: stdlib, third-party, local
+- Use absolute imports: `from usbguard_gui.device import ...`
+- Sort imports with ruff (I001)
+
+### Type Hints
+
+- Required on all public APIs (functions, classes, methods)
+- Use Python 3.10+ syntax (`X | None` over `Optional[X]`)
+- Return type annotations: always present on public methods
+
+### Naming Conventions
+
+- **Classes**: `PascalCase` (e.g., `USBGuardClient`, `DeviceActionDialog`)
+- **Functions/methods**: `snake_case` (e.g., `apply_device_policy`, `_handle_disconnect`)
+- **Constants**: `SCREAMING_SNAKE_CASE` (e.g., `USBGUARD_BUS_NAME`)
+- **Private members**: leading underscore (e.g., `self._client`, `self._connected`)
+
+### Docstrings
+
+- Module-level: `"""Module description."""`
+- Classes: `"""Short description.\n\nExtended explanation if needed.\n"""`
+- Methods: `"""One-line description."""` or multi-line for complex methods
+
+### Error Handling
+
+- Use logging (`log = logging.getLogger(__name__)`) for errors and warnings
+- D-Bus errors: catch `DBusError` from `dbus_fast.error`
+- Permission errors: check error names via `_is_permission_error()` pattern
+- Never expose secrets or credentials in logs
+
+### Dataclasses & Enums
+
+- Use `@dataclass` for data models with `field(default_factory=...)` for mutable defaults
+- Use `IntEnum` for integer-backed enums (e.g., `DeviceTarget`, `PresenceEvent`)
+- Prefer `.name` over string comparison when available
+
+### Qt/PyQt6 Patterns
+
+- Subclass `QObject` for classes that emit signals
+- Use `pyqtSignal` for typed signals
+- Parent parameter in `__init__(self, parent: QObject | None = None)`
+- Connect signals in `_connect_signals()` method
+- Use `QTimer.singleShot()` for deferred actions
+
+## Project Structure
+
+```
+src/usbguard_gui/
+    __init__.py       # Package init (can export VERSION)
+    __main__.py       # python -m entry point
+    app.py            # Main tray application
+    dbus_client.py    # D-Bus client for USBGuard daemon
+    device.py         # Device model and rule parsing
+    device_dialog.py  # Device action dialog window
+    device_list.py    # Device list window
+    screensaver.py    # Screensaver state monitoring
+    settings.py       # Application settings
+
+tests/
+    test_app.py          # Tests for main tray application
+    test_device.py       # Tests for device model
+    test_device_list.py  # Tests for device list window
+    test_dbus_client.py  # Tests for D-Bus client
+    test_async_api.py    # Tests for async signal-based API
+    test_release.py      # Tests for release scripts
+```
+
+## Testing Conventions
+
+- Use `pytest` with `pytest-mock` and `pytest-cov`
+- Test files: `tests/test_<module>.py`
+- Test classes: `TestClassName` with descriptive methods
+- Test methods: `test_<what_is_tested>`
+- Use `pytest.mark.parametrize` for multiple test cases
+- Private helper methods in tests prefixed with `_`
+- Use sentinel pattern (`object()`) for special default values
+
+### Example Test Structure
+
+```python
+"""Tests for the device model and rule parser."""
+
+from usbguard_gui.device import Device, DeviceTarget, parse_device_rule
+
+
+class TestParseDeviceRule:
+  """Test rule string parsing."""
+
+  RULE_ALLOW = 'allow id 1d6b:0002 serial "..." name "..." ...'
+
+  def test_allow_rule(self):
+    result = parse_device_rule(self.RULE_ALLOW)
+    assert result["rule"] == "allow"
+```
+
+## Pre-commit Checklist
+
+Before submitting changes:
+
+1. Run `make check` (lint + tests)
+2. Ensure all new public APIs have type hints
+3. Add tests for new functionality
+4. Update docstrings for user-facing APIs
+5. No commented-out code in final submissions

usbguard_gui-0.3.1/CHANGELOG.md

@@ -0,0 +1,196 @@
+## 0.3.1 — 2026-04-11
+
+### Changes since v0.3.0
+
+- dd7565d Try integrating tags with COPR builds.
+- 004266e COPR take 3.
+- 393d0bf Fix spec file version sed-s.
+- 2acf64f Makefile: fix RPM_VER fallback for empty git output
+- d884b58 Makefile: fallback RPM_VER from __version__ if git fails
+- 05617c2 Fedora COPR Makefile integration take 2.
+
+## 0.3.0 — 2026-04-11
+
+### Changes since v0.2.3
+
+- a047831 Fix ScreenSaver inhibited detection, update dcs.
+- 1b51b2a Fast-fail D-Bus scheduler calls when disconnected
+- 6e1c049 Update the RPM spec file description.
+
+## 0.2.3 — 2026-04-11
+
+### Changes since v0.2.2
+
+- 72264b5 Fix f-string without placeholders in test_app.py and improve AGENTS.md
+- fbd4070 Increase HID lock delay from 3 to 4 seconds
+- bfd0eac Add HID disable option, fix config names, UI polish, and bug fixes
+
+## 0.2.2 — 2026-04-11
+
+### Changes since v0.2.1
+
+- d527c45 Add upgrade restart mechanism with SIGUSR1
+
+## 0.2.1 — 2026-04-11
+
+### Changes since v0.2.0
+
+- 5a70f2d Fedora COPR Makefile integration?
+
+## 0.2.0 — 2026-04-11
+
+### Changes since v0.1.0
+
+- 0aa9fd7 Release 0.2.0
+- f5ed81f Add option to disable special HID device treatment
+- cd2c7d5 Claude Opus fixes.
+- 89d6b07 Cleanup.
+- 5508d9b fix: Screen lock not triggered on HID device insertion
+- f947d8a fix: Treat composite HID devices with the same security path as pure HID
+- 3179df3 chore: Replace ruff format with autopep8 for formatting
+
+## 0.2.0 — 2026-04-11
+
+### Changes since v0.1.0
+
+- f5ed81f Add option to disable special HID device treatment
+- cd2c7d5 Claude Opus fixes.
+- 89d6b07 Cleanup.
+- 5508d9b fix: Screen lock not triggered on HID device insertion
+- f947d8a fix: Treat composite HID devices with the same security path as pure HID
+- 3179df3 chore: Replace ruff format with autopep8 for formatting
+
+## 0.1.0 — 2026-04-10
+
+### Changes since v0.0.13
+
+- e00caa3 feat: Toggle device list visibility on tray icon click
+- 91f6cd9 OpenCode is no Anthropic ;-)
+- ebaf3ac CI: add libglvnd-egl for libEGL.so.1 required by PyQt6
+- 0c2d19c Return some needed deps.
+- 4fad4fa Fix tox: add pytest-qt, tox-uv; run all Pythons in CI via Fedora packages
+- 567e4da fix: Fix ImportError: libGL.so.1, CI
+
+## 0.0.13 — 2026-04-10
+
+### Changes since v0.0.12
+
+- dff22be Fix clean exit and persist device list window state
+
+## 0.0.12 — 2026-04-10
+
+### Changes since v0.0.11
+
+- bc80337 Enforce single application instance using QLockFile
+- 34bedf1 Improve devices dialog: sortable, resizable, and reorderable columns
+- 2cfd0f5 Add documentation on how the application works and its architecture
+- cda1066 Clean up test_device_list.py: remove unused variables and noqa comments
+
+## 0.0.11 — 2026-04-05
+
+### Changes since v0.0.10
+
+- 0d5f69e Fix device list never populated due to two independent bugs
+- 2d15e00 Fix device list refresh by using refresh ID for signal correlation
+- 7f02094 Fix device list not updating due to missing pending_devices storage
+- b835a3a Add tests for async signal-based API
+- 520b74b Fix app.py and device_list.py for async API
+- dbf08f2 Add DESIGN.md documenting the PyGObject replacement approaches
+- 3f83c62 Replace PyGObject dependency with dbus-fast (QThread+asyncio)
+- db4f6db Update GitHub Actions workflow to use Podman
+
+## 0.0.10 — 2026-04-05
+
+### Changes since v0.0.9
+
+- 3a94720 fix: release.py
+- 5b72884 Configure ruff to prefer compact formatting: (by Qwen3.6 Plus Free)
+- 059df0f Remove empty file.
+- 7af2f9c Fix medium-priority issues: (by Qwen3.6 Plus Free)
+- 025d8a1 Fix high-priority issues: (by Qwen3.6 Plus Free)
+- 2d8f605 Fix critical bugs: by Qwen3.6 Plus Free - release.py build_impl crash - HID stale device reference - dialog
+  WA_DeleteOnClose access
+- ef68b4c Fix TODO.md: add trailing newline
+- 3d586a3 Add TODO.md with circuit breaker pattern suggestion for future improvements
+- 805d07d Improve error handling: Add logging, exponential backoff, and enhanced error context
+- f4e668d Fix bug in device.py, add type hints, add __all__ exports, add pyqt6-stubs
+- 4cd31a5 expand dbus_client tests to 100% coverage (by big-pickle/OpenCode)
+- 3ce112f refactor release.py for testability, add comprehensive tests (by big-pickle/OpenCode)
+- 81a1213 make CLAUDE.md a redirect to AGENTS.md
+
+## 0.0.9 — 2026-04-05
+
+### Changes since v0.0.8
+
+- f604cac dynamic versioning from __init__.py (by big-pickle/OpenCode)
+
+## 0.0.8 — 2026-04-05
+
+### Changes since v0.0.7
+
+- 6ac501c release.py: remove automatic dev version bump after release (by big-pickle/OpenCode)
+- ad32718 release.py: fix version mismatch after release, format fixes, add AGENTS.md
+- 797fb54 README: add credits section
+- 69be8be Start 0.0.8-dev
+
+## 0.0.7 — 2026-04-04
+
+### Changes since v0.0.6
+
+- 1e4fc6d rpm: install XDG autostart entry for session auto-start
+- e983a43 Start 0.0.7-dev
+
+## 0.0.6 — 2026-04-04
+
+### Changes since v0.0.5
+
+- 0be0a9c app: use usbguard_gui theme icon with fallback to source-tree SVG
+- e41aa82 device_list: remove permanent rule when demoting to temporary allow
+- 85808c5 device_list: refresh immediately after context-menu action
+- b347e57 device_list: blue background for temporarily allowed devices
+- ebd9daa app: fix spurious device dialogs for allowed/non-insert events
+- dbb035c app: add detailed debug logging for device presence events
+- e638935 Makefile: use python -m usbguard_gui in run target
+- df30bd7 app: fix spurious device dialogs for allowed/non-insert events
+- 713e99b Start 0.0.6-dev
+
+## 0.0.5 — 2026-04-04
+
+### Changes since v0.0.4
+
+- 96bdf78 app: use usbguard_gui theme icon with fallback
+- 8c2b9d7 Start 0.0.5-dev
+
+## 0.0.4 — 2026-04-04
+
+### Changes since v0.0.3
+
+- 28396f0 Add whl_local/.gitignore
+- 49fbc4d rpm: fix %preun, drop %postun and unused systemd macros
+- 7b50b6f rpm: force-enable usbguard-dbus.service on install
+- f40e501 Start 0.0.4-dev
+
+## 0.0.3 — 2026-04-04
+
+### Changes since v0.0.2
+
+- 49c55d1 device_list: use dark row colors with white text
+- ff03739 rpm: require usbguard-dbus, enable its service on install
+- 552a629 Fix duplicate signals, auth errors, add polkit rule
+- 58e907d Start 0.0.3-dev
+
+## 0.0.2 — 2026-04-04
+
+### Changes since v0.0.1
+
+- b2408ca Add RPM packaging
+- 430cd16 Start 0.0.2-dev
+
+## 0.0.1 — 2026-04-04
+
+### Changes since beginning
+
+- a071a82 Rename to usbguard_gui, python things...
+- 76f5233 Add release.py.
+- 83838a4 Add Makefile
+- adc75c8 Initial implementation of usbguard_gui

usbguard_gui-0.3.1/CLAUDE.md

@@ -0,0 +1,3 @@
+# usbguard_gui
+
+See [AGENTS.md](AGENTS.md) for full instructions.

usbguard_gui-0.3.1/DESIGN.md

@@ -0,0 +1,203 @@
+# Replacing PyGObject with dbus-fast
+
+This document describes the migration from `dasbus + PyGObject` to `dbus-fast` to eliminate the PyGObject dependency.
+
+## Motivation
+
+dasbus uses PyGObject (gi) internally for GLib type system integration. Even though the application uses PyQt6 (not
+GTK), dasbus requires GLib's type introspection layer. PyGObject is a heavy dependency that many systems may not have
+pre-installed.
+
+## Solution: dbus-fast
+
+`dbus-fast` is a pure-Python asyncio D-Bus library with no GLib dependency. Two integration approaches were explored:
+
+### Branch 1: `dev-glib`
+
+Uses `dbus_fast.glib` which integrates with GLib's main loop.
+
+### Branch 2: `dev-qthread` (This branch)
+
+Uses `dbus_fast.aio` in a dedicated QThread with its own asyncio event loop.
+
+---
+
+## Implementation Details
+
+### Dependencies Changed
+
+**Before:**
+
+```toml
+dependencies = [
+  "PyQt6>=6.5",
+  "dasbus>=1.7",
+  "PyGObject>=3.42",
+]
+```
+
+**After:**
+
+```toml
+dependencies = [
+  "PyQt6>=6.5",
+  "dbus-fast>=1.0",
+]
+```
+
+### New Files
+
+```
+src/usbguard_gui/introspection/
+├── org.usbguard.Devices1.xml    # USBGuard Devices interface
+├── org.usbguard.Policy1.xml     # USBGuard Policy interface
+└── org.freedesktop.ScreenSaver.xml  # ScreenSaver interface
+```
+
+### API Changes
+
+| dasbus                        | dbus-fast                                                    |
+|-------------------------------|--------------------------------------------------------------|
+| `SystemMessageBus()`          | `MessageBus(bus_type=BusType.SYSTEM)`                        |
+| `bus.get_proxy(name, path)`   | `bus.get_proxy_object(name, path, xml).get_interface(iface)` |
+| `proxy.listDevices()`         | `proxy.call_list_devices()`                                  |
+| `proxy.Signal.connect(cb)`    | `proxy.on_signal(cb)`                                        |
+| `proxy.Signal.disconnect(cb)` | `proxy.off_signal(cb)`                                       |
+| `DBusError.error_name`        | `DBusError.type`                                             |
+
+### Error Handling
+
+```python
+# dasbus
+def _is_permission_error(e: DBusError) -> bool:
+  name = getattr(e, "error_name", "") or ""
+
+
+# dbus-fast
+def _is_permission_error(e: DBusError) -> bool:
+  error_name = getattr(e, "type", "") or ""
+```
+
+---
+
+## This Branch: QThread + asyncio
+
+This implementation uses a dedicated QThread running an asyncio event loop to handle D-Bus communication.
+
+### Architecture
+
+```
+USBGuardClient (QObject)                    _DBusThread (QThread)
+├── Public API (unchanged)                  ├── Runs asyncio event loop
+├── Receives results via signals            ├── Connects to D-Bus
+└── Forwards signals to GUI                ├── Schedules commands from queue
+                                            └── Emits results as Qt signals
+
+ScreensaverMonitor (QObject)                _ScreensaverThread (QThread)
+├── Public API (unchanged)                  ├── Runs asyncio event loop
+├── Receives active_changed via signal      └── Connects to session D-Bus
+```
+
+### Key Components
+
+**`_DBusThread`**: QThread subclass that:
+
+- Creates a new asyncio event loop
+- Connects to system D-Bus using `dbus_fast.aio.MessageBus`
+- Maintains proxy objects for USBGuard interfaces
+- Subscribes to D-Bus signals (DevicePresenceChanged, DevicePolicyChanged)
+- Processes commands from a queue (thread-safe communication)
+- Emits Qt signals for device events and method results
+
+**Command Queue Pattern**:
+
+```python
+def list_devices(self, query: str = "match") -> None:
+  if self._devices_iface and self._loop:
+    self._schedule(self._do_list_devices(query))
+
+
+def _schedule(self, coro: asyncio.coroutine) -> None:
+  if self._loop and self._running:
+    self._loop.call_soon_threadsafe(asyncio.ensure_future, coro)
+```
+
+### API Changes in This Branch
+
+Methods are now **asynchronous fire-and-forget**:
+
+- `client.list_devices()` → returns via `list_devices_result` signal
+- `client.apply_device_policy()` → returns via `apply_policy_result` signal
+- `client.list_rules()` → returns via `list_rules_result` signal
+- `client.remove_rule()` → returns via `remove_rule_result` signal
+
+### New Signals Added
+
+| Signal                | Parameters              | Description                     |
+|-----------------------|-------------------------|---------------------------------|
+| `list_devices_result` | `list[Device]`          | Result of list_devices()        |
+| `apply_policy_result` | `int \| None`           | Result of apply_device_policy() |
+| `list_rules_result`   | `list[tuple[int, str]]` | Result of list_rules()          |
+| `remove_rule_result`  | `bool`                  | Result of remove_rule()         |
+
+---
+
+## Approach Comparison
+
+### dev-glib: GLib Integration
+
+**Pros:**
+
+- Simpler implementation
+- No additional threads needed
+- Direct signal/callback integration with Qt
+- Synchronous methods (return values directly)
+
+**Cons:**
+
+- Still requires GLib dependency
+
+### dev-qthread: QThread + asyncio (This branch)
+
+**Pros:**
+
+- Pure asyncio, no GLib dependency
+- Clear separation of async and sync code
+- More control over event loop
+
+**Cons:**
+
+- More complex architecture
+- Command queue pattern required for thread-safe communication
+- Asynchronous methods become fire-and-forget (results via signals)
+- Additional Qt signals needed for results
+
+---
+
+## Files Modified
+
+| File                        | Changes                                                   |
+|-----------------------------|-----------------------------------------------------------|
+| `pyproject.toml`            | Replace dasbus + PyGObject with dbus-fast                 |
+| `dbus_client.py`            | Add `_DBusThread` class, refactor to async pattern        |
+| `screensaver.py`            | Add `_ScreensaverThread` class, refactor to async pattern |
+| `tests/test_dbus_client.py` | Update mocks for new architecture                         |
+
+## Verification
+
+Both branches pass:
+
+- All unit tests (75 tests)
+- Lint checks (ruff)
+- Format checks (ruff)
+
+## Recommendation
+
+**Use `dev-glib`** for production. It's simpler, has fewer components, and the GLib dependency is already present on
+most Linux systems that would run USBGuard.
+
+Use `dev-qthread` only if:
+
+- GLib dependency must be completely avoided
+- Maximum isolation of async code is required
+- Debugging async behavior is easier with a separate thread