Encaminhamento de portas SSH para agentes autônomos: túneis mais seguros

O encaminhamento de portas SSH para agentes autônomos exige um desenho mais rigoroso do que o acesso comum de desenvolvedores. Um túnel pode transformar um banco de dados disponível apenas em localhost, um painel administrativo ou um serviço de staging em algo que o agente consegue acessar com um único comando SSH. Se o agente possui credenciais SSH amplas, o túnel é apenas um dos sintomas. A falha real é que ninguém restringiu o destino, a duração ou a autoridade por trás desse comando.

Já vi equipes chamarem um túnel de «temporário» porque alguém digitou ssh -L em um terminal. Depois, o terminal continuou ativo por dias, a porta virou dependência de outro processo e a pessoa que o abriu estava indisponível quando a segurança perguntou por que um serviço próximo da produção tinha um listener sem explicação. O trabalho autônomo piora esse padrão, pois o agente pode repetir tentativas, reconectar e usar um túnel de forma muito mais constante do que uma pessoa distraída.

A abordagem segura é simples: dê ao agente um caminho de conexão com escopo restrito, aprove uma exposição temporária específica, registre contexto suficiente para reconstruí-la depois e faça do encerramento um evento obrigatório, não uma intenção.

Um túnel muda o alcance da rede, não apenas o comportamento do SSH

Um encaminhamento de porta SSH cria um listener de um lado da conexão SSH e transporta o tráfego até um destino acessível do outro lado. Esse listener é um caminho de acesso. Analisá-lo apenas como «acesso SSH» deixa de fora a parte que cria o risco: quem pode se conectar, onde o tráfego termina e o que pode passar por ele.

Considere um agente executado em um host de build que precisa consultar db-admin.internal.example na porta 5432. Um encaminhamento local pode fazer esse serviço aparecer como 127.0.0.1:15432 no host de build. O banco continua privado na internet pública, mas todo processo nesse host que consiga alcançar o listener pode tentar uma conexão. O servidor SSH também se torna uma rota autorizada até o banco.

Isso pode ser aceitável. Não equivale a permitir que o agente «use SSH para manutenção». A aprovação deve descrever esta rota exata:

• carga de trabalho e host que iniciam a conexão
• endereço e porta do listener
• host e porta de destino
• motivo da rota
• expiração e pessoa aprovadora

Um encaminhamento remoto inverte a localização do listener. Se um agente se conecta a um bastion e pede que o bastion escute na porta 18080, um processo que alcance esse listener pode receber tráfego de volta para o host do agente. O encaminhamento remoto costuma surpreender as equipes porque pode expor um serviço atrás de um firewall sem abrir uma regra de entrada nesse firewall.

O OpenSSH documenta esses modos separadamente em ssh(1): -L cria encaminhamentos locais, -R cria encaminhamentos remotos e -D cria um proxy SOCKS. Essa separação é útil na operação. Não aprove «encaminhamento de portas» como uma permissão única e indiferenciada. Cada modo expõe um listener diferente e exige restrições próprias.

Os encaminhamentos local, remoto e dinâmico exigem decisões diferentes

Um encaminhamento local costuma atender a uma tarefa de agente quando ele precisa de um serviço conhecido por meio de um jump host controlado. O listener existe no lado do agente, e o servidor SSH se conecta ao destino interno. O formato do comando é familiar:

ssh -N \\
  -L 127.0.0.1:15432:db-admin.internal.example:5432 \\
  [email protected]

-N pede ao SSH que não execute um comando remoto. Isso não torna a conexão inofensiva. O endereço de vinculação 127.0.0.1 limita o listener ao host local, enquanto db-admin.internal.example:5432 declara o destino solicitado. São propriedades separadas e ambas devem aparecer no registro de aprovação.

Um encaminhamento remoto só é apropriado quando alguém escolheu explicitamente criar um listener no lado remoto. O comando abaixo pede que o bastion escute na própria interface de loopback e transporte o tráfego de volta para a porta 8080 da máquina do agente:

ssh -N \\
  -R 127.0.0.1:18080:127.0.0.1:8080 \\
  [email protected]

