aur-shield/HOWTO.md

# AUR-Shield HOWTO

## Server einrichten

### Voll-Modus (Server mit GPU, baut Pakete)

```bash
git clone https://gitea.die-heimatlosen.eu/arch_agent/aur-shield.git
cd aur-shield
./install.sh
cp config.example.yaml config.yaml
# nano config.yaml — Modell, Port etc. anpassen
sudo systemctl enable --now aur-shield
```

### Scan-Only Modus (VPS ohne GPU, Client baut lokal)

```bash
git clone https://gitea.die-heimatlosen.eu/arch_agent/aur-shield.git /opt/aur-shield
cd /opt/aur-shield
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
cp config.example.yaml config.yaml

# Scan-Only aktivieren + kleinstes Modell:
sed -i 's/model: qwen2.5:latest/model: qwen2.5-coder:3b/' config.yaml
sed -i 's/scan_only: false/scan_only: true/' config.yaml

# Systemd Service:
cat > /etc/systemd/system/aur-shield.service << 'EOF'
[Unit]
Description=AUR-Shield (Scan-Only)
After=network.target ollama.service
[Service]
Type=simple
ExecStart=/opt/aur-shield/.venv/bin/python -m aur_shield /opt/aur-shield/config.yaml
WorkingDirectory=/opt/aur-shield
Restart=on-failure
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload && systemctl enable --now aur-shield
```

Im Scan-Only Modus:
- Server macht nur IOC + Regex + LLM Scan (kein `makepkg`, kein pacman repo)
- Client baut das Paket lokal mit `yay`/`paru` nachdem der Scan clean ist
- Braucht nur ~4GB RAM (3B Modell) + Python — kein `base-devel`, kein `devtools`

## Client einrichten (Desktop/Laptop)

### Standard-Installation

```bash
# Einzeiler — installiert safe-yay + pacman repo + config
curl -sL https://gitea.die-heimatlosen.eu/arch_agent/aur-shield/raw/branch/main/install-client.sh | sudo bash
```

### Mit VPS (Scan-Only Server)

```bash
# VPS als Scanner, Client baut lokal
curl -sL https://gitea.die-heimatlosen.eu/arch_agent/aur-shield/raw/branch/main/install-client.sh \
  | AUR_SHIELD_HOST=89.58.33.228 sudo bash
```

Der Client erkennt automatisch ob der Server im Scan-Only Modus läuft:
- **Scan-Only Server:** Clean → `yay -S <pkg>` lokal bauen
- **Full Server:** Clean → `pacman -S aur-shield/<pkg>` aus Repo

### Manuelle Installation (anderer Server)

Falls der AUR-Shield Server woanders läuft:

```bash
curl -sL https://gitea.die-heimatlosen.eu/arch_agent/aur-shield/raw/branch/main/install-client.sh \
  | AUR_SHIELD_HOST=192.168.1.50 AUR_SHIELD_PORT=8443 sudo bash
```

Oder nachträglich ändern:
```bash
sudo nano /etc/safe-yay.conf
# SHIELD_HOST="192.168.1.50" eintragen
# Dann pacman.conf aktualisieren:
sudo sed -i 's|Server = .*|Server = http://192.168.1.50:8443/repo|' /etc/pacman.conf
```

### Config-Datei

`/etc/safe-yay.conf`:
```bash
# AUR-Shield client configuration
SHIELD_HOST="10.90.9.102"
SHIELD_PORT="8443"
```

Env-Variablen überschreiben die Config-Datei:
```bash
AUR_SHIELD_HOST=192.168.1.50 safe-yay firefox-nightly
```

## Verwendung

### Neue Pakete installieren

```bash
# Scan + Build + Install
safe-yay firefox-nightly

# Mehrere Pakete
safe-yay google-chrome discord spotify
```

Ablauf:
1. AUR-Shield holt PKGBUILD vom AUR
2. IOC Pre-Check (HedgeDoc, Gist, Arch Security, aur-audit, etc.)
3. Regex Pre-Scan (`curl|bash`, `eval|base64`, etc.)
4. LLM Scan (Ollama analysiert den PKGBUILD)
5. Clean → `makepkg` baut das Paket → `repo-add` fügt es zum Repo hinzu
6. `pacman -S aur-shield/<paket>` installiert es

