datadunia
149 lines
5.6 KiB
Markdown
149 lines
5.6 KiB
Markdown
# 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
|
|
```
|