Não trate um listener remoto de loopback como automaticamente seguro. Um processo local no bastion pode ter muito mais acesso do que a máquina de origem do agente, e outro usuário em um bastion compartilhado pode alcançá-lo. Analise os usuários e os processos locais do host remoto antes de permiti-lo.

O encaminhamento dinâmico deve ser negado por padrão para agentes autônomos:

ssh -N -D 127.0.0.1:1080 [email protected]

Isso inicia um listener SOCKS. O cliente escolhe os destinos depois, por meio de solicitações SOCKS, em vez de nomear um destino no comando SSH. As equipes gostam desse recurso porque ele faz rapidamente uma interface web interna funcionar em um navegador ou harness de testes. Essa conveniência elimina o limite de destino necessário para o trabalho sem supervisão. Um revisor não consegue aprovar uma única rota, e as restrições comuns de destino do SSH não conseguem expressar uma lista de permissões útil para tráfego SOCKS arbitrário.

Não tente resolver isso com um formulário de aprovação mais longo. Negue o encaminhamento dinâmico à conta do agente. Se a tarefa precisa de vários destinos, defina cada encaminhamento separadamente ou coloque um proxy criado especificamente para isso na frente dos serviços, com autenticação e logs próprios.

O endereço de vinculação decide quem pode usar o listener

O endereço de vinculação faz parte da decisão de segurança porque determina quais máquinas podem se conectar ao listener do túnel. Um encaminhamento vinculado à interface de loopback e outro vinculado a todas as interfaces podem usar o mesmo destino e, ainda assim, criar exposições completamente diferentes.

Para um encaminhamento local, use um endereço de loopback explícito:

-L 127.0.0.1:15432:db-admin.internal.example:5432

Evite depender do padrão. O OpenSSH normalmente vincula encaminhamentos locais à interface de loopback quando o endereço é omitido, mas especificá-lo torna a revisão, os logs e a investigação de incidentes menos ambíguos. Também evita que uma alteração posterior na configuração do cliente mude silenciosamente o escopo do listener.

Esta é a versão perigosa:

-L 0.0.0.0:15432:db-admin.internal.example:5432

Ela expõe a porta 15432 em todas as interfaces IPv4 do host cliente. Qualquer host que consiga alcançar o cliente pode tentar usar o túnel. Um runner de build em uma sub-rede compartilhada pode virar uma ponte para um banco interno, embora o próprio banco aceite conexões apenas do bastion.

O IPv6 exige a mesma atenção. ::1 é loopback, enquanto :: escuta em todas as interfaces IPv6. Verifique as duas famílias de endereços. Já vi equipes confirmarem que 127.0.0.1 era seguro e descobrirem depois que a automação também havia aberto um listener IPv6 por um caminho de configuração separado.

Nos encaminhamentos remotos, o servidor SSH controla quais endereços de vinculação aceita. Em sshd_config, GatewayPorts afeta o comportamento do endereço de vinculação dos encaminhamentos remotos. O OpenSSH documenta que, por padrão, os encaminhamentos remotos são vinculados à interface de loopback, sujeitos ao endereço solicitado e à política do servidor. Mantenha GatewayPorts no, a menos que exista um motivo analisado para permitir listeners remotos mais amplos. GatewayPorts clientspecified dá controle demais aos clientes de uma conta de agente.

Depois de abrir um encaminhamento, inspecione o listener na máquina que o possui. No macOS ou Linux, esta é uma verificação local útil:

lsof -nP -iTCP:15432 -sTCP:LISTEN

A saída deve mostrar um processo ssh com um endereço como 127.0.0.1:15432 ou ::1:15432. Se mostrar *:15432, interrompa a tarefa e examine o comando e a configuração do cliente. Esse comando prova apenas o endereço do listener local. Não prova que a outra ponta está limitada ao destino pretendido.

Uma conta SSH dedicada deve expressar a rota permitida

Uma conta SSH dedicada com restrições no servidor é o limite mínimo razoável para túneis de agentes. Um arquivo de configuração do cliente não consegue impor nada contra um agente que pode alterar os próprios argumentos do comando. Coloque os limites no local em que o servidor SSH aceita a conexão.

