aur-shield/HOWTO.md

# AUR-Shield HOWTO

## Server einrichten (10.90.9.102)

```bash
# Klonen
git clone https://gitea.die-heimatlosen.eu/arch_agent/aur-shield.git
cd aur-shield

# Installieren (Python venv, systemd service, cache dirs)
./install.sh

# Config anpassen falls nötig
cp config.example.yaml config.yaml
nano config.yaml

# Service starten
sudo systemctl enable --now aur-shield

# Verifikation
curl http://localhost:8443/api/status
```

Erwartete Ausgabe:
```json
{
  "status": "running",
  "model": "qwen2.5:latest",
  "ollama_url": "http://localhost:11434",
  "repo_dir": "/var/cache/aur-shield/repo",
  "cached_scans": 0
}
```

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

Das macht:
1. `/etc/safe-yay.conf` — Server-Adresse (`SHIELD_HOST="10.90.9.102"`)
2. `[aur-shield]` repo in `/etc/pacman.conf` — zeigt auf `http://10.90.9.102:8443/repo`
3. `/usr/local/bin/safe-yay` — Wrapper-Skript

### 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.