Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- Explicit screen-reader names for the device filter/list, device details action,
and icon-only main menu; a repeatable 20-device background memory check.
- A development-only `USBGUARD_GUI_ISOLATED_INSTANCE=1` option for running a
demo/test GUI without forwarding activation to the installed application.
- AT-SPI name assertions in the disposable clean-install UI test for the device
filter/list/details and main menu.
- A local event history for observed device insertions/removals, authorization
outcomes, daemon reconnections and resynchronization gaps. It is capped at 200
entries, stores only categories and timestamps, persists only by opt-in, and
Expand Down Expand Up @@ -50,6 +56,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Fixed

- Closing native dialogs with animations disabled retains the dialog until the
GTK button callback finishes, avoiding a GObject critical during destruction.
- Coverage targets find checkout-local cargo-llvm-cov without shell PATH changes,
check graphical prerequisites before running tests, and give pinned install
instructions when tools are absent. The diagnostic GUI regression handles
Expand Down
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ keywords = ["usbguard", "usb", "security", "gtk4", "linux"]
categories = ["gui"]
exclude = [
"docs/", ".github/", "SESSION_HANDOFF.md",
"scripts/clean-install-*", "scripts/verify-clean-install.py", "tests/test_clean_install.py",
"scripts/clean-install-*", "scripts/verify-clean-install.py", "tests/test_clean_install*.py",
]

# ---------------------------------------------------------------------------
Expand Down
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,17 +67,23 @@ case.
* **Live device list** — authorization state with icon *and* text, name, `vendor:product`, serial,
and port, sorted by physical topology. Insertion bursts are merged, so a hub full of devices does
not freeze the window.
* **Device details** — USB interfaces, physical port path, connection type and state reported by
the daemon, with the source of the rule text stated explicitly.
* **Device actions** — allow, block, reject; this session only or permanently; a Cancel button while
a password prompt is open, which never times out on its own.
* **Policy view** — the ruleset in the order the daemon evaluates it, a rule editor with a guided
mode and a text mode, live preview and validation before anything is sent, and explicit placement
mode and a text mode, live rule-text validation before anything is sent, and explicit placement
("at the end" or "after rule N").
* **Matching-device preview** — ask USBGuard which connected devices match a new rule's attributes
before saving it. The preview is read-only; conditions and earlier rules can affect the final decision.
* **Runtime parameters** — `ImplicitPolicyTarget` and `InsertedDevicePolicy`, changed with
confirmation.
* **Notifications** — when a device that is not authorized is plugged in, with an *Allow for this
session* button where the notification server supports it.
* **Background mode** — keeps announcing new devices after the window is closed, with a status icon
where the desktop has one, and an optional start at login.
* **Local event history** — the latest 200 observed events, with observation gaps marked and JSON
export containing event types and times only. Keeping history between runs is opt-in.
* **`usbguard-gui --diagnose`** — the whole access check as one command whose output you can paste
into a bug report.

