Lux Guard – protection against harmful downloaded programs
Lux Guard (package luxos-guard, service luxos-guard.service, window Lux Guard =
luxos-guard-gui, command luxos-guard) checks programs and scripts that came from outside the
computer at the moment they are started, and keeps hourly read-only snapshots of /home so that
deleted or encrypted files can be restored. It is not a classic antivirus: no signature database, no
background scanning of all files, no cloud. Normal programs and files cost nothing.
What it watches
Only executable content from outside:
- files in the Downloads folder (
XDG_DOWNLOAD_DIRand~/Downloads),~/Sandbox, mail and web attachments opened from/tmp/mozilla_*, removable media (/run/media,/media,/mnt), - files with the
user.xdg.origin.urlattribute (set by browsers andwget --xattr), - files written anywhere in a home folder by a browser, mail, download, torrent or chat app,
- files written by a program that itself came from outside (droppers) or by a program that has a file from outside open (unpacking an archive from Downloads, copying from USB) – a watched file that the program has open counts only when the new file has its size (a real copy; git reading many files at once no longer turns every script it writes into a "copy"),
- copies of a watched file (same size and SHA-256).
Git hook templates (.git/hooks/*.sample) are never watched – git does not run them.
Executable content = ELF programs, AppImages, scripts with #! or with .sh/.py/.pl/.rb/.lsl
extensions, .desktop launchers, .jar and Windows .exe (via Wine). Documents, pictures,
archives and videos are never touched.
Levels and what happens
| Level | When | What the user sees |
|---|---|---|
| Risky | any unknown program or script from outside | dialog "Run a program from outside this computer?" with Don't Run (default), Run in Sandbox, Run Anyway |
| Critical | dangerous behaviour found (list below) | the start is always refused outside the sandbox; dialog "Lux Guard blocked a dangerous program" with OK, Run in Sandbox, Move to Trash; a notification already when it is downloaded |
Run Anyway is remembered for that exact content (SHA-256); the file is then no longer watched
and starts at full speed. Don't Run or no answer within 90 s refuses the start (the program
gets "Permission denied"); the same file is not asked about again for 60 s. If no Lux Guard session
helper runs for that user (no graphical session, SSH), risky files are refused without asking –
an administrator can release one with sudo luxos-guard allow FILE.
luxos-guard allow FILE run as a normal user opens the same Lux Guard dialog in the desktop
session ("Confirm in the Lux Guard window..."): the file is allowed only after Run Anyway there.
Without a session helper it is refused; as administrator (sudo) it works directly.
Critical findings (reasons shown in the dialog):
- deletes your files, your home folder or the whole system –
rm -rf ~,rm -rf /,find ~ -delete,find ~ -name '*.jpg' -delete,shutil.rmtree(Path.home()), walking the home folder and deleting/overwriting files,fs.rmSync(os.homedir(), …),FileUtils.rm_rf(Dir.home)… - formats, wipes or overwrites a disk –
dd of=/dev/sda,mkfs,wipefs -a,shred /dev/…,blkdiscard,> /dev/nvme0n1, writing to/dev/sd*from Python - removes the bootloader, kernels or core system packages; breaks permissions of the whole system
- freezes the computer (fork bomb); crashes the kernel (
/proc/sysrq-trigger) - changes sudo, polkit or PAM security settings (writes to
/etc/sudoers,/etc/pam.d…) - tries to switch off Lux Guard or delete its backups
- downloads code from the internet and runs it immediately without any check –
curl … | shas administrator (| sudo bash), from plainhttp://, an IP address, paste or link-shortener sites, or combined with decoding; plaincurl https://… | shis only a note in the risky dialog - runs hidden (encoded) code –
base64 -d | sh,xxd -r | sh,eval "$(… base64 -d)",exec(base64.b64decode(…)),eval(Buffer.from(…, 'base64')); base64 text inside a script is also decoded and checked - encrypts your files (ransomware behaviour) –
openssl enc/gpg -c/7z -pin a loop over the home folder, PythonFernet/AES overos.walk(home)
Notes (risky dialog only): asks for administrator rights, adds a program to startup, changes user
accounts, downloads more code, disables package signature checks. Typical install and build
scripts (rm -rf "$TMPDIR", rm -rf build, sudo usermod -aG …, rm -rf "$DIR/"* with an unknown
variable) are not critical. For programs (ELF) only readable command strings are checked;
compressed programs and AppImages are usually just risky.
Why something was blocked – for AI assistants
luxos-guard scan FILE– type, dangerous findings and notes, origin and Lux Guard state.luxos-guard list– watched files and recent decisions;journalctl -t luxos-guard– the log (blocked critical PATH (by PROGRAM[PID], uid N): REASON).- Explain the reason in plain words. For a critical file recommend Run in Sandbox or deleting
it. Never suggest switching Lux Guard off, never run
luxos-guard allow --forceand never copy the file elsewhere or strip it to get around the check. - A false alarm on a trusted risky file: the user clicks Run Anyway or runs
luxos-guard allow FILE. A critical file can only be released by an administrator withsudo luxos-guard allow --force FILE– only when the user explicitly insists and understands it.
Run in Sandbox
The button starts the file in the user's Sandbox. Nothing alarming pops up – a normal user just clicks the button:
- Programs with a window run with
luxos-sandbox run --gui -- FILEin their own sandbox window, without a terminal: AppImage, jar, exe, ELF programs linking a window library (X11/xcb, GTK, Qt, SDL, GLFW, wayland-client, Electron …), scripts using Tk/GTK/Qt/pygame or zenity/yad that do not ask for input, and.desktoplaunchers withTerminal=false(theirExecruns in the sandbox). One that fails right away (within 20 s) shows a notification with the last lines of its output. - Text programs and scripts (CLI ELF, shell/Python/… scripts) run without any window or terminal
(
luxos-sandbox run -- FILE). Their output (stdout and stderr, only the last 64 KB, escape sequences and control characters removed) goes to a private file in$XDG_RUNTIME_DIR/luxos-guard/(0700, deleted after a day or at logout). When the program ends, one calm notification appears: “NAME ran safely in the sandbox” or “NAME finished with an error” (“It finished with error code N …”, normal urgency; only a crash – SIGSEGV, SIGABRT … – is shown as “NAME crashed in the sandbox”), with a Show Output button that opens a small read-only window with the output (Copy, Esc closes). A program still running after 20 s shows “NAME is running in the sandbox” with Show Output and Stop (stops only this run: its process group gets SIGTERM, then SIGKILL after 3 s); the final notification replaces it. The run is watched by a small separate process (luxos_guard_session.py headless), so it survives closing the Lux Guard window or an update of the agent. - A terminal opens only when the user clearly works in one or the program obviously needs typing:
the blocked process had a controlling terminal (a command typed in a terminal, also "Run in Terminal"
in the file manager), the script reads input (
read/select/whiptail//dev/ttyin shell scripts – notwhile read … < fileor pipes –,input()/getpassin Python,<STDIN>in Perl,getsin Ruby,readlinein Node), or a launcher hasTerminal=true. A text program's terminal stays open so the output can be read; a program with a window started from a terminal closes it by itself (it stays only on an error). Without any terminal application the program runs without a window as above.
Real case: a background process (no terminal) ran a shell script from the AUR; after Run in Sandbox the user now sees only the notification “… finished with an error” with Show Output (the script's usage text) instead of a terminal window popping up.
The file is copied into the sandbox; inside it cannot see the home folder, desktop or local network. If the
sandbox does not exist yet, the Sandbox window opens (click Create, then try again). The sandbox is a
minimal Arch Linux without Python, Java or Wine unless installed with luxos-sandbox install.
Snapshots and restoring files
If /home is a btrfs subvolume (standard LuxOS installation: @home), luxos-guard-snapshot.timer
makes a read-only snapshot every hour in /home/.luxos-guard-snapshots/YYYY-MM-DD_HH-MM. Kept: all
from the last 24 hours, then the newest of each day for 7 days; with less than 5 % (or 2 GiB) free
space the oldest are deleted (the newest two stay). Snapshots cost almost no space until files
change. Programs of the user cannot change or delete them (read-only subvolumes, root-owned
folder); each user sees only their own home in them (original permissions).
Restoring – window Lux Guard › Restore files: Show Files (opens the snapshot in Files),
Restore Deleted (copies back missing files, skips .cache), Restore All… (also replaces
changed files, e.g. encrypted by ransomware; newer files are kept). Command line, as the user:
luxos-guard snapshots # list times
luxos-guard restore ~/Documents/report.odt # newest snapshot, only if missing
luxos-guard restore --from "2026-10-23 14:00" ~/Pictures
luxos-guard restore --overwrite --from 2026-10-22 ~ # everything back to that day
luxos-guard restore --dry-run ~/Documents # only count
On ext4/xfs or when /home is not a subvolume there are no snapshots (luxos-guard status says so).
How enforcement works
- Kernel fanotify: writes (
FAN_CLOSE_WRITE) on the mounts of/home,/tmpand/dev/shm(/var/tmponly if it has its own mount) are reported asynchronously (writers are never slowed down); only executable content is analysed in a background thread. - Watched files get a mark on their inode with
FAN_OPEN_EXEC_PERM(everyexecve, however the program is started) and, for scripts,FAN_OPEN_PERM–bash file.sh,python3 file.py,. file.share checked too; editors,cat,cpor file managers only reading the file are allowed immediately. Removable media get the mark on the whole mount (files are analysed when started). Marks are restored from/var/lib/luxos-guard/state.jsonafter a reboot. - Critical files also lose their execute bits.
- The service runs as root (
systemctl status luxos-guard); the session helperluxos-guard-agent(autostart) shows the dialogs. Kernel option needed:CONFIG_FANOTIFY_ACCESS_PERMISSIONS=y(set inlinux-luxosand Arch kernels). - Only the real session helper may answer the dialogs:
/usr/lib/luxos-guard/luxos-guard-agentis setgidluxos-guardand the service accepts answers only from a connection opened by that program (group and process checked by the kernel,SO_PEERCRED+SO_PEERPIDFD). Another program of the same user cannot pretend to be the helper and allow files for itself. The dialog itself runs with the user's normal rights and a clean environment. After an update the running helper switches to the new version by itself within seconds (no new login).luxos-guard statuswarns when no verified helper is connected.
Limits
- Malware started as root can stop the service; already allowed programs (Run Anyway) run with the user's full rights – they can delete what the user can delete (snapshots stay).
- Code that never touches a watched file: commands pasted into a terminal,
cat file | sh,curl … | shtyped by hand, browser exploits, Flatpak/sandboxed apps writing through their own mounts, files on network shares (gvfs, SMB), interpreters not in the list (e.g.awk -fis,Rscriptis,make -fis not). - Content analysis is pattern based: well-hidden or compiled malware is only risky (the user still gets the dialog). A file run in the first milliseconds after download may start before the check (normally the mark is set before a user could click).
- On X11 any program of the user can send key presses and clicks to the user's windows, including the Lux Guard dialog. Lux Guard cannot stop a program that already runs as the user from "clicking" Run Anyway for a risky file this way (critical files stay blocked).
.desktoplaunchers: a critical one cannot even be read (Files cannot start it); a risky one is not asked about – what it starts is checked only if that file is watched.
Related: sandbox.md, for-ai-assistants.md, troubleshooting.md.
Live system
In the live system started from the USB stick (/run/archiso exists) Lux Guard does not run: the
installer itself runs disk tools (mkfs, cryptsetup, dd) and nothing in the live session is kept.
The installed system has Lux Guard from the first start.