Helpers SSH stateless para fluxos de agentes de IA mais seguros

Agentes autônomos de programação não devem carregar uma sessão SSH de uma execução para a seguinte. Um contexto de execução local novo para cada ação dificulta que uma execução anterior empreste autoridade, identidade ou efeitos colaterais inexplicados para uma execução posterior. Isso também oferece aos revisores uma unidade de evidência clara: este processo solicitou este comando para este host, e o helper devolveu este resultado.

Isso não torna o SSH inofensivo. Uma conexão nova não desfaz uma implantação, não interrompe um processo em segundo plano nem protege uma conta de servidor com acesso excessivo. A execução stateless resolve um problema mais específico e muito prático: remove a herança local que os agentes, por acidente, exploram com facilidade.

Helpers SSH stateless removem a herança local, não o estado remoto

Um helper SSH stateless cria a conexão necessária para uma ação, executa essa ação, devolve o resultado e sai sem preservar um transporte autenticado para chamadas posteriores. A ação seguinte começa novamente com um processo helper novo e uma nova tentativa de conexão.

A diferença é importante porque muitas pessoas dizem «SSH stateless» quando querem dizer «nada persiste em lugar algum». Isso é falso. O SSH tem vários pontos onde o estado pode permanecer:

• O cliente pode manter uma conexão mestre, um socket de multiplexação, uma entrada de hosts conhecidos, um socket de agente, uma configuração ou arquivos temporários.
• O host remoto pode manter um diretório de trabalho, histórico do shell, artefato enviado, arquivo de bloqueio, processo de serviço, cache de pacotes e banco de dados alterado.
• O sistema de autorização pode manter uma conta, um certificado SSH, uma chave pública e permissões.

Um helper stateless trata da primeira categoria. Ele impede que uma chamada posterior do agente herde silenciosamente uma conexão ativa ou um contexto local de credenciais deixado por uma chamada anterior. O lado remoto continua sendo um computador real, com consequências reais.

Por isso, «conexão nova» é uma expressão operacional melhor que «servidor novo». O helper é novo. O servidor, não.

Suponha que um agente execute uma verificação de implantação e saia depois que um revisor rejeite sua próxima alteração proposta. Se a primeira execução deixou um socket de multiplexação, outro processo na mesma máquina pode se conectar a um canal já autenticado. O processo seguinte pulou um limite de segurança que os operadores imaginavam aplicar a cada execução. Com um helper stateless, esse segundo processo precisa solicitar uma nova ação e passar novamente pelo caminho de autorização esperado.

O benefício é em parte de segurança e em parte de diagnóstico. Quando um revisor de incidentes vê uma conexão compartilhada que durou horas, precisa reconstruir qual de vários processos a usou. Quando cada solicitação controla seu próprio ciclo de vida da conexão, o registro tem um início e um fim naturais.

O compartilhamento de conexões entra em conflito com a atribuição por execução

O OpenSSH oferece suporte deliberado ao compartilhamento de conexões. O manual de ssh_config descreve ControlMaster como uma opção que permite que várias sessões compartilhem uma única conexão de rede. ControlPersist pode manter a conexão mestre aberta em segundo plano depois que os clientes saem. Essas opções são úteis para um administrador que executa vários comandos em um terminal. Elas são um padrão ruim para execuções de agentes que precisam de autoridade e registros separados.

Considere esta configuração comum:

Host build-box
  HostName 10.0.0.24
  User deploy
  ControlMaster auto
  ControlPath ~/.ssh/cm-%r@%h:%p
  ControlPersist 15m

A primeira chamada SSH cria um socket mestre autenticado em ~/.ssh. Chamadas posteriores que conseguem acessar esse socket podem reutilizar sua conexão durante a janela de persistência de quinze minutos. Um processo de agente iniciado depois que o processo original sai pode parecer ter feito uma conexão independente em seu próprio registro, quando na verdade usou um transporte estabelecido anteriormente.

Isso cria quatro problemas distintos.

Primeiro, o significado da aprovação muda. Se uma pessoa aprovou um processo específico do agente para executar uma verificação, essa aprovação não deveria abranger automaticamente um processo novo que por acaso encontrou o mesmo socket.