Para uma conta de encaminhamento apenas local, comece com um bloco de correspondência como este em sshd_config:

Match User agent-db-tunnel
    PasswordAuthentication no
    KbdInteractiveAuthentication no
    PubkeyAuthentication yes
    PermitTTY no
    X11Forwarding no
    AllowAgentForwarding no
    AllowStreamLocalForwarding no
    AllowTcpForwarding local
    PermitOpen db-admin.internal.example:5432
    GatewayPorts no
    PermitUserEnvironment no

AllowTcpForwarding local permite encaminhamentos locais e nega encaminhamentos remotos. PermitOpen nomeia o destino que essa conta pode solicitar. A restrição importa porque, sem ela, um comando de encaminhamento local poderia apontar para qualquer host e porta alcançáveis a partir do bastion. Sem PermitOpen, um agente que precisa legitimamente do banco também pode solicitar um encaminhamento para uma API administrativa, um cache, um serviço de metadados ou outro servidor SSH.

Use nomes de host com cuidado. O servidor SSH resolve o host de destino, portanto o nome em PermitOpen precisa ser resolvido ali. Torne esse nome estável e pertencente à sua infraestrutura. Se um nome DNS puder mudar para endereços arbitrários, a configuração parecerá restrita enquanto o destino real muda por baixo dela. Um endereço IP pode ser mais claro para um appliance fixo, mas um nome de host funciona quando o controle do DNS interno e a propriedade do serviço são rigorosos.

O manual sshd_config(5) do OpenSSH descreve PermitOpen como uma restrição de destino no formato host:port. Ele não transforma a conta em um mecanismo de políticas. Faz uma tarefa precisa: rejeita uma solicitação de encaminhamento cujo destino não esteja listado. Mantenha o desenho da conta igualmente preciso.

Não dê um shell a essa conta porque «o agente não vai usá-lo». Remova a capacidade em vez de confiar nessa promessa. Uma conta dedicada deve existir para uma única função de conexão. Configure a chave pública autorizada com um comando forçado que encerre a sessão se a conta precisar de uma proteção adicional contra uso interativo, mas teste essa escolha com o encaminhamento no seu ambiente. Alguns padrões de comando forçado e wrappers interferem nas sessões SSH esperadas, e uma restrição quebrada costuma levar alguém a remover todo o bloco sob pressão de prazo.

Evite também o encaminhamento do agente. AllowAgentForwarding no impede que o servidor conectado peça ao agente SSH do lado cliente para assinar solicitações de autenticação. Uma conta de túnel SSH deve transportar tráfego, não virar um ponto de passagem para outros hosts.

Para um destino com dois serviços legítimos, liste duas entradas explícitas de PermitOpen. Não use um curinga nem substitua a conta por uma conta geral de bastion apenas para evitar criar mais uma conta. Uma conta adicional custa menos do que explicar por que um agente de código conseguia alcançar uma sub-rede interna inteira.

Temporário significa expiração obrigatória e encerramento correto

Um túnel só é temporário quando algo além de boas intenções o encerra. O próprio SSH mantém a conexão até que o cliente a feche, a rede falhe ou um timeout a interrompa. Um agente autônomo pode deixar um processo ativo depois que um teste termina, falha ou expira.

Dê a cada tarefa uma duração máxima fixa de sessão, fora do controle do agente. Um runner pode impor esse limite com timeout, quando disponível:

timeout 20m ssh -N \\
  -o ExitOnForwardFailure=yes \\
  -o ServerAliveInterval=30 \\
  -o ServerAliveCountMax=3 \\
  -L 127.0.0.1:15432:db-admin.internal.example:5432 \\
  [email protected]

ExitOnForwardFailure=yes impede que a tarefa prossiga quando o SSH não consegue criar o listener solicitado. Sem ele, o agente pode continuar e informar um erro confuso da aplicação em vez de uma falha na configuração do túnel. As configurações de keepalive fazem o SSH sair depois de respostas perdidas, o que ajuda quando uma máquina cliente perde a conectividade de rede silenciosamente. Elas não substituem o limite de 20 minutos.

