docs: HOWTO.md — complete usage guide
Server setup, client install, all commands (safe-yay, -Syu, --check-installed, --scan-only, --doctor), API usage, model switching, troubleshooting, exit codes with script examples.
This commit is contained in:
arch_agent
@@ -0,0 +1,236 @@
|
|||||||
|
# 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.
|
||||||
Reference in New Issue
Block a user