CLI-/Headless-Betriebshandbuch

1. Komponenten

Eine Headless-Bereitstellung läuft auf dem Daemon + roamswitch CLI (plus roamswitch-mcp, falls gewünscht). Alle autonomen Abwehrmechanismen funktionieren ohne GUI.

2. Daemon (Systemd-Dienste)

Client-Edition

sudo systemctl status  roamswitch.service      # Status
sudo systemctl enable  roamswitch.service      # Autostart beim Booten (bei Installation aktiviert)
sudo systemctl restart roamswitch.service      # Neustart
journalctl -u roamswitch.service -f            # Logs verfolgen
journalctl -u roamswitch.service --since "1h ago"

Was der Client-Daemon beim Start und in jedem Zyklus (3 s) autonom macht:

• Identifiziert den verbundenen Gateway-MAC und wendet nftables-Profile (open / balanced / lockdown) auf trusted_networks an.
• Verhaltensbasierte Ransomware-Erkennung (Fanotify + Shannon-Entropie + Kanarienvögel)
• On-Access-Malware-Scanning (Fanotify, optional ClamAV)
• ARP-Spoof-Überwachung und präventives Gateway-ARP/NDP-Pinning in nicht vertrauenswürdigen Netzwerken
• Kernel-Härtung (sysctl / Yama / core dumps / /tmp noexec) pro Profil
• Bedrohungsschutz-DNS-Durchsetzung (dns_enabled + dns_scope)
• Link Guard (NFQUEUE) zum Abfangen von Phishing
• Ausgabe des Laufzeitstatus an /run/roamswitch/state.json

Server-Edition

sudo systemctl status  roamswitch-server.service      # Status
sudo systemctl restart roamswitch-server.service      # Neustart
journalctl -u roamswitch-server.service -f            # Logs verfolgen

3. CLI-Befehlsreferenz

Grundlegende Syntax: roamswitch <command> [options]. Bei der Ausführung ohne Argumente wird standardmäßig status verwendet. Die Ausgabesprache folgt automatisch dem Betriebssystemgebietsschema (LC_ALL / LC_MESSAGES / LANG).

Isolationsrichtlinie (Air-Gap)

Eine Aufhebung allein nach einem festen Timer lässt einen geduldigen Angreifer abwarten, daher wird der Auslöser einer Isolation nach Konfidenz klassifiziert (in beiden Editionen).

• Geringe Konfidenz (ein manuelles Air-Gap, generische Anomalien, eBPF Error / Warning und darunter): wird nach einem kurzen Timer vollständig wiederhergestellt (Client: airgap_low_confidence_secs, standardmäßig 600 s; Server: safety_timer_secs in guard.yaml, standardmäßig 300 s; 0 deaktiviert den Timer).
• Hohe Konfidenz (Manipulation von Canaries, ransomwareartiges Massen-Umschreiben, ARP-Spoofing unter Lockdown, eBPF Critical / Emergency / Alert, wiederholtes Auslösen derselben Regel und so weiter): wird nie stillschweigend wiederhergestellt. Nach dem Timer wird die Ursache (eingefrorene PID, Canary, ARP, erneut auslösende Regel) erneut geprüft, und die Isolation wird mit einer Benachrichtigung nur dann aufgehoben, wenn die Ursache verifiziert beseitigt ist. Lässt sich das nicht bestätigen, hat niemand quittiert und ist die Obergrenze erreicht (Client: airgap_hard_cap_secs; Server: isolation_hard_cap_secs in server.conf; beide standardmäßig 3600 s, 0 = keine Obergrenze), geht sie in den DEGRADED-Modus über.
• Der DEGRADED-Modus öffnet sich nie per Timer (der Client erlaubt nur Loopback; der Server erlaubt nur die Verwaltungspfade der SSH-Wartung und der Whitelist-IPs). Er wird nur durch eine verifiziert erfolgreiche erneute Prüfung, eine ausdrückliche Quittierung (Server: roamswitch server ack) oder eine manuelle Aufhebung (die GUI-Schaltfläche / roamswitch emergency-restore) aufgehoben. Im DEGRADED-Modus des Clients wird auch das rfkill des WLANs nicht aufgehoben, es sei denn, airgap_degraded_lift_rfkill ist true.
• Bestehende Verbindungen außer den Verwaltungspfaden werden gekappt (Server: alles außer den SSH-Wartungsports und den Whitelist-IPs, sodass auch ein C2-Kanal oder eine Reverse Shell, die der Angreifer bereits geöffnet hat, gekappt wird). Ein manuelles Air-Gap hat geringe Konfidenz, wenn es über das Menü / die GUI / roamswitch airgap enable ohne Warnungskontext ausgelöst wird; wird es jedoch über die Schaltfläche „Jetzt blockieren“ einer ARP-Spoofing-Warnung gestartet, erbt es die (hohe) Konfidenz dieser Warnung, und die MAC des Gateways wird ohne Aussenden von Datenverkehr erneut geprüft, bis sie bei aufeinanderfolgenden Prüfungen mit der vertrauenswürdigen MAC übereinstimmt (arp_recheck_consecutive Prüfungen über mindestens arp_recheck_min_secs Sekunden). Jeder Übergang wird in der Vorfalls-Zeitachse festgehalten.

