Platypus

Un hub di gestione degli host per flotte di macchine Linux. Installa l'agente Platypus su ogni host che possiedi; l'agente si riconnette al tuo server Platypus tramite TLS + protobuf; dal server ottieni una shell interattiva, gestione dei file e tunneling di rete su ogni host gestito — attraverso un unico pannello di controllo centrale.

Screenshot

Un'interfaccia utente a navigazione piatta stile Vercel con una dashboard di progetto, un browser per host/listener/sessioni, una console di dispatch multi-host e un gestore utenti amministrativi. Vedi la galleria completa in docs/screenshots/. Esegui di nuovo make screenshots per rigenerarli dall'app live.

Architettura

Platypus viene fornito come due binari backend più un client desktop standalone:

Il server è puramente un'API — nessuna interfaccia web integrata. Più desktop possono connettersi allo stesso server contemporaneamente.

Funzionalità

• Canale TLS + protobuf tra agente e server
• Più porte di ingresso in modo che flotte in reti diverse condividano un unico hub
• Shell interattiva per host, trasmessa tramite WebSocket
• Lettura / scrittura / upload / download di file con trasferimento a blocchi
• Tunnel di rete: forward porta locale, forward porta remota, SOCKS5 dinamico
• API REST autenticata con token Bearer
• Python SDK
• Avvio automatico dei listener da config.yml
• Arresto graduale (scarica le connessioni su SIGINT/SIGTERM entro 30 secondi)

Documenti

• Cinese | 中文文档

Avvio rapido

Distribuzione con un clic (Consigliata)

Il modo più veloce per ottenere un sistema Platypus completo (inclusi Server, Web UI e un Distributore di Agenti basato su MinIO) è usare Docker Compose:

git clone https://github.com/WangYihang/Platypus
cd Platypus
docker-compose up -d

• Web UI: Apri https://localhost:9443 nel tuo browser (il container viene fornito con un certificato auto-firmato; il browser ti chiederà di accettarlo al primo accesso).
• Login: Il bootstrap_secret viene scritto in /app/data/bootstrap.secret all'interno del container al primo avvio (modalità 0600). Leggilo con docker compose exec platypus-server cat /app/data/bootstrap.secret, usalo una volta per creare il primo amministratore, poi elimina il file. Dopo il completamento del bootstrap il secret non viene più accettato.
• Aggiungere agenti: Clicca "Add Agent" nell'interfaccia per ottenere un comando curl ... | sh su una riga, firmato e associato alla CA del progetto, per distribuire agenti nella tua flotta.

Compilare dal sorgente

Richiede Go 1.24+ e protoc (solo se rigeneri il codice protobuf).

git clone https://github.com/WangYihang/Platypus
cd Platypus
make build              # → ./build/{platypus-server,platypus-agent}

Altri target utili: make test, make lint, make snapshot (cross-platform tramite goreleaser), make help.

Sviluppo (hook pre-commit)

I contributori dovrebbero installare gli hook git in modo che gofmt / goimports / go vet / golangci-lint vengano eseguiti prima di ogni commit:

pip install pre-commit   # oppure: pipx install pre-commit
make hooks               # una tantum: collega .git/hooks/pre-commit
make pre-commit          # opzionale: esegui tutti gli hook su ogni file ora

Compilare l'app desktop

Richiede Node 22+, dipendenze Wails CLI (wails doctor) e le librerie WebView della piattaforma (webkit2gtk-4.1 su Linux, WebView2 su Windows, WKWebView su macOS).

make desktop-deps       # una tantum: installa Wails CLI + pacchetti pnpm
make desktop-build      # → desktop/build/bin/platypus-desktop
make desktop-dev        # modalità sviluppo con hot-reload

Oppure: usa l'interfaccia web standalone (nessuna installazione)

Stesse pagine, stesse funzionalità (tranne il push di eventi in tempo reale), funziona in qualsiasi browser:

make web-ui             # → desktop/frontend/dist-web/ (bundle statico)
make web-ui-serve       # anteprima su http://localhost:8080

dist-web/ è completamente statico; caricalo su GitHub Pages / S3 / nginx. Puntalo a qualsiasi platypus-server tramite il modulo di login.

Note complete in desktop/README.md.

Installare dai binari di rilascio

Scarica l'archivio appropriato per il tuo sistema operativo/architettura dalla pagina Releases, estrai ed esegui.

Eseguire con Docker

docker build -t platypus-server .
docker run --rm -p 9443:9443 \
  -e PLATYPUS_DEV=1 \
  -v $(pwd)/config.yml:/config.yml \
  platypus-server

PLATYPUS_DEV=1 abilita il fallback KEK su disco in modo che un avvio fresco "funzioni subito"; per produzione, rimuovi quella variabile d'ambiente e imposta PLATYPUS_CA_KEK (32 byte esadecimali; openssl rand -hex 32) in modo che la chiave di crittografia della chiave privata CA non venga mai scritta accanto al database crittografato.