Expand Down
4 changes: 2 additions & 2 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,8 +240,8 @@ and AUR publication remain deferred; they are not prerequisites for these milest
| :--- | :--- | :--- | :--- |
| **1** | **Preview matching devices before adding a rule** | A read-only action in both rule-editor modes asks USBGuard which currently connected devices match the attributes. Show results, no matches, errors and cancellation; discard results after edits or closing. State explicitly that conditions and rule precedence are not simulated. No authorization or policy mutation is performed. Test target-independent queries, hostile text, stale replies and failure paths; maintain >=98% application line coverage. | Merged; unreleased |
| **2** | **Device details and observed decisions** | Add an accessible per-device details view for USB interfaces/functions, physical port topology, connection type and daemon-reported state/rule text. Label the source and distinguish that device description from the effective policy rule. Show a matched rule only when USBGuard reports an unambiguous, current identity; otherwise say that the API does not provide it. Test missing/malformed fields, hostile strings and invalidation on row replacement/reconnection. | Merged; unreleased |
| **3** | **Local event history** | Show insertions, removals, authorization outcomes and reconnections observed while the app runs. Mark observation gaps; bound retention and make persistence opt-in. Offer export with identifiers obscured and test redaction. | In progress |
| **4** | **Desktop quality** | Measure and reduce memory usage; verify keyboard navigation, screen-reader labels, Wayland and GNOME/KDE behavior. Track repeatable measurements and desktop-specific regressions. | Planned |
| **3** | **Local event history** | Show insertions, removals, authorization outcomes and reconnections observed while the app runs. Mark observation gaps; bound retention and make persistence opt-in. Offer export with identifiers obscured and test redaction. | Merged; unreleased |
| **4** | **Desktop quality** | Measure and reduce memory usage; verify keyboard navigation, screen-reader labels, Wayland and GNOME/KDE behavior. Track repeatable measurements and desktop-specific regressions. | Validated; PR #61 pending merge. Memory baseline, installed Fedora AT-SPI/keyboard and native Weston checks passed. Corrected diagnostic executable passed 7/7 cases on GNOME and Plasma with 10/30 stress cycles and fatal criticals; application coverage 98.0917%. Versioned release-package verification remains a release gate. |

All four retain the unprivileged D-Bus architecture. Each completed milestone must
pass the existing tests, coverage and packaging gates before release. The first
Expand Down
138 changes: 61 additions & 77 deletions SESSION_HANDOFF.md
Original file line number Diff line number Diff line change
@@ -1,77 +1,61 @@
# Development handoff — 2026-10-25

Completed implementation follow-up: the user explicitly requested **98% coverage across the entire
application, including GTK**, plus an edge-case review. The local gate passes at **4841/4928 = 98.2346%**.
The implementation is on
`test/core-coverage-98` (the branch name predates the clarified whole-app scope).

- Production fixes: cancellable-operation events survive queue backpressure;
Guided → Text releases its preview borrow before GTK's synchronous callbacks;
parameter signals preserve structural denials and disable unknown values;
policy error descriptions escape markup; one tray registration in flight
follows the latest background preference, including rapid off/on changes.
- Unit tests moved to `tests/unit/`, graphical contracts to `tests/gui/`, preserving
all existing tests. `make coverage-app` measures production source across GUI
and headless feature configurations, with private display/buses/user dirs.
- Graphical tests cover real 20/180-second notices. Do not edit the launcher
while it is executing. The 180-second test is intentionally a wall-clock wait.
- New coverage checker rejects omitted GUI files, malformed/duplicate reports,
test-code inflation and percentages that only round to 98%.
- The original zbus migration / real clean-install work below is complete;
these new GUI tests simulate the backend and do not replace its PAM receipts.


The requested zbus/ksni migration and clean-install verification are implemented
and locally verified. No translation expansion or AUR publication was undertaken.