O macOS não inclui o comando GNU timeout por padrão. Use o recurso de timeout do seu runner, um processo supervisionado com prazo ou um pequeno wrapper que envie TERM e confirme depois que o processo terminou. Não substitua um prazo ausente por um cron que mate «SSH antigo». Isso pode encerrar trabalhos não relacionados e impede provar qual conexão foi interrompida.

Exija que a própria tarefa feche o túnel em seu caminho de limpeza. Para um processo que ela iniciou, guarde o PID, envie TERM quando a tarefa terminar, aguarde brevemente e verifique se o listener desapareceu com lsof ou ss. O prazo captura falhas; o caminho de limpeza trata a conclusão normal.

O multiplexamento de conexões exige cuidado especial. Com ControlMaster e um ControlPath compartilhado, diferentes chamadas SSH podem reutilizar uma conexão mestre. Isso economiza tempo em uma sessão de terminal humana. No trabalho de agentes, porém, confunde propriedade e expiração: uma tarefa pode herdar uma conexão aprovada para outra, e fechar um cliente pode não fechar a conexão mestre. Desative o multiplexamento para a conta do túnel ou gere um caminho de controle exclusivo para cada tarefa aprovada.

Um fluxo de manutenção que precisa de acesso recorrente deve solicitar sessões recorrentes com limites separados. Não deixe um túnel aberto porque recriá-lo parece inconveniente. Os poucos segundos economizados na configuração se transformam em ambiguidade sempre que alguém investiga uma conexão inesperada.

Uma aprovação deve descrever a conexão que o revisor consegue reconstruir

Um registro de aprovação deve permitir que o revisor responda quem autorizou uma rota, o que a abriu e se ela permaneceu dentro do limite declarado. Um comentário genérico em um ticket, como «acesso do agente aprovado», não é evidência. Ele não identifica um listener, um destino ou uma duração.

Registre a aprovação antes de o túnel começar. Capture a identidade do aprovador humano, o timestamp, o identificador da tarefa ou execução, a identidade do processo do agente, a máquina de origem, a conta SSH dedicada e a impressão digital da chave pública. Depois, capture o encaminhamento solicitado por inteiro: direção, endereço de vinculação, porta do listener, host de destino, porta de destino, finalidade e expiração.

O registro do resultado precisa de seus próprios campos. Inclua se o SSH criou o encaminhamento, o identificador do processo cliente, o horário de início, o status final de saída, o horário de encerramento e o motivo do encerramento. Um timeout, uma limpeza normal, uma revogação pelo operador e uma falha de rede têm significados diferentes em uma revisão.

Use registros estruturados em vez de prosa que obrigue alguém a deduzir os campos. Este formato é suficiente para muitos sistemas internos:

{
  "run_id": "run-7c31",
  "approved_by": "oncall-engineer",
  "approved_at": "2025-04-12T14:03:00Z",
  "ssh_account": "agent-db-tunnel",
  "direction": "local",
  "listen": "127.0.0.1:15432",
  "destination": "db-admin.internal.example:5432",
  "expires_at": "2025-04-12T14:23:00Z",
  "purpose": "run migration compatibility check"
}

Os identificadores do exemplo são placeholders, não um esquema que você precise copiar exatamente. O que importa é a disciplina: um registro deve vincular uma pessoa, um processo, uma rota e uma janela de tempo.

Não permita que o próprio agente gere a aprovação e trate isso como autorização humana. O agente pode explicar por que deseja uma conexão, mas uma pessoa ou um fluxo governado separadamente deve decidir se ela será permitida. Se a ação for rotineira o bastante para aprovação automática, codifique essa decisão em uma definição de tarefa restrita, com expiração, e preserve a versão da regra que a autorizou.

A fadiga de aprovações é uma falha de design. Pedir que alguém aprove cada pacote cria cliques sem significado. Pedir uma aprovação por rota temporária e específica dá ao aprovador algo concreto para avaliar. Mantenha o pedido curto, mas inclua o endereço de vinculação e o destino exato. Essas duas strings identificam um número surpreendente de solicitações incorretas.

