diff --git a/.gitignore b/.gitignore index 7b8dbea..0f1206d 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ .test/ +.sisyphus/ diff --git a/AGENTS.md b/AGENTS.md index 6576f54..6598b46 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,12 @@ -# WireGuard Policy Firewall (`03.wireguard-policy`) +# WireGuard Policy Firewall + WGRplane (`03.wireguard-policy`) + +This repository contains two components: +1. **WireGuard Policy Firewall** - Shell script-based dynamic iptables/ipset policy engine +2. **WGRplane** - Go-native control plane with Vue 3 frontend + +--- + +## Component 1: WireGuard Policy Firewall ## Architecture & Configuration Flow - **Goal:** Dynamic iptables/ipset rules based on WireGuard configuration (`wg0.conf`). @@ -25,3 +33,72 @@ ## Development Commands - Restart the watcher service: `systemctl restart wg-policy.service` - Check service logs: `journalctl -u wg-policy.service -f` + +--- + +## Component 2: WGRplane (Go App in `/app`) + +## Architecture Overview +WGRplane is a Go-native WireGuard control plane application with a Vue 3 frontend, providing a modern web dashboard for WireGuard management. + +- **Single Binary:** The Go binary (`app/main.go`) serves both the REST API (port 10087) and the built Vue frontend from `app/frontend/dist/`. +- **Hybrid Mode:** + - `forward` - Directly applies nftables rules on the local machine + - `standalone` - Acts as a control plane that triggers webhooks to remote WireGuard servers +- **2-Column Policy:** Each peer has `AllowAccess` (CIDR whitelist) and `AllowInternet` (boolean toggle) + +## Key File Locations +- `app/main.go` - Bootstrap server, routing, init DB +- `app/handlers.go` - REST API route handlers +- `app/models.go` - GORM models (Server, Peer, Webhook, SMTP) +- `app/auth.go` - JWT, TOTP, API key auth middleware +- `app/nftables.go` - nftables rule management (mode forward) +- `app/webhook.go` - Webhook engine with retry/backoff +- `app/scheduler.go` - Cron jobs (expiry, data limit, reset) +- `app/stats.go` - WebSocket Hub for real-time stats +- `app/frontend/` - Vue 3 SPA (TypeScript, TailwindCSS 4) + +## Tech Stack +| Component | Technology | +|-----------|------------| +| **Backend** | Go, Gorilla Mux, GORM (SQLite via glebarez/sqlite) | +| **Frontend** | Vue 3, TypeScript, Vite, TailwindCSS 4, vue-i18n 9 | +| **Auth** | JWT (golang-jwt/v5), TOTP (pquerna/otp), API Key | +| **WebSockets** | gorilla/websocket | +| **Webhooks** | Go net/http with retry + exponential backoff | +| **Scheduling** | robfig/cron v3 | +| **QR Code** | skip2/go-qrcode | +| **Email** | jordan-wright/email (SMTP) | + +## Authentication Methods +WGRplane supports three authentication methods: + +| Method | Header | Notes | +|--------|--------|-------| +| API Key | `wg-rplane-datadunia: ` | Set via env var `WG_API_KEY`. Default: `test-api-key` | +| JWT | `Authorization: Bearer ` | Expires in 15 minutes. Secret via env var `JWT_SECRET` | +| TOTP | `X-TOTP: ` | Required if user enables TOTP | + +## Development Commands +- Build Go binary: `cd app && go build -o ../wgrplane .` +- Build frontend: `cd app/frontend && npm install && npm run build` +- Run locally: `./wgrplane` (serves on `http://localhost:10087`) +- Restart service: `systemctl restart wgrplane.service` +- Check service logs: `journalctl -u wgrplane.service -f` + +## Testing & Verifying +- Test auth (no header): `curl http://localhost:10087/api/servers` (expect 401) +- Test auth (correct): `curl -H "wg-rplane-datadunia: test-api-key" http://localhost:10087/api/servers` +- View Swagger docs: Visit `http://localhost:10087/swagger/` +- WebSocket test: Connect to `ws://localhost:10087/ws/stats` + +## References +- For detailed WGRplane documentation: See `app/README.md` +- For WGRplane-specific AI agent guidance: See `app/AGENTS.md` + +--- + +## Notes for AI Agents +- The `.sisyphus/` directory contains planning artifacts and may be cleaned up after plan completion. +- When working on Policy Firewall scripts, always preserve `#Access` comment parsing logic. +- When working on WGRplane, remember it's a single binary serving both API and frontend on port 10087. diff --git a/README.md b/README.md index 74865eb..ab62bb2 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,29 @@ -# WireGuard Dynamic Policy Firewall +# WireGuard Policy Firewall + WGRplane Control Plane -A lightweight, robust, and highly dynamic iptables/ipset policy firewall engine designed to restrict and control WireGuard peer traffic (egress traffic mapping) straight from `wg0.conf`. +A complete WireGuard management solution combining two powerful components: -Rather than allowing all VPN clients to reach any part of your internal network, this tool isolates clients from each other by default and reads a custom `#Access` comment inside `wg0.conf` to automatically generate strict `iptables` rules and `ipset` whitelists per-client on the fly. +1. **WireGuard Dynamic Policy Firewall** - A lightweight, robust iptables/ipset policy engine that restricts and controls WireGuard peer traffic directly from `wg0.conf` using custom `#Access` comments. +2. **WGRplane** - A Go-native control plane application with Vue 3 frontend, providing a modern web dashboard for WireGuard management with real-time monitoring, peer CRUD, and hybrid firewall enforcement. + +--- + +## πŸ“‘ Table of Contents + +### Policy Firewall (Shell Scripts) +- [Architecture & Data Flow](#-architecture--data-flow) +- [Installation](#-installation) +- [Prerequisites](#-prerequisites) +- [wg0.conf Integration](#-integrasi-ke-wg0conf) +- [CLI Usage](#-wg-policy-ctl-cli-usage) +- [Systemd Integration](#-systemd-integration-watcher-daemon) + +### WGRplane (Go App) +- [WGRplane Overview](#-wgrplane-overview) +- [WGRplane Architecture](#-wgrplane-architecture) +- [WGRplane Features](#-wgrplane-features) +- [WGRplane Tech Stack](#-wgrplane-tech-stack) +- [WGRplane API Endpoints](#-wgrplane-api-endpoints) +- [WGRplane Installation](#-wgrplane-installation) --- @@ -171,3 +192,210 @@ Check the watcher logs: ```bash journalctl -u wg-policy.service -f ``` + +--- + +## πŸš€ WGRplane Overview + +**WGRplane** is a Go-native WireGuard control plane application with a Vue 3 frontend, providing a modern web dashboard for WireGuard management. It features a single Go binary backend, SPA frontend, dynamic policy firewall integration, and glassmorphism UI design. + +The application lives in the `/app` directory. For full documentation, see [`app/README.md`](app/README.md). + +--- + +## πŸ— WGRplane Architecture + +``` +wg0.conf (with/without #Access) + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ WGRplane (Go Binary :10087) β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Gorilla β”‚ β”‚ GORM β”‚ β”‚ nftables β”‚ β”‚ +β”‚ β”‚ Mux Routerβ”‚ β”‚ SQLite β”‚ β”‚ Engine β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Webhook β”‚ β”‚ Schedulerβ”‚ β”‚ WebSocketβ”‚ β”‚ +β”‚ β”‚ Engine β”‚ β”‚ Cron β”‚ β”‚ Hub β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Auth β”‚ β”‚ SMTP β”‚ β”‚ Plugins β”‚ β”‚ +β”‚ β”‚ JWT/TOTP β”‚ β”‚ Email β”‚ β”‚ TG/Slack β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ HTTP/WebSocket +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Frontend (Vue 3 + TypeScript + Tailwind) β”‚ +β”‚ Glassmorphism UI, i18n, Dark/Light mode β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Hybrid Mode + +WGRplane supports two server modes: + +- **`forward`** - Directly applies nftables rules on the local machine. Peer policies are enforced via `nft` commands. +- **`standalone`** - Acts as a control plane that triggers webhooks to remote WireGuard servers. Policy enforcement happens on the remote side. + +### 2-Column Policy + +Each peer has two independent policy columns: + +| Column | Function | +|--------|----------| +| **AllowAccess** | List of CIDRs the peer can access (internal targets) | +| **AllowInternet** | Boolean flag. If `true`, peer gets unlimited internet access (MASQUERADE) | + +Peers without any rules are isolated from other peers and the internet by default. + +--- + +## ✨ WGRplane Features + +- **Go-Native Architecture**: Single Go binary handles all API, database, webhooks, scheduler, and nftables. No Python/Flask needed. +- **Complete Peer CRUD**: Add, edit, delete peers. Generate QR codes for mobile client import. Export `.conf` configuration files. +- **Hybrid Mode**: `forward` mode (local nftables) or `standalone` mode (webhook to remote servers). +- **2-Column Policy UI**: "Allow Access" column (firewall whitelist CIDR) and "Allow Internet" toggle per peer. +- **Real-time Monitoring**: WebSocket broadcasts peer statistics and traffic every 5 seconds. +- **Automated Scheduling**: Daily cron jobs to delete expired peers, restrict over-limit peers, and reset monthly data usage. +- **Security**: API Key authentication (`wg-rplane-datadunia`), JWT Bearer tokens, and TOTP (2FA). +- **Webhook Engine**: Integration with remote servers (Mikrotik, etc.). Retry with exponential backoff, custom headers, Go templates. +- **Plugin System**: Telegram, Slack, and Traffic Logger notifications. +- **i18n & Themes**: Multi-language (English, Indonesian, Chinese). Dark/Light/Auto mode. +- **Glassmorphism UI**: Futuristic design with frosted glass cards, buttons, and inputs. + +--- + +## πŸ›  WGRplane Tech Stack + +| Component | Technology | +|-----------|------------| +| **Backend** | Go, Gorilla Mux, GORM (SQLite via glebarez/sqlite) | +| **Frontend** | Vue 3, TypeScript, Vite, TailwindCSS 4, vue-i18n 9 | +| **Auth** | JWT (golang-jwt/v5), TOTP (pquerna/otp), API Key | +| **WebSockets** | gorilla/websocket | +| **Webhooks** | Go net/http with retry + exponential backoff | +| **Scheduling** | robfig/cron v3 | +| **QR Code** | skip2/go-qrcode | +| **Email** | jordan-wright/email (SMTP) | +| **Firewall** | Bash, iptables, ipset, nftables, inotify-tools, jq | +| **Container** | Docker (multi-stage build), docker-compose | + +--- + +## 🌐 WGRplane API Endpoints Summary + +All endpoints are served on port **10087**. For complete API documentation with request/response details, see [`app/README.md`](app/README.md) or visit `/swagger/` on your running instance. + +### Authentication + +| Method | Header | Notes | +|--------|--------|-------| +| API Key | `wg-rplane-datadunia: ` | Set via env var `WG_API_KEY`. Default: `test-api-key` | +| JWT | `Authorization: Bearer ` | Expires in 15 minutes. Secret via env var `JWT_SECRET` | +| TOTP | `X-TOTP: ` | Required if user enables TOTP | + +### Main Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/servers` | `GET/POST` | List all servers / Create new server | +| `/api/servers/{id}` | `GET/PUT/DELETE` | Get/Update/Delete server | +| `/api/servers/{id}/peers` | `GET/POST` | List peers / Create new peer | +| `/api/peers/{id}` | `PUT/DELETE` | Update/Delete peer | +| `/api/peers/{id}/config` | `GET` | Download WireGuard `.conf` file | +| `/api/peers/{id}/qrcode` | `GET` | Generate QR code PNG for mobile import | +| `/api/servers/{id}/webhooks` | `GET/POST` | List/Create webhooks | +| `/api/stats` | `GET` | Global statistics | +| `/ws/stats` | WebSocket | Real-time stats broadcast (5s interval) | +| `/swagger/` | - | Interactive Swagger UI documentation | + +--- + +## πŸ“¦ WGRplane Installation + +### Option 1: Docker Compose (Recommended) + +```bash +# Clone repository +git clone https://git.datadunia.com/hainzero/WGRplane.git +cd 03.wireguard-policy + +# Start WGRplane and WireGuard +docker compose up -d + +# Access dashboard at http://localhost:10087 +``` + +### Option 2: Install Script + +```bash +# Run automated installer (Ubuntu/Debian/CentOS) +sudo ./install.sh install + +# Uninstall +sudo ./install.sh uninstall +``` + +### Option 3: Manual Build + +```bash +# Build Go binary +cd app +go build -o ../wgrplane . +cd .. + +# Build frontend +cd app/frontend +npm install && npm run build +cd ../.. + +# Run +./wgrplane +# Server starts on :10087 +``` + +### Option 4: Systemd Service + +```bash +# Install service file +sudo cp wgrplane.service /etc/systemd/system/ +sudo systemctl daemon-reload +sudo systemctl enable wgrplane.service +sudo systemctl start wgrplane.service + +# View logs +journalctl -u wgrplane.service -f +``` + +--- + +## πŸ“ Project Structure + +``` +03.wireguard-policy/ +β”œβ”€β”€ app/ # Go backend + Vue frontend +β”‚ β”œβ”€β”€ main.go # Bootstrap server, routing, init DB +β”‚ β”œβ”€β”€ handlers.go # REST API route handlers +β”‚ β”œβ”€β”€ models.go # GORM models (Server, Peer, Webhook, SMTP) +β”‚ β”œβ”€β”€ auth.go # JWT, TOTP, API key auth middleware +β”‚ β”œβ”€β”€ nftables.go # nftables rule management (mode forward) +β”‚ β”œβ”€β”€ webhook.go # Webhook engine with retry/backoff +β”‚ β”œβ”€β”€ scheduler.go # Cron jobs (expiry, data limit, reset) +β”‚ β”œβ”€β”€ stats.go # WebSocket Hub for real-time stats +β”‚ β”œβ”€β”€ frontend/ # Vue 3 SPA (TypeScript, TailwindCSS) +β”‚ └── docs/ # Swagger documentation +β”œβ”€β”€ wg-sync-policy.sh # Parse wg0.conf β†’ policy.json +β”œβ”€β”€ wg-policy-engine.sh # Apply policy.json β†’ iptables/ipset +β”œβ”€β”€ wg-sync-watch.sh # inotifywait watcher daemon +β”œβ”€β”€ wg-policy-ctl # CLI wrapper for policy management +β”œβ”€β”€ wg-policy-cleanup.sh # Cleanup script for PostDown +β”œβ”€β”€ wg-policy.service # Systemd unit for watcher daemon +β”œβ”€β”€ wgrplane.service # Systemd unit for Go backend +β”œβ”€β”€ install.sh # Automated installer (Docker + services) +β”œβ”€β”€ Dockerfile # Multi-stage Docker build +β”œβ”€β”€ docker-compose.yml # Docker Compose stack +└── README.md # This file +``` + +For detailed WGRplane documentation including webhooks, plugins, scheduler, and frontend details, refer to [`app/README.md`](app/README.md).