feat: enhance service discovery and proxy management
This commit is contained in:
gabdevele
+413
@@ -0,0 +1,413 @@
|
||||
# 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:
|
||||
|
||||
```text
|
||||
/home/user/service-a/docker-compose.yml
|
||||
/home/user/service-b/docker-compose.yml
|
||||
```
|
||||
|
||||
Esempio non visto se la root è `/home/user`:
|
||||
|
||||
```text
|
||||
/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
|
||||
- `6379` redis
|
||||
- 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:
|
||||
|
||||
```bash
|
||||
cd /home/gabdevele/CTF/thePlug
|
||||
./setup.sh deps
|
||||
export SERVICE_SCAN_ROOT="$PWD"
|
||||
./setup.sh playground
|
||||
```
|
||||
|
||||
Questo fa due cose:
|
||||
|
||||
- avvia solo `mongodb` e `redis` in Docker
|
||||
- avvia un piccolo upstream locale in `playground/`
|
||||
|
||||
Il playground espone:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:9081
|
||||
```
|
||||
|
||||
### Avvio applicazione
|
||||
|
||||
In un terminale:
|
||||
|
||||
```bash
|
||||
cd /home/gabdevele/CTF/thePlug
|
||||
npm run dev:backend
|
||||
```
|
||||
|
||||
In un secondo terminale:
|
||||
|
||||
```bash
|
||||
cd /home/gabdevele/CTF/thePlug
|
||||
npm run dev:frontend
|
||||
```
|
||||
|
||||
### Login
|
||||
|
||||
Le credenziali sono in:
|
||||
|
||||
- [backend/.env](/home/gabdevele/CTF/thePlug/backend/.env)
|
||||
|
||||
Apri:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:3671/proxy/services
|
||||
```
|
||||
|
||||
Controlla i log proxy dalla UI o via API:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:3671/proxy/9081/logs
|
||||
```
|
||||
|
||||
### Cleanup
|
||||
|
||||
```bash
|
||||
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/Redis
|
||||
- build frontend e wiring API
|
||||
|
||||
### Avvio
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```text
|
||||
/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
|
||||
|
||||
```bash
|
||||
cd /path/to/thePlug
|
||||
cp backend/.env.example backend/.env
|
||||
./setup.sh deps
|
||||
```
|
||||
|
||||
Se i servizi non sono sotto `HOME`:
|
||||
|
||||
```bash
|
||||
export SERVICE_SCAN_ROOT="/path/che/contiene/le/cartelle-servizio"
|
||||
```
|
||||
|
||||
### Avvio backend
|
||||
|
||||
```bash
|
||||
cd /path/to/thePlug
|
||||
npm run dev:backend
|
||||
```
|
||||
|
||||
### Avvio frontend
|
||||
|
||||
In sviluppo:
|
||||
|
||||
```bash
|
||||
cd /path/to/thePlug
|
||||
npm run dev:frontend
|
||||
```
|
||||
|
||||
Oppure build statico:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
uv run ruff check .
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
Build frontend:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
Avvio playground:
|
||||
|
||||
```bash
|
||||
./setup.sh playground
|
||||
```
|
||||
|
||||
Solo dipendenze backend per test host:
|
||||
|
||||
```bash
|
||||
./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.
|
||||
Reference in New Issue
Block a user