### System-Update

```bash
safe-yay -Syu
```

Ablauf:
1. `pacman -Sy` (Repo-Listen aktualisieren)
2. `yay -Qua` (AUR-Updates finden)
3. Jedes AUR-Update → AUR-Shield Scan
4. Clean → installieren | Suspicious → fragen | Malicious → blockieren
5. `pacman -Su` (Repo-Updates installieren)

### Installierte Pakete prüfen

```bash
safe-yay --check-installed
```

Prüft alle installierten AUR-Pakete (`pacman -Qmq`) gegen die IOC-Listen.
Ähnlich wie `archcanary` — findet Pakete die nach der Installation als malicious markiert wurden.

### Nur scannen (ohne Installation)

```bash
safe-yay --scan-only firefox-nightly
```

Nützlich um zu prüfen ob ein Paket safe ist bevor man es installiert.

### Health Check

```bash
safe-yay --doctor
```

Zeigt:
- Server erreichbar?
- Welches Modell?
- Wie viele cached scans?
- Ollama läuft?
- pacman repo konfiguriert?

## Exit Codes

| Code | Bedeutung | Verwendung in Scripts |
|------|-----------|----------------------|
| 0 | Clean | `if safe-yay $pkg; then echo "safe"; fi` |
| 1 | Warning (suspicious) | Review empfohlen |
| 2 | Malicious (blocked) | Nicht installieren |

Beispiel:
```bash
#!/bin/bash
for pkg in firefox-nightly google-chrome discord; do
    safe-yay --scan-only $pkg
    case $? in
        0) echo "$pkg: safe to install" ;;
        1) echo "$pkg: suspicious — review needed" ;;
        2) echo "$pkg: MALICIOUS — do not install!" ;;
    esac
done
```

## API direkt verwenden

```bash
# Paket scannen
curl http://10.90.9.102:8443/api/scan/yay | python3 -m json.tool

# Paket scannen + bauen
curl http://10.90.9.102:8443/api/build/yay | python3 -m json.tool

# Server-Status
curl http://10.90.9.102:8443/api/status

# Scan-Report abrufen
curl http://10.90.9.102:8443/api/report/yay

# Cache leeren für ein Paket
curl -X DELETE http://10.90.9.102:8443/api/cache/yay

# Alle cached scans anzeigen
curl http://10.90.9.102:8443/api/cache
```

## Modell wechseln

In `config.yaml` auf dem Server:
```yaml
ollama:
  model: qwen2.5:latest  # 4.7GB, 6GB VRAM (default)
  # model: qwen2.5-coder:3b  # 1.9GB, 3GB VRAM (kleinstes)
  # model: qwen3.5:9b  # 6.6GB, 8GB VRAM (besser)
  # model: hf.co/AtomicChat/Laguna-XS-2.1-GGUF:Q3_K_M  # 16GB, 16GB VRAM (beste)
```

Dann: `sudo systemctl restart aur-shield`

## Troubleshooting

### Server nicht erreichbar
```bash
# Auf dem Server prüfen:
sudo systemctl status aur-shield
journalctl -u aur-shield -f
```

### Ollama nicht erreichbar
```bash
# Auf dem Server prüfen:
sudo systemctl status ollama
ollama list  # Modell da?
```

### pacman sync Fehler (404)
Die Repo-DB ist leer wenn noch kein Paket gebaut wurde. Leere DB erstellen:
```bash
ssh hbock@10.90.9.102 'cd /var/cache/aur-shield/repo && repo-add aur-shield.db.tar.gz'
```

### Build schlägt fehl
```bash
# Build-Log ansehen:
journalctl -u aur-shield --since "5 min ago" | grep -i error

# Manuelles Build-Test auf dem Server:
cd /var/cache/aur-shield/build/<package>
makepkg -sf --noconfirm
```

### AUR RPC 404
AUR API URL hat sich geändert. Prüfen:
```bash
curl -sf "https://aur.archlinux.org/rpc?type=info&v=5&arg[]=yay" | python3 -m json.tool
```
Wenn 404: URL in `aur_shield/aur_client.py` anpassen.