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