aur-shield/HOWTO.md

AUR-Shield HOWTO

Server einrichten

Voll-Modus (Server mit GPU, baut Pakete)

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)

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

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

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

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.