Unnikked - Esperienze personali in campo informatico

ngrok – tunnel sicuri su localhost

ngrok è uno strumento che permette di aprire tunnel sulla rete per poter esporre un servizio installato sulla macchina locale su Internet.

Durante lo sviluppo di una applicazione web o tcp è necessario poterla provare per testarne le funzionalità o mostrarla ad un potenziale cliente, grazie ad ngrok non è necessario configurare firewall, inoltrare porte o altro, con un semplice comando si apre un tunnel ed il servizio viene esposto automaticamente su Internet.

ngrok è uno strumento open-source e disponibile in versione hosted online, tuttavia avendo disponibile i sorgenti è possibile creare una propria istanza privata dell’applicazione.

Sebbene sia disponibile la versione 2.0 dell’applicazione tratterò la versione 1.x poiché completamente open source.

Caratteristiche di ngrok

  • E’ possibile esporre qualsiasi servizio http dietro una rete NAT o firewall su Internet attraverso un sottodominio di ngrok.com
  • E’ possibile esporre qualsiasi servizio tcp dietro una NAT o firewall su Internet su una porta casuale di ngrok.com
  • E’ possibile ispezionare tutte le richieste/risposte http trasmesse sul tunnel
  • E’ possibile rispondere a qualsiasi richiesta che è stata trasmessa sul tunnell

ngork è utile per condividere temporaneamente un sito web che sta girando solamente sulla macchina locale di sviluppo, mostrare un’app in un contest senza distribuirla, distribuire qualsiasi servizio che consuma webhooks (callback HTTP), debug e studio di qualsiasi servizio web attraverso l’ispezione del traffico HTTP e l’esecuzione di servizi di rete su macchine che risiedono dietro un firewall.

Installazione ed utilizzo

ngrok è multipiattaforma, è disponibile per Linux, Windows, Mac OS X, FreeBSD e architettura Linux/ARM.

Una volta scaricato l’archivio .zip ed estratto, digitando:

./ngrok -help

verranno mostrate i comandi che è possibile impartire all’applicazione.

ngork-help

Esporre un webserver locale su Internet

Assumendo che abbiamo installato Apache, poiché il webserver opera sulla porta 80 bisogna digitare:

./ngrok 80

ngrok-apache

Dall’immagine si può notare che è stato creato il tunnel correttamente, è possibile accederlo sia tramite http che https.

Introspezione del traffico

ngork cattura tutto il traffico HTTP che vi passa attraverso e fornisce una interfaccia web in tempo reale dove è possibile visionare le richieste in dettaglio.

Una volta avviato ngork, aprendo http://localhost:4040 è possibile accedere a tale interfaccia.

Effettuando una richiesta al tunnel è possibile vedere le informazioni dettagliate riguardante la richiesta includendo il tempo, la durata, gli header, form e parametri della query e anche l’accesso ai byte grezzi inviati.

ngrok-instrospezione

Controllo di sintassi XML/JSON

ngrok ha uno speciale supporto per i formati dati di interscambio più comuni in uso sul web. Qualsiasi dato in formato JSON o XML viene automaticamente formattato e controllato per errori di sintassi.

ngrok-syntax-checking

Rispondere alle richieste

ngrok permette di rispondere a qualsiasi richiesta http fatta attraverso un tunnel.

ngrok-replay

Protezione del tunnel tramite password

Di default i tunnel creati non richiedono l’autenticazione attraverso username o password. Ciò significa che qualsiasi utente che conosce o può intuire l’URL del tunnel può fare richieste.

E’ possibile mettere in sicurezza il tunnel attraverso una username e password usando l’opzione -httpauth durante la creazione del tunnel.

Ciò forzerà l’utilizzo di credenziali di accesso ad ogni richiesta tramite l’autenticazione base HTTP.

ngrok -httpauth="unnikked:password" 80

Richiedere un sottodominio specifico

ngrok assegna un nome casuale in esadecimale come https://3a4bfceb.ngrok.com ai tunnel creati.

E’ possibile anche scegliere un nome personalizzato usando l’opzione -subdomain.

ngrok -subdomain=unnikked 80

