130 lines
2.9 KiB
Markdown
130 lines
2.9 KiB
Markdown
# thePlug
|
|
|
|
Wrapper web per gestire proxy `mitmdump` davanti a servizi esposti via Docker
|
|
Compose.
|
|
|
|
## Struttura
|
|
|
|
```text
|
|
backend/ FastAPI, MongoDB, Redis, mitmdump manager
|
|
frontend/ Vue 3, Vite, CodeMirror + Python LSP
|
|
playground/ servizio locale minimale per test end-to-end
|
|
```
|
|
|
|
## Setup rapido
|
|
|
|
```bash
|
|
./setup.sh
|
|
```
|
|
|
|
Lo script crea `backend/.env`, genera le credenziali mancanti e avvia lo stack
|
|
Docker completo:
|
|
|
|
```text
|
|
Frontend http://localhost:5173
|
|
Backend http://localhost:3671
|
|
```
|
|
|
|
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
|
|
macchina host.
|
|
|
|
Guida completa: [TESTING.md](/home/gabdevele/CTF/thePlug/TESTING.md)
|
|
|
|
Per installare anche il servizio systemd user:
|
|
|
|
```bash
|
|
./setup.sh service
|
|
```
|
|
|
|
## Dev backend
|
|
|
|
```bash
|
|
cp backend/.env.example backend/.env
|
|
docker compose --env-file backend/.env up -d mongodb redis
|
|
npm run dev:backend
|
|
```
|
|
|
|
Docs FastAPI in dev: `http://localhost:3671/docs`.
|
|
|
|
## Test locale realistico
|
|
|
|
Per simulare il deployment reale, usa il backend sulla macchina host:
|
|
|
|
```bash
|
|
./setup.sh deps
|
|
export SERVICE_SCAN_ROOT="$PWD"
|
|
npm run dev:backend
|
|
npm run dev:frontend
|
|
./setup.sh playground
|
|
```
|
|
|
|
Poi:
|
|
|
|
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/`.
|
|
|
|
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
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Il dev server usa `/api` come proxy verso `http://127.0.0.1:3671`.
|
|
|
|
## Test
|
|
|
|
```bash
|
|
npm run test
|
|
```
|
|
|
|
Equivalente a:
|
|
|
|
```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
|
|
```
|
|
|
|
## 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`
|
|
- `GET /proxy/mitmproxy/options`
|
|
- `GET /proxy/mitmproxy/examples`
|
|
|
|
## 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/
|