# NexusGuard SD-WAN

**Zero-Trust Network Isolation with Stealth WireGuard Tunneling**

NexusGuard is an SD-WAN system that enforces Zero-Trust network isolation through hardware-bound device identity, nftables-based micro-segmentation, and userspace WireGuard tunneling — all managed from a Vue 3 dashboard.

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                   Dashboard UI                      │
│              (Vue 3 + Vite + Tailwind)              │
└────────────────────┬────────────────────────────────┘
                     │ JWT Auth / REST API
                     ▼
┌──────────────────────────────────────────────────────┐
│                    Server Core                        │
│  (Go + Gin + GORM + PostgreSQL + Redis + nftables)   │
└──────┬─────────────────────────────────────┬─────────┘
       │ encrypted config (AES-256-GCM)      │
       │ heartbeat / provisioning            │
       ▼                                     ▼
┌──────────────┐                     ┌──────────────┐
│ Device Agent │  ─── WireGuard ──▶  │ Device Agent │
│ (Stealth WG) │  peer-to-peer       │ (Stealth WG) │
└──────────────┘                     └──────────────┘
```

## Repository Structure

| Repository | Language | Role |
|---|---|---|
| [server-core](./apps/server-core) | Go 1.25 | REST API, auth, device management, nftables orchestration, IPAM |
| [device-agent](./apps/device-agent) | Go 1.25 | Stealth WireGuard agent, HWID binding, encrypted provisioning |
| [dashboard-ui](./apps/dashboard-ui) | TypeScript / Vue 3 | Management dashboard, device CRUD, firewall rule editor |

## Key Features

- **Zero-Trust Firewall** — nftables default-drop policy with per-user isolation sets
- **Hardware-Bound Identity** — AES-256-GCM key derived from hardware fingerprint (product_uuid / machine-id / cpuinfo)
- **Stealth Tunneling** — pure userspace WireGuard via wireguard-go `IpcSet()`, zero config files on disk
- **Encrypted Provisioning** — one-time registration token + HWID → encrypted WireGuard config (key never transmitted)
- **JWT Auth** — dashboard authentication with 24h token expiry
- **Redis Heartbeat** — real-time device online/offline tracking with 90s TTL
- **IPAM** — automatic IP allocation from configurable CIDR pool (default 10.8.0.0/16)

## Quick Start

### Prerequisites

- Docker + Docker Compose (for local dev)
- Go 1.25+ (for native builds)
- Node 24+ (for dashboard development)

### Clone with Submodules

```bash
git clone --recursive https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
cd Nexus-Guard-Suite
```

If already cloned without `--recursive`:

```bash
git submodule update --init --recursive
```

### Start Server + Database

```bash
cp apps/server-core/.env.example apps/server-core/.env
# edit .env with your secrets
docker-compose up -d
```

This starts PostgreSQL 16, Redis 7, and Server-Core on port 8080.

### Build & Run Dashboard

```bash
cd apps/dashboard-ui
cp .env.example .env
npm install
npm run dev
```

### Deploy Agent on a Linux Host

```bash
# Using the bash installer (requires root)
sudo bash apps/device-agent/scripts/install_agent.sh \
  --server-url http://your-server:8080 \
  --token your-registration-token
```

Or build from source:

```bash
cd apps/device-agent
go build -o sys-bridge .
SERVER_URL=http://your-server:8080 REG_TOKEN=your-token ./sys-bridge
```

## 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 |
| Dashboard | Vue 3, Vite 8, Pinia, Tailwind CSS 4 |
| Dashboard API | Axios, vue-router |
| CI/CD | Gitea Actions |

## Project Phases

| Phase | Status | Description |
|---|---|---|
| Phase 1 — Server Core | ✅ Complete | Go backend, nftables manager, IPAM, crypto, REST API |
| Phase 2 — Device Agent | ✅ Complete | Stealth WireGuard tunnel, HWID discovery, provisioning client |
| Phase 3 — DevOps | ✅ Complete | Docker Compose, bash installer, systemd service, Gitea CI/CD |
| Phase 4 — Dashboard UI | ✅ Complete | Vue 3 dashboard, device CRUD, firewall rule editor |
| Phase 5 — Advanced Docs | ✅ Complete | TLS deployment, STUN, key rotation, peer discovery notes |

## Security Design

- **No agent disk writes**: WireGuard config lives in memory only (IpcSet)
- **Encrypted at rest**: Device private keys encrypted in DB; configs decrypted per-session
- **One-time tokens**: Registration tokens invalidated after first use
- **Auth isolation**: JWT for dashboard ↔ server; X-Token-Auth for agent ↔ server
- **nftables element-level ops**: No `nft flush table`, only individual element add/remove

## Development

```bash
# Run all Go tests
cd apps/server-core && go test ./... -tags dev
cd apps/device-agent && go test ./...

# Run dashboard dev server
cd apps/dashboard-ui && npm run dev

# Full integration test (Linux with nftables)
# See integration smoke tests in plan document
```