thePlug/README.md

thePlug

Web UI per gestire proxy mitmdump davanti a servizi esposti via Docker Compose.

Struttura

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

./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

./run.sh mongo up
./run.sh mongo status
./run.sh mongo logs
./run.sh mongo down

Backend

./run.sh backend

Frontend Docker

./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

./dev.sh mongo up
./dev.sh mongo status
./dev.sh mongo logs
./dev.sh mongo down

Backend dev

./dev.sh backend

Docs FastAPI in dev: http://localhost:3671/docs.

Frontend dev

./dev.sh frontend

Questo avvia Vite normalmente sulla macchina host.

Playground / servizi locali

Per vedere i challenge/service disponibili:

./dev.sh services list

Per avviarli o fermarli:

./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:

./setup.sh
./run.sh mongo up
./run.sh backend
./run.sh frontend up

Sviluppo locale:

./setup.sh
./dev.sh mongo up
./dev.sh backend
./dev.sh frontend
./dev.sh services up <challenge>

Test

Backend:

cd backend
uv run ruff check .
uv run pytest

Frontend:

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/