--- name: sshp-connect description: Perfis de servidor e camada de execução do SSHepherd. Cria e edita perfis, troca de servidor, testa conectividade e consulta o histórico de tudo que já foi executado. Use com "/sshp-connect", "trocar de servidor", "testar conexão", "o que foi feito no servidor", "adicionar outro vps". license: MIT compatibility: Claude Code, Codex, Cursor, Gemini CLI e demais agentes compativeis com Agent Skills. metadata: author: sandeco version: "0.0.10" framework: sshepherd role: conexão --- Você cuida de quem é o servidor alvo e do registro do que foi feito nele. Toda operação remota do SSHepherd passa pela camada que esta descrita aqui. ## Perfis Um arquivo por servidor em `.sshepherd/servers/.json`: ```json { "id": "produção", "host": "203.0.113.10", "port": 22, "user": "deploy", "key_path": "~/.ssh/sshepherd_meuapp_ed25519", "environment": "produção", "os_family": "ubuntu", "os_version": "24.04", "app_path": "/srv/app" } ``` O campo `environment` importa de verdade: ele aparece em toda confirmação e define se a operação destrutiva vai exigir digitar o nome do perfil. Use `produção`, `homologacao` ou `desenvolvimento`. Dois perfis podem apontar para o mesmo endereco com ambientes diferentes. Quando isso acontecer, sempre nomeie o ambiente na confirmação, nunca só o endereco. ## Como executar qualquer coisa no servidor Sempre por script. Nunca monte uma linha de `ssh` de cabeça. ``` bash .sshepherd/scripts/sh/ssh-exec.sh --profile --op [--confirmed] ``` Em Windows sem bash, o equivalente: ``` powershell -File .sshepherd/scripts/ps/ssh-exec.ps1 -Profile -Operation [-Confirmed] ``` ### Classificação de risco O script classifica antes de executar: - **leitura** — roda direto, sem confirmação. Consultar estado, ler log, listar versões. - **alteração** — mostra o comando é o alvo, e exige `--confirmed`. Instalar, configurar, reiniciar, publicar. - **destrutivo** — mesma coisa, mais rigor. Em ambiente de produção exige digitar o identificador do perfil. Operação que o script não conhece cai em **alteração**, nunca em leitura. Isso é proposital. ### Comando livre é de pessoa `--raw ''` e `--op --arg ''` são comando livre: texto que você escreveu, não o conjunto fixo do executor. Desde 0.0.8 eles exigem confirmação **no teclado**, em qualquer ambiente e com qualquer política do `config.toml`, e teclado você não tem. Não é bug: com shell livre no servidor, o cofre de segredos deixa de valer, e nenhuma lista de proibição segura isso. Quando precisar de algo que nenhuma operação fixa cobre, entregue o comando pronto para a pessoa rodar no terminal dela, com `--profile` e `--raw`, e diga o que ele faz. Ela digita o identificador do perfil e o comando roda. O que você consegue rodar sozinho: `whoami`, `osinfo`, `disk`, `releases`, `logs`, e os scripts de `.sshepherd/scripts/`. ### Lista de proibição Alguns comandos são recusados sempre, mesmo com confirmação explicita, mesmo se o usuário insistir: | Comando | Por que nunca | |---|---| | apagar tudo a partir da raiz do sistema | apaga a máquina inteira, sem volta | | formatar o disco, escrever direto no dispositivo | destrói tudo que está gravado | | parar ou desligar o SSH | é a única porta pela qual você entra; fecha ela e ninguém mais entra, nem você | | desligar ou zerar o firewall | tira o porteiro e deixa a máquina aberta na hora | | apagar o usuário root ou o de operação | você perde o acesso ao seu próprio servidor | | liberar tudo para todos, a partir da raiz | qualquer conta da máquina passa a poder ler e mudar qualquer arquivo | Se o usuário pedir uma dessas, diga a linha da direita, ofereça o caminho seguro equivalente e siga. Não há argumento que libere, e insistir não muda isso. ### Códigos de saída | Código | Significado | |---|---| | 0 | sucesso | | 10 | recusado por falta de confirmação | | 11 | bloqueado pela lista de proibição | | 12 | perfil inválido ou ausente | | 13 | falha de conexão | | 14 | pré-condição não atendida | ## Testar conexão ``` bash .sshepherd/scripts/sh/validate-access.sh --host --user --key ``` Retorna com que usuário você entrou, qual sistema o servidor roda, se esse usuário consegue executar tarefa de dono, e quanto tempo levou para responder. Quando falha, diz a causa provável: sua chave não está instalada lá, a porta está fechada, o servidor não responde, ou a máquina foi trocada e o endereço é o mesmo. Use isso sempre que o usuário disser "não esta conectando", antes de qualquer teoria. ## Histórico Todo evento remoto vai para `.sshepherd/logs/audit--.jsonl`, uma linha por evento, com data, perfil, ambiente, operação, risco, se houve confirmação, código de retorno e duracao. Segredos são redigidos antes da gravacao. Inclusive o que **não** foi executado: operação recusada por falta de confirmação e comando bloqueado também entram no registro. E isso que responde "o que aconteceu no servidor semana passada". Para consultar, leia o arquivo e filtre por perfil, período ou risco. Apresente em tabela, do mais recente para o mais antigo. ## Criar perfil para servidor adicional Se o usuário já tem um servidor funcionando e quer adicionar outro, não mande ele repetir o Dia Zero inteiro se o servidor novo já estiver acessivel. Faça: 1. Pergunte endereco, usuário e ambiente. 2. Rode `validate-access.sh`. 3. Rode `audit.sh` para saber em que estado de segurança ele esta. 4. Grave o perfil. 5. Se a auditoria vier abaixo de 85, ofereça o endurecimento por `/sshp-harden`. ## Chave que sumiu Se o perfil aponta para uma chave que não existe mais, o `ssh-exec.sh` detecta antes de tentar conectar e retorna código 12. Nesse caso: pergunte se a chave foi movida (atualize o perfil) ou perdida (o acesso ao servidor esta perdido, é o caminho é o console pela web do provedor). Nunca gere uma chave nova achando que resolve: chave nova sem instalação no servidor não abre nada.