Segundo, fica mais difícil analisar a identidade do destino no momento certo. A verificação do host pelo SSH ocorre quando a conexão mestre é formada. Os clientes posteriores herdam esse resultado. Um revisor que examina uma chamada posterior precisa localizar um evento de conexão mais antigo para saber qual verificação do host ocorreu.

Terceiro, os logs perdem uma relação simples entre uma solicitação e um transporte. Um log tradicional do servidor SSH pode registrar um login, enquanto os registros no nível da aplicação mostram muitos comandos. Os dois podem estar corretos, mas correlacioná-los dá trabalho justamente quando ninguém tem tempo sobrando.

Quarto, o próprio socket se torna um ativo. O OpenSSH alerta em ssh_config que qualquer pessoa capaz de acessar o socket de controle pode acessar a conexão. As permissões de arquivo ajudam, mas não fazem um canal autenticado compartilhado caber em um espaço de trabalho hostil ou simplesmente confuso.

Desative a multiplexação para chamadas que precisam de atribuição clara. Uma chamada direta pode tornar essa decisão explícita:

ssh -o ControlMaster=no -o ControlPath=none deploy@build-box 'id; hostname'

A saída esperada tem o formato do próprio comando, por exemplo:

uid=1004(deploy) gid=1004(deploy) groups=1004(deploy)
build-box

O comando prova apenas qual conta e qual host responderam. Ele não prova que a conta tinha direitos apropriados ou que a tarefa solicitada era segura. Ainda assim, oferece ao revisor uma ação para relacionar a uma tentativa de conexão.

Não confunda a ausência da linha ControlMaster com uma solução completa. Uma configuração global do SSH pode defini-la, um wrapper pode adicioná-la e um processo pode apontar ControlPath para um local inesperado. O limite de execução deve definir suas próprias opções de SSH, em vez de confiar nos dotfiles do repositório.

Cada execução do agente precisa de seu próprio limite de autoridade

Uma execução de agente não é uma sessão de terminal humana com um digitador mais rápido. Ela pode receber novas instruções de issues, pull requests, saídas de testes geradas, trechos de logs copiados e arquivos-fonte que não criou. Qualquer um desses conteúdos pode conduzi-la a comandos que não faziam parte da intenção original.

Isso muda o significado dos recursos de conveniência. Uma pessoa que mantém uma sessão normalmente sabe que está fazendo isso. Um agente pode iniciar uma tarefa posterior sem perceber que um canal antigo ainda está disponível. Sua interface de ferramenta muitas vezes mostra apenas «executar comando», enquanto o cliente subjacente encontra silenciosamente um socket e obtém a autoridade anterior.

Trate o processo do agente como a unidade que recebe aprovação. Quando ele sair, seu acesso deve terminar junto. Se um processo novo for iniciado, mesmo que pelo mesmo editor ou orquestrador, exija uma nova decisão de autorização antes que ele alcance um host protegido.

Essa abordagem é mais rígida do que muitos desenvolvedores desejam inicialmente. Eles veem aprovações repetidas e recorrem a uma lista de permissões ampla. Isso resolve um incômodo removendo o limite útil. Um design melhor reúne ações relacionadas em uma execução explícita, concede acesso depois que um revisor vê sua identidade e revoga o acesso quando a execução termina.

A identidade de assinatura de código é importante aqui, mas não responde a todas as perguntas. Ela pode dizer ao revisor qual programa assinado iniciou o processo. Não pode dizer se o programa está agindo com base em instruções confiáveis ou se o repositório atual contém um prompt malicioso. A aprovação deve vincular um processo conhecido a um período limitado de autoridade, não aprovar todas as instruções que esse processo vier a ler.

Um limite claro também trata as tentativas novamente da maneira correta. Uma falha de rede pode gerar uma nova solicitação. O gateway deve registrar que a primeira ação falhou antes da execução ou durante o transporte e depois registrar a tentativa novamente como outra ação. Juntar as tentativas em um único registro vago de sucesso remove informações necessárias para quem responde a incidentes.

O encaminhamento do agente derrota o limite de credenciais

O encaminhamento do agente SSH oferece a um host remoto um caminho para solicitar que seu agente de autenticação local assine desafios. Ele não copia o arquivo da chave privada para esse host, mas essa diferença pode parecer mais segura do que realmente é.

