aur-shield v0.1.0: AI-powered AUR firewall

- FastAPI server with scan/build/repo endpoints - LLM scanner (Ollama) with regex pre-scan - makepkg/devtools builder with chroot isolation - Scan cache with TTL + PKGBUILD hash - Client installer + safe-yay wrapper - Docs + config example
2026-08-04 09:35:35 +02:00
commit adee5dfc78
14 changed files with 1368 additions and 0 deletions
@@ -0,0 +1,138 @@
+# 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
+
+```bash
+# 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`:
+```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. **Request:** Client asks for `aur-shield/<package>`
+2. **Fetch:** Server pulls PKGBUILD + .SRCINFO from AUR API
+3. **Scan:** LLM 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
+4. **Build:** If clean, `makepkg` builds the package
+5. **Serve:** `repo-add` adds it to the local pacman repo
+6. **Cache:** Approved packages stay cached until upstream update
+
+## 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 /repo/<file>` — Pacman repo endpoint (for client pacman.conf)
+
+## 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