sshmng

Gerenciador de sessões SSH baseado em MCP para equipes de backend Linux

GitHub
9

Documentação

English | 简体中文

sshmng

sshmng é um gerenciador SSH unificado que cobre todos os formatos de conexão — direta, saltos transparentes ssh -J, bastiões interativos, proxies de transporte — em um único binário sem dependências que suporta atualização automática. Ele roda como um servidor MCP para agentes de IA (Claude Code / Hermes / etc.) e uma CLI sshmng ssh para humanos, ambos apoiados pela mesma configuração. Quando algo quebra, o Agente lê o rastreamento de falha, corrige a configuração e tenta novamente — autocura em malha fechada, sem intervenção humana.

Recursos

  • Bastiões interativos que realmente funcionam: a maioria das ferramentas SSH desiste de bastiões baseados em menu. A árvore de decisão LoginFlow do sshmng (enviar + esperar, glob ou regex re:) conduz o menu até fazer login no destino — e quando o texto do menu muda, o rastreamento de falha volta para o Agente para que ele possa corrigir o padrão e tentar novamente
  • Loop de configuração autocorretiva: o Agente lê error / login_trace, chama update_* para corrigir o padrão LoginFlow quebrado, tenta login novamente — fecha o loop de diagnóstico sem assistência humana
  • Assistente de configuração em um comando: sshmng install cria o diretório de configuração + modelo, detecta automaticamente Agentes de IA instalados (Claude Code / Hermes / OpenCode) e se injeta nas configurações deles com backups com timestamp; sshmng doctor verifica se tudo está conectado
  • Uma configuração, duas interfaces: servidor MCP para agentes de IA (Claude Code / Hermes / OpenCode / Claude Desktop / Cursor), CLI sshmng ssh para humanos. Mesmo config.json, mesmos padrões direto / Pattern A (ssh -J) / Pattern B (bastião) — configure um servidor uma vez, use de qualquer lado
  • Gerenciamento explícito de sessão: trio login → run_in_session → close_session; comandos consecutivos compartilham cwd / env / trabalhos em segundo plano, ao contrário do ssh host cmd de uso único
  • Transferência de arquivos sftp: upload / download transferem arquivos individuais por um canal sftp dedicado, separado do canal de comandos PTY; degradação graciosa quando indisponível. upload_dir / download_dir transferem recursivamente árvores de diretórios, concorrente (padrão 4), política de conflito sobrescrever / pular / renomear. relay_transfer transmite um arquivo de uma sessão para N outras via sshmng (sem disco local, fanout 1:N, fonte lida uma vez)
  • Diagnóstico de comandos: run_in_session timeout com Ctrl-C automático + drenagem, retorna timed_out / ctrl_c_sent; get_trace recupera o histórico de comandos (incluindo raw_output, ctrl_c_sent)
  • Chave de host TOFU: a primeira conexão registra a chave pública em known_hosts; alterações são rejeitadas ("host key changed, possible MITM")
  • CRUD de configuração: famílias de ferramentas list_* / get_* / update_* gerenciam SSHServer / Jumphost / Proxy, com semântica RFC 7396 JSON Merge Patch

Instalação e Build

sshmng é um único binário sem dependências de runtime. Escolha uma opção:

# Option 0: one-click install — downloads release, places on PATH
#   macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/jim58246/sshmng/main/install.sh | bash
#   Windows (PowerShell):
irm https://raw.githubusercontent.com/jim58246/sshmng/main/install.ps1 | iex

# Option 1: download release binary (recommended, no Go required)
#   From https://github.com/jim58246/sshmng/releases, pick the binary for your OS/Arch
chmod +x sshmng

# Option 2: go install (requires Go 1.25+)
go install github.com/jim58246/sshmng/cmd/sshmng@latest

# Option 3: clone and build locally
git clone https://github.com/jim58246/sshmng.git
cd sshmng && go build -o sshmng ./cmd/sshmng

Ou deixe seu Agente de IA instalá-lo para você: copie o prompt em docs/agent-install-prompt.md e cole no Claude Code / Cursor / Hermes / OpenCode — o Agente baixará o binário, o colocará em PATH e executará sshmng install para você.

macOS: binários baixados pelo navegador carregam um atributo de quarentena do Gatekeeper — execute xattr -d com.apple.quarantine sshmng antes do primeiro uso. Binários go install / go build não precisam disso (compilação local). Binários atualizados automaticamente também não precisam (veja docs/auto-update.md).

Depois de obter o binário, execute sshmng install para criar ~/.sshmng/ e injetar nos Agentes de IA instalados (Claude Code / Hermes / OpenCode, etc.). Veja Quick Start.

