Architektur

Platypus wird als zwei Backend-Binärdateien plus einem eigenständigen Desktop-Client ausgeliefert:

Der Server ist rein eine API – keine eingebettete Web-UI. Mehrere Desktops können sich gleichzeitig mit demselben Server verbinden.

Funktionen

• TLS + Protobuf-Kanal zwischen Agent und Server
• Mehrere Eingangsports, sodass Flotten in verschiedenen Netzwerken einen Hub teilen
• Interaktive Shell pro Host, gestreamt über WebSocket
• Datei lesen / schreiben / hochladen / herunterladen mit chunked transfer
• Netzwerk-Tunnel: Local-Port-Forward, Remote-Port-Forward, dynamisches SOCKS5
• Bearer-Token-authentifizierte REST API
• Python SDK
• Listener automatisch aus config.yml starten
• Graceful Shutdown (entfernt Verbindungen bei SIGINT/SIGTERM innerhalb von 30s)

Dokumente

• Chinesisch | 中文文档

Schnellstart

One-Click-Bereitstellung (Empfohlen)

Der schnellste Weg, ein vollständiges Platypus-System zum Laufen zu bringen (einschließlich Server, Web-UI und eines MinIO-gestützten Agenten-Verteilers), ist die Verwendung von Docker Compose:

• Web-UI: Öffnen Sie https://localhost:9443 in Ihrem Browser (der Container wird mit einem selbstsignierten Zertifikat ausgeliefert; Ihr Browser fordert Sie auf, es beim ersten Besuch zu akzeptieren).
• Anmeldung: Der bootstrap_secret wird beim ersten Start in /app/data/bootstrap.secret im Container geschrieben (Modus 0600). Lesen Sie es mit docker compose exec platypus-server cat /app/data/bootstrap.secret, verwenden Sie es einmal, um den ersten Administrator zu erstellen, und löschen Sie dann die Datei. Nach Abschluss des Bootstraps wird das Secret nicht mehr akzeptiert.
• Agenten hinzufügen: Klicken Sie in der UI auf "Add Agent", um einen einzeiligen curl ... | sh-Befehl zu erhalten, der mit der Projekt-CA signiert und verankert ist, um Agenten in Ihrer Flotte bereitzustellen.

Aus dem Quellcode erstellen

Erfordert Go 1.24+ und protoc (nur wenn Sie Protobuf-Code neu generieren).

Andere nützliche Ziele: make test, make lint, make snapshot (plattformübergreifend über goreleaser), make help.

Entwicklung (Pre-Commit-Hooks)

Mitwirkende sollten die Git-Hooks installieren, damit gofmt / goimports / go vet / golangci-lint vor jedem Commit ausgeführt werden:

Die Desktop-App erstellen

Erfordert Node 22+, Wails CLI-Abhängigkeiten (wails doctor) und die WebView-Bibliotheken der Plattform (webkit2gtk-4.1 unter Linux, WebView2 unter Windows, WKWebView unter macOS).

Oder: Die eigenständige Web-UI verwenden (keine Installation)

Gleiche Seiten, gleiche Funktionen (minus Echtzeit-Ereignis-Push), läuft in jedem Browser:

dist-web/ ist vollständig statisch; legen Sie es auf GitHub Pages / S3 / nginx ab. Verweisen Sie es über das Anmeldeformular auf einen beliebigen platypus-server.

Vollständige Hinweise in desktop/README.md.

Aus Release-Binärdateien installieren

Laden Sie das entsprechende Archiv für Ihr Betriebssystem/Ihre Architektur von der Releases-Seite herunter, entpacken Sie es und führen Sie es aus.

Mit Docker ausführen

PLATYPUS_DEV=1 aktiviert den KEK-Fallback auf der Festplatte, sodass ein Neustart "einfach funktioniert"; für die Produktion entfernen Sie diese Umgebungsvariable und setzen stattdessen PLATYPUS_CA_KEK (32 Bytes hex; openssl rand -hex 32), damit der Verschlüsselungsschlüssel des CA-Private-Key nie neben der verschlüsselten Datenbank geschrieben wird.

Ausführen

Für die Produktion führen Sie den Server unter systemd aus, anstatt ihn manuell im Hintergrund laufen zu lassen.

Produktionshinweise