Inoltro di servizi TCP

ngrok permette anche di esporre un servizio tcp su Internet. Utilizzando questa caratteristica gli strumenti di debug e introspezione saranno più primitivi poiché ngrok non sa come trattare questi dati.

ngrok -proto=tcp 22

Inoltro di servizi non locali

ngork può essere usato anche per inoltrare traffico a servizi dietro una NAT o firewall anche quando questi servizi non sono sulla stessa macchina.

ngrok 192.168.0.1:80

Il file di configurazione di ngrok

Il file di configurazione di ngork è opzionale e formattato usando il formato YAML e permette di usare caratteristiche più avanzate come:

  1. Avvio di più tunnel insieme.
  2. Connessione ad un server personale ngork.
  3. La configurazione di parametri particolari.
  4. Il file di configurazione è caricato di default da ~/.ngrok ma è possibile sovrascrivere il percorso tramite il parametro -config a linea di comando.

Avvio di più tunnel insieme

Per avviare più di un tunnel è necessario configurare ognuno nel file di configurazione usando i gli appropriati parametri.

I parametri dei tunnel richiedono un dizionario di nomi per la configurazione dei tunnel.

Per esempio, definiamo la configurazione di tre tunnel diversi: il primo sarà un tunnel per un sito in sviluppo che viene raggiunto solo tramite https e dispone di autenticazione, il secondo servirà per l’accesso remoto alla macchina tramite la porta 22 e infine l’ultimo tunnel servirà per mostrare i progetti personali.

tunnels:
  client:
    auth: "user:password"
    proto:
      https: 8080
  ssh:
    proto: 
      tcp: 22
  projects.unnikked.tk:
    proto:
      http: 9090

I tre tunnel definiti possono essere avviati simultaneamente usando il comando ngork start seguiti dai nomi dei tunnel da avviare:

ngrok start client ssh projects.unnikked.tk

Configurazione del tunnel

Ogni tunnel configurato può specificare cinque parametri: proto, subdomain, auth, hostname e remote_port.

Ogni tunnel deve avere il parametro proto definito che è un dizionario di protocolli per l’indirizzo di inoltro locale.

Il parametro auth è opzionale ed è usato per l’autenticazione dei tunnel http/https.

Il parametro remote_port è opzionale e server per legare sul server remoto la porta opzionale, è usato solo per i tunnel tcp.

ngork usa il nome del tunnel come sottodominio o hostname per il tunnel creato, ma può essere sovrascritto:

tunnels:
  client:
    subdomain: "esempio"
    auth: "unnikked:password"
    proto:
      https: 8080

Una volta avviato il client inoltrerà esempio.ngrok.com -> 127.0.0.1:8080.

Per i tunnel TCP si può richiedere una specifica porta dal server tramite il parametro remote_port. Se non specificato, il server assegnerà una porta causale.

tunnels:
  ssh:
    remote_port: 60123
    proto:
      tcp: 22

Altre opzioni di configurazione

Il file di configurazione ngrok consente di impostare parametri poco comuni.

Per esempio può essere specificato l’authtoken usato durante la validazione su ngrok.com usando il parametro auth_token.

E’ possibile cambiare l’indirizzo che ngrok usa per legare il servizio di introspezione utilizzando il parametro inspect_addr:

auth_token: abc123
inspect_addr: "0.0.0.0:8888"
tunnels:
  ...

Connessione ad un server ngork personale

ngrok supporta la connessione ad un server non ospitato da ngrok.com. Per prima cosa bisogna installare un server, vedremo in seguito come eseguire questa operazione.

Una volta avviato il server ngrokd è necessario configurare due parametri per permettere ad ngork di connettersi in modo sicuro al server installato.

Il parametro server_addr è l’indirizzo del server personale e trust_host_root_certs per rendere la connessione TLS fidata.

server_addr: "esempio.com:4443"
trust_host_root_certs: true
tunnels:
  ...

Eseguire ngrok da proxy

Può essere configurato per poter essere eseguito dietro ad un server proxy http usando il parametro http_proxy:

http_proxy: "http://user:password@10.0.0.1:3128"
tunnels:
  ...