Recomendado: antes de executar install, mova o binário para um local estável no seu PATH (ex.: mv sshmng /usr/local/bin/, ou confie em ~/go/bin/ se você usou go install). sshmng install registra o caminho absoluto do binário nas configurações do Agente, e sshmng doctor verifica se ele corresponde ao executável em execução — escolher um local estável antecipadamente evita reexecutar a instalação após uma movimentação posterior.

Build a partir do código-fonte

# Plain build (version.Version is "dev", self-update is disabled)
go build -o sshmng ./cmd/sshmng

# Inject version via ldflags (self-update needs a real version number)
go build -ldflags="-X github.com/jim58246/sshmng/internal/version.Version=v1.2.3" -o sshmng ./cmd/sshmng

Sem ldflags, version.Version assume o padrão "dev", caso em que tanto sshmng update quanto a goroutine de atualização automática na inicialização do mcp são ignoradas.

Execute:

./sshmng                                  # Print help
./sshmng mcp                              # Start MCP server (what Agent configs use)
./sshmng install                          # First-time setup wizard
./sshmng doctor                           # Verify setup
./sshmng version                          # Print version / commit / date
./sshmng version --check                  # Check latest version against source
./sshmng update                           # Self-update to latest release
./sshmng mcp --config /path/to/config.json  # MCP server with custom config
SSHMNG_HOME=/custom/dir ./sshmng mcp         # MCP server with custom home
./sshmng server list [keywords...]        # List SSH servers (AND match on name/addr/tags)
./sshmng server get <name>                # Show SSH server details (full auth)
./sshmng jumphost list|get ...            # Same for jumphosts
./sshmng proxy list|get ...               # Same for proxies
./sshmng ssh <name> [command]             # Interactive SSH login; with command, non-interactive
./sshmng file upload <name> <local> <remote>   # File transfer via sftp (also: download, upload-dir, download-dir, relay)
./sshmng file relay <src-name> <src-path> <dst-path> --to <dst1,dst2>  # 1:N fanout to multiple servers

Início Rápido

# 1. Build
go build -o sshmng ./cmd/sshmng

# 2. First-time install (creates ~/.sshmng/ + injects into installed AI Agents)
./sshmng install

# 3. Verify config
./sshmng doctor

# 4. Restart your Agent, have it call sshmng:
#    "list_ssh_servers"          → should return an empty array
#    "add an SSH server named prod-web-01 at 10.0.0.1:22 with password ..."
#    "login to prod-web-01 and run df -h"

Não interativo:

./sshmng install --yes --agents claude-code,hermes

Para configuração manual de fallback e etapas de integração por Agente, veja docs/agents.md.

Visão Geral das Ferramentas MCP

19 ferramentas no total:

CategoriaFerramentaDescrição
Consulta de configuraçãolist_ssh_servers / list_jumphosts / list_proxiesCorrespondência AND de múltiplas palavras-chave em nome/endereço/tags (separadas por espaço, sem diferenciar maiúsculas, autenticação oculta)
Consulta de configuraçãoget_ssh_server / get_jumphost / get_proxyRegistro único por nome (autenticação completa)
Atualização de configuraçãoupdate_ssh_server / update_jumphost / update_proxyRFC 7396 JSON Merge Patch; null exclui, objeto mescla/cria
Sessãologin(name) → {sid, sftp_available}Dial + LoginFlow + injeção de RC + configuração do canal sftp
Sessãorun_in_session(sid, cmd, timeout_ms?, max_output_bytes?)Executa comando, retorna output/exit_code/timed_out/truncated/total_bytes
Sessãoclose_session(sid)Força fechamento, rastreamento retido por 10 minutos
Sessãostat()Lista todos os resumos de sessões ativas (incluindo sftp_available)
Diagnósticoget_trace(sid, last_n?, trunc_output?)Recupera histórico de comandos (incluindo ctrl_c_sent, saída bruta)
Transferência de arquivosupload(sid, src, dst, timeout_ms?)Local → remoto, via sftp
Transferência de arquivosdownload(sid, src, dst, timeout_ms?)Remoto → local, via sftp
Transferência de arquivosupload_dir(sid, src, dst, conflict?, concurrency?, timeout_ms?)Árvore de diretórios local → remoto, sftp recursivo, concorrente padrão 4, política de conflito sobrescrever/pular/renomear
Transferência de arquivosdownload_dir(sid, src, dst, conflict?, concurrency?, timeout_ms?)Árvore de diretórios remota → local, sftp recursivo, concorrente padrão 4, política de conflito sobrescrever/pular/renomear
Transferência de arquivosrelay_transfer(src_sid, src_path, dst_sids[], dst_path, timeout_ms?)Transmite um arquivo remoto de uma sessão para N outras via sshmng (sem disco local, fanout 1:N, fonte lida uma vez); requer sftp na fonte + todos os destinos; falhas parciais retornam ok:false (verifique o campo ok, não IsError)