• Nur Single-Instance. Der Opaque-Token-Verifizierer speichert verifizierte Token in einem prozessinternen LRU-Cache. Widerruf (Abmeldung, Passwortänderung, AAT-Widerruf, Benutzerlöschung) entfernt den Eintrag auf demselben Prozess synchron – aber eine Multi-Replica-Bereitstellung hat heute keinen prozessübergreifenden Invalidierungskanal, sodass ein widerrufenes Token auf anderen Replicas bis zur Cache-TTL (30s) weiter funktionieren kann. Führen Sie nicht mehr als einen platypus-server gegen dieselbe Datenbank aus, bis der prozessübergreifende Widerruf implementiert ist. Vertikale Skalierung + ein HA-Standby ist die unterstützte Form; horizontale Lastverteilungs-Replicas werden nicht unterstützt.
• PLATYPUS_CA_KEK in der Umgebung. Der CA-Private-Key wird mit AES-256-GCM gegen diesen 32-Byte-Hex-Wert versiegelt. Ohne diese Einstellung weigert sich der Server zu starten, es sei denn, PLATYPUS_DEV=1 ist ebenfalls gesetzt (was einen nur für die Entwicklung bestimmten On-Disk-Fallback unter <data-dir>/ca.kek aktiviert – unsicher für die Produktion, da Chiffrat und Schlüssel auf demselben Volume landen).
• Desktop-Viewport, kein mobiles Layout (noch). Die Web-UI zielt auf Viewports ≥ 1280px ab; die Rail / Sidebar / Statusleiste belegt ~300px, sodass der Inhaltsbereich im optimalen Lesefenster von 80–100 Zeichen bleibt. Es gibt derzeit kein responsives Einklappen für schmale Fenster – Viewports unter 1024px zeigen horizontale Scrollbalken in Tabellen. Tablet-/Telefon-Unterstützung steht auf der Rückstandliste (P4 im UX-Audit), blockiert aber nicht; Admin-Arbeit ist Schreibtischarbeit.
• Object-Store-Anmeldedaten. Wenn der Verteiler aktiviert ist (distributor.store.endpoint gesetzt), setzen Sie PLATYPUS_DISTRIBUTOR_STORE_ACCESS_KEY_ID und PLATYPUS_DISTRIBUTOR_STORE_SECRET_ACCESS_KEY, anstatt sie in config.yml zu hinterlegen. Die mitgelieferte config.docker.yml enthält die YAML-Felder aus diesem Grund leer.

Verwendung

Topologie

• Server: 192.168.88.129
  • Einheitlicher TLS-Eingang (REST API + Agenten-Link + Installer): 0.0.0.0:9443
• Verwalteter Host: 192.168.88.130 (führt platypus-agent aus)

Kurze Übersicht

Führen Sie zuerst ./platypus-server aus. Eine config.yml wird aus assets/config.example.yml generiert, falls keine vorhanden ist. Die Standardeinstellungen sind sinnvoll.

Um einen neuen verwalteten Host anzumelden:

1. Öffnen Sie die Web-UI / Desktop-App, navigieren Sie zum Projekt, klicken Sie auf Add Agent.
2. Wählen Sie das Ziel-BS / die Architektur und TTL aus, klicken Sie auf Generate.
3. Kopieren Sie den Einzeiler, den die UI anzeigt, und führen Sie ihn auf dem verwalteten Host aus.

Der serverseitig gerenderte Einzeiler sieht so aus:

Das Einmal-Installationstoken läuft kurz nach der Ausstellung ab und wird beim ersten erfolgreichen Treffer verbraucht. Das vom Server zurückgegebene Skript:

• bettet die Projekt-CA ein, sodass der Agenten-Binärdatei-Download mit curl --cacert verifiziert wird (kein -k, kein TOFU);
• injiziert ein Einmal-PAT, damit der Agent die Anmeldung abschließen und sein mTLS-Client-Zertifikat erhalten kann;
• weigert sich zu laufen, wenn der Server keine Projekt-CA konfiguriert hat, es sei denn, der Betreiber setzt explizit PLATYPUS_INSECURE_DOWNLOAD=1.

Schreiben Sie keine curl http://...-URLs von Hand gegen den veralteten /agent/<host>:<port>-Pfad – dieser Ablauf wurde entfernt. Rendern Sie den Installationsbefehl immer über die UI, damit er den Vertrauensanker enthält.

Desktop / Web

Öffnen Sie die Desktop-App (platypus-desktop) oder die Web-UI (make web-ui-serve), geben Sie die Server-URL und das Secret ein, und schon sind Sie drin. Tabs: Sitzungen (jeder Agent, der verbunden ist), Terminal, Dateien, Tunnel, Listener.

Fortgeschrittene Nutzung

• REST API
• Python SDK

Weitere Materialien

• Präsentation auf der KCon 2019
• Präsentation auf der GCSIS 2021

Mitwirkende

Dieses Projekt existiert dank aller Menschen, die dazu beitragen.

Unterstützer

Danke an alle unsere Unterstützer! 🙏 [Unterstützer werden]

Sponsoren

Unterstützen Sie dieses Projekt, indem Sie Sponsor werden. Ihr Logo wird hier mit einem Link zu Ihrer Website erscheinen. [Sponsor werden]