sshroute

CI	Codice	OpenSpec	Sicurezza

Router SSH consapevole della rete. Rileva la rete attiva o la VPN e seleziona automaticamente l'host, la porta, il file di identità e il jump host corretti per ogni connessione SSH, senza toccare ~/.ssh/config.

Come funziona

Definisci ogni host logico una volta con un profilo default e override opzionali per rete. Ad ogni connessione, sshroute rileva su quale rete ti trovi (VPN, LAN ufficio, peer WireGuard, ecc.) e risolve i parametri SSH corretti prima di passare il controllo al vero /usr/bin/ssh.

ssh myserver
  → sshroute rileva: corp-vpn è attiva
  → risolve: 10.100.0.50:2222 tramite bastion.corp.internal
  → exec /usr/bin/ssh -p 2222 -i ~/.ssh/corp_key -J bastion.corp.internal 10.100.0.50

Perché sshroute?

Per gli appassionati di homelab

Il tuo laboratorio ha probabilmente almeno due realtà: sei a casa sulla LAN, oppure sei fuori e ti connetti tramite WireGuard o un'altra VPN. Il problema è che ~/.ssh/config non sa in quale ti trovi — così ti ritrovi con alias separati (server-lan, server-vpn), o un jump host che funziona solo a metà, o semplicemente memorizzi gli IP.

sshroute risolve questo problema rilevando la rete corrente prima di ogni connessione. Quando l'interfaccia WireGuard è attiva e la route del peer esiste, si connette direttamente all'IP del tunnel. Quando sei sulla LAN, usa l'indirizzo locale. Quando nessuno dei due è raggiungibile, ricade sul nome host pubblico. Un alias, tre realtà, nessuna commutazione manuale.

Intercetta anche SSH in modo trasparente — git push, rsync, scp passano tutti attraverso automaticamente una volta impostata la modalità shadow. Nessun wrapper, nessuna funzione di shell, nessun pensiero.

Per ambienti aziendali

Le reti aziendali sono peggio. Hai Internet pubblico, forse una VPN site-to-site, forse una VPN personale split-tunnel, e all'interno di questa diversi jump host a seconda dell'ambiente che stai targetizzando — dev, staging, prod, ciascuno con il proprio bastion e la propria chiave. Mantenere tutto in ordine in ~/.ssh/config significa o un file enorme che si rompe ogni volta che l'infrastruttura cambia, o scrivere uno script che ogni membro del team mantiene in modo diverso.

sshroute ti permette di definire la logica di routing in modo dichiarativo, mantenerla in un file YAML con versionamento e condividerla con il team. La stessa configurazione funziona per tutti — la rete giusta viene rilevata automaticamente in base alle interfacce o route attive su ciascuna macchina. Chiavi, porte, utenti e jump host vengono risolti senza che l'utente debba pensarci.

Confronto

Teleport e Boundary sono una categoria diversa — aggiungono controllo degli accessi, log di audit e autenticazione basata su certificati oltre al routing. Se è ciò di cui hai bisogno, usali. sshroute è per quando vuoi l'intelligenza di routing senza il sovraccarico operativo di gestire un server di autenticazione centrale.

Installazione

Download binario

Scarica l'ultima release da GitHub Releases. I binari sono disponibili per Linux, macOS e Android su AMD64 e ARM64.

Installazione con Go

go install github.com/thereisnotime/sshroute@latest

Android (Termux)

Scarica il tarball android_arm64 da GitHub Releases, estrailo e posiziona il binario in ~/.local/bin:

mkdir -p ~/.local/bin
curl -Lo "$TMPDIR/sshroute.tar.gz" \
  https://github.com/thereisnotime/sshroute/releases/latest/download/sshroute_android_arm64.tar.gz
tar -xzf "$TMPDIR/sshroute.tar.gz" -C ~/.local/bin sshroute
chmod +x ~/.local/bin/sshroute

Aggiungi ~/.local/bin al tuo PATH in ~/.bashrc o ~/.profile se non lo è già:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

In alternativa, compila dal sorgente con Go di Termux. Poiché la toolchain ufficiale di Go non pubblica binari android/arm64, imposta GOTOOLCHAIN=local per usare ciò che Termux fornisce:

GOTOOLCHAIN=local go install github.com/thereisnotime/sshroute@latest

