cachyos-scripts

A collection of shell scripts for managing and maintaining CachyOS systems — and in many cases, any Arch-based or systemd Linux distro.

The goal is not to replace existing tools, but to complement them with scripts that have real operational criteria: security auditing with pentester perspective, intelligent maintenance that avoids breaking things, and CachyOS-specific tooling that doesn't exist elsewhere.

---

Quick start

git clone https://github.com/YOUR_USERNAME/cachyos-scripts.git
cd cachyos-scripts
chmod +x doctor.sh
./doctor.sh

doctor.sh runs a full read-only healthcheck of your system and tells you what needs attention. It won't modify anything.

---

Structure

cachyos-scripts/
├── doctor.sh              # Full system healthcheck — start here
│
├── maintenance/           # System upkeep
│   ├── full-upgrade.sh
│   ├── clean-system.sh
│   └── check-failed-services.sh
│
├── security/              # Auditing and hardening
│   ├── audit-suid.sh
│   ├── audit-open-ports.sh
│   ├── audit-firewall.sh
│   ├── hardening-check.sh
│   └── aur-gate.sh
│
├── performance/           # CPU, scheduler and I/O tuning
│   ├── set-cpu-governor.sh
│   ├── scx-scheduler-switch.sh
│   └── io-latency-check.sh
│
├── kernel/                # Kernel management
│   ├── list-kernels.sh
│   └── switch-kernel.sh
│
├── disk/                  # Disk and filesystem tools
│   ├── disk-usage.sh
│   ├── smart-check.sh
│   ├── mount-manager.sh
│   └── disk-formatter.sh
│
├── network/               # Network diagnostics and management
│   ├── net-summary.sh
│   ├── open-connections.sh
│   ├── wifi-manager.sh
│   ├── bandwidth-check.sh
│   └── vpn-check.sh
│
├── snapshots/             # Btrfs snapshot management
│   ├── list-snapshots.sh
│   ├── create-snapshot.sh
│   └── restore-snapshot.sh
│
├── packages/              # Package auditing and management
│   ├── export-pkglist.sh
│   └── diff-pkglist.sh
│
├── logs/                  # Log analysis and cleanup
│   ├── boot-errors.sh
│   ├── log-analyzer.sh
│   └── clean-logs.sh
│
└── utils/                 # General utilities
    ├── system-info.sh
    └── backup-configs.sh

---

Compatibility

Each script includes a header with:

Field	Meaning
Dependencies	Required binaries or packages
Compatibility	Any Linux, Any systemd Linux, Arch-based, or CachyOS

Scripts marked CachyOS use features specific to that distro (scx schedulers, cachyos-kernel-manager, etc).
Scripts marked Any Linux rely only on standard POSIX/systemd tools and work on most distros.

Note: Scripts in snapshots/ require a Btrfs filesystem. They are not compatible with ext4, XFS or other filesystems. For ext4 users, consider Timeshift as an alternative.

---

Categories

🔧 Maintenance

Intelligent system upkeep beyond basic pacman usage.

Script	Description	Compatibility
full-upgrade.sh	Full system upgrade with optional Btrfs snapshot, package diff and firmware updates (fwupd/LVFS)	CachyOS, Arch
clean-system.sh	Remove orphans, trim pacman and AUR helper (yay/paru) caches, rotate logs with configurable limits	Arch-based
check-failed-services.sh	List failed systemd services with suggested actions	Any systemd Linux

Firmware updates (full-upgrade.sh) run after the package upgrade, through fwupd and the LVFS. The stage is optional and asks before doing anything; it refuses to flash on a battery below 30%, warns when the ESP is too full to stage a UEFI capsule update, lists every pending update with its version change, and lets you pick which devices to flash (jq required for the per-device menu). Nothing is uploaded to LVFS.

./maintenance/full-upgrade.sh                 # packages, then ask about firmware
./maintenance/full-upgrade.sh --no-firmware   # packages only
./maintenance/full-upgrade.sh --firmware-only # firmware only

Note: a firmware flash is performed by the device itself and cannot be rolled back by a Btrfs snapshot. Most updates only finish after a reboot (some need a full power off).

---

🔒 Security

Auditing scripts written with an operational security mindset — not just checklists.

