# Gradio Tunnel Dashboard (studio progetto)

Questo repository contiene una proposta di studio per un servizio Linux che:

- **scansiona le porte in uso** sul server (inclusi i servizi Docker);
- **mostra i risultati in una dashboard**;
- **permette di selezionare un servizio/porta** e **attivare un tunnel** basato su [gradio-tunneling](https://github.com/arkohut/gradio-tunneling);
- **espone l'URL del tunnel in dashboard**, con controlli per **mantenere** o **spegnere** il tunnel e liberare la risorsa.

## Obiettivo del progetto

Costruire un servizio che renda semplice e sicuro l'esposizione temporanea di servizi locali (es. container Docker) tramite tunnel, con un'interfaccia web centralizzata.

## Architettura proposta

### 1) Scanner delle porte

- **Input**: porte in ascolto sul server (TCP/UDP), con informazioni su processo, PID, utente.
- **Fonti consigliate**:
  - `ss -ltnp` / `ss -lunp` per porte e processi.
  - Docker: `docker ps` + `docker inspect` per mappature porte/servizi.
- **Output**: lista normalizzata con:
  - porta, protocollo, PID/processo,
  - container (se applicabile),
  - metadati (nome servizio, descrizione, tag).

### 2) Service registry (modello dati)

- **Store**: SQLite o PostgreSQL.
- **Entità principali**:
  - `Service` (nome, porta, protocollo, tipo, metadata)
  - `Tunnel` (service_id, status, public_url, created_at, updated_at)

### 3) Orchestratore Tunnel

- **Driver**: integrazione con `gradio-tunneling`.
- **Funzioni**:
  - `start_tunnel(service)`
  - `stop_tunnel(tunnel)`
  - `health_check(tunnel)`
- **Process supervision**:
  - `systemd` (service unit) oppure job manager interno (process/thread pool).
- **Persistence**:
  - mantenere stato e URL pubblico nel DB.

### 4) Dashboard web

- **Funzionalità**:
  - elenco porte/servizi disponibili
  - filtri (per container, protocollo, status tunnel)
  - azioni: avvia/termina tunnel
  - mostra URL pubblico del tunnel con pulsante copia
- **Stack possibili**:
  - Backend: FastAPI/Flask
  - Frontend: React/Vue, oppure UI server-side (Jinja2) o Gradio stesso

### 5) Sicurezza e policy

- Whitelist di porte consentite.
- Autenticazione (OAuth, basic auth o SSO).
- Audit log per avvio/stop tunnel.
- Rate limiting per creare tunnel.

## Flusso operativo (happy path)

1. Scanner rileva porte attive e aggiorna il registry.
2. L'utente apre la dashboard e seleziona un servizio.
3. Il backend avvia `gradio-tunneling` sulla porta selezionata.
4. L'URL pubblico del tunnel viene visualizzato in dashboard.
5. L'utente può interrompere il tunnel e liberare la risorsa.

## Milestone suggerite

1. **MVP scanner**: lista porte + metadati base.
2. **MVP dashboard**: tabella + pulsanti avvio/stop.
3. **Tunnel orchestration**: integrazione `gradio-tunneling`.
4. **Stabilità**: gestione processi, retry, health checks.
5. **Security**: auth + policy + audit.

## Note implementative

- Per Docker: associare porta -> container tramite inspect o naming convention.
- Prevedere un layer di caching per evitare scansioni continue troppo costose.
- In caso di reboot, ripristinare lo stato dei tunnel o marcarli come inattivi.

## Prossimi passi

Se vuoi, posso:

- generare una struttura iniziale del progetto (backend + frontend);
- creare un prototipo funzionante con API di scansione e avvio tunnel;
- aggiungere un esempio di integrazione con `gradio-tunneling`;
- scrivere i container Docker per sviluppo locale.