ARCHCANARY(1)

NAME
archcanary - security scanner for Arch Linux

SYNOPSIS
archcanary [OPTIONS]

DESCRIPTION
archcanary is a layered security detection stack for Arch Linux. It integrates and orchestrates existing security tools — lynis, bpftool, and others — into a single unified scanner, while also performing its own checks for malicious AUR packages, systemd and eBPF persistence, npm/bun/yarn/pnpm cache poisoning, PKGBUILD obfuscation, kernel module tampering, library injection, and more.

By default (no flags) it checks currently installed foreign packages against the known-bad list and scans /var/log/pacman.log for historical installs. All checks are read-only; nothing is removed or quarantined.

OPTIONS

  Scan checks

--check-systemd
    Scan for unknown systemd services with Restart=always.

--check-ebpf
    Check for eBPF rootkit traces under /sys/fs/bpf/hidden_*.

--check-npm-cache
    Check the npm cache for package names in malicious_npm_packages.txt.

--check-bun-cache
    Check the bun cache for packages in malicious_npm_packages.txt.

--check-yarn-cache
    Scan yarn v1 and Berry caches, including fnm per-version globals.

--check-pnpm-cache
    Scan the pnpm store, global installs, metadata cache, and dlx cache.

--check-pkgbuild
    Scan AUR helper caches for obfuscation patterns in PKGBUILD and .install files (base64 decode-to-shell, eval subshell, printf hex/octal, variable-split command reassembly), and for undocumented ELF binaries committed directly to a package's own cache/git tree (outside src/ and pkg/ build output).

--check-bpftool
    Enumerate loaded eBPF programs, perf/kprobe attachments with owning PID and hooked function, and XDP/TC network attachments. Requires root.

--check-ldso
    Check /etc/ld.so.preload for shared library injection and recent /etc/ld.so.conf.d/ changes.

--check-autostart
    Scan XDG autostart entries, user systemd services, and shell RC files for download-and-exec patterns.

--check-kmod
    Audit loaded kernel modules against pacman-tracked files; flag untracked DKMS builds not in the allowlist. Requires root.

--check-lynis
    Parse the last Lynis hardening report at /var/log/lynis-report.dat. Requires root.

--run-lynis
    Run lynis audit system and stream the output. Requires root.

--check-pkginteg
    Verify installed file checksums against the pacman database using pacman -Qkk. Reports SHA256 mismatches on files that are not pacman-managed backup files and not under /factory/. Backup files (config files pacman marks as user-editable) diverge by design and are excluded. Prioritise any hits in /usr/bin/, /usr/lib/, and /usr/sbin/. Running as root gives complete coverage; as a regular user pacman silently skips files it cannot read. Requires root.

--check-list-overlap
    Note custom list (extra_lists.conf or --extra-list) entries already covered by an official list (package_list.txt, CHAOS RAT, Russian Spam, Community Reports, or aur-audit black/red) — safe to remove, since the official list is authoritative. Prints a ready-to-run sed command per affected file. A note, not a warning: never affects the exit status, never warns in the check summary, and not included in --full.

--scan-all-homes
    Enumerate real local users (/etc/login.defs UID range, valid shell, home directory exists) and run the npm/bun/yarn/pnpm/pkgbuild/autostart checks against each of their homes, not just yours — privilege-dropped per user via sudo-u. For shared/multi-user machines. Requires root. Not included in --full.

--search-packages= PKG [, PKG ...]
    Check package name(s) against every loaded threat list, independent of what's installed locally. No scan is run; prints a ready-to-copy pacman -Rns command for any match, and exits.

--full
    Enable all of the above checks.

  List management

--refresh
    Download the latest package list from the Arch Linux HedgeDoc before scanning. Also refreshes the supplementary npm/CHAOS RAT/Russian Spam/Community Reports lists and syncs the black/red package feed from the third-party aur-audit.wtako.net service (continuous community AUR scan; free, unauthenticated API). Hits from that feed are merged into the same infected-package check and annotated [aur-audit: black] / [aur-audit: red]. Yellow (minor/qualitative) findings are not synced.

--no-aur-audit
    Skip the aur-audit.wtako.net feed on --refresh, leaving any previously fetched black/red lists on disk untouched. Persists across runs via AUR_AUDIT_ENABLE=false in ~/.config/archcanary/env (also toggleable from archcanary-gui's Scan settings menu row).

--package-list=PATH
    Override the infected AUR package list (default: ~/.config/archcanary/package_list.txt).

--malicious-npm-list=PATH
    Override the malicious npm package name list (default: ~/.config/archcanary/malicious_npm_packages.txt).

--chaos-rat-list=PATH
    Override the CHAOS RAT campaign package list.

--russian-spam-list=PATH
    Override the Russian Spam Campaign package list.

--community-list=PATH
    Override the community-reported package list.

--extra-list=PATH_OR_URL
    Load an additional package list from a file path or https:// URL. Repeatable.

  Output control

--verbose, -v
    Verbose output.

--debug
    Verbose; enables set -x.

--log-file=PATH
    Write full detail log to PATH. If PATH is auto, the log is written to ~/.cache/archcanary/aur-check-<date>.log.

--no-notify
    Suppress the desktop notification on detection.

--no-summary
    Suppress the check summary table at the end of a scan.

--color=auto|always|never
    Control color and Unicode symbol output (default: auto). auto enables color only when stdout is a terminal.

  Health check

--doctor
    Report the install and configuration status of every stack element (binary dependencies, systemd units, yay/paru hooks) and exit.

--doctor=SECTION[,SECTION...]
    Check only the named section(s) with extra per-item detail. Sections: platform, deps, user, system, systemd, external. Tool names (paru, yad...) are also accepted.

--version ,  -V
    Print the version and exit.

--help ,  -h
    Print a short usage summary and exit.

EXIT STATUS

0   Clean — no indicators found.

1   Warnings — potential issues or skipped root checks.

2   Infected — malicious packages or artifacts detected.

ENVIRONMENT

NO_COLOR
    If set, disables all color and Unicode symbols (equivalent to --color=never).

PACMAN_LOG_GLOB
    Override the glob used to find pacman log files. Default: /var/log/pacman.log*.

FILES

~/.config/archcanary/package_list.txt
    Known-bad AUR package list (infostealer + eBPF rootkit campaign).

~/.config/archcanary/malicious_npm_packages.txt
    Malicious npm package name list.

/var/lib/archcanary/last-scan.log
    Last system scan result.

~/.cache/archcanary/last-user-scan.log
    Last user scan result.

/var/lib/archcanary/last-scan-all-homes.log
    Last --scan-all-homes result (if enabled).

/etc/archcanary/dkms_allowlist.conf
    System-wide DKMS module allowlist for --check-kmod.

/var/log/lynis-report.dat
    Lynis report file read by --check-lynis.

/usr/lib/archcanary/
    System library directory.

SEE ALSO
yay(8), pacman(8), auditd(8), bpftool(8), systemctl(1), lynis(8)

AUTHORS
musqz https://github.com/musqz/archcanary