Eseguire

./build/platypus-server                # in primo piano; Ctrl-C per arresto graduale

Per produzione, esegui il server sotto systemd piuttosto che metterlo in background manualmente.

Avvertenze per la produzione

• Solo istanza singola. Il verificatore di token opachi memorizza nella cache i token verificati in un LRU per processo. La revoca (logout, cambio password, revoca AAT, eliminazione utente) elimina la voce nello stesso processo in modo sincrono — ma una distribuzione multi-replica non ha un canale di invalidamento tra processi oggi, quindi un token revocato può continuare a funzionare su altre repliche fino alla scadenza della cache (30 secondi). Non eseguire più di un platypus-server contro lo stesso database finché non viene implementata la revoca tra processi. La scalabilità verticale + un standby HA è la forma supportata; le repliche orizzontali con bilanciamento del carico non sono supportate.
• PLATYPUS_CA_KEK nell'ambiente. La chiave privata CA è sigillata con AES-256-GCM usando questo valore esadecimale di 32 byte. Senza di esso impostato, il server rifiuta di avviarsi a meno che non sia presente anche PLATYPUS_DEV=1 (che abilita un fallback su disco solo per sviluppo in <data-dir>/ca.kek — non sicuro per produzione perché il testo cifrato e la chiave finiscono sullo stesso volume).
• Viewport per desktop, nessun layout mobile (ancora). L'interfaccia web è pensata per viewport ≥ 1280px; la barra laterale / rail / barra di stato occupa ~300px, lasciando il corpo del contenuto nella fascia di lettura ottimale di 80–100 caratteri. Non esiste un collasso reattivo per finestre strette oggi — i viewport inferiori a 1024px mostreranno scorrimento orizzontale sulle tabelle. Il supporto per tablet / telefono è nel backlog (P4 nell'audit UX) ma non è bloccante; il lavoro di amministrazione è lavoro da scrivania.
• Credenziali dell'object store. Quando il distributore è abilitato (distributor.store.endpoint impostato), imposta PLATYPUS_DISTRIBUTOR_STORE_ACCESS_KEY_ID e PLATYPUS_DISTRIBUTOR_STORE_SECRET_ACCESS_KEY piuttosto che includerli in . Il file fornito in dotazione ha i campi YAML vuoti per questo motivo.

Utilizzo

Topologia

• Server: 192.168.88.129
  • Ingresso TLS unificato (API REST + collegamento agente + installer): 0.0.0.0:9443
• Host gestito: 192.168.88.130 (esegue platypus-agent)

Giro rapido

Prima, esegui ./platypus-server. Un file config.yml viene generato da assets/config.example.yml se non esiste già. Le impostazioni predefinite sono sensate.

Per arruolare un nuovo host gestito:

1. Apri l'interfaccia web / desktop app, vai al progetto, clicca Add Agent.
2. Scegli il sistema operativo / architettura di destinazione e il TTL, clicca Generate.
3. Copia il comando su una riga visualizzato dall'interfaccia ed eseguilo sull'host gestito.

Il comando su una riga renderizzato dal server appare come:

curl -fsSL https://<server>:9443/api/v1/install/<one-shot-token> | sh

Il token di installazione monouso scade poco dopo l'emissione e viene bruciato al primo hit riuscito. Lo script restituito dal server:

• incorpora la CA del progetto in modo che il download del binario dell'agente sia verificato con curl --cacert (nessun -k, nessun TOFU);
• inietta un PAT monouso in modo che l'agente possa completare l'arruolamento e ottenere il suo certificato client mTLS;
• rifiuta di eseguire se il server non ha una CA di progetto configurata, a meno che l'operatore non imposti esplicitamente PLATYPUS_INSECURE_DOWNLOAD=1.

Non scrivere manualmente URL curl http://... verso il percorso legacy /agent/<host>:<port> — quel flusso è stato rimosso. Genera sempre il comando di installazione tramite l'interfaccia in modo che porti l'ancora di fiducia.

Desktop / Web

Apri l'app desktop (platypus-desktop) o l'interfaccia web (make web-ui-serve), inserisci l'URL del server e il secret, e sei dentro. Schede: Sessions (ogni agente che si è connesso), Terminal, Files, Tunnels, Listeners.

Utilizzi avanzati

• API REST
• Python SDK

Altri materiali

• Presentazione al KCon 2019
• Presentazione al GCSIS 2021

Collaboratori

Questo progetto esiste grazie a tutte le persone che contribuiscono.

Sostenitori

Grazie a tutti i nostri sostenitori! 🙏 [Diventa un sostenitore]

Sponsor

Supporta questo progetto diventando uno sponsor. Il tuo logo apparirà qui con un link al tuo sito web. [Diventa uno sponsor]