O manual do ssh do OpenSSH alerta que usuários capazes de contornar as permissões de arquivo no host remoto podem acessar o agente encaminhado. Um usuário root nesse host pode usar o socket encaminhado para autenticar-se em outro lugar enquanto a conexão permanecer aberta. Ele ainda não recebe o material da chave privada, mas pode usar a autoridade por trás dela. Para um agente autônomo, esse costuma ser exatamente o risco que você queria evitar.

Evite chamadas como:

ssh -A deploy@build-box 'git fetch && ./deploy.sh'

A opção -A encaminha o agente de autenticação local. Um script de implantação que alcança uma segunda máquina pode então fazer com que o host remoto solicite assinaturas pelo socket encaminhado. Uma máquina de build comprometida, ou um script alterado por um colaborador não confiável, ganha uma rota inesperada para outro ambiente.

Use uma credencial que pertença à tarefa no destino. Isso pode significar uma conta de implantação com uma chave pública restrita, um certificado SSH de curta duração emitido para um ambiente ou uma conta de serviço remota que só consiga buscar o artefato necessário. O mecanismo exato depende da sua infraestrutura. A disciplina não muda: não transforme a ação aprovada de um agente em acesso geral de autenticação a partir de uma máquina remota.

Algumas equipes mantêm o encaminhamento porque o SSH aninhado é conveniente. Elas têm um bastion host e depois avançam para hosts privados. Use ProxyJump ou uma rota de gateway controlada com rigor sempre que possível. Esses padrões mantêm o cliente no controle do estabelecimento da conexão, em vez de colocar um socket de agente local poderoso no host intermediário.

O encaminhamento de portas merece a mesma desconfiança. O encaminhamento local, remoto e dinâmico pode transformar um comando aprovado em um túnel aberto que continua existindo depois que seu trabalho útil termina. Um helper stateless deve rejeitar ou exigir aprovação separada para recursos de encaminhamento, a menos que a tarefa solicitada precise deles de forma específica.

Uma conta remota precisa limitar os danos de instruções ruins

O estado local novo não ajuda quando o login remoto pode fazer qualquer coisa. A conta alcançada pelo agente deve ter uma finalidade declarada e permissões compatíveis com ela.

Em um host de implantação, isso pode significar uma conta capaz de alternar um symlink de release, reiniciar um único serviço e ler um diretório de implantação. Ela também não deveria ter escalada de privilégios irrestrita sem senha, acesso ao diretório pessoal de todos os usuários e permissão para modificar o runner de CI. Essas combinações aparecem porque alguém queria fazer uma tarefa de automação funcionar antes do almoço. Elas permanecem porque ninguém volta para reduzi-las.

O OpenSSH oferece aos operadores de servidores vários controles no formato de authorized_keys. O manual documenta opções como command=, que força um comando quando a chave autentica, além de opções que desativam o encaminhamento de portas, o encaminhamento X11 e o encaminhamento do agente. Esses controles são úteis quando o destino tem uma superfície pequena e estável de comandos.

Por exemplo, uma equipe de operações pode associar uma chave pública dedicada a um wrapper remoto restrito:

command="/usr/local/libexec/release-action",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-ed25519 AAAA... agent-release

O comando forçado deve analisar os argumentos solicitados com cuidado. Não passe texto bruto do usuário para um shell. Um wrapper seguro aceita um pequeno conjunto de verbos, valida os identificadores de release conforme um formato esperado, grava um registro de auditoria e executa a operação fixa correspondente. Se o agente precisa de acesso arbitrário ao shell, reconheça isso abertamente e mantenha as permissões da conta estreitas o suficiente para esse risco.

Um comando forçado não é uma linguagem de políticas genérica. É uma interface deliberadamente pequena em um único host. Essa restrição é sua força. Você pode testá-la, revisá-la e identificar quais ações ela consegue executar sem interpretar um conjunto extenso de regras em linguagem natural.

Tenha cuidado com sudo. Uma linha que permite um script ainda pode se transformar em acesso amplo se o script aceitar caminhos arbitrários, carregar configurações de um diretório gravável, chamar um editor ou invocar outro programa por meio de uma variável de ambiente controlada pelo usuário. Leia toda a cadeia de chamadas. A linha de permissão é o início da revisão, não o fim.

O registro da ação deve responder quem, o quê, onde e qual foi o resultado

