diff --git a/README.md b/README.md index 4e05bd5..f82048b 100644 --- a/README.md +++ b/README.md @@ -1,148 +1,37 @@ -# NexusGuard SD-WAN +# NexusGuard SD-WAN Suite -**Zero-Trust Network Isolation with Stealth WireGuard Tunneling** +NexusGuard is an Enterprise Zero-Trust SD-WAN solution built with Go, Vue 3, and WireGuard. -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. +## System Architecture +This suite contains three main components: +1. **[Server Core (Master/Hub)](apps/server-core/README.md)**: The central API and VPN Hub managing IPAM, routing, and `nftables` isolation. +2. **[Dashboard UI](apps/dashboard-ui/README.md)**: The Admin web interface for managing users, devices, and firewall rules. +3. **[Device Agent](apps/device-agent/README.md)**: A stealth background service for client machines that establishes secure WireGuard tunnels. -## 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 +## Complete Workflow Guide +### 1. Initial Setup & Creating the Admin (Terminal) +For maximum security, the initial administrator account **cannot** be created via the web. It must be created directly on the server via the terminal. +Inside the `apps/server-core` directory (or inside your docker container), run: ```bash -git clone --recursive https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git -cd Nexus-Guard-Suite +go run . -create-admin -user "admin" -pass "YourSecurePassword123" ``` +*(This command creates the superuser `admin` in the database).* -If already cloned without `--recursive`: +### 2. Creating Regular Users (Web Dashboard) +1. Open the **Dashboard UI** in your web browser. +2. Log in using the `admin` credentials created in Step 1. +3. Once logged in as `admin`, you have the authorization to create regular User accounts for your team members. +*(Note: Public registration is disabled. Only the `admin` can provision new users).* -```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 -``` +### 3. Registering a Device +1. A User logs into the Dashboard UI using their assigned account. +2. They click **"+ New Device"** and enter a recognizable name (e.g., "Johns-Laptop"). +3. The Dashboard will display a one-time **Registration Token**. +4. The user copies this token and runs the agent installer on their machine: + ```bash + sudo ./install_agent.sh --server-url "http://:8080" --token "" + ``` +5. The device connects, binds its Hardware ID securely, provisions its WireGuard keys, and appears as **Online** in the Dashboard. diff --git a/apps/dashboard-ui b/apps/dashboard-ui index dadf979..b2c0f1c 160000 --- a/apps/dashboard-ui +++ b/apps/dashboard-ui @@ -1 +1 @@ -Subproject commit dadf97979d14884cbebd6c330a50b1d37ea97fbd +Subproject commit b2c0f1cc73ff37703c9ec4871b588a6892d06c0f diff --git a/apps/device-agent b/apps/device-agent index 4ce0a1e..60ca014 160000 --- a/apps/device-agent +++ b/apps/device-agent @@ -1 +1 @@ -Subproject commit 4ce0a1e8f6906d8b8cc2ef212e23248b5f758422 +Subproject commit 60ca0145389b53186eb92f958b7fff27caf526ad diff --git a/apps/server-core b/apps/server-core index 6b9e33b..b99af3a 160000 --- a/apps/server-core +++ b/apps/server-core @@ -1 +1 @@ -Subproject commit 6b9e33bc04ff269be8206e325f1fa0ec2b32c8da +Subproject commit b99af3a316679de4802f01622f94efc09b7c6d40