Dopo l'installazione, imposta il percorso del binario SSH poiché Termux non ha /usr/bin/ssh:

# ~/.config/sshroute/config.yaml
ssh_binary: /data/data/com.termux/files/usr/bin/ssh

Oppure tramite variabile d'ambiente: export SSHROUTE_SSH=$(which ssh)

Docker

docker run --rm -v ~/.config/sshroute:/root/.config/sshroute \
  ghcr.io/thereisnotime/sshroute network

Podman

podman run --rm -v ~/.config/sshroute:/root/.config/sshroute \
  ghcr.io/thereisnotime/sshroute network

Su sistemi con SELinux abilitato (Fedora, RHEL, ecc.) aggiungi :Z al flag del volume:

podman run --rm -v ~/.config/sshroute:/root/.config/sshroute:Z \
  ghcr.io/thereisnotime/sshroute network

Modalità shadow (sostituzione SSH trasparente)

Installa sshroute come ssh prima nel tuo $PATH. Tutte le chiamate SSH — dal terminale, da git, rsync, scp — vengono intercettate automaticamente. Gli host non presenti nella tua configurazione passano a /usr/bin/ssh invariati.

mkdir -p ~/.local/bin
ln -s $(which sshroute) ~/.local/bin/ssh

# Aggiungi a ~/.bashrc o ~/.zshrc se non già presente:
export PATH="$HOME/.local/bin:$PATH"

Avvio rapido

# Aggiungi un host con un profilo predefinito
sshroute add myserver --host myserver.example.com --user alice --key ~/.ssh/id_ed25519

# Aggiungi un override specifico per VPN
sshroute add myserver --network vpn --host 10.8.0.50 --port 2222 --jump bastion.vpn

# Connettiti — la rete viene rilevata automaticamente
sshroute connect myserver

# Anteprima del comando risolto senza eseguirlo
sshroute connect myserver --dry-run

# Vedi quale rete è attualmente attiva
sshroute network

Comandi

Flag globali

Questi flag si applicano a ogni comando:

init

Crea un file di configurazione iniziale con esempi commentati. Fallisce se il file esiste già.

connect <alias>

Rileva la rete attiva, risolve i parametri SSH per alias ed esegue il vero binario SSH. Eventuali argomenti extra dopo l'alias vengono passati a SSH invariati.

Con --reconnect, sshroute mantiene ssh vivo attraverso cadute di connessione (sospensione del laptop, handoff WiFi, roaming tra reti). Poiché rileva la rete a ogni riconnessione, ti segue su una route diversa: ad esempio, dormire sulla LAN e svegliarsi su un hotspot si riconnette tramite la route pubblica invece di ritentare l'indirizzo LAN ora irraggiungibile. Un logout pulito (exit 0) o un fallimento di autenticazione/comando remoto ferma il ciclo; solo le cadute genuine di connessione provocano la riconnessione. Riconnetti esegue ssh come sottoprocesso (come --fallback), quindi sshroute rimane residente per la sessione; SIGINT/SIGTERM lo abbatte. Lo stato della sessione attraverso il breve intervallo è compito del tuo multiplexer (tmux/zellij); combina --reconnect con -- tmux attach o -- zellij attach -c <nome> per tornare direttamente nella tua sessione:

sshroute connect myserver --reconnect --fallback -- zellij attach -c lavoro

list

Elenca tutti gli host configurati e i parametri SSH che verrebbero utilizzati sulla rete corrente. Supporta -o table|json|yaml.

add <alias>

Aggiunge un host o ne aggiorna uno esistente. I flag omessi mantengono il loro valore corrente. Esegui più volte con diversi valori --network per creare override per rete.

remove <alias>

Rimuove tutti i profili per alias dalla configurazione.

network

Stampa il nome della rete attualmente rilevata (o default se nessuna corrisponde).

network list

Elenca tutte le reti configurate con la loro priorità, regole di controllo e stato attuale. Supporta -o table|json|yaml.

network test <nome>

Esegue ogni controllo per la rete nome e stampa superato/fallito per ogni regola. Utile per il debug della logica di rilevamento.

config

Stampa il percorso risolto del file di configurazione.

config edit

Apre il file di configurazione in $EDITOR (ricade su nano). Crea il file e la directory padre se non esistono.

resolve <alias>