Um registro de auditoria útil faz mais que afirmar que o SSH aconteceu. Ele precisa permitir que uma pessoa reconstrua uma ação sem adivinhar qual execução do agente era responsável por ela.

Registre o identificador da execução do agente, sua autoridade de processo, a decisão do revisor, o destino, a conta remota, o comando ou operação solicitada, o horário, o resultado e uma referência à saída. Capture a identidade resolvida do host quando seu design puder expô-la. Registre também uma negação. Uma ação negada é evidência de que o limite funcionou como planejado e pode revelar uma instrução ruim antes que ocorram danos.

Os comandos exigem tratamento especial. O comando bruto pode conter senhas, tokens de acesso, valores de consultas e caminhos privados. Ocultar tudo torna o registro inútil, enquanto manter tudo pode transformar o log em outro cofre de segredos. A resposta prática é criar a interface da ação de modo que valores sensíveis não apareçam nos argumentos desde o começo. Quando a ocultação for necessária, registre tanto o evento de ocultação quanto contexto estruturado suficiente para identificar a operação.

A saída tem o mesmo problema. Um erro de um comando de implantação pode imprimir uma variável de ambiente ou uma URL com credenciais. Mantenha a saída separada do registro principal do evento, limite quem pode lê-la e trate-a como uma entrada potencialmente sensível para a próxima execução do agente. Não devolva automaticamente uma transcrição completa de produção a um agente só porque ele pediu ajuda para diagnosticar uma falha.

Há outra distinção que vale a pena manter clara: um log que diz que um agente solicitou uma ação é diferente de um log que prova que a ação chegou ao host remoto. Falhas de transporte, rejeição da chave do host, falha na autenticação remota, status de saída do comando e conexões perdidas são resultados distintos. Um bom registro dá a cada resultado seu próprio status, em vez de colocar todos sob «falhou».

A evidência de adulteração muda o modelo de confiança do registro. Um log encadeado por hashes pode mostrar que entradas foram alteradas, removidas ou reordenadas quando a verificação falha. Ele não pode dizer que o comando original era sensato nem tornar verdadeiro um endpoint comprometido. Ele protege o histórico que você tem, mas não substitui o reforço da segurança do sistema.

Uma implantação malsucedida mostra por que o estado novo ajuda

Imagine que um agente de programação receba uma solicitação para implantar uma branch em um host de staging. Na primeira chamada, ele abre uma conexão SSH, verifica o espaço em disco e inicia um comando de release. O comando falha porque existe um bloqueio de migração. O agente vê a falha, lê as notas do repositório e recebe uma mensagem copiada dizendo para «limpar o bloqueio e tentar novamente com a conta de emergência».

Essa mensagem pode ser uma sugestão inocente, porém insegura, ou pode ser uma injeção de prompt escondida em um arquivo que o agente foi instruído a inspecionar. De qualquer forma, agora o agente propõe um comando fora da rotina de implantação original.

Com uma conexão compartilhada de longa duração, várias coisas podem dar errado. O transporte original ainda pode autenticar como uma conta de implantação ampla. Um processo novo pode reutilizá-lo. O revisor vê apenas a primeira aprovação da conexão e talvez não perceba claramente a escalada posterior. Se a configuração também encaminhava um agente SSH, o host de staging pode ter uma maneira de usar outra identidade.

Com um helper stateless e autorização por execução, a próxima chamada do agente começa como uma nova solicitação. O limite identifica o novo processo do agente, registra o comando e o destino realmente propostos e pede aprovação se a execução ainda não estiver aprovada. Um revisor pode rejeitar a solicitação da conta de emergência e aprovar, em seu lugar, uma operação restrita que inspecione o proprietário do bloqueio.

A conexão nova não decidiu que apagar um bloqueio era inseguro. As pessoas ainda precisam avaliar as operações. Ela impediu que um canal antigo e aprovado tornasse essa decisão irrelevante em silêncio.

É por isso que um design SSH stateless deve estar ao lado de restrições sensatas de comandos, não no lugar delas. O isolamento da conexão limita a autoridade local herdada. Uma interface remota restrita limita o que uma conexão nova pode fazer. Os registros de auditoria permitem que as pessoas entendam as duas decisões mais tarde.

A execução stateless precisa de um design operacional explícito