Ransomware-Wiederherstellung (Snapshots und Dateiwiederherstellung)

Die folgenden Befehle gehören zu roamswitch-ransomware-rollback (es sind keine Unterbefehle von roamswitch). Der Zustand wird in /var/lib/roamswitch gespeichert.

Beispiele

sudo roamswitch status                 # Vollständige Client-Diagnose (27 Punkte)
sudo roamswitch status --server        # Vollständige Diagnose der Server Edition (34 Punkte)
sudo roamswitch ports -a               # Alle lauschenden Ports
roamswitch guards                      # Guard-Status
roamswitch audit-url https://examp1e-login.com
roamswitch audit-secrets ./deploy.env
roamswitch audit-secrets .                          # Aktuelles Verzeichnis rekursiv scannen
roamswitch audit-logs 72               # Logs der letzten 72 Stunden analysieren
sudo roamswitch sharing on             # SSH/Samba/RDP in nicht vertrauenswürdigen Netzwerken automatisch stoppen
sudo roamswitch fim verify             # FIM-Dateiintegritätsprüfung
sudo roamswitch fim update             # FIM-Baseline aktualisieren
sudo roamswitch emergency-restore      # Notabschaltung vollständig aufheben und wiederherstellen
sudo roamswitch airgap enable          # Notabschaltung
sudo roamswitch airgap disable         # Aufheben
sudo roamswitch server ack             # Quittiert die Notfall-Isolation (hält eine FULL-Isolation strikt aufrecht, hebt eine DEGRADED-Isolation auf)
roamswitch canary                      # Canary-Vorfallshistorie
roamswitch vuln-status                 # Zeigt das letzte Scan-Ergebnis und die verstrichenen Tage (pass_age)
roamswitch port-anomaly                # Vorfallshistorie des Port-Anomaly-Guards
roamswitch server ebpf                 # Eindämmungsstatus und Vorfallshistorie des eBPF-Guards
roamswitch server bans                 # Zustand des SSH-Brute-Force-Schutzes und die gesperrten Quellen
sudo roamswitch server unban 203.0.113.9   # Eine Sperre des SSH-Schutzes aufheben (benötigt root)
roamswitch notifications               # Benachrichtigungsverlauf der letzten 7 Tage
roamswitch frozen                      # Eingefrorene Prozesse auflisten
sudo roamswitch frozen resume 12345    # Fehlalarm wieder freigeben
sudo roamswitch sensor pair --addr 192.168.1.50 --code AB3DFGH2 --fingerprint 3F:45:89:E1:...:36:10  # Paart sich per Pairing-Code mit Sensor
sudo roamswitch sensor key             # Zeigt den eigenen Public Key/Adresse dieses Endpunkts
roamswitch port-scan                   # Portscan-Erkennungsverlauf
roamswitch timeline --json             # all incident-timeline records as JSON
roamswitch notifications --export n.jsonl   # JSON Lines
sudo roamswitch events search --since 2h --exe curl
sudo roamswitch forward status
sudo roamswitch server allowlist add "<rule>" mytool --exe /usr/local/bin/mytool
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT>
sudo roamswitch server tui

