Arquitetura

O Platypus é distribuído como dois binários de backend mais um cliente desktop independente:

O servidor é puramente uma API — sem IU web embutida. Múltiplos desktops podem se conectar ao mesmo servidor simultaneamente.

Funcionalidades

• Canal TLS + protobuf entre agente e servidor
• Múltiplas portas de ingresso para que frotas em redes diferentes compartilhem um hub
• Shell interativo por host, transmitido via WebSocket
• Leitura/escrita/upload/download de arquivos com transferência em partes
• Túneis de rede: redirecionamento de porta local, redirecionamento de porta remota, SOCKS5 dinâmico
• API REST autenticada por token Bearer
• Python SDK
• Iniciar listeners automaticamente a partir do config.yml
• Desligamento gracioso (drena conexões ao receber SIGINT/SIGTERM em 30s)

Documentos

• Chinese | 中文文档

Início Rápido

Implantação com Um Clique (Recomendado)

A maneira mais rápida de obter um sistema Platypus completo em execução (incluindo o Servidor, a IU Web e um Distribuidor de Agentes baseado em MinIO) é usando o Docker Compose:

• IU Web: Abra https://localhost:9443 no seu navegador (o contêiner vem com um certificado autoassinado; seu navegador solicitará que você o aceite na primeira visita).
• Login: O bootstrap_secret é escrito em /app/data/bootstrap.secret dentro do contêiner na primeira inicialização (modo 0600). Leia-o com docker compose exec platypus-server cat /app/data/bootstrap.secret, use-o uma vez para criar o primeiro administrador, depois exclua o arquivo. Após a inicialização, o segredo não é mais aceito.
• Adicionar Agentes: Clique em "Add Agent" na IU para obter um comando de uma linha curl ... | sh, assinado e fixado ao CA do projeto, para implantar agentes em sua frota.

Compilar a partir do código fonte

Requer Go 1.24+ e protoc (apenas se você regenerar o código protobuf).

Outros alvos úteis: make test, make lint, make snapshot (multi-plataforma via goreleaser), make help.

Desenvolvimento (hooks pre-commit)

Contribuidores devem instalar os hooks do git para que gofmt / goimports / go vet / golangci-lint sejam executados antes de cada commit:

Compilar o aplicativo desktop

Requer Node 22+, dependências da CLI do Wails (wails doctor) e as bibliotecas WebView da plataforma (webkit2gtk-4.1 no Linux, WebView2 no Windows, WKWebView no macOS).

Ou: use a IU web independente (sem instalação)

Mesmas páginas, mesmas funcionalidades (exceto push de eventos em tempo real), roda em qualquer navegador:

dist-web/ é totalmente estático; coloque-o no GitHub Pages / S3 / nginx. Aponte-o para qualquer platypus-server através do formulário de login.

Notas completas em desktop/README.md.

Instalar a partir de binários de release

Baixe o arquivo apropriado para seu SO/arquitetura da página de Releases, extraia e execute.

Executar com Docker

PLATYPUS_DEV=1 ativa o fallback de KEK em disco para que uma nova inicialização funcione sem problemas; para produção, remova essa env var e defina PLATYPUS_CA_KEK (32 bytes hex; openssl rand -hex 32) para que a chave de criptografia da chave privada do CA nunca seja escrita ao lado do banco de dados criptografado.

Executar

Para produção, execute o servidor sob systemd em vez de colocá-lo em segundo plano manualmente.

Advertências de produção

