Home
A Windows UAC-style confirmation dialog for Linux privilege escalation.
PAM module + libcosmic helper + polkit authentication agent, designed
for COSMIC and sudo-rs, Wayland-only.
Confirmation dialog (--windowed debug mode shown). In production, the
same card sits on a full-screen zwlr-layer-shell-v1 overlay with a
translucent backdrop — see Architecture.
Caution
Sentinel sits in the PAM authentication path. Misconfiguration can lock
you out of sudo, polkit, or login. Read Troubleshooting before
installing. Always keep a root shell open in a second terminal during
the first install. The software is provided as-is under GPL-3.0; the
author takes no responsibility for damaged systems.
- Installation — AUR, Debian, RPM, Nix, generic tarball, source build
-
Configuration — TOML reference for
/etc/security/sentinel.conf -
PAM Wiring — wiring
pam_sentinel.sointosudo,polkit,su -
Polkit Agent — how
sentinel-polkit-agentworks - Building from Source — toolchain, build vars, cargo features
- Architecture — sequence diagrams, security model
- Troubleshooting — recovery, common failure modes, debug logging
- Contributing — dev workflow, code style, release process
When something requests privilege escalation (sudo, pkexec, …) and
the PAM stack hits pam_sentinel.so, the module either:
- asks the running
sentinel-polkit-agent(via Unix socket) whether this auth was already approved by the user via the dialog. If yes, returnPAM_SUCCESSimmediately. - otherwise, spawn
sentinel-helperto render a layer-shell overlay with the confirm/deny dialog and act on the click.
For polkit-mediated auth (pkexec, COSMIC Settings panels, mounting
disks, etc.), sentinel-polkit-agent is registered as the session's
authentication agent so polkit consults Sentinel directly — no more
two-dialog races with cosmic-osd / polkit-gnome / polkit-kde.
| Component | State |
|---|---|
pam_sentinel.so |
Stable |
sentinel-helper |
Stable |
sentinel-polkit-agent |
Stable (v0.5.0) |
| Layer-shell overlay UI | Stable |
| Layer-shell auto-fallback | Stable (GNOME / Mutter detected, drops to --windowed) |
| i18n (12 locales embedded) | Stable |
| Structured audit logs | Stable (logfmt via journalctl) |
| Transactional install | Stable |
| Hot install (no relogin) | Stable |
| Shell completions + man pages | Stable |
| AUR + .deb + .rpm + Nix | Built per release |
--windowed fallback |
Stable (auto on Mutter; --windowed flag for manual) |