{"id":29224749,"url":"https://github.com/friedjof/wireguardadmin","last_synced_at":"2026-04-15T19:36:31.256Z","repository":{"id":302406243,"uuid":"1012328892","full_name":"Friedjof/WireguardAdmin","owner":"Friedjof","description":"A modern web interface for managing WireGuard VPNs with live status, firewall management, and real-time updates.","archived":false,"fork":false,"pushed_at":"2025-07-02T07:27:12.000Z","size":152,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-02T08:35:19.420Z","etag":null,"topics":["admin","api","deshboard","docker","firewall","flask","iptables","linux","management","monitoring","network","peer","python","realtime","security","vpn","webinterface","websocket","wireguard"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Friedjof.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-02T07:03:18.000Z","updated_at":"2025-07-02T07:27:17.000Z","dependencies_parsed_at":"2025-07-02T08:46:29.156Z","dependency_job_id":null,"html_url":"https://github.com/Friedjof/WireguardAdmin","commit_stats":null,"previous_names":["friedjof/wireguardadmin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Friedjof/WireguardAdmin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Friedjof%2FWireguardAdmin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Friedjof%2FWireguardAdmin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Friedjof%2FWireguardAdmin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Friedjof%2FWireguardAdmin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Friedjof","download_url":"https://codeload.github.com/Friedjof/WireguardAdmin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Friedjof%2FWireguardAdmin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263271499,"owners_count":23440396,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admin","api","deshboard","docker","firewall","flask","iptables","linux","management","monitoring","network","peer","python","realtime","security","vpn","webinterface","websocket","wireguard"],"created_at":"2025-07-03T06:07:51.812Z","updated_at":"2025-10-22T21:34:52.528Z","avatar_url":"https://github.com/Friedjof.png","language":"Python","readme":"# 🔐 WireGuard Management System\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=flat\u0026logo=docker\u0026logoColor=white)](https://www.docker.com/)\n[![Flask](https://img.shields.io/badge/flask-%23000.svg?style=flat\u0026logo=flask\u0026logoColor=white)](https://flask.palletsprojects.com/)\n[![CI/CD](https://img.shields.io/badge/CI%2FCD-GitHub%20Actions-green.svg)](https://github.com/features/actions)\n[![Tests](https://img.shields.io/badge/Tests-Pytest-orange.svg)](https://pytest.org/)\n[![Code Style](https://img.shields.io/badge/Code%20Style-Black-black.svg)](https://black.readthedocs.io/)\n\nA professional, enterprise-ready web application for managing WireGuard VPN peers with **real-time monitoring**, **advanced firewall management**, and **WebSocket-powered live updates**.\n\n\u003e ⚠️ **Development Status**: This project is actively under development. The firewall management and VPN functionality are experimental and may contain bugs. Use with caution in production environments.\n\n## ✨ **Key Features**\n\n### 🚀 **Real-Time Monitoring**\n- **Live Status Updates** via WebSockets (2-second intervals)\n- **Traffic Graphs** showing upload/download rates for last 40 seconds\n- **Connection Monitoring** with visual indicators\n- **Automatic Reconnection** with fallback to HTTP polling\n\n### 👥 **Advanced Peer Management**\n- **Auto-IP Assignment** with conflict detection\n- **Bulk Operations** with validation\n- **Multiple Allowed IPs** with descriptions\n- **QR Code Generation** for mobile devices\n- **Configuration Export** (file download + API)\n\n### 🛡️ **Enterprise Firewall Management** ⚠️ *Experimental*\n- **iptables Integration** with rule preview\n- **Security Templates** (Admin, Guest, Restricted, etc.)\n- **Custom Rule Builder** with priorities\n- **Terminal-Style Interface** for rule management\n- **Dry-Run Testing** before applying rules\n- *Note: Firewall features are experimental and may require manual intervention*\n\n### 🔧 **Professional Architecture**\n- **REST API** with full CRUD operations\n- **WebSocket Events** for real-time communication\n- **Docker Support** with production-ready setup\n- **Modular Design** with separated concerns\n- **Comprehensive Logging** and error handling\n\n## 🎯 **Quick Start**\n\n### **Using Make Commands (Recommended)**\n\n```bash\n# Clone repository\ngit clone https://github.com/Friedjof/WireguardAdmin.git\ncd wireguard-management\n\n# Show all available commands\nmake help\n\n# Setup development environment\nmake setup\n\n# Run tests and linting\nmake check\n\n# Start development server\nmake dev\n```\n\n### **Docker Deployment**\n\n```bash\n# Configure environment\ncp .env.example .env\n# Edit .env with your server details\n\n# Build and start with Docker\nmake build\nmake up\n\n# Check status\nmake status\n\n# Access web interface\nopen http://localhost:5000\n```\n\n### **Manual Installation**\n\n```bash\n# Install system dependencies\nsudo apt update\nsudo apt install wireguard-tools iptables python3 python3-pip\n\n# Clone and setup\ngit clone https://github.com/Friedjof/WireguardAdmin.git\ncd wireguard-management\n\n# Setup with Make\nmake setup\n\n# Or manually\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n\n# Configure environment\ncp .env.example .env\n# Edit .env with your configuration\n\n# Run application\npython app.py\n```\n\n## 📊 **Screenshots \u0026 Demo**\n\n\u003cdetails\u003e\n\u003csummary\u003e🖼️ **Click to view screenshots**\u003c/summary\u003e\n\n### Dashboard with Real-Time Monitoring\n![Dashboard](docs/images/dashboard.png)\n\n### Peer Details with Traffic Graph\n![Peer Details](docs/images/peer-details.png)\n\n### Firewall Management Console\n![Firewall Console](docs/images/firewall-console.png)\n\n### Mobile QR Code Setup\n![QR Code](docs/images/qr-code.png)\n\n\u003c/details\u003e\n\n## 🏗️ **Architecture**\n\n```\nwireguard-management/\n├── 📁 app/                    # Core application\n│   ├── 🐍 __init__.py        # Flask app \u0026 WebSocket setup\n│   ├── 🗃️  models.py          # Database models\n│   ├── 🛣️  routes.py          # Web routes \u0026 API endpoints\n│   ├── ⚙️  utils.py           # Utility functions\n│   ├── 🔥 iptables_manager.py # Firewall management\n│   ├── 📡 websocket_manager.py # Real-time updates\n│   ├── 🔌 websocket_events.py # WebSocket event handlers\n│   └── 📊 wireguard_status.py # Status monitoring\n├── 📁 static/                 # Frontend assets\n│   ├── 🎨 css/               # Stylesheets\n│   └── ⚡ js/                # JavaScript modules\n├── 📁 templates/              # Jinja2 templates\n├── 📁 docker/                 # Docker configuration\n├── 📁 docs/                   # Documentation\n├── 📁 scripts/                # Utility scripts\n└── 🐳 docker-compose.yml     # Production setup\n```\n\n## 🔌 **API Reference**\n\n### **Peer Management**\n```http\nGET    /api/v1/peers              # List all peers\nPOST   /api/v1/peers              # Create new peer\nGET    /api/v1/peers/{id}         # Get peer details\nPUT    /api/v1/peers/{id}         # Update peer\nDELETE /api/v1/peers/{id}         # Delete peer\nPOST   /api/v1/peers/{id}/toggle  # Toggle peer status\n```\n\n### **Real-Time WebSocket Events**\n```javascript\n// Connect to WebSocket\nconst socket = io();\n\n// Listen for real-time updates\nsocket.on('peer_status_update', (data) =\u003e {\n  // data.data contains all peer statuses\n  // data.data[peerId].graph_data contains traffic history\n});\n\n// Activate/deactivate peers\nsocket.emit('peer_action', {\n  peer_id: 123,\n  action: 'activate' // or 'deactivate'\n});\n```\n\n### **Firewall Management**\n```http\nGET  /api/v1/firewall/status           # Check iptables access\nGET  /api/v1/firewall/rules/generate   # Preview generated rules\nPOST /api/v1/firewall/rules/apply      # Apply rules to system\nPOST /api/v1/firewall/backup           # Backup current rules\n```\n\n## 🛡️ **Security Features**\n\n\u003e ⚠️ **Security Notice**: This application manages critical network infrastructure. The firewall and VPN features are experimental and should be thoroughly tested before production use. Always maintain backup access to your server.\n\n### **Built-in Security**\n- ✅ **Input Validation** with SQLAlchemy ORM protection\n- ✅ **Rate Limiting** on API endpoints\n- ✅ **CSRF Protection** on forms\n- ✅ **Secure Headers** with Flask-Talisman\n- ✅ **Environment-based Secrets** (no hardcoded keys)\n\n### **Network Security** ⚠️ *Experimental*\n- ⚠️ **iptables Integration** with custom rules *(may require manual fixes)*\n- ⚠️ **Firewall Templates** for different security levels *(test thoroughly)*\n- ⚠️ **Peer Isolation** options *(experimental feature)*\n- ✅ **Traffic Monitoring** and logging\n\n### **Production Deployment**\n- ✅ **Docker Security** with non-root user\n- ✅ **Reverse Proxy** support (nginx/Traefik)\n- ✅ **SSL/TLS** certificate integration\n- ✅ **Environment Isolation** with Docker networks\n\n## ⚙️ **Configuration**\n\n### **Environment Variables**\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `SERVER_PUBLIC_IP` | Your server's public IP/domain | - | ✅ |\n| `SERVER_PRIVATE_KEY` | WireGuard server private key | - | ✅ |\n| `SERVER_PUBLIC_KEY` | WireGuard server public key | - | ✅ |\n| `LISTEN_PORT` | WireGuard listen port | `51820` | ❌ |\n| `VPN_SUBNET` | VPN internal network | `10.0.0.0/24` | ❌ |\n| `FLASK_ENV` | Flask environment | `production` | ❌ |\n\n### **Docker Configuration**\n\n```yaml\n# docker-compose.yml\nservices:\n  vpn-manager:\n    build: .\n    ports:\n      - \"5000:5000\"      # Web interface\n      - \"51820:51820/udp\" # WireGuard\n    environment:\n      - SERVER_PUBLIC_IP=your-server.com\n      - SERVER_PRIVATE_KEY=your_private_key\n      - SERVER_PUBLIC_KEY=your_public_key\n    volumes:\n      - ./instance:/app/instance    # Database persistence\n      - ./logs:/app/logs           # Logs\n      - ./backups:/app/backups     # Backups\n```\n\n## 🔧 **Development**\n\n### **Quick Development Setup**\n\n```bash\n# Clone repository\ngit clone https://github.com/Friedjof/WireguardAdmin.git\ncd wireguard-management\n\n# Complete setup with one command\nmake setup\n\n# Show all available commands\nmake help\n```\n\n### **Development Commands**\n\n#### **🔧 Setup \u0026 Development**\n```bash\nmake setup          # Setup development environment\nmake install        # Install dependencies (alias for setup)\nmake dev            # Start development server\nmake clean          # Clean up development environment\n```\n\n#### **🧪 Testing \u0026 Quality**\n```bash\nmake test           # Run all tests\nmake test-watch     # Run tests in watch mode\nmake lint           # Run linting checks (dry-run)\nmake format         # Format code with Black\nmake check          # Run all checks (lint + test)\n```\n\n#### **🐳 Docker Operations**\n```bash\nmake build          # Build Docker container\nmake up             # Start system (Docker)\nmake down           # Stop system (Docker)\nmake logs           # Show container logs\nmake shell          # Open shell in container\nmake restart        # Restart system\nmake docker-clean   # Clean Docker resources\n```\n\n#### **📊 Monitoring \u0026 Operations**\n```bash\nmake status         # Show system status\nmake keys           # Show WireGuard server keys\nmake backup         # Create backup of configuration\n```\n\n### **CI/CD Pipeline**\n\nThe project includes automated CI/CD with GitHub Actions:\n\n- **Automated Testing**: All tests run on every push\n- **Code Quality**: Flake8 linting and Black formatting checks\n- **Release Automation**: Docker images built on version tags (`v*`)\n- **Container Registry**: Images pushed to GitHub Container Registry\n\n#### **Release Process**\n```bash\n# Create and push a release tag\ngit tag v1.0.0\ngit push origin v1.0.0\n\n# This automatically triggers:\n# 1. Run tests and linting\n# 2. Build Docker image\n# 3. Push to registry\n# 4. Create GitHub release\n```\n\n## 📋 **Requirements**\n\n### **System Requirements**\n- **Linux Server** (Ubuntu 22.04+ recommended)\n- **WireGuard Tools** (`wireguard-tools` package)\n- **iptables** (for firewall management)\n- **Docker** and **Docker Compose** (for containerized deployment)\n- **Make** (for development commands)\n\n### **Python Requirements**\n- **Python 3.12+**\n- **pytest** (testing framework)\n- **flake8** (code linting)\n- **black** (code formatting)\n- See `requirements.txt` for complete list\n\n### **Network Requirements**\n- **Open Port 51820/UDP** (WireGuard)\n- **Open Port 5000/TCP** (Web interface, can be proxied)\n- **Root Access** (for WireGuard and iptables management)\n\n## 🤝 **Contributing**\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### **Development Workflow**\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### **Bug Reports**\nPlease use the [GitHub Issues](https://github.com/Friedjof/WireguardAdmin/issues) for bug reports and feature requests.\n\n## 📄 **License**\n\nThis project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 **Acknowledgments**\n\n- **WireGuard** team for the amazing VPN technology\n- **Flask** community for the excellent web framework\n- **Bootstrap** team for the responsive UI components\n- **Chart.js** for beautiful traffic visualization\n- **Socket.IO** for real-time communication\n\n## 📞 **Support**\n\n- 📖 **Documentation**: [Wiki](https://github.com/Friedjof/WireguardAdmin/wiki)\n- 🐛 **Bug Reports**: [Issues](https://github.com/Friedjof/WireguardAdmin/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/Friedjof/WireguardAdmin/discussions)\n- 📧 **Email**: dev@noweck.info\n\n---\n\n⭐ **Star this repository if it helped you!**\n\nMade with ❤️ by [Friedjof](https://github.com/Friedjof)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriedjof%2Fwireguardadmin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffriedjof%2Fwireguardadmin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriedjof%2Fwireguardadmin/lists"}