OmaShield

Interactive, scanner-guarded AUR updates and installs for Omarchy.

Instead of blindly upgrading everything, OmaShield lists every pending repo and AUR update preselected, lets you defer any of them, reviews the surviving AUR set with aur-scan (static analysis) and yay-guard (heuristics + AUR metadata), and only installs what you explicitly greenlight. Native yay hooks guard every yay invocation as a second layer.

Waiver: AI-generated, as-is, test at your own risk

OmaShield was generated with AI assistance and is released as-is, without any guarantees of correctness, completeness, or security. A scanner guard is security-adjacent software: a bug here could block legitimate updates or, worse, wave something malicious through. Test it on your own responsibility — ideally on a non-critical machine first — and never treat a clean scan as proof of safety.

Open call for review (and forks)

I openly ask for scrutiny by people experienced in any of: Arch Linux packaging (PKGBUILDs, makepkg), the yay hooks API (init.lua autocmds), Quickshell/QML shell plugins, or supply-chain / AUR malware analysis. If that is you, your review is the single most valuable contribution this project could receive — please open an issue for anything suspicious, sloppy, or just wrong.

Forking is explicitly encouraged: fork it, fix it, improve it. If you find merit in your changes, pull requests are welcome. The MIT license already permits all of this; consider this a personal invitation on top.

Acknowledgments

OmaShield is a thin orchestration layer — the real security expertise lives in the two tools it drives. Full credit to their developers:

• aur-scanner by KiefStudioMA — a Rust-based static analyzer with 110+ detection codes covering malicious patterns, persistence mechanisms, and known indicators of compromise, built on real-world AUR attack research. OmaShield uses it for PKGBUILD review and system audits.
• yay-guard by jwcastillo (MIT) — heuristics over PKGBUILD/install scripts plus AUR metadata (popularity, maintainer, dates), an affected-packages denylist, an optional AI verdict, and the native yay v13 hooks OmaShield installs.

If these tools keep you safe, consider starring their repositories. And note the waiver above covers OmaShield's glue code, not their work — evaluate each tool on its own merits.

Hard dependencies

OmaShield stays OFF until both of these are installed:

• aur-scanner (provides aur-scan)
• yay-guard (provides aur_audit.py)

Install them through the standard procedure (Omarchy Menu > Install > AUR, or yay -S aur-scanner yay-guard), then switch OmaShield ON. The switch re-checks on every attempt and tells you what is missing. If either tool is removed later, the next guarded flow prints the same notice and switches OmaShield OFF automatically — nothing is ever reinstalled on your behalf.

Install

omarchy plugin add https://github.com/hogar1977/omashield.git --enable

The widget appears in the bar, OFF by default. Switching it ON for the first time wires everything up (see below). No files outside this plugin directory are touched before that — switching ON is the explicit consent for the wiring described in "Files touched".

What each control does

Control	Behaviour
ON/OFF switch	Arms/disarms the guard. Refuses with a dialog while hard deps are missing. OFF keeps all files in place; flows bypass to stock behaviour.
Update	Same as Omarchy Menu > Update, but repo, AUR and mise sets are each preselected for you first
Install AUR	Same as Omarchy Menu > Install > AUR
Audit AUR	Read-only audit of all installed AUR packages with both tools. Changes nothing.
Uninstall	Restores the stock menu, removes the yay hooks, the omarchy-omashield command and the state dir, then removes the plugin itself. aur-scanner/yay-guard stay installed (remove them via Main Menu > Remove > Package if wanted).

Middle-click the bar icon re-reads status. Keys in the popup: toggle, u update, i install, a audit, esc close.

The bar shows two glyphs: the stock update-available icon on the left (visible only while updates are pending — same probe and polling as the stock widget) and the shield on the right. Either opens this popup. Disable the stock omarchy.system-update widget (omarchy plugin disable omarchy.system-update) to avoid two updaters side by side.

During Update, declining the AUR set (after a finding, or at greenlight) defers only the AUR stage — the repo picks still install. Cancelling the picker itself (esc) aborts the whole update; nothing runs.

Files touched (all reversible via Uninstall)

Path	What
~/.local/bin/omarchy-omashield	Symlink to this plugin's CLI (created on first ON).
~/.config/omarchy/extensions/omarchy-menu.jsonc	update.omarchy / install.aur routed through OmaShield (stock values captured once for restore).
~/.config/yay/init.lua	Native guard hooks (pre-existing user file backed up as init.lua.omashield-bak.* first).
~/.config/omashield/	State (enabled=1/0), pending selections, review stamp, PATH-shadow symlinks.

Nothing is installed system-wide. OmaShield scripts never handle elevation themselves: the single credential prompt of an update comes from the stock omarchy-update stages, and any later one from pacman/yay themselves — after every preselection and scan decision is made. (The guarded AUR installer also skips the stock updatedb locate refresh, a root-only step left to its regular schedule.)

Privilege boundary

• Plugin code (QML, CLI, hooks, shadows) contains no elevation primitives: no sudo, pkexec, su, setuid bits, or system-wide writes.
• Elevation happens only inside programs you already trust with it: the stock omarchy-update / omarchy-pkg-aur-install stages, pacman, and yay.
• If aur-scanner/yay-guard go missing while the shield is ON, every flow refuses with the message from "Hard dependencies" below and the shield switches itself OFF (stock behaviour returns) instead of reinstalling anything. Switch ON again after reinstalling the tools.

Disable vs uninstall

• Disabling the widget (plugin manager / omarchy plugin disable) keeps every file but bypasses the guard: Update/Install run the stock flows until the widget is re-enabled.
• Uninstall button removes everything above plus the plugin directory, as if it was never installed.

Bypasses

• OMASHIELD_OFF=1 (or yay-guard's AUR_AUDIT_OFF=1) disables the hooks and the guarded flows for a single command.
• Choosing Force install anyway in the guarded Update/Install flows records those packages in ~/.config/omashield/forced-aur for one hour, so the native yay hooks let exactly those packages through on the subsequent yay -S (everything else is still audited). No manual OMASHIELD_OFF=1 retry is needed.

Removal (manual, without the panel)

omarchy-omashield uninstall --yes

License

MIT — see LICENSE.