168 lines
2.7 KiB
Markdown
168 lines
2.7 KiB
Markdown
# thePlug
|
||
|
||
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/ challenge/service compose locali
|
||
templates/ template proxy YAML file-backed
|
||
```
|
||
|
||
## Setup iniziale
|
||
|
||
```bash
|
||
./setup.sh
|
||
```
|
||
|
||
`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
|
||
|
||
## 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
|
||
```
|
||
|
||
### 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.
|
||
|
||
## Workflow development
|
||
|
||
Questi comandi sono pensati per sviluppo locale, test e playground.
|
||
|
||
### MongoDB
|
||
|
||
```bash
|
||
./dev.sh mongo up
|
||
./dev.sh mongo status
|
||
./dev.sh mongo logs
|
||
./dev.sh mongo down
|
||
```
|
||
|
||
### Backend dev
|
||
|
||
```bash
|
||
./dev.sh backend
|
||
```
|
||
|
||
Docs FastAPI in dev: `http://localhost:3671/docs`.
|
||
|
||
### Frontend dev
|
||
|
||
```bash
|
||
./dev.sh frontend
|
||
```
|
||
|
||
Questo avvia Vite normalmente sulla macchina host.
|
||
|
||
### Playground / servizi locali
|
||
|
||
Per vedere i challenge/service disponibili:
|
||
|
||
```bash
|
||
./dev.sh services list
|
||
```
|
||
|
||
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
|
||
cd backend
|
||
uv run ruff check .
|
||
uv run pytest
|
||
```
|
||
|
||
Frontend:
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run build
|
||
```
|
||
|
||
## API principali
|
||
|
||
- `POST /auth/login`
|
||
- `POST /auth/logout`
|
||
- `GET /proxy`
|
||
- `POST /proxy`
|
||
- `POST /proxy/{port}/start`
|
||
- `POST /proxy/{port}/stop`
|
||
- `POST /proxy/{port}/restart`
|
||
- `GET /proxy/{port}/health`
|
||
- `GET /proxy/{port}/logs`
|
||
- `WS /proxy/{port}/logs/ws`
|
||
- `GET /proxy/mitmproxy/options`
|
||
- `GET /proxy/mitmproxy/templates`
|
||
|
||
## Riferimenti
|
||
|
||
- Mitmproxy addons: https://docs.mitmproxy.org/stable/addons/examples/
|
||
- Mitmproxy modes: https://docs.mitmproxy.org/stable/concepts/modes/
|
||
- Mitmproxy options: https://docs.mitmproxy.org/stable/concepts/options/
|