Architecture

Platypus est fourni sous forme de deux binaires backend plus un client de bureau autonome :

Le serveur est purement une API — pas d'interface web intégrée. Plusieurs bureaux peuvent se connecter au même serveur simultanément.

Fonctionnalités

• Canal TLS + protobuf entre l'agent et le serveur
• Plusieurs ports d'entrée (ingress) pour que des flottes dans différents réseaux partagent un même hub
• Shell interactif par hôte, diffusé via WebSocket
• Lecture/écriture/téléchargement/upload de fichiers avec transfert par morceaux
• Tunnels réseau : local-port-forward, remote-port-forward, SOCKS5 dynamique
• API REST authentifiée par jeton Bearer
• Python SDK
• Démarrage automatique des listeners depuis config.yml
• Arrêt gracieux (draine les connexions sur SIGINT/SIGTERM en 30s)

Documents

• Chinese | 中文文档

Démarrage rapide

Déploiement en un clic (Recommandé)

Le moyen le plus rapide d'obtenir un système Platypus complet (comprenant le serveur, l'interface Web et un distributeur d'agents basé sur MinIO) est d'utiliser Docker Compose :

• Interface Web : Ouvrez https://localhost:9443 dans votre navigateur (le conteneur est livré avec un certificat auto-signé ; votre navigateur vous demandera de l'accepter lors de la première visite).
• Connexion : Le bootstrap_secret est écrit dans /app/data/bootstrap.secret à l'intérieur du conteneur lors du premier démarrage (mode 0600). Lisez-le avec docker compose exec platypus-server cat /app/data/bootstrap.secret, utilisez-le une fois pour créer le premier administrateur, puis supprimez le fichier. Une fois l'amorçage terminé, le secret n'est plus accepté.
• Ajouter des agents : Cliquez sur "Add Agent" dans l'interface pour obtenir une commande en une ligne curl ... | sh, signée et épinglée au CA du projet, pour déployer des agents sur votre flotte.

Construire à partir des sources

Nécessite Go 1.24+ et protoc (uniquement si vous régénérez le code protobuf).

Autres cibles utiles : make test, make lint, make snapshot (multi-plateforme via goreleaser), make help.

Développement (hooks pre-commit)

Les contributeurs devraient installer les hooks git pour que gofmt / goimports / go vet / golangci-lint s'exécutent avant chaque commit :

Construire l'application de bureau

Nécessite Node 22+, les dépendances Wails CLI (wails doctor) et les bibliothèques WebView de la plateforme (webkit2gtk-4.1 sur Linux, WebView2 sur Windows, WKWebView sur macOS).

Ou : utiliser l'interface Web autonome (sans installation)

