diff --git a/README.md b/README.md index 319deec..62babe1 100644 --- a/README.md +++ b/README.md @@ -1,157 +1,57 @@ # NexusGuard SD-WAN Suite -NexusGuard is an Enterprise Zero-Trust SD-WAN solution built with Go, Vue 3, and WireGuard. - -## System Architecture +NexusGuard is an Enterprise Zero-Trust SD-WAN solution built with Go, Vue 3, and WireGuard. It enables stealth VPN tunneling, centralized IPAM, and real-time network isolation via `nftables`. +## πŸ—οΈ System Architecture This suite contains three main components: - -1. **[Server Core (Master/Hub)](http://git.datadunia.com/nexusguard/nexus-server-core)** β€” The central API and VPN Hub managing IPAM, routing, and `nftables` isolation. -2. **[Dashboard UI](http://git.datadunia.com/nexusguard/nexus-dashboard-ui)** β€” The Admin web interface for managing users, devices, and firewall rules. -3. **[Device Agent](http://git.datadunia.com/nexusguard/nexus-device-agent)** β€” A stealth background service for client machines that establishes secure WireGuard tunnels. - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” JWT Auth β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Dashboard UI β”‚ ────────────────▢ β”‚ Server Core β”‚ -β”‚ (Vue 3 / Vite) β”‚ ◀──────────────── β”‚ (Go / Gin/GORM) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ REST API :8080 β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - AES-256-GCM Config β”‚ Heartbeat - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β–Ό β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚Device Agent │◀─ WireGuard ─│Device Agent β”‚ - β”‚(stealth WG) β”‚ tunnel β”‚(stealth WG) β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` +1. **[Server Core](apps/server-core/README.md)**: The central API and VPN Hub managing database state, token distribution, and Linux firewall isolation. +2. **[Dashboard UI](apps/dashboard-ui/README.md)**: The Admin Web GUI for managing Nodes, Users, Devices, and Firewall rules. +3. **[Device Agent](apps/device-agent/README.md)**: A stealth background daemon for Linux client machines that establishes memory-injected WireGuard tunnels. --- -## Complete Workflow Guide +## πŸš€ Deployment & Installation -### 1. Clone Repository +### 1. Initial Setup +To deploy the entire backend infrastructure (PostgreSQL, Redis, and Server-Core), simply clone this repository and run the setup script: ```bash -git clone --recursive http://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git +git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git cd Nexus-Guard-Suite +chmod +x setup.sh +./setup.sh ``` -### 2. Start Infrastructure (Docker) +The `setup.sh` script will automatically: +- Create a master `.env` file (if it doesn't exist). +- Boot up all required infrastructure via `docker-compose`. + +### 2. Domain & Port Configuration +If you are deploying this to production, you must edit the `.env` file generated in the root directory: +- **Change API Port**: Modify `API_PORT=8080`. +- **Change Web/API Domain**: Modify `VITE_API_BASE_URL` to point to your public API domain (e.g., `https://api.yourdomain.com/api/v1`). +- **Database & Crypto**: Ensure you change the default database passwords and generate secure 256-bit Hex keys for `JWT_SECRET` and `SERVER_SALT`. + +### 3. Creating / Changing the Admin Account +The system operates on a strict **Zero-Attack Surface** policy. The `/auth/register` API is locked down. To create the first Admin user (or reset their password), you must execute a command directly inside the running Docker container: ```bash -cp apps/server-core/.env.example .env -# edit .env β€” at minimum ganti JWT_SECRET dan SERVER_SALT -docker compose up -d +docker exec -it nexus-guard-suite-server-core-1 ./server-core -create-admin -user "admin" -pass "YourNewSecurePassword123!" ``` - -Ini akan menjalankan: -- **PostgreSQL 16** β€” database utama -- **Redis 7** β€” heartbeat/cache -- **Server Core** β€” API server port `:8080` - -### 3. Create Admin User - -Server berjalan di container. Untuk membuat admin user pertama, jalankan: - -```bash -# Lihat container name -docker compose ps - -# Exec ke container server-core -docker compose exec server-core ./server-core -create-admin -user "admin" -pass "PasswordKuat123!" -``` - -Atau jika build dari source: -```bash -cd apps/server-core -go run . -create-admin -user "admin" -pass "PasswordKuat123!" -``` - -Perintah ini membuat user `admin` dengan password yang sudah di-hash bcrypt di PostgreSQL. - -### 4. Start Dashboard UI - -```bash -cd apps/dashboard-ui -cp .env.example .env -npm install -npm run dev -``` - -Buka `http://localhost:5173` dan login dengan user `admin` yang dibuat di step 3. - -### 5. Create Regular Users - -Hanya user bernama `admin` yang bisa membuat user lain. Setelah login sebagai `admin`: -1. Buka Dashboard UI -2. Register user baru (fitur register hanya visible untuk admin) - -### 6. Register Device - -1. Login ke Dashboard sebagai user biasa -2. Klik **"+ New Device"**, masukkan nama device -3. Copy **Registration Token** yang muncul -4. Install agent di mesin client: - -```bash -sudo bash apps/device-agent/scripts/install_agent.sh \ - --server-url "http://:8080" \ - --token "" -``` - -5. Device akan muncul sebagai **Online** di Dashboard. +*(You can use this exact same command later if you ever forget the admin password to forcefully reset it).* --- -## Repository Structure +## πŸ“– Operational Workflow -``` -Nexus-Guard-Suite/ -β”œβ”€β”€ apps/ -β”‚ β”œβ”€β”€ server-core/ β†’ http://git.datadunia.com/nexusguard/nexus-server-core -β”‚ β”œβ”€β”€ device-agent/ β†’ http://git.datadunia.com/nexusguard/nexus-device-agent -β”‚ └── dashboard-ui/ β†’ http://git.datadunia.com/nexusguard/nexus-dashboard-ui -β”œβ”€β”€ docker-compose.yml β†’ PostgreSQL + Redis + Server Core -β”œβ”€β”€ docker-compose.dev.yml -β”œβ”€β”€ setup.sh β†’ Start Docker -β”œβ”€β”€ upgrade.sh β†’ Git pull + Docker restart -└── update_repo.sh β†’ Git pull only (Docker tetap stop) -``` +Once the server is running and the Admin account is created, follow this flow: -## Tech Stack - -| Component | Technology | -|---|---| -| Backend API | Go 1.25, Gin, GORM | -| Database | PostgreSQL 16 | -| Cache & Heartbeat | Redis 7 | -| Firewall | nftables (google/nftables) | -| Tunneling | wireguard-go (userspace) | -| Cryptography | AES-256-GCM, SHA-256, bcrypt | -| Dashboard | Vue 3, Vite 8, Pinia, Tailwind CSS 4 | -| CI/CD | Gitea Actions | - -## Quick Reference - -```bash -# Start all services -./setup.sh - -# Update code + restart (Docker down β†’ git pull β†’ docker up) -./upgrade.sh - -# Update code only (Docker tetap stop) -./update_repo.sh - -# Create admin via Docker -docker compose exec server-core ./server-core -create-admin -user admin -pass "pass123" - -# View logs -docker compose logs -f server-core - -# Rebuild + restart -docker compose up -d --build - -# Stop everything -docker compose down -``` +1. **Log in to the Dashboard UI** using the `admin` credentials. +2. **Register a WireGuard Node**: Go to the **Nodes** menu. Add your public WireGuard server endpoint (e.g., `vpn.yourdomain.com:51820`) and its Public Key. +3. **Add a Device**: Go to the **Devices** menu. Click **+ New Device**, select the target Node, and name the device. +4. **Copy the Token**: The system will display a single-use **Registration Token**. +5. **Install the Agent on Client**: On the target Linux machine, run the agent installer: + ```bash + sudo ./install_agent.sh --server-url "https://api.yourdomain.com" --token "" + ``` +6. The client will automatically connect, provision its WireGuard keys securely via AES-256-GCM, and appear as **Online** on your Dashboard. diff --git a/apps/dashboard-ui b/apps/dashboard-ui index 4ec0053..924c811 160000 --- a/apps/dashboard-ui +++ b/apps/dashboard-ui @@ -1 +1 @@ -Subproject commit 4ec0053605e07653b59dd562c05c74f2e2e6e4b1 +Subproject commit 924c811d5397f16a3064c03023042e2d284d6767 diff --git a/apps/device-agent b/apps/device-agent index 05b65fd..2646fd7 160000 --- a/apps/device-agent +++ b/apps/device-agent @@ -1 +1 @@ -Subproject commit 05b65fdc8a15320f607b3929c9dcd2545802dd63 +Subproject commit 2646fd74c69a03d4366857a9778ee3985ec00362 diff --git a/apps/server-core b/apps/server-core index 5bda512..0bf53bc 160000 --- a/apps/server-core +++ b/apps/server-core @@ -1 +1 @@ -Subproject commit 5bda512e054fd3c8e796c006d2202fd02ded5cf3 +Subproject commit 0bf53bc912c27814aad91e0ffaa4f6166d5db57b