thePlug/TESTING.md

Testing Guide

Questa guida descrive come preparare e testare thePlug in tre scenari:

1. laptop con backend sulla macchina host
2. laptop con stack tutto Dockerizzato
3. vulnbox reale con backend fuori Docker

L’obiettivo non è solo far partire UI e API, ma verificare il comportamento reale del proxy: remap della porta del servizio, avvio di mitmdump, healthcheck e ripristino su Stop.

Concetti Chiave

Cosa fa Save

Save salva solo la configurazione del proxy nel backend. Non tocca:

• porte del servizio reale
• processi mitmdump
• Docker Compose

Cosa fa Start

In reverse mode, se il proxy è associato a un servizio Docker Compose e mode_spec non è impostato:

1. il backend sposta la porta pubblica del servizio reale su una porta libera
2. salva quella nuova porta come upstream live
3. avvia mitmdump sulla porta originale

Quindi, se vuoi che il proxy prenda davvero il posto del servizio originale, proxy_port deve coincidere con la porta pubblica del servizio.

Come vengono scoperti i servizi

Il backend cerca i servizi Docker Compose sotto una root di scansione:

• di default: HOME
• override: SERVICE_SCAN_ROOT

La scansione è volutamente shallow:

• il backend guarda solo le cartelle immediate sotto la root
• non scende ricorsivamente in profondità

Questa scelta riflette il layout atteso sulla macchina reale.

Esempio valido:

/home/user/service-a/docker-compose.yml
/home/user/service-b/docker-compose.yml

Esempio non visto se la root è /home/user:

/home/user/projects/lab/service-a/docker-compose.yml

In quel caso devi cambiare SERVICE_SCAN_ROOT.

Prerequisiti

Su tutte le macchine:

• docker
• docker compose
• uv
• python 3.14
• node 22

Il backend installerà anche:

• mitmproxy
• basedpyright

Porte usate tipicamente:

• 3671 backend
• 5173 frontend
• 27017 mongodb
• una o più porte proxy/test

Scenario 1: Laptop con Backend sulla Macchina Host

Questo è il setup migliore per testare davvero il comportamento del proxy.

Quando usarlo

Usa questo scenario se vuoi verificare:

• discovery servizi
• remap porta Docker Compose
• takeover reale della porta pubblica
• start/stop/restart di mitmdump
• esempi script e editor

Preparazione

Dalla root del progetto:

cd /home/gabdevele/CTF/thePlug
./setup.sh deps
export SERVICE_SCAN_ROOT="$PWD"
./setup.sh playground

Questo fa due cose:

• avvia mongodb in Docker
• avvia un piccolo upstream locale in playground/

Il playground espone:

http://127.0.0.1:9081

Avvio applicazione

In un terminale:

cd /home/gabdevele/CTF/thePlug
npm run dev:backend

In un secondo terminale:

cd /home/gabdevele/CTF/thePlug
npm run dev:frontend

Login

Le credenziali sono in:

• backend/.env

Apri:

http://localhost:5173

Test End-to-End Consigliato

1. Crea un nuovo proxy.
2. Seleziona il servizio echo rilevato dal backend.
3. Lascia mode=reverse.
4. Verifica che proxy_port=9081.
5. Salva.
6. Premi Start.
7. Esegui:

curl -i http://127.0.0.1:9081/

Cosa devi vedere

Prima di Start:

• 9081 risponde direttamente il servizio playground

Dopo Start:

• mitmdump è in ascolto su 9081
• il servizio reale è stato spostato su una porta upstream temporanea
• la UI mostra il live upstream cambiato
• i log del proxy iniziano a popolarsi

Dopo Stop:

• la porta pubblica originaria torna al servizio reale
• service.upstream_port torna null

Verifiche Utili

Controlla i servizi rilevati:

curl -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:3671/proxy/services

Controlla i log proxy dalla UI o via API:

curl -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:3671/proxy/9081/logs

Cleanup

npm run playground:down
docker compose --env-file backend/.env -f docker-compose.yml down