Mêmes pages, mêmes fonctionnalités (sauf le push d'événements en temps réel), fonctionne dans n'importe quel navigateur :

dist-web/ est entièrement statique ; déposez-le sur GitHub Pages / S3 / nginx. Pointez-le vers n'importe quel platypus-server via le formulaire de connexion.

Notes complètes dans desktop/README.md.

Installer à partir des binaires de version

Téléchargez l'archive appropriée pour votre OS/arch depuis la page des versions, extrayez-la et exécutez-la.

Exécuter avec Docker

PLATYPUS_DEV=1 active le recours au KEK sur disque pour qu'un démarrage frais « fonctionne directement » ; en production, supprimez cette variable d'environnement et définissez PLATYPUS_CA_KEK (32 octets hexadécimaux ; openssl rand -hex 32) à la place pour que la clé de chiffrement de la clé privée du CA ne soit jamais écrite à côté de la base de données chiffrée.

Exécuter

En production, exécutez le serveur sous systemd plutôt que de le mettre en arrière-plan manuellement.

Mises en garde pour la production

• Instance unique seulement. Le vérificateur de jetons opaques met en cache les jetons vérifiés dans un LRU par processus. La révocation (déconnexion, changement de mot de passe, révocation AAT, suppression d'utilisateur) supprime l'entrée sur le même processus de manière synchrone — mais un déploiement multi-réplicas n'a pas de canal d'invalidation inter-processus aujourd'hui, donc un jeton révoqué peut continuer à fonctionner sur d'autres réplicas jusqu'à la durée de vie du cache (30s). N'exécutez pas plus d'un platypus-server contre la même base de données jusqu'à ce que la révocation inter-processus soit implémentée. L'évolutivité verticale + un stand-by haute disponibilité est la forme prise en charge ; les réplicas horizontaux équilibrés en charge ne le sont pas.
• PLATYPUS_CA_KEK dans l'environnement. La clé privée du CA est scellée avec AES-256-GCM contre cette valeur hexadécimale de 32 octets. Sans celle-ci, le serveur refuse de démarrer sauf si PLATYPUS_DEV=1 est également présent (ce qui active un recours sur disque réservé au développement dans <data-dir>/ca.kek — dangereux en production car le texte chiffré et la clé se retrouvent sur le même volume).
• Viewport de classe bureau, pas de mise en page mobile (pour l'instant). L'interface Web cible les viewports ≥ 1280px ; le rail / sidebar / barre d'état prend environ 300px, laissant le corps du contenu dans la zone de confort de lecture de 80 à 100 caractères. Il n'y a pas de réduction responsive pour les fenêtres étroites aujourd'hui — les viewports inférieurs à 1024px afficheront des barres de défilement horizontales sur les tableaux. La prise en charge des tablettes/téléphones est dans le backlog (P4 dans l'audit UX) mais ne bloque pas ; le travail d'administration est un travail de bureau.
• Identifiants du stockage objet. Lorsque le distributeur est activé (distributor.store.endpoint défini), définissez PLATYPUS_DISTRIBUTOR_STORE_ACCESS_KEY_ID et PLATYPUS_DISTRIBUTOR_STORE_SECRET_ACCESS_KEY plutôt que de les intégrer dans config.yml. Le fichier config.docker.yml fourni est livré avec les champs YAML vides pour cette raison.

Utilisation

Topologie

• Serveur : 192.168.88.129
  • Entrée TLS unifiée (API REST + lien agent + installeur) : 0.0.0.0:9443
• Hôte géré : 192.168.88.130 (exécute platypus-agent)

Tour rapide

Tout d'abord, exécutez ./platypus-server. Un config.yml est généré à partir de assets/config.example.yml s'il n'existe pas. Les valeurs par défaut sont raisonnables.

Pour enrôler un nouvel hôte géré :

1. Ouvrez l'interface Web / l'application de bureau, naviguez vers le projet, cliquez sur Add Agent.
2. Choisissez l'OS/arch cible et le TTL, cliquez sur Generate.
3. Copiez la commande en une ligne affichée par l'interface et exécutez-la sur l'hôte géré.

La commande en une ligne rendue par le serveur ressemble à :

Le jeton d'installation à usage unique expire peu après son émission et est brûlé lors du premier accès réussi. Le script renvoyé par le serveur :

• intègre le CA du projet pour que le téléchargement du binaire agent soit vérifié avec curl --cacert (pas de -k, pas de TOFU) ;
• injecte un PAT à usage unique pour que l'agent puisse terminer l'enrôlement et obtenir son certificat client mTLS ;
• refuse de s'exécuter si le serveur n'a pas de CA de projet configuré, sauf si l'opérateur définit explicitement PLATYPUS_INSECURE_DOWNLOAD=1.

Ne rédigez pas manuellement des URL curl http://... vers l'ancien chemin /agent/<host>:<port> — ce flux a été supprimé. Rendez toujours la commande d'installation via l'interface pour qu'elle porte l'ancre de confiance.

Bureau / Web

Ouvrez l'application de bureau (platypus-desktop) ou l'interface Web (make web-ui-serve), remplissez l'URL du serveur et le secret, et vous êtes dedans. Onglets : Sessions (chaque agent qui s'est connecté), Terminal, Fichiers, Tunnels, Listeners.

Utilisations avancées

• REST API
• Python SDK

Autres documents

• Presentation on KCon 2019
• Presentation on GCSIS 2021

Contributeurs

Ce projet existe grâce à toutes les personnes qui contribuent.

Soutiens

Merci à tous nos soutiens ! 🙏 [Devenir un soutien]

Sponsors

Soutenez ce projet en devenant sponsor. Votre logo apparaîtra ici avec un lien vers votre site web. [Devenir sponsor]