Script	Description	Compatibility
audit-suid.sh	Classifies SUID/SGID binaries as Expected/Unusual/Suspicious via baseline + pacman cross-check	Arch-based
audit-open-ports.sh	List listening ports by exposure (local/LAN/public) with process, user, package and firewall coverage	Arch-based
audit-firewall.sh	Audit firewall (ufw/firewalld/nftables/iptables): stale rules, IPv6 parity, anti-patterns	Any Linux
hardening-check.sh	30+ pragmatic checks: SSH, sysctl, file perms, PAM, mounts, AppArmor, coredumps, arch-audit CVE scan	Any systemd Linux
aur-gate.sh	Pre-build gate for AUR packages (as yay's makepkg): maintainer changes, orphans, repo→AUR switches, known-compromised list, risky lines added since the installed version	Arch-based

AUR gate (aur-gate.sh) reviews every AUR build before makepkg runs any of the PKGBUILD. It was written after the June 2026 "Atomic Arch" campaign, in which orphaned AUR packages were adopted and changed to npm install a credential stealer during the build.

./security/aur-gate.sh install         # yay builds through the gate from now on
./security/aur-gate.sh check <pkg>     # review a package before installing it
./security/aur-gate.sh pending         # review pending AUR updates (full-upgrade.sh runs this)

• Red — the build stops until you type yes: maintainer changed since your last build, a package switching from a signed repo build to the AUR, a package on the compromised list, or new lines that install a named npm/bun/pip package, pipe a download into a shell, decode embedded data, or reach the network from an .install scriptlet.
• Yellow — shown, Enter continues: orphaned or very new package, new download origin, disabled checksums, changed .install, generic npm install, eval, sudo.
• For updates only the lines added since the installed version are checked, so long-standing build tricks don't raise the alarm on every update.

Heuristics raise the bar against mass campaigns; they don't prove a package safe. -bin packages ship binaries that no pattern can look inside.

---

⚡ Performance

CPU governor management and CachyOS-specific scheduler tooling.

Script	Description	Compatibility
set-cpu-governor.sh	Switch CPU governor with hardware auto-detection	Any Linux
scx-scheduler-switch.sh	Manage and switch between scx_* schedulers (BORE, LAVD, etc.)	CachyOS
io-latency-check.sh	Quick I/O latency benchmark per device	Any Linux

---

🐧 Kernel

Script	Description	Compatibility
list-kernels.sh	List installed kernels, highlight active and next-boot kernel	CachyOS, Arch
switch-kernel.sh	Set default kernel in systemd-boot or GRUB	CachyOS, Arch

---

💾 Disk

Script	Description	Compatibility
disk-usage.sh	Disk usage summary by partition and top-N directories	Any Linux
smart-check.sh	SMART status for all disks with bad sector alerts	Any Linux
mount-manager.sh	Mount/unmount devices and manage persistent fstab entries (UUID-based, with backups)	Any Linux
disk-formatter.sh	Format devices, change labels and partition disks (quick or cfdisk); system disk protected	Any Linux

---

🌐 Network

Script	Description	Compatibility
net-summary.sh	Active interfaces, IPs, gateway and DNS summary	Any Linux
open-connections.sh	Active network connections with owning process and user	Any Linux
wifi-manager.sh	WiFi network management from CLI via nmcli	Any Linux (NetworkManager)
bandwidth-check.sh	Bandwidth and latency test to configurable targets	Any Linux
vpn-check.sh	Detect active VPN interfaces, daemons and DNS leak risk	Any Linux

---

📸 Snapshots (Btrfs only)

Script	Description	Compatibility
list-snapshots.sh	List available Btrfs snapshots by subvolume	Linux + Btrfs
create-snapshot.sh	Create a named, timestamped snapshot of root or home	Linux + Btrfs
restore-snapshot.sh	Restore a previous snapshot with backup of current state	Linux + Btrfs

---

📦 Packages

Script	Description	Compatibility
export-pkglist.sh	Export installed packages (official + AUR) with versions	CachyOS, Arch
diff-pkglist.sh	Compare package lists between two systems or snapshots	CachyOS, Arch

---

📋 Logs

Script	Description	Compatibility
boot-errors.sh	Errors and warnings from current and previous boot	Any systemd Linux
log-analyzer.sh	Detect anomalous patterns in journald, summarized by service	Any systemd Linux
clean-logs.sh	Intelligent log cleanup with size and age limits	Any systemd Linux

---

🛠 Utils

Script	Description	Compatibility
system-info.sh	Full system summary: hardware, OS, resources, uptime	Any Linux
backup-configs.sh	Backup /etc and critical configs to a timestamped tar with checksum	Any Linux

---