MITMVpn
Consent-only OpenVPN passive telemetry lab with a localized dashboard and one-script VPS deployment.
🇷🇺 Русский ·
🇺🇸 English ·
🇻🇳 Tiếng Việt ·
🇨🇳 中文
MITMVpn is a roadwarrior-style lab environment for classroom demonstrations. It deploys OpenVPN, DNS capture, passive network metadata collection, and a live Apache dashboard that shows VPN client sessions, domains, app fingerprints, risks, TLS/QUIC metadata, and category-based browsing summaries.
It is built for controlled demonstrations with explicit consent. It does **not** decrypt HTTPS traffic.
## How this shit works?
## Как Это Работает?
## Project Snapshot
| Area | What You Get |
| --- | --- |
| Deployment | One-script VPS installer for Debian/Ubuntu. |
| VPN | OpenVPN roadwarrior server with three generated lab clients. |
| Dashboard | Live Apache/PHP dashboard with auto-refresh, tables, timeline, exports, and category popups. |
| Telemetry | DNS visibility, Suricata EVE metadata, p0f OS hints, JA3/JA3S, QUIC/TLS fingerprints. |
| App Hints | Browser, messenger, cloud, media, developer tools, Tor/proxy/VPN, remote-admin and other categories. |
| Localization | Dashboard and project page in 🇷🇺 Russian, 🇺🇸 English, 🇻🇳 Vietnamese, 🇨🇳 Chinese. |
| Safety | Consent-only lab, no HTTPS payload decryption, generated secrets ignored by Git. |
## Quick Start
Clone the private repository on a clean Debian/Ubuntu VPS and run the roadwarrior installer:
git clone https://github.com/vektort13/MITMVpn.git
cd MITMVpn
sudo ./roadwarrior.sh
If your VPS has multiple addresses or the public IP is detected incorrectly:
sudo PUBLIC_IP=203.0.113.10 TIMEZONE=Europe/London ./roadwarrior.sh
After installation:
| Item | Location |
| --- | --- |
| Dashboard | `http://SERVER_IP/` |
| Public student view | `http://SERVER_IP/student/` |
| Dashboard credentials | `/root/openvpn-dashboard-credentials.txt` |
| OpenVPN client profiles | `/root/client-configs/files/*.ovpn` |
Download generated client profiles:
scp -r root@SERVER_IP:/root/client-configs/files ./client-configs
## Deploy From Workstation
If the project is local and the VPS is reachable by SSH:
./deploy.sh root@SERVER_IP /path/to/private_key
Or with environment variables:
SSH_TARGET=root@SERVER_IP SSH_KEY=/path/to/private_key ./deploy.sh
## Localized Dashboard
The live dashboard includes a language selector and remembers the chosen language in the browser.
| Language | UI Coverage |
| --- | --- |
| 🇷🇺 Русский | Main dashboard, controls, status messages, tables, modals, category labels. |
| 🇺🇸 English | Main dashboard, controls, status messages, tables, modals, category labels. |
| 🇻🇳 Tiếng Việt | Main dashboard, controls, status messages, tables, modals, category labels. |
| 🇨🇳 中文 | Main dashboard, controls, status messages, tables, modals, category labels. |
Runtime data such as raw domains, application names, JA3 hints, and detector evidence is shown as collected.
## Public Student View
The installer publishes a separate read-only page for the classroom:
http://SERVER_IP/student/
Students can watch the live dashboard from their own devices and change only the interface language. Admin actions stay behind the authenticated dashboard:
- no log clearing;
- no DNS redirect controls;
- no exports or reports;
- no access to `logs.php` mutation endpoints.
## Architecture
flowchart LR
C1[Lab Client 1] -->|OpenVPN| VPN[OpenVPN Server]
C2[Lab Client 2] -->|OpenVPN| VPN
C3[Lab Client 3] -->|OpenVPN| VPN
VPN --> DNS[dnsmasq DNS logs]
VPN --> SUR[Suricata EVE metadata]
VPN --> P0F[p0f OS fingerprints]
VPN --> SESS[OpenVPN session logs]
DNS --> DET[Passive classifier]
SUR --> DET
P0F --> DET
SESS --> API[PHP API]
DET --> API
API --> DASH[Localized Apache Dashboard]
DASH --> EXP[JSON / HTML exports]
DASH --> REDIR[DNS Redirect Lab]
## What The Dashboard Shows
| View | Details |
| --- | --- |
| Client dossier | Real ingress IP, geo hints, active/offline status, session duration, traffic counters. |
| Sites and domains | Domain list, favicons, dwell time estimate, event source, DNS redirect controls. |
| Interests/categories | Clickable category chips that open a modal with all sites from that category. |
| Detected software | Passive app hints with confidence score and signal explanation. |
| Risks | Tor, proxy, VPN, remote-admin and other high-signal categories. |
| TLS/QUIC fingerprints | JA3/JA3S hashes, classifier hints, lab uniqueness, hit counts. |
| Timeline | Chronological activity stream for presentation and analysis. |
## Components
| File | Purpose |
| --- | --- |
| `roadwarrior.sh` | One-script VPS installer and orchestrator. |
| `provision_openvpn_lab.sh` | OpenVPN, dnsmasq, NAT/firewall, Apache basic auth, client config generation. |
| `setup_passive_detection.sh` | Suricata, p0f, passive classifier, controlled client port scan timer. |
| `deploy_dashboard.sh` | Installs the localized dashboard into Apache web root. |
| `dashboard_live.php` | Live localized SPA dashboard. |
| `dashboard_api.php` | JSON data feed consumed by the dashboard. |
| `dashboard_logs.php` | Export, report, log clearing, DNS redirect API. |
| `dashboard_favicon.php` | Favicon proxy/cache for domain rows. |
| `passive_app_detection.py` | Passive metadata parser and application classifier. |
| `client_portscan.py` | Controlled lab scan of connected VPN client addresses. |
| `dns_redirect_manager.py` | DNS-only redirect manager used by the dashboard. |
## Safety Model
This project is for controlled education and internal lab demonstrations only.
- Use it only with explicit authorization from every participant.
- HTTPS payloads are not decrypted.
- DNS redirect is DNS-only and intentionally demonstrates browser certificate and HSTS limitations.
- Generated `.ovpn` files, SSH keys, certificates, and dashboard credentials are excluded from Git by default.
## Requirements
| Requirement | Notes |
| --- | --- |
| OS | Debian 11/12 or Ubuntu 22.04/24.04 VPS. |
| Access | Root access or sudo. |
| Network | Public IPv4 address. |
| Firewall | Open inbound `80/tcp` and `1194/udp`. |
## Useful Commands
systemctl status openvpn-server@server dnsmasq apache2
systemctl status suricata-openvpn p0f-openvpn openvpn-passive-detect
journalctl -u openvpn-passive-detect -f
tail -f /var/log/openvpn/dnsmasq.log
## Repository Hygiene
The repository intentionally ignores generated lab secrets and runtime artifacts:
.ssh/
client-configs/
*.ovpn
*credentials*.txt
__pycache__/
*.log
Keep generated lab secrets on the server or in a private vault, not in Git.
## 🇷🇺 Русский
**MITMVpn** поднимает на чистом VPS учебную OpenVPN-инфраструктуру и веб-дашборд для демонстрации того, какие метаданные видит оператор VPN.
Возможности:
- активные и завершенные VPN-сессии;
- реальный входной IP клиента до VPN;
- DNS-запросы и домены, увиденные через VPN;
- фавиконки сайтов и примерное время активности по доменам;
- пассивные признаки приложений: браузеры, мессенджеры, облака, Tor/proxy/VPN, remote-admin и другие категории;
- p0f OS fingerprinting и JA3/JA3S TLS/QUIC fingerprints;
- таблицы, timeline, live-console, HTML/JSON export;
- DNS redirect lab-переключатели для демонстрации ограничений DNS-only redirect;
- локализация дашборда: 🇷🇺 RU, 🇺🇸 EN, 🇻🇳 VI, 🇨🇳 ZH.
Быстрый запуск:
git clone https://github.com/vektort13/MITMVpn.git
cd MITMVpn
sudo ./roadwarrior.sh
После установки:
- Dashboard: `http://SERVER_IP/`
- Страница для студентов: `http://SERVER_IP/student/`
- Логин/пароль: `/root/openvpn-dashboard-credentials.txt`
- OpenVPN-конфиги: `/root/client-configs/files/*.ovpn`
## 🇺🇸 English
**MITMVpn** provisions a teaching OpenVPN lab on a clean VPS and exposes a live dashboard for consent-based demonstrations of VPN operator visibility.
Highlights:
- active and historical VPN sessions;
- real ingress IP before the VPN tunnel;
- DNS requests and domains observed through the tunnel;
- site favicons and approximate domain dwell time;
- passive application hints for browsers, messengers, cloud apps, Tor/proxy/VPN, remote admin tools, and other categories;
- p0f OS fingerprints and JA3/JA3S TLS/QUIC fingerprints;
- tables, timeline, live console, HTML/JSON exports;
- DNS redirect lab toggles for showing DNS-only redirect limitations;
- dashboard localization: 🇷🇺 RU, 🇺🇸 EN, 🇻🇳 VI, 🇨🇳 ZH.
Quick start:
git clone https://github.com/vektort13/MITMVpn.git
cd MITMVpn
sudo ./roadwarrior.sh
After installation:
- Dashboard: `http://SERVER_IP/`
- Public student view: `http://SERVER_IP/student/`
- Credentials: `/root/openvpn-dashboard-credentials.txt`
- OpenVPN profiles: `/root/client-configs/files/*.ovpn`
## 🇻🇳 Tiếng Việt
**MITMVpn** triển khai một lab OpenVPN trên VPS sạch và cung cấp dashboard live cho bài demo có sự đồng ý của người tham gia.
Tính năng chính:
- phiên VPN đang hoạt động và lịch sử phiên;
- IP thật trước khi đi vào VPN;
- truy vấn DNS và tên miền đi qua VPN;
- favicon website và thời lượng hoạt động ước lượng theo tên miền;
- gợi ý ứng dụng từ metadata thụ động: trình duyệt, nhắn tin, cloud, Tor/proxy/VPN, remote-admin và các nhóm khác;
- fingerprint hệ điều hành bằng p0f và fingerprint TLS/QUIC JA3/JA3S;
- bảng dữ liệu, timeline, live console, export HTML/JSON;
- DNS redirect lab để minh họa giới hạn của redirect chỉ bằng DNS;
- ngôn ngữ dashboard: 🇷🇺 RU, 🇺🇸 EN, 🇻🇳 VI, 🇨🇳 ZH.
Cài đặt nhanh:
git clone https://github.com/vektort13/MITMVpn.git
cd MITMVpn
sudo ./roadwarrior.sh
Sau khi cài đặt:
- Dashboard: `http://SERVER_IP/`
- Trang xem cho sinh viên: `http://SERVER_IP/student/`
- Tài khoản/mật khẩu: `/root/openvpn-dashboard-credentials.txt`
- Cấu hình OpenVPN: `/root/client-configs/files/*.ovpn`
## 🇨🇳 中文
**MITMVpn** 会在干净的 VPS 上部署一个教学用 OpenVPN 实验环境，并提供实时仪表盘，用于经过同意的课堂演示。
主要功能：
- 当前和历史 VPN 会话；
- VPN 前的真实入口 IP；
- 通过 VPN 看到的 DNS 请求和域名；
- 网站 favicon 和按域名估算的停留时间；
- 基于被动元数据的应用识别提示：浏览器、即时通讯、云服务、Tor/proxy/VPN、远程管理等；
- p0f 操作系统指纹和 JA3/JA3S TLS/QUIC 指纹；
- 表格、时间线、实时控制台、HTML/JSON 导出；
- DNS redirect lab，用于展示 DNS-only 重定向的限制；
- 仪表盘语言：🇷🇺 RU、🇺🇸 EN、🇻🇳 VI、🇨🇳 ZH。
快速安装：
git clone https://github.com/vektort13/MITMVpn.git
cd MITMVpn
sudo ./roadwarrior.sh
安装完成后：
- Dashboard: `http://SERVER_IP/`
- 学生只读页面：`http://SERVER_IP/student/`
- 登录信息：`/root/openvpn-dashboard-credentials.txt`
- OpenVPN 配置：`/root/client-configs/files/*.ovpn`