aur-shield/README.md

AUR-Shield

AI-powered AUR firewall. Scans PKGBUILDs with a local LLM before building, caches approved packages as a local pacman repo.

Problem

The AUR is under active attack (2026 supply-chain incidents, 400+ malicious packages). yay/paru blindly execute PKGBUILDs that can contain curl | bash, reverse shells, typosquatting, obfuscated payloads.

Solution

AUR-Shield sits between your clients and the AUR:

Client (yay/pacman) → AUR-Shield (Server) → AUR
                           ↓
                      Fetch PKGBUILD + .SRCINFO
                           ↓
                      LLM scans for malicious patterns
                           ↓
                 clean → makepkg + repo-add → serve
                 sketchy → block + warn

Requirements

Server:

• Arch Linux
• ollama running (any model, even 3B works)
• base-devel, devtools for building
• Python 3.11+ with uv (or venv)
• ~2GB disk for cache

Clients:

• Arch Linux
• pacman (repo mode) or yay/paru (wrapper mode)

Quick Start

# On the server:
git clone https://gitea.die-heimatlosen.eu/arch_agent/aur-shield.git
cd aur-shield
./install.sh

# Edit config if needed (model, port, etc.)
cp config.example.yaml config.yaml
nano config.yaml

# Start the service
systemctl --user start aur-shield
# Or directly:
python -m aur_shield

# On the client:
sudo ./install-client.sh
# Then install packages:
safe-yay firefox-nightly
# Or via pacman:
sudo pacman -S aur-shield/firefox-nightly

Configuration

config.yaml:

ollama:
  url: http://localhost:11434
  model: qwen2.5:latest  # smallest model that works well
  timeout: 60

server:
  host: 0.0.0.0
  port: 8443
  repo_dir: /var/cache/aur-shield/repo
  work_dir: /var/cache/aur-shield/build

security:
  block_patterns:
    - "curl.*\\|.*bash"
    - "wget.*\\/tmp\\/.*\\|.*sh"
    - "eval.*base64"
  max_pkg_size_mb: 500
  allowed_sources:
    - "https://"
    - "http://"
    - "git://"
    - "ftp://"

cache:
  ttl_hours: 168  # 7 days

How It Works

1. IOC Pre-Check: Package name checked against public threat lists (HedgeDoc, Atomic Arch Gist, Arch Security Tracker, AUR Orphan detection). Known malicious → instant block, no LLM needed.
2. Fetch: Server pulls PKGBUILD + .SRCINFO from AUR API
3. Regex Pre-Scan: Fast pattern matching for curl|bash, eval|base64, /dev/tcp, etc.
4. LLM Scan: Ollama analyzes the PKGBUILD for:
   • Suspicious source=() URLs (npm, tor, raw IPs)
   • Obfuscated bash (eval, base64 -d, hex encoding)
   • Reverse shells, nc, /dev/tcp
   • post_install hooks creating services/cronjobs
   • Typosquatting package names
   • Unusual depends for the package type
5. Build: If clean, makepkg builds the package
6. Serve: repo-add adds it to the local pacman repo
7. Cache: Approved packages stay cached until upstream update

Threat Intelligence Sources

Based on AegisAUR IOC fetcher + archcanary extended sources:

Source	Type	Freshness	URL
HedgeDoc	Live paste	Always current	md.archlinux.org/s/SxbqukK6IA
Atomic Arch Gist	GitHub Gist	Versioned	gist.githubusercontent.com/Kidev/...
Arch Security	Official advisory	Slow but authoritative	security.archlinux.org
AUR RPC	API	Real-time	aur.archlinux.org/rpc/v5
aur-audit (black)	3rd-party API	Continuous	aur-audit.wtako.net/api/black
aur-audit (red)	3rd-party API	Continuous	aur-audit.wtako.net/api/red
Community Reports	Curated list	Manual	github.com/musqz/archcanary
CHAOS RAT	Campaign list	Manual	github.com/musqz/archcanary
Russian Spam	Campaign list	Manual	github.com/musqz/archcanary

Exit Codes

Code	Meaning
0	Clean — no indicators found
1	Warning — suspicious, review recommended
2	Malicious — package blocked

API

• GET /api/scan/<package> — Scan a package without building
• GET /api/build/<package> — Scan + build + add to repo
• GET /api/status — Server status + cache info
• GET /api/report/<package> — Get last scan report
• GET /api/cache — List all cached scan results
• DELETE /api/cache/<package> — Clear cached scan for a package
• GET /repo/<file> — Pacman repo endpoint (for client pacman.conf)

Client Usage

# Neue Pakete installieren (Scan + Build + Install)
safe-yay <package>

# System-Update (AUR-Updates werden gescannt vor Installation)
safe-yay -Syu

# Nur scannen, nicht installieren
safe-yay --scan-only <package>

# Installierte AUR-Pakete gegen IOC-Listen pruefen
safe-yay --check-installed

# Setup-Verifikation
safe-yay --doctor

Models

Tested models (smallest to best):

Model	Size	VRAM	Quality	Speed
qwen2.5:latest	4.7GB	6GB	★★★☆☆	fast
qwen2.5-coder:3b	1.9GB	3GB	★★☆☆☆	fastest
qwen3.5:9b	6.6GB	8GB	★★★★☆	medium
Laguna-XS-2.1:Q3_K_M	16GB	16GB	★★★★★	slow

Recommended: qwen2.5:latest — good balance of speed and accuracy, fits in 6GB VRAM.

Security Notes

• AUR-Shield is a defense layer, not a guarantee. The LLM can miss things.
• Always review the scan report for high-risk packages.
• The build runs in an isolated makepkg environment (non-root).
• For extra isolation, use devtools (extra-x86_64-build) in a chroot.

License

MIT