Der Server-Edition-Daemon läuft als root, daher liefern Befehle, die das nftables-Regelwerk lesen oder den Prozessbesitzer ermitteln müssen (status / status --server / ports -a), ohne sudo ungenaue Ergebnisse (eine fälschliche „inaktiv“-Bewertung oder fehlende Prozessinformationen). Befehle, die die Konfiguration ändern (sharing / fim update / airgap / emergency-restore usw.), benötigen ebenfalls sudo. Alle anderen, reinen Lesebefehle funktionieren auch ohne sudo korrekt.

4. Konfigurationsdateien

Client-Edition (~/.config/roamswitch/config.json)

Der Daemon wird als Root ausgeführt und scannt /home/*/.config/roamswitch/config.json, wobei er die erste gültige Datei verwendet, die er findet (oder /root/.config/roamswitch/config.json in Nur-Root-Umgebungen).

Server-Edition (/etc/roamswitch/server.conf)

Die Server Edition nutzt eine Konfigurationsdatei im INI-Format, geschützt mit den Berechtigungen 0600 (nur root). Typ, zulässige Werte, Standard und Neustartbedarf jedes Schlüssels stehen im Server-Betriebshandbuch §18. Schlüssel ändern Sie mit roamswitch server config show|get|set oder im Konfigurationseditor von roamswitch server tui (alle 146 Schlüssel von server.conf und guard.yaml). Die Server Edition unterstützt kein Neuladen der Konfiguration, wenden Sie Änderungen daher mit sudo roamswitch server restart an.

Gemeinsam genutzte Rechner: Nur-Administrator-Modus

Auf einem Rechner, den mehrere Personen nutzen, schaltet sudo touch /etc/roamswitch/admin-only den Nur-Administrator-Modus ein. Änderungen, die den ganzen Rechner betreffen (Firewall, DNS, VPN, USB, Kernel- und Mount-Härtung, Funkmodule, Sensor-Vertrauen u. a.), sind dann auf root oder Benutzer der Gruppe sudo, wheel oder roamswitch beschränkt. Aktionen, die an eigene Dateien und Prozesse gebunden sind (Isolation, kill, freeze, Scans), funktionieren wie bisher. /etc/roamswitch/admin-only gilt nur, wenn die Datei root gehört und andere sie nicht beschreiben können (ein Benutzer kann den Modus also nicht selbst umschalten). Standardmäßig ist der Modus aus (keine Datei).

5. Protokolle und Laufzeitstatusdateien

IPC direkt aufrufen (Erweitert)

Der Daemon akzeptiert durch Zeilenumbrüche getrenntes JSON auf /run/roamswitch/roamswitch.sock:

# Profil erzwungen wechseln (Client Edition)
printf '{"id":1,"method":"set_security_level","params":{"level":"lockdown"}}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

# Gateway-ARP-Sperre jetzt abgleichen
printf '{"id":1,"method":"reconcile_gateway_lock","params":null}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

6. Programmatischer Status (MCP)

roamswitch-mcp macht schreibgeschützte Tools über JSON-RPC auf stdio verfügbar (get_security_report / verify_security_findings / get_exposed_ports / get_guard_status / audit_url_safety / audit_secrets / audit_security_logs / audit_mcp_configs / audit_agent_setup / get_app_help / get_quarantine_status / get_file_scan_guard_status / verify_fim / get_port_anomaly_incidents / get_ebpf_incidents / get_resource_guard_incidents / get_port_scan_incidents / get_ssh_guard_incidents / get_canary_status / get_vulnerability_scan_history / get_notification_history / search_exec_events / get_process_tree / get_incident_timeline / get_fleet_status / get_vpn_status / get_link_guard_status / get_air_gap_status / get_sharing_services_status / get_bluetooth_guard_status / get_usb_guard_status / run_active_vuln_scan / run_package_cve_scan / run_package_cve_scan_languages / run_package_lifecycle_script_scan / run_typosquat_scan / run_npm_audit_signatures / get_sensor_audit_results).

Es verbindet sich nicht mit externen Hosts, sondern spricht lokal mit dem Daemon-Socket oder ruft roamswitch-core direkt auf. get_security_report und verify_security_findings senden auch nichts ins LAN (das Gateway wird nur aus dem ARP-Cache und anderen lokalen Informationen gelesen). Siehe MCP-Einrichtungshandbuch

• RoamSwitch für Linux-Produktseite
• Whitepaper zur Client-Sicherheit
• Whitepaper zur Serversicherheit
• Server-Bedienungsanleitung
• AI-Assistent und MCP-Integrationsleitfaden
• FAQ