Nexus-Guard-Suite/README.md

# 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](http://git.datadunia.com/nexusguard/nexus-server-core)**: The central API and VPN Hub managing database state, token distribution, and Linux firewall isolation.
2. **[Dashboard UI](http://git.datadunia.com/nexusguard/nexus-dashboard-ui)**: The Admin Web GUI for managing Nodes, Users, Devices, and Firewall rules.
3. **[Device Agent](http://git.datadunia.com/nexusguard/nexus-device-agent)**: A stealth background daemon for Linux client machines that establishes memory-injected WireGuard tunnels.

---

## 🚀 Deployment & Installation

### 1. Initial Setup
Clone this repository and start all services:

```bash
git clone https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite
cp .env.example .env        # Edit .env with your configuration
make up                     # Start all services (PostgreSQL, Redis, Server-Core, Dashboard UI)
```

The first run will automatically:
- Create the database schema via GORM AutoMigrate.
- Boot up all required infrastructure via Docker Compose.

### 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:

```bash
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):
```bash
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:
   ```bash
   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.