Stampa i parametri SSH che verrebbero utilizzati per alias sulla rete corrente. Utile per debug e scripting. Usa --network <nome> per sovrascrivere la rete rilevata. Supporta -o table|json|yaml.

copy <alias> <src> <dst>

Copia file da o verso un host configurato usando scp con gli stessi parametri risolti (chiave, porta, jump) di connect. Usa la sintassi <alias>:<percorso> per i percorsi remoti:

sshroute copy myserver ./local.txt myserver:/percorso/remoto/
sshroute copy myserver myserver:/file_remoto.txt ./locale/

La variabile d'ambiente SSHROUTE_SCP sovrascrive il binario scp utilizzato.

version

Stampa la versione, il commit git, la data di build e le informazioni sul runtime Go.

update

Aggiorna sshroute sul posto all'ultima release di GitHub. Scarica l'archivio per la tua piattaforma, verifica il suo sha256 rispetto a checksums.txt e, se cosign è installato, verifica la firma cosign della release, prima di sostituire atomicamente il binario in esecuzione.

sshroute update            # scarica, verifica e installa l'ultima release
sshroute update --check    # segnala solo se è disponibile una versione più recente
sshroute update --force    # reinstalla l'ultima anche se già attuale

Se la verifica sha256 (o cosign, quando presente) fallisce, l'aggiornamento viene annullato e il binario rimane intatto. Questo è destinato alle installazioni del binario di release; se hai installato tramite go install o un gestore di pacchetti, aggiorna con quello.

File di configurazione

Posizione predefinita: ~/.config/sshroute/config.yaml

networks:
  corp-vpn:
    priority: 10          # inferiore = controllato per primo
    checks:
      - type: interface
        match: wg0
      - type: route
        match: 10.100.0.0

  office:
    priority: 20
    checks:
      - type: ping
        host: 192.168.1.1
        timeout: 500ms

hosts:
  myserver:
    default:              # richiesto — usato quando nessuna rete corrisponde
      host: myserver.example.com
      port: 22
      user: alice
      key: ~/.ssh/id_ed25519
      options:            # opzionale — passato come flag SSH -o Key=Value
        ConnectTimeout: "10"
        ServerAliveInterval: "30"
    corp-vpn:
      host: 10.100.0.50
      port: 2222
      key: ~/.ssh/corp_key
      jump: bastion.corp.internal
      options:
        ConnectTimeout: "5"   # sovrascrive il default solo per questa rete
    office:
      host: 192.168.1.50

Ogni host deve avere un profilo default. I profili di rete devono solo specificare i campi che differiscono dal default — i campi non impostati ereditano da default.

Campi del profilo host

Le chiavi di options vengono unite dal default nei profili di rete — i valori di rete sovrascrivono le chiavi corrispondenti, le chiavi non sovrapposte vengono ereditate.

Rilevamento rete

Le reti vengono valutate in ordine di priority (valore più basso per primo). L'ordine alfabetico rompe i pareggi. Viene utilizzata la prima rete i cui controlli passano tutti; se nessuna corrisponde, viene applicato default.

Più controlli all'interno di una definizione di rete utilizzano logica AND — tutti devono passare.

Esempi

I file di configurazione pronti all'uso sono in examples/:

Documentazione

Guide approfondite sono in docs/:

Formati di output

Tutti i comandi di elenco supportano più formati di output:

sshroute list                  # table (default)
sshroute list -o json          # JSON — per scripting
sshroute list -o yaml          # YAML
sshroute network list -o json

Community

Ottieni il software — scarica un binario precompilato da Releases, installa con go install github.com/thereisnotime/sshroute@latest, o compila dal sorgente.

Feedback e segnalazioni di bug — apri un issue su GitHub Issues. Usa il template per segnalazione bug per comportamenti imprevisti e il template per richiesta funzionalità per idee.

Contribuire — vedi CONTRIBUTING.md per come impostare il progetto, eseguire i test e aprire una pull request. Le vulnerabilità di sicurezza devono essere segnalate privatamente tramite GitHub Security Advisories.

Compilazione dal sorgente

Richiede Go 1.22+ e just.

git clone [email protected]:thereisnotime/sshroute.git
cd sshroute

just build        # output in bin/sshroute
just build-all    # cross-compila linux/darwin × amd64/arm64
just test         # esegue i test con rilevatore di race condition
just install      # go install con ldflags di versione iniettati