aur-shield/HOWTO.md

AUR-Shield HOWTO

Server einrichten (10.90.9.102)

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

{
  "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

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

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:

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:

# AUR-Shield client configuration
SHIELD_HOST="10.90.9.102"
SHIELD_PORT="8443"

Env-Variablen überschreiben die Config-Datei:

AUR_SHIELD_HOST=192.168.1.50 safe-yay firefox-nightly

Verwendung

Neue Pakete installieren

# 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

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

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)

safe-yay --scan-only firefox-nightly

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

Health Check

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:

#!/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

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

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

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

Ollama nicht erreichbar

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

ssh hbock@10.90.9.102 'cd /var/cache/aur-shield/repo && repo-add aur-shield.db.tar.gz'

Build schlägt fehl

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

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.