Nenhum send_input / send_special fornecido: clientes MCP serializam chamadas de ferramentas, então durante a execução de run_in_session essas duas ferramentas não podem ser invocadas; após o comando terminar (saída normal ou timeout Ctrl-C), a sessão já está ociosa ou fechada, e chamá-las também gera erro. Comandos interativos (sudo/read/cat>file) dependem do próprio timeout do run_in_session + get_trace para diagnóstico de raw_output, não do envio de entrada.

Notas de Segurança

  • Armazenamento em texto puro: v1 armazena senha / passphrase em texto puro em config.json, documentado explicitamente; se inaceitável, criptografe todo o config.json com age / gpg você mesmo, descriptografe antes do uso
  • Chave de host TOFU: habilitada por padrão; a primeira conexão registra a chave pública em ~/.sshmng/known_hosts, alterações rejeitadas ("host key changed, possible MITM"). Pode ser desabilitada por entidade via host_key_verify: false (ignora completamente leitura/escrita de known_hosts, perde proteção MITM — apenas para bastiões de intranet confiáveis, etc.); excluir uma chave registrada ainda requer edição manual de ~/.sshmng/known_hosts, sem suporte de ferramenta
  • Rastreamento contém dados sensíveis: Send (estágio LoginFlow), Output (fluxo bruto PTY) podem conter senhas; o rastreamento é apenas em memória, retido por 10 minutos após close_session e então limpo automaticamente, nunca persistido em disco
  • stdout nunca deve registrar logs: JSON-RPC é dedicado ao stdout; logs de operação vão para o arquivo rotativo especificado por config.log_path (10MB / 5 arquivos, permissões 0600), ou sem registro se não configurado; erros de bootstrap vão para stderr
  • Escopo de autenticação (v1): apenas Password + PrivateKey suportados; sem keyboard-interactive / agente SSH / certificado SSH / 2FA (se seu ambiente exigir esses, extensão v2 ou interação codificada no LoginFlow)

Atualização automática

sshmng verifica silenciosamente atualizações em uma goroutine em segundo plano na inicialização do mcp (escreve apenas log log_path, nunca stdout). Desative via {"auto_update_enabled": false}. Atualização manual: sshmng update. Limitado pelo GitHub? Baixe o asset com seu navegador e execute sshmng update --file <path> (ignora a cota da API; aceita .tar.gz, .tar ou um diretório extraído). Verificação de versão: sshmng version --check. Fonte personalizada: defina update_url (veja docs/auto-update.md para layout de fonte auto-hospedada, notas macOS, modo --file e fluxo de release).

Testes e Desenvolvimento

# Run all tests (with race detector)
go test -race ./...

Para cobertura de testes e detalhes de desenvolvimento, veja docs/development.md (apenas em chinês — traduções bem-vindas).

Documentação

  • Referência de configuração — referência completa de campos do config.json, restrições de formato Pattern A/B, exemplos
  • Guia de integração de agentes — configuração detalhada do Claude Code / Hermes Agent / OpenCode / Claude Desktop, depuração com MCP Inspector, fluxo de configuração inicial, fluxo típico de chamadas
  • Prompt de instalação do agente — prompt copiável para seu Agente de IA instalar o sshmng de ponta a ponta
  • Atualização automática — layout de fonte HTTP auto-hospedada, notas macOS, fluxo de release
  • Arquitetura e desenvolvimento — estrutura de pacotes, designs principais, despacho de subcomandos, cobertura de testes (apenas em chinês — traduções bem-vindas)
  • Documento de design — especificação completa de design (sentinel PTY, LoginFlow, máquina de estados de sessão, etc.) (apenas em chinês — traduções bem-vindas)
  • Plano de implementação — progresso da implementação v1 (apenas em chinês — traduções bem-vindas)

Status

Estágio v1: cliente executa standalone, stdio de processo único, configuração armazenada localmente. Documento de design: docs/ssh-session-manager-design.md (apenas em chinês — traduções bem-vindas).

Contribuindo

Sinta-se à vontade para abrir issues para bugs e solicitações de recursos.

Licença

MIT — Copyright (c) 2026 jim58246