ARIA-AGENT/host-agent/README.md

# ARIA Host-Agent

Ein schlanker Agent, der **direkt auf einem Rechner** läuft und ARIA erlaubt,
diesen Rechner zu steuern — auch wenn er sonst aus dem Netz **nicht erreichbar**
ist (hinter NAT/Firewall, kein offener Port). Der Agent verbindet sich
**ausgehend** zum RVS (gleicher Token wie der Rest von ARIA).

Unterschied zum **Satelliten**: der Satellit entdeckt und steuert *andere*
Geräte in einem LAN; der Host-Agent steuert *den Rechner, auf dem er läuft*.

## Fähigkeiten

| Aktion       | Was |
|--------------|-----|
| `exec`       | Shell-Kommando ausführen (optional `sudo`), stdout/stderr/exit |
| `read`       | Datei lesen (Base64, mit Offset/Limit) |
| `write`      | Datei schreiben/anhängen (Base64 oder Text) |
| `info`       | OS, CPU/RAM/Disk-Auslastung, Uptime, IP |
| `screenshot` | Bildschirmfoto (X11: scrot/maim · Wayland: grim) |

ARIA nutzt diese über die Brain-Tools `host_list` / `host_exec` / `host_read` /
`host_write` / `host_info` / `host_screenshot`.

## Plattformen

Eine Codebasis, läuft auf **Linux, macOS und Windows** (der Agent wählt Shell,
Screenshot-Methode und Root/Admin-Check je OS automatisch):

| | exec | Root/Admin | Screenshot |
|---|---|---|---|
| **Linux** | `bash -lc` | sudo (`SUDO_PASSWORD`/`SUDO_NOPASSWD`) / root | grim (Wayland) · scrot/maim (X11) |
| **macOS** | `bash -lc` | sudo (wie Linux) | `screencapture` (Bordmittel) |
| **Windows** | PowerShell | Agent **als Administrator** starten (kein sudo) | PowerShell/System.Drawing (Bordmittel) |

PyInstaller kann **nicht cross-kompilieren** — jede Binary wird auf ihrem OS gebaut.

## Bauen

**Linux (portabel, empfohlen)** — Docker-Container mit altem glibc:
```bash
./build.sh          # -> dist/aria-host-agent  (~15 MB, läuft auf vielen Distros)
```

**Linux/macOS ohne Docker** — PyInstaller direkt (linkt gegen lokales glibc/OS):
```bash
./build-native.sh   # -> dist/aria-host-agent
```

**Windows** — PyInstaller (Python 3 im PATH nötig):
```bat
build-native.bat    REM -> dist\aria-host-agent.exe
```

### Docker scheitert? (Live-ISO / overlayfs-Root)

Wenn `build.sh` mit `failed to mount … overlayfs … invalid argument` abbricht,
läufst du wahrscheinlich auf einem **Live-System** (Live-ISO). Dessen Root ist
selbst ein overlayfs, und Dockers `overlay2`-Treiber kann kein Overlay-auf-
Overlay stapeln. Zwei Auswege:

- **Empfohlen:** Binary auf einem normal installierten Linux bauen (`./build.sh`)
  und nur die fertige `dist/aria-host-agent` aufs Live-System kopieren. Die
  Binary ist portabel — Ziel braucht weder Docker noch Python.
- **Nativ bauen (ohne Docker):**
  ```bash
  sudo apt install -y python3-pip python3-venv
  ./build-native.sh
  ```
  Achtung: nativ gebaut linkt die Binary gegen das glibc **dieser** Maschine —
  sie läuft dann nur auf Systemen mit gleichem oder neuerem glibc.

## Installieren

1. `dist/aria-host-agent` auf den Ziel-Rechner kopieren.
2. `.env.example` → `.env` daneben, RVS-Zugang + `CONTROL_ENABLED=true` eintragen.
3. Starten: `chmod +x aria-host-agent && ./aria-host-agent`

### Als systemd-Dienst (empfohlen für Dauerbetrieb)

Der Installer kopiert Binary + `.env` an ihre Plätze und richtet den Dienst ein:

```bash
# .env-Pfad direkt übergeben:
sudo ./install-service.sh /pfad/zur/.env

# ODER ohne Argument -> ncurses-Dateidialog (dialog) zum Auswählen der .env:
sudo ./install-service.sh
```

Er legt ab:
- Binary → `/usr/local/bin/aria-host-agent`
- `.env` → `/etc/aria-host-agent/.env` (Rechte `0600`, enthält Token/Passwörter)
- Unit → `/etc/systemd/system/aria-host-agent.service`, dann `enable --now`.

Danach: `systemctl status aria-host-agent` · `journalctl -u aria-host-agent -f`.
Die Binary sucht er unter `dist/aria-host-agent` bzw. `./aria-host-agent` (oder
2. Argument). Braucht `dialog` für den Dateibrowser (bietet die Installation an).

## TLS / SNI — Agent im selben Netz wie der RVS

Steht der Rechner im **selben Netz wie der RVS** (z.B. Rechenzentrum) und soll
direkt auf dessen **interne IP** verbinden (kein NAT-Hairpin über den externen
Hostnamen), scheitert der TLS-Handshake sonst an `tlsv1 alert internal error`
(Caddy hat kein Zertifikat für die IP). Lösung — in der `.env`:

```
RVS_HOST=10.0.0.2            # interne RVS-IP
RVS_SNI=example.com    # Name, für den das Caddy-Zert gilt
```

Der Agent verbindet dann auf die IP, präsentiert aber den Namen im TLS-SNI.
Zuhause / im Normalfall `RVS_SNI` leer lassen und den Hostnamen als `RVS_HOST`.

## sudo

Vier Fälle, der Agent wählt automatisch:

1. **Agent läuft als root** (z.B. systemd `User=root`) → volle Rechte, kein sudo nötig.
2. `SUDO_PASSWORD=…` in der `.env` → `sudo -S` mit Passwort.
3. `SUDO_NOPASSWD=true` → `sudo -n` (Live-ISO / passwortloses sudo, z.B. Linux
   Mint vom Stick).
4. sonst → sudo-Kommandos scheitern mit klarer Meldung.

## Sicherheit

- Reagiert **nur** auf den eigenen RVS-Raum (Token) und **nur**, wenn
  `CONTROL_ENABLED=true`.
- Keine offenen Ports (reiner ausgehender Client).
- Alle Kommandos werden geloggt.
- Der Agent gibt **vollen** Zugriff auf den Rechner — nur auf Maschinen
  einsetzen, denen du ARIA anvertraust.

## Hinweis Screenshot

Als Systemdienst fehlt die grafische Session. Für `screenshot` den Agent in der
Desktop-Session starten (Autostart) oder `DISPLAY`/`XAUTHORITY` in der Unit setzen.