Scenario 2: Laptop con Stack Tutto Dockerizzato

Questo scenario è adatto soprattutto a smoke test applicativi.

Quando usarlo

Usalo per verificare:

• login/logout
• CRUD proxy
• examples
• options
• persistenza Mongo
• build frontend e wiring API

Avvio

cd /home/gabdevele/CTF/thePlug
./setup.sh

Apri:

• frontend: http://localhost:5173
• backend: http://localhost:3671

Cosa testare qui

Puoi testare bene:

• creazione proxy
• update/delete
• validazione codice
• examples custom
• health endpoint
• editor e autocomplete

Limite importante

Questo non è il setup migliore per validare il takeover reale delle porte di un servizio locale, perché il backend è dentro Docker e non replica la topologia host-native del deployment reale.

Quindi:

• bene per smoke test UI/API
• non abbastanza per validare il flusso finale di orchestration

Per il test realistico del proxy usa lo Scenario 1.

Spegnimento

docker compose --env-file backend/.env -f docker-compose.yml down

Scenario 3: Vulnbox Reale con Backend fuori Docker

Questo è il modello più vicino al deployment reale.

Layout atteso dei servizi

Caso ideale sotto HOME:

/home/user/service-a/docker-compose.yml
/home/user/service-b/docker-compose.yml
/home/user/service-c/docker-compose.yml

Se il layout è diverso, imposta SERVICE_SCAN_ROOT.

Preparazione backend

cd /path/to/thePlug
cp backend/.env.example backend/.env
./setup.sh deps

Se i servizi non sono sotto HOME:

export SERVICE_SCAN_ROOT="/path/che/contiene/le/cartelle-servizio"

Avvio backend

cd /path/to/thePlug
npm run dev:backend

Avvio frontend

In sviluppo:

cd /path/to/thePlug
npm run dev:frontend

Oppure build statico:

cd /path/to/thePlug/frontend
VITE_API_BASE_URL=http://IP_O_HOST:3671 npm run build

Test operativo reale

1. Apri la UI.
2. Seleziona un servizio reale scoperto dal backend.
3. Se vuoi takeover vero della porta pubblica: proxy_port deve essere uguale alla porta pubblica del servizio.
4. Salva.
5. Premi Start.
6. Verifica da terminale o con la tua applicazione client che il traffico passi ancora sulla porta originale.

Cosa aspettarsi

Su Start:

• il servizio reale viene spostato su una porta temporanea
• mitmdump si lega alla porta originaria
• il traffico continua a entrare dalla porta originale
• la UI mostra il nuovo live upstream

Su Stop:

• la porta originaria torna al servizio reale
• il proxy viene fermato

Failure Modes Comuni

Il backend non trova nessun servizio

Controlla:

• valore di SERVICE_SCAN_ROOT
• che i compose siano nelle cartelle immediate sotto quella root
• che i file si chiamino uno tra:
  • compose.yml
  • compose.yaml
  • docker-compose.yml
  • docker-compose.yaml

Il proxy parte ma non prende il posto del servizio

Controlla:

• mode=reverse
• mode_spec vuoto
• proxy_port uguale alla porta del servizio
• servizio selezionato dalla UI correttamente

Start fallisce

Controlla:

• mitmdump disponibile nel backend host
• conflitti di porta
• errori di sintassi nello script
• log del proxy

Il frontend mostra session expired

Vuol dire che il token JWT è scaduto o non è più valido. Fai login di nuovo.

Comandi Utili

Test backend:

cd backend
uv run ruff check .
uv run pytest

Build frontend:

cd frontend
npm run build

Avvio playground:

./setup.sh playground

Solo dipendenze backend per test host:

./setup.sh deps

Raccomandazione Finale

Per lavorare in modo efficiente:

• usa ./setup.sh per smoke test rapidi
• usa backend host + frontend dev + playground per il test vero del proxy
• usa backend host sulla vulnbox reale per validare il comportamento finale

Se devi testare davvero il remap porta, considera valido solo un setup con backend fuori Docker.