NexusGuard SD-WAN Suite

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: The central API and VPN Hub managing database state, token distribution, and Linux firewall isolation.
2. Dashboard UI: The Admin Web GUI for managing Nodes, Users, Devices, and Firewall rules.
3. Device Agent: A stealth background daemon for Linux client machines that establishes memory-injected WireGuard tunnels.

---

🚀 Deployment & Installation

Option A: Docker (Recommended)

Clone this repository and start all services:

git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite
./setup.sh                  # Generate .env file automatically
# Edit .env with your configuration
bash update.sh              # Pull, build, migrate, and start

The first run will automatically:

• Pull the latest code and build the Docker containers (via update.sh).
• Auto-generate the Local Primary Node WireGuard keys on the first boot.
• Create the database schema via automated migration.

Option B: Native (Without Docker)

If you prefer to run the components directly on your host machine, you will need Go 1.25+, Node.js 24+, PostgreSQL, and Redis.

1. Setup Database & Environment Create a PostgreSQL database. Copy .env.example to .env and configure DB_HOST, DB_USER, DB_PASSWORD, and DB_NAME to point to your local database.

2. Start Backend (Server Core)

cd apps/server-core
go mod download
go run -tags dev .

(The dev tag automatically runs migrations and provisions the local node)

3. Start Frontend (Dashboard UI)

cd apps/dashboard-ui
npm install
npm run dev

4. Create Admin Account In a new terminal:

cd apps/server-core
go run -tags dev . -create-admin -user "admin" -pass "YourNewSecurePassword123!"

2. Quick Reference with Makefile

Command	Description
make up	Start all services
make down	Stop all services
make logs	Tail all service logs
make dev	Start with hot-reload (air) for development
make migrate	Run production database migration manually
make reset-db	Reset database to initial state (drops volume, recreates tables, runs migration)

make reset-db is useful during development to wipe all data and start fresh. It stops all containers, deletes the PostgreSQL volume, recreates the tables, and runs the migration in one command.

3. 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.

4. 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:

docker exec -it nexus-guard-suite-server-core-1 ./server-core -create-admin -user "admin" -pass "YourNewSecurePassword123!"

(You can use this exact same command later if you ever forget the admin password to forcefully reset it).

Or using the Makefile directly (requires local Go toolchain):

make migrate
go run -tags dev ./apps/server-core -create-admin -user "admin" -pass "YourNewSecurePassword123!"

---

📖 Operational Workflow

Once the server is running and the Admin account is created, follow this flow:

Managing Nodes

1. Go to the Nodes menu.
2. Click Register Node and fill in:
   • Basic Info: Name, Public Key, Public Endpoint
   • Network Settings: Listen Address, Port, MTU, DNS, IP Pool (CIDR), Interface Address
   • Advanced Overrides: Table (Auto/Off), PreUp/PostDown scripts
   • Peer Defaults: Default DNS, MTU, Keepalive, AllowedIPs for new peers on this node
3. The Interface Address is auto-calculated from the IP Pool CIDR (first usable IP) if left empty.
4. Edit existing nodes to adjust any overrides or peer defaults at any time.

Adding Peers (Devices)

1. Go to the Devices menu.
2. Click + Add Peer.
3. Select the target Node and name the device.
4. Toggle Allow Internet Access for full-tunnel VPN (0.0.0.0/0).
5. After creation, you can:
   • Download the .conf file
   • Show the QR code for mobile apps
   • Copy the config text
   • Generate a Share Link (public, time-limited)
   • Configure Firewall Rules for the peer

Advanced Device Settings

Each device has detailed configuration options in its detail page:

• Allowed IPs: Override the default routing prefix
• DNS / MTU / PersistentKeepalive: Device-level overrides (cascade: device > node defaults > hardcoded defaults)
• Notes: Annotate the device
• Suspend/Unsuspend: Temporarily disable the tunnel without deleting the device

Firewall Rules

Manage per-peer nftables firewall rules directly from the UI:

• Allow/block specific IP ranges and port numbers
• Rules are synced to the server kernel in real-time via nft
• Default SSH access (port 22) is provisioned automatically for new peers

Agent Provisioning (automated device registration)

For automated client deployment with the Device Agent:

1. Create a device from the Devices page.
2. Copy the single-use Registration Token.
3. On the target Linux machine, run:

   sudo ./install_agent.sh --server-url "https://api.yourdomain.com" --token "<REG_TOKEN>"
   

4. The agent will securely provision its WireGuard keys via AES-256-GCM and appear as Online on the Dashboard.