Um helper que abre uma conexão para cada solicitação precisa ter um comportamento claro para verificação de hosts, tempos limite, cancelamento e comunicação de falhas. Deixar esses detalhes a cargo do que o ambiente do agente oferecer por acaso recria o estado oculto com outro nome.

Verifique as chaves dos hosts. StrictHostKeyChecking=yes do OpenSSH instrui o cliente a rejeitar hosts cuja chave seja desconhecida ou tenha mudado, em vez de perguntar interativamente. Essa costuma ser a postura correta para uma ação automatizada protegida. Provisione chaves confiáveis de hosts por meio de um processo controlado e depois falhe de forma segura se o destino não corresponder.

Use tempos limite definidos. Uma conexão SSH travada deve eventualmente devolver uma falha registrada, não permanecer disponível indefinidamente como uma sessão parcialmente concluída. O helper também deve encerrar processos filhos quando houver cancelamento, sempre que o sistema operacional permitir, e informar se consegue confirmar esse encerramento. Não informe que um comando remoto foi cancelado quando o transporte caiu depois que o servidor já o havia iniciado.

Mantenha o formato da solicitação pequeno e fácil de inspecionar. Um limite de ação pode representar uma solicitação SSH com campos estruturados como destino, conta, comando, diretório de trabalho quando houver suporte e tempo limite. Ele não deve aceitar um bloco de configuração do shell que altere arquivos de identidade, comportamento do proxy, caminhos de sockets de controle e opções de encaminhamento sem revisão.

Um gateway pode guardar a credencial SSH enquanto o agente solicita uma ação. O Sallyport segue esse modelo para SSH por meio do helper stateless integrado sp-ssh: o agente não recebe a chave SSH, e o app executa a ação.

O limite também deve distinguir uma aprovação de sessão de uma aprovação por chamada. A aprovação de sessão é adequada para uma execução de agente delimitada, em que um revisor aceita uma sequência de trabalhos esperados. A aprovação por chamada é adequada para credenciais ou destinos em que cada uso merece uma decisão humana separada. Não finja que essas escolhas oferecem o mesmo controle. Elas trocam deliberadamente interrupção por granularidade.

Teste a reutilização oculta antes de confiar no limite

Você pode testar se sua configuração realmente cria conexões independentes. Faça isso em um ambiente que não seja de produção, com uma conta sem acesso sensível.

Primeiro, inicie dois processos separados de agente ou helper, cada um executando um comando inofensivo como id. Verifique o log de autenticação do servidor SSH e seu log de ações. Você deve ver duas tentativas de conexão que possam ser associadas a dois registros de processo separados.

Depois, procure sockets de multiplexação no lado do cliente. Em sistemas macOS e semelhantes ao Linux, uma inspeção ampla pode ser assim:

find ~/.ssh -type s -print

Se aparecer um caminho correspondente a um socket de controle, identifique qual configuração o criou. Não exclua um socket às cegas em uma máquina compartilhada; primeiro descubra o proprietário e os clientes ativos. Remova as configurações de compartilhamento de conexões do caminho de execução do helper isolado, em vez de depender da limpeza posterior.

Por fim, execute uma ação aprovada, encerre o processo do agente e inicie um segundo processo. O segundo processo não deve herdar a autorização, o transporte de autenticação ou a capacidade de invocar um shell remoto do primeiro processo sem uma nova decisão. Teste o caminho negado com o mesmo cuidado que o caminho aprovado. As equipes frequentemente descobrem que o caminho normal está isolado, mas um manipulador de erros recorre a um comando SSH direto.

Essa última verificação detecta a falha conhecida: um gateway cuidadoso trata as solicitações normais, mas um script de nova tentativa ou uma ferramenta de diagnóstico o ignora quando a pressão aumenta. O desvio costuma ser criado por alguém tentando restaurar o serviço rapidamente. Depois, ele se torna a rota que um agente encontra quando sua primeira tentativa falha.

O estado novo para cada ação SSH não é uma formalidade. Ele oferece ao trabalho autônomo um limite que as pessoas podem inspecionar, aprovar, revogar e investigar. Mantenha a conta remota restrita, recuse credenciais encaminhadas, registre os resultados com precisão e faça com que cada novo processo de agente conquiste seu próprio acesso.