- zbus 6.1 and Rust 1.89 replace the old dependency/compiler baseline. The fixed
SNI/menu implementation runs directly on zbus, replacing ksni and the deprecated
zvariant stack. Architecture, dependency inventory and ADR 0002 describe it.
- All four real GUI/PAM cases pass on Ubuntu 24.04.5, Debian 13.7, Fedora 44 and
Arch rolling: no agent, cancelled authentication, correct-password runtime block
with unchanged permanent rules, daemon restart/GUI reconnection.
- Tests also verify wire properties/actions, both tooltip signals, watcher restart,
mutation error classification and installed artifact identity. Core per-file
coverage stays above 90%; the dependency audit has no findings or notices.
- [Testing](docs/testing.md#zbus-6-and-real-clean-system-validation-2026-10-2425)
and [verification](docs/verification.md#post-012-zbus-6-validation-2026-10-2425)
contain exact scope, reproduction and committed receipts.

Checkpoint artifacts under ignored `target/zbus6-repro-final` are measured
modified-worktree builds retaining version 0.1.2, distinct from the published
0.1.2 release. The native binary hash in all guest receipts is
`e6f620ab6756d34849a15357b9967fe1b07541a0b509686f3d930484ff53cf82`.
The CI reproduction gate measures the final PR source independently.

Local test VM disks and evidence remain under `target/clean-install-*`, with
credentials private and never committed. Stop VMs after collecting evidence.
Use generic Debian images with USB support, start the packaged modern Polkit
helper socket when needed, and reload fixture policy after writing it.
Do not enable SUID or disable SELinux to make a test pass.

No new release/tag is part of this implementation handoff. Publication needs the
usual versioning and release gates. Signed-off-by with the configured Git identity
was explicitly approved for this work; avoid asking for that consent again.

Developer tools: `/home/onyks/.cargo/bin` and `target/tools/bin` (cargo-deny 0.20.2,
cargo-llvm-cov 0.9.1). Use `/bin/bash`, `login:false`. The host lacks /dev/kvm,
so VM execution uses TCG. Historical detailed pause instructions are preserved
in commit `ccfb96d`; the work described there has now been completed.

Whole-app evidence: `docs/validation/application-coverage-2026-10-25.json`;
full LLVM JSON `target/coverage-application.json`; HTML
`target/llvm-cov/html/index.html`; logs `target/coverage-98-complete.log`,
`target/coverage-98-verify-final.log`, `target/coverage-98-msrv.log`,
`target/coverage-98-properties.log`. The native test host lacked Xvfb/xdotool:
RPMs were downloaded/extracted under `target/coverage-tools/root` without a host
installation. `make coverage` now discovers both local tool locations automatically, including
the unpacked desktop libraries; no manual PATH/LD_LIBRARY_PATH exports are needed.
Missing dependencies fail before tests with install instructions. Four new tool
discovery/preflight regressions bring the Python suite to 65 tests. The diagnostic
GUI regression now accepts the no-agent CI case and separately checks an IPC
denial with copyable commands. CI installs normal Ubuntu test packages.

Coverage command follow-up: `make coverage` succeeded without any manually added
PATH or LD_LIBRARY_PATH (`target/coverage-user-entrypoint.log`), still 98.2346%.
`target/coverage-tools-gui.log` verifies the agent-independent diagnostic fixture;
`target/coverage-tools-tests.log` has 13 checker/tool tests and Clippy is clean.
# Development checkpoint — 2026-10-26

Continue completing PR #61 (`feat/desktop-quality`), then prepare and publish
0.2.0 through a verified release candidate. The user authorized signed-off commits,
PR management and release/tag publication; DCO consent already exists.

**Privacy:** never inspect the real host's desktop, applications, services or
physical devices. Use only the marked private VM with synthetic USB, or the
narrow namespace wrapper `target/run-private-tests.py`. No subagents requested.

## Completed and verified

- Production fix at pushed `ddd8977`: retain transient dialogs through native
close callbacks, then release at GLib idle. Preferences/About contract verifies
native close and eventual release. Earlier main-window deferral was ineffective
and reverted. Investigation: `docs/validation/desktop-quality-2026-10-26/`.
- Final whole-application coverage: **5500/5607 = 98.0917%**, GUI included.
Receipt identifies source and Rust-test digests. Log:
`target/dialog-lifetime-coverage.log`; HTML `target/llvm-cov/html/index.html`.
- Final native desktop tests passed: GNOME seven cases/10 cycles, Plasma seven
cases/30 cycles, fatal criticals, no debugger, same owner, single notice and
clean exit. Plasma uses its real watcher/tray. Both receipts identify diagnostic
executable SHA256 `d7d4337c009f06e3799f865a4c74e0f8b8b8bb4e6a51591741a405d2b9ad093a`,
NOT an installed release package. Version at build remains 0.1.2.
- The final driver uses atomic AT-SPI root GetChildren during window hiding.
GDB traced the separate stale-index critical to GTK 4.22.5's root handler.
This corrects our observer; it does not fix GTK for other accessibility clients.
- All 17 PR checks passed on ddd8977, including coverage, reproducibility of every
package format, stable/beta/MSRV, lint, audit, DCO and CodeQL. Final subsequent
driver/docs/receipt changes need their own CI before merge.
- Local checks already passed: driver 20 tests, reproducibility 30, dependency
policy 6, i18n 7; audit/deny, lint, pinned strict MkDocs. Markdownlint unavailable.

## VM and local evidence

The private Fedora VM is **STOPPED** (graceful shutdown and private QMP socket
checked). Its directory is `target/clean-install-fedora-pr61`; keys/credentials
must never be printed or committed. Evidence archive:
`target/clean-install-fedora-pr61/desktop-accepted-evidence.tar.gz`.
Final raw reports/logs: `target/desktop-{gnome,kde}-atomic-{report.json,app.log}`.
Resume only if needed via `target/start-desktop-test-vm.py` (refuses second writer).

Host GUI/coverage tests MUST use `target/run-private-tests.py`: empty mount root,
private proc/dev/tmp/run/sys/buses/network, only explicit code/toolchain binds,
software Mesa. Do not use the older whole-root bind or the real desktop.

## Remaining release work

1. Commit final observer, verified receipts, updated roadmap/docs; push PR #61,
update its description, mark ready, wait for green exact-head CI and squash
merge with the already-authorized Git identity's Signed-off-by.
2. Prepare 0.2.0 version metadata/changelog/AppStream/Arch version in a new branch.
Include all four completed product milestones in 0.2.0 scope; no more languages
or AUR publication. Draft notes: `target/release-020-notes.md`.
3. Pass CI and merge version PR; require main checks before tagging. Follow
`docs/releasing.md`: publish v0.2.0-rc.1, verify checksums/Sigstore identity,
installed candidate package and pinned Flatpak validation; stable tag at the
same verified commit. Existing native receipts from prior candidates must not
be described as installed 0.2.0 validation.

No v0.2.0 tag exists at this checkpoint. Stable remains 0.1.2.
8 changes: 7 additions & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -1851,7 +1851,7 @@ reproduced the native GTK 4.22.5 crash and now passes; see [testing.md](testing.
| Burst latency | ≤ 250 ms + render | Guaranteed by `MAX_LATENCY` (§5.4); verified in T3 |
| Event loss under burst | zero | T3: final displayed state compared against `usbguard list-devices` |
| Polkit resilience | zero timeouts on waits ≤ 10 min | T13 |
| Idle memory | RSS < 110 MB, PSS < 70 MB | `smem`, after 10 minutes in background with 20 devices |
| Idle memory | RSS < 110 MB with Cairo, PSS < 70 MB | `scripts/measure-memory.sh`, after 10 minutes in background with 20 invented devices |
| Direct first-party system filesystem access | zero | `strace -f -k` on `/etc`, `/var`, `/sys`, with library accesses attributed separately |
| Parser robustness | zero panics over 10⁶ fuzz inputs | `cargo-fuzz` |
| Application coverage | ≥ 98% of production lines, GUI and headless configuration included | `make coverage-app` / `cargo-llvm-cov` |
Expand Down Expand Up @@ -1880,6 +1880,12 @@ substantial fraction of their pages with every other GTK application in the
session, so RSS overstates what this program actually costs a running desktop,
and PSS is the honest number to hold ourselves to.

**Measured again (2026-10-25, debug build):** with 20 synthetic devices after
600 seconds in background on Fedora 44 / GNOME Shell 50.6 / Wayland (GTK 4.22.5,
libadwaita 1.9.4, Cairo renderer), RSS was 63.4 MiB and PSS 34.4 MiB. Both
targets passed. The procedure and its scope are recorded in
[`docs/testing.md`](testing.md#background-memory-check).

### 13.3 Phase 0: Upstream Verification Procedure

Run before any code depends on §2, and again on every change to the supported
Expand Down
Loading
Loading