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

```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. **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](https://gitea.die-heimatlosen.eu/arch_agent/aegisaur) IOC fetcher + [archcanary](https://github.com/musqz/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

```bash
# 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