• Apenas instância única. O verificador de token opaco armazena tokens verificados em cache em um LRU por processo. A revogação (logout, alteração de senha, revogação de AAT, exclusão de usuário) remove a entrada no mesmo processo de forma síncrona — mas uma implantação com múltiplas réplicas não possui um canal de invalidação entre processos atualmente, então um token revogado pode continuar funcionando em outras réplicas por até o TTL do cache (30s). Não execute mais de um platypus-server contra o mesmo banco de dados até que a revogação entre processos seja implementada. Escala vertical + um standby de alta disponibilidade é o formato suportado; réplicas horizontais balanceadas por carga não são.
• PLATYPUS_CA_KEK no ambiente. A chave privada do CA é selada com AES-256-GCM usando este valor hex de 32 bytes. Sem ele definido, o servidor se recusa a iniciar a menos que PLATYPUS_DEV=1 também esteja presente (o que ativa um fallback apenas para desenvolvimento em disco em <data-dir>/ca.kek — inseguro para produção porque o texto cifrado e a chave acabam no mesmo volume).
• Viewport de classe desktop, sem layout mobile (ainda). A IU Web tem como alvo viewports de ≥ 1280px; a barra lateral / faixa / barra de status ocupa ~300px, deixando o corpo do conteúdo na faixa ideal de leitura de 80 a 100 caracteres. Não há colapso responsivo para janelas estreitas atualmente — viewports abaixo de 1024px mostrarão barras de rolagem horizontais nas tabelas. O suporte para tablet / telefone está no backlog (P4 na auditoria de UX), mas não é bloqueador; o trabalho de administração é trabalho de mesa.
• Credenciais do object store. Quando o distribuidor está habilitado (distributor.store.endpoint definido), defina PLATYPUS_DISTRIBUTOR_STORE_ACCESS_KEY_ID e PLATYPUS_DISTRIBUTOR_STORE_SECRET_ACCESS_KEY em vez de colocá-los diretamente no config.yml. O config.docker.yml incluído vem com os campos YAML em branco por esse motivo.

Uso

Topologia

• Servidor: 192.168.88.129
  • Ingresso TLS unificado (API REST + link do agente + instalador): 0.0.0.0:9443
• Host gerenciado: 192.168.88.130 (executa platypus-agent)

Tour Rápido

Primeiro, execute ./platypus-server. Um config.yml é gerado a partir de assets/config.example.yml se nenhum existir. Os padrões são sensatos.

Para inscrever um novo host gerenciado:

1. Abra a IU Web / aplicativo desktop, navegue até o projeto, clique em Add Agent.
2. Escolha o sistema operacional / arquitetura alvo e TTL, clique em Generate.
3. Copie o comando de uma linha que a IU exibe e execute-o no host gerenciado.

O comando de uma linha renderizado pelo servidor se parece com:

O token de instalação de uso único expira pouco após a emissão e é queimado no primeiro acesso bem-sucedido. O script que o servidor retorna:

• incorpora o CA do projeto para que o download do binário do agente seja verificado com curl --cacert (sem -k, sem TOFU);
• injeta um PAT de uso único para que o agente possa concluir a inscrição e obter seu certificado de cliente mTLS;
• recusa-se a executar se o servidor não tiver um CA de projeto configurado, a menos que o operador defina explicitamente PLATYPUS_INSECURE_DOWNLOAD=1.

Não escreva manualmente URLs curl http://... para o caminho legado /agent/<host>:<port> — esse fluxo foi removido. Sempre renderize o comando de instalação através da IU para que ele carregue a âncora de confiança.

Desktop / Web

Abra o aplicativo desktop (platypus-desktop) ou a IU web (make web-ui-serve), preencha a URL do servidor e o segredo, e pronto. Abas: Sessions (cada agente que se conectou), Terminal, Files, Tunnels, Listeners.

Usos Avançados

• API REST
• Python SDK

Outros Materiais

• Apresentação no KCon 2019
• Apresentação no GCSIS 2021

Contribuidores

Este projeto existe graças a todas as pessoas que contribuem.

Apoiadores

Obrigado a todos os nossos apoiadores! 🙏 [Torne-se um apoiador]

Patrocinadores

Apoie este projeto tornando-se um patrocinador. Seu logotipo aparecerá aqui com um link para seu site. [Torne-se um patrocinador]