feat: update README, enhance setup scripts, and add dev utilities for improved workflow
This commit is contained in:
gabdevele
@@ -1,111 +1,148 @@
|
||||
# thePlug
|
||||
|
||||
Wrapper web per gestire proxy `mitmdump` davanti a servizi esposti via Docker
|
||||
Web UI per gestire proxy `mitmdump` davanti a servizi esposti via Docker
|
||||
Compose.
|
||||
|
||||
## Struttura
|
||||
|
||||
```text
|
||||
backend/ FastAPI, MongoDB, mitmdump manager
|
||||
frontend/ Vue 3, Vite, CodeMirror + Python LSP
|
||||
playground/ servizio locale minimale per test end-to-end
|
||||
backend/ FastAPI, MongoDB, mitmdump manager
|
||||
frontend/ Vue 3, Vite, CodeMirror + Python LSP
|
||||
playground/ challenge/service compose locali
|
||||
templates/ template proxy YAML file-backed
|
||||
```
|
||||
|
||||
## Setup rapido
|
||||
## Setup iniziale
|
||||
|
||||
```bash
|
||||
./setup.sh
|
||||
```
|
||||
|
||||
Lo script crea `backend/.env`, genera le credenziali mancanti e avvia lo stack
|
||||
Docker completo:
|
||||
`setup.sh` fa bootstrap della macchina/progetto:
|
||||
- installa `uv` se manca
|
||||
- installa Python `3.14` via `uv`
|
||||
- crea `backend/.env` se manca
|
||||
- installa dipendenze backend e frontend
|
||||
- builda il frontend
|
||||
- prepara MongoDB e l'immagine Docker del frontend
|
||||
|
||||
```text
|
||||
Frontend http://localhost:5173
|
||||
Backend http://localhost:3671
|
||||
## Runtime reale / vulnbox
|
||||
|
||||
Questi sono i comandi pensati per l’ambiente reale di gara.
|
||||
|
||||
### MongoDB
|
||||
|
||||
```bash
|
||||
./run.sh mongo up
|
||||
./run.sh mongo status
|
||||
./run.sh mongo logs
|
||||
./run.sh mongo down
|
||||
```
|
||||
|
||||
Questa modalità è buona per smoke test UI/API. Se vuoi provare davvero il
|
||||
takeover della porta di un servizio Docker locale, fai girare il backend sulla
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
./run.sh backend
|
||||
```
|
||||
|
||||
### Frontend Docker
|
||||
|
||||
```bash
|
||||
./run.sh frontend up
|
||||
./run.sh frontend status
|
||||
./run.sh frontend logs
|
||||
./run.sh frontend down
|
||||
```
|
||||
|
||||
Il frontend in container fa proxy API verso il backend in esecuzione sulla
|
||||
macchina host.
|
||||
|
||||
Guida completa: [TESTING.md](/home/gabdevele/CTF/thePlug/TESTING.md)
|
||||
## Workflow development
|
||||
|
||||
Per installare anche il servizio systemd user:
|
||||
Questi comandi sono pensati per sviluppo locale, test e playground.
|
||||
|
||||
### MongoDB
|
||||
|
||||
```bash
|
||||
./setup.sh service
|
||||
./dev.sh mongo up
|
||||
./dev.sh mongo status
|
||||
./dev.sh mongo logs
|
||||
./dev.sh mongo down
|
||||
```
|
||||
|
||||
## Dev backend
|
||||
### Backend dev
|
||||
|
||||
```bash
|
||||
cp backend/.env.example backend/.env
|
||||
docker compose --env-file backend/.env up -d mongodb
|
||||
npm run dev:backend
|
||||
./dev.sh backend
|
||||
```
|
||||
|
||||
Docs FastAPI in dev: `http://localhost:3671/docs`.
|
||||
|
||||
## Test locale realistico
|
||||
|
||||
Per simulare il deployment reale, usa il backend sulla macchina host:
|
||||
### Frontend dev
|
||||
|
||||
```bash
|
||||
./setup.sh deps
|
||||
export SERVICE_SCAN_ROOT="$PWD"
|
||||
npm run dev:backend
|
||||
npm run dev:frontend
|
||||
./setup.sh playground
|
||||
./dev.sh frontend
|
||||
```
|
||||
|
||||
Poi:
|
||||
Questo avvia Vite normalmente sulla macchina host.
|
||||
|
||||
1. Apri `http://localhost:5173`.
|
||||
2. Fai login con le credenziali in `backend/.env`.
|
||||
3. Crea un nuovo proxy.
|
||||
4. Seleziona il servizio `echo` rilevato dal backend sotto la cartella `playground`.
|
||||
5. Lascia `mode=reverse`.
|
||||
6. Verifica che `proxy_port` combaci con la porta del servizio (`9081`) se vuoi che il proxy prenda davvero il posto della route originale.
|
||||
7. Salva e premi `Start`.
|
||||
8. Esegui `curl http://127.0.0.1:9081/`.
|
||||
### Playground / servizi locali
|
||||
|
||||
Se il proxy è attivo, la route originale è ora posseduta da `mitmdump` e il
|
||||
servizio reale è stato spostato su una porta upstream temporanea, visibile nella
|
||||
UI e nello stato runtime.
|
||||
|
||||
`SERVICE_SCAN_ROOT` controls where the backend looks for services. The scan is
|
||||
intentionally shallow: it inspects only the immediate child directories of that
|
||||
root, which matches the expected host layout.
|
||||
|
||||
## Dev frontend
|
||||
Per vedere i challenge/service disponibili:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
./dev.sh services list
|
||||
```
|
||||
|
||||
Il dev server usa `/api` come proxy verso `http://127.0.0.1:3671`.
|
||||
Per avviarli o fermarli:
|
||||
|
||||
```bash
|
||||
./dev.sh services up GabibbiTowers
|
||||
./dev.sh services down GabibbiTowers
|
||||
|
||||
./dev.sh services up all
|
||||
./dev.sh services status all
|
||||
./dev.sh services down all
|
||||
```
|
||||
|
||||
`dev.sh` scopre automaticamente i compose da `playground/*/docker-compose.yml`.
|
||||
|
||||
## Flussi consigliati
|
||||
|
||||
Runtime reale:
|
||||
|
||||
```bash
|
||||
./setup.sh
|
||||
./run.sh mongo up
|
||||
./run.sh backend
|
||||
./run.sh frontend up
|
||||
```
|
||||
|
||||
Sviluppo locale:
|
||||
|
||||
```bash
|
||||
./setup.sh
|
||||
./dev.sh mongo up
|
||||
./dev.sh backend
|
||||
./dev.sh frontend
|
||||
./dev.sh services up <challenge>
|
||||
```
|
||||
|
||||
## Test
|
||||
|
||||
Backend:
|
||||
|
||||
```bash
|
||||
npm run test
|
||||
cd backend
|
||||
uv run ruff check .
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
Equivalente a:
|
||||
Frontend:
|
||||
|
||||
```bash
|
||||
cd backend && uv run ruff check . && uv run pytest
|
||||
cd frontend && npm run build
|
||||
```
|
||||
|
||||
Per testare solo il playground:
|
||||
|
||||
```bash
|
||||
npm run playground:up
|
||||
npm run playground:down
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
## API principali
|
||||
@@ -121,7 +158,7 @@ npm run playground:down
|
||||
- `GET /proxy/{port}/logs`
|
||||
- `WS /proxy/{port}/logs/ws`
|
||||
- `GET /proxy/mitmproxy/options`
|
||||
- `GET /proxy/mitmproxy/examples`
|
||||
- `GET /proxy/mitmproxy/templates`
|
||||
|
||||
## Riferimenti
|
||||
|
||||
|
||||
Reference in New Issue
Block a user