Mantenha as credenciais fora do agente e a autoridade fora do prompt

Um agente autônomo deve solicitar uma conexão, não receber uma chave privada capaz de criar conexões arbitrárias depois. Quando um agente tem uma chave SSH ampla no ambiente do processo ou no workspace, ele pode copiá-la, chamar outro cliente SSH, usá-la depois do fim da tarefa aprovada ou entregá-la a uma ferramenta que você não planejava confiar. Um prompt que diga «use isto apenas para o banco» não limita nenhuma dessas ações.

Um desenho melhor mantém as credenciais SSH em um limite de execução separado. O agente envia uma ação solicitada com os campos da rota. Esse limite verifica se o cofre está disponível, se a sessão tem autorização e se a credencial solicitada recebeu a aprovação necessária. Ele executa a ação SSH e devolve o resultado sem entregar a chave privada ao agente.

O Sallyport usa esse modelo no macOS: o helper sp-ssh incluído executa ações SSH enquanto as chaves permanecem no cofre criptografado do app, sem chegar ao agente MCP.

Essa distinção importa durante a análise de uma falha. A custódia da credencial responde: «O agente poderia reutilizar o segredo em outro lugar?» A restrição da rota responde: «Essa conta poderia alcançar um destino não aprovado?» A aprovação responde: «Quem permitiu esse uso específico?» As equipes costumam juntar tudo em um único controle e descobrem depois que o registro de auditoria diz que uma chave foi usada, mas não informa qual rota ela habilitou.

Torne a interface de solicitação mais restrita do que argumentos SSH brutos. Aceite campos como destination_host, destination_port, listen_address, listen_port e max_duration. Rejeite opções fornecidas pelo cliente que alterem proxying, direção do encaminhamento, execução de comandos remotos, arquivos de identidade ou sockets de controle. Se você aceitar uma string de comando ssh arbitrária, terá delegado a interpretação da política ao parsing de strings. Essa abordagem falha assim que alguém adiciona -R, -D, ProxyCommand ou um segundo encaminhamento.

Não exponha um shell geral como saída de emergência para um fluxo de túnel. O agente não precisa executar ssh interativamente quando a ação consiste em criar um canal restrito. Ações estreitas são mais fáceis de aprovar e revogar.

As evidências de auditoria devem sobreviver a uma revisão hostil

Os logs de túneis só são úteis se um agente comprometido ou um processo local não puder reescrevê-los depois. Logs de texto simples ao lado do workspace do agente são convenientes, mas provam muito pouco quando a mesma entidade pode editar tanto o comando do túnel quanto seu histórico.

Registre o evento de aprovação, o evento da solicitação, o resultado da execução e o resultado do encerramento como eventos separados, com um identificador de execução compartilhado. Preserve os campos originais da solicitação em vez de registrar apenas uma linha de comando renderizada. Uma linha de comando pode esconder valores em um arquivo de configuração ou omitir padrões que afetaram o listener.

Colete registros de confirmação de mais de um lugar. Os logs SSH do bastion podem mostrar autenticações aceitas e falhas de encaminhamento. O runner pode mostrar a criação e a saída do processo. O serviço de destino pode mostrar uma conexão originada no bastion. Nenhuma dessas fontes explica o evento inteiro sozinha, mas juntas revelam contradições.

Por exemplo, uma aprovação pode autorizar 127.0.0.1:15432 para um banco por 20 minutos. Se o log do cliente diz que ele foi encerrado às 14:23, mas o destino registra tráfego às 15:10 vindo do bastion, investigue imediatamente. O agente pode ter aberto outra conexão, reutilizado uma sessão mestre compartilhada ou alguém pode estar usando outro caminho com a mesma conta.

O Sallyport projeta os diários de sessões e chamadas individuais a partir de um log de auditoria criptografado e encadeado por hashes, e sp audit verify verifica essa cadeia offline sem exigir a chave do cofre. Essa é uma propriedade mais forte do que a de um arquivo de log que um processo do agente pode alterar, embora não substitua restrições fracas na conta.

Faça a verificação durante a revisão, não apenas depois de um incidente. Uma cadeia que evidencia adulteração informa se o histórico registrado mantém continuidade. Ela não informa se você registrou campos suficientes desde o início. Decida o que precisará saber em um dia difícil e garanta que esses campos entrem no evento antes de a conexão começar.

Revogue o caminho antes de investigar a história

Quando suspeitar de um túnel incorreto ou abusado, interrompa primeiro o caminho de conexão. A investigação pode esperar alguns minutos; uma rota exposta pode mover dados ou permitir acesso lateral enquanto as pessoas discutem qual log é confiável.

Encerre o processo cliente e confirme que o listener desapareceu. Desative a conta SSH dedicada ou remova sua chave pública no servidor que aceita a conexão. Se o serviço de destino usa uma credencial que passou pelo túnel e pode ter sido exposta a um processo não confiável, faça a rotação dessa credencial de acordo com o procedimento do serviço. Não faça a rotação de credenciais não relacionadas apenas porque existia um túnel.

Depois, preserve as evidências. Salve o registro de aprovação, a rota solicitada, os logs do processo, os logs do servidor SSH, os registros de conexão do serviço de destino e o resultado do encerramento. Registre os horários em um único fuso, de preferência UTC. As pessoas perdem horas em revisões de incidentes quando o runner usa horário local, o bastion usa UTC e uma aplicação grava timestamps sem fuso.

Verifique se existe um segundo listener antes de declarar o evento contido. No host do agente, examine a porta solicitada e os processos de encaminhamento próximos. No bastion, examine as sessões SSH ativas e os logs de autenticação da conta dedicada. No destino, procure conexões iniciadas depois da expiração prevista. O objetivo é encontrar caminhos de acesso que sobreviveram, não produzir rapidamente uma narrativa organizada.

Se uma aprovação humana habilitou a rota errada, corrija primeiro a interface de solicitação. Uma tela de revisão melhor que ainda aceite flags SSH arbitrárias reproduzirá o mesmo erro. Se uma restrição do servidor falhou, teste o comando exato que deveria ser rejeitado depois do reparo e preserve a saída da falha. Os controles ganham credibilidade quando você confirma que eles negam a rota que pretendia negar.

Teste os caminhos de negação antes de o agente depender do túnel

Um desenho de túnel só está pronto depois que você testa tanto a conexão aprovada quanto as variações proibidas. Testes do caminho feliz encontram erros de digitação. Testes de negação mostram se o limite realmente existe.

Use uma conta de não produção e tente um encaminhamento que deve funcionar:

ssh -N -o ExitOnForwardFailure=yes \\
  -L 127.0.0.1:15432:db-admin.internal.example:5432 \\
  [email protected]

Depois, tente um destino que PermitOpen não permite:

ssh -N -o ExitOnForwardFailure=yes \\
  -L 127.0.0.1:15433:admin-api.internal.example:443 \\
  [email protected]

O segundo comando deve falhar durante a configuração do encaminhamento. Capture a saída do cliente e a entrada correspondente no log do servidor. Em seguida, tente -R e -D; ambos devem falhar para uma conta configurada com AllowTcpForwarding local. Por fim, solicite um listener que não seja de loopback com 0.0.0.0 e confirme que o limite da solicitação o rejeita antes de o SSH ser executado ou que o ambiente local impede a exposição que você pretende evitar.

Teste a expiração com uma duração curta. Inicie o túnel aprovado, deixe o prazo do supervisor expirar e verifique três coisas: o processo SSH termina, lsof não encontra mais o listener e o registro de encerramento identifica o prazo, em vez de fingir que a tarefa terminou normalmente. Esse pequeno exercício encontra o problema de processos órfãos antes que o trabalho de produção dependa de um túnel que nunca fecha.

Mantenha uma regra simples quando a pressão aumentar: um agente autônomo pode receber a rota mínima necessária para a tarefa atual, por um tempo limitado e sob uma aprovação identificada. Se sua configuração não consegue declarar essa rota em uma linha e provar seu encerramento depois, o agente tem mais autoridade de rede do que a tarefa justifica.