docs: add comprehensive README for all repos

2026-05-15 17:15:34 +07:00
parent aee72d371d
commit a52facb1f9
4 changed files with 151 additions and 3 deletions
@@ -0,0 +1,148 @@
+# 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
+```