# Namespace + VRF Architecture > Enterprise Network Isolation for NexusGuard SD-WAN ## Overview This document describes the **Namespace + VRF** architecture for enterprise-grade network isolation. This is a **reference architecture** for future development — not currently implemented. ## Problem Statement Current architecture has limitations: 1. **Single routing domain** — All users share same kernel routing table 2. **IP conflicts** — Same IP on different WgServers causes routing issues 3. **No user isolation** — Users can see each other's traffic 4. **API access control** — Limited multi-user support per namespace ## Solution: Network Namespace + VRF ### Layer 1: Network Namespace (Kernel Isolation) Network namespace provides **complete network stack isolation**: ``` ┌─────────────────────────────────────────────────────────┐ │ Linux Kernel │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Default Namespace (root) │ │ │ │ ├── eth0 (mgmt interface) │ │ │ │ ├── wg0 (server WireGuard) │ │ │ │ └── nftables (global rules) │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Namespace: ns_zerocode │ │ │ │ ├── lo (loopback) │ │ │ │ ├── veth0 (virtual ethernet) │ │ │ │ ├── WireGuard interfaces │ │ │ │ └── nftables (isolated rules) │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Namespace: ns_alice │ │ │ │ ├── lo (loopback) │ │ │ │ ├── veth0 (virtual ethernet) │ │ │ │ ├── WireGuard interfaces │ │ │ │ └── nftables (isolated rules) │ │ │ └──────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ ``` **What's isolated per namespace:** - Network interfaces - Routing tables - iptables/nftables rules - `/proc/net` entries - Socket bindings ### Layer 2: VRF (Routing Isolation within Namespace) VRF provides **routing table isolation** within a namespace: ``` ┌─────────────────────────────────────────────────────────┐ │ Namespace: ns_zerocode │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ VRF: vrf_main (table 100) │ │ │ │ ├── wg-z-main (10.100.0.1/24) │ │ │ │ │ ├── Device A: 10.100.0.2 │ │ │ │ │ └── Device B: 10.100.0.3 │ │ │ │ └── Routing table 100 │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ VRF: vrf_isolated (table 200) │ │ │ │ ├── wg-z-iso (10.200.0.1/24) │ │ │ │ │ └── Device C: 10.200.0.2 │ │ │ │ └── Routing table 200 │ │ │ └──────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ ``` **What's isolated per VRF:** - Routing tables - Gateway routes - Policy routing ### Layer 3: API Access Control (Multi-User) Multi-control user access per namespace: ``` ┌─────────────────────────────────────────────────────────┐ │ Namespace: ns_zerocode │ │ │ │ Users: │ │ ├── zerocode (admin) → Full API access │ │ ├── bob (operator) → Limited API access │ │ └── charlie (viewer) → Read-only API access │ │ │ │ API Endpoints: │ │ ├── POST /api/v1/ns/zerocode/devices [admin] │ │ ├── GET /api/v1/ns/zerocode/devices [all] │ │ ├── PUT /api/v1/ns/zerocode/devices/:id [admin] │ │ ├── DELETE /api/v1/ns/zerocode/devices/:id [admin] │ │ └── GET /api/v1/ns/zerocode/status [all] │ └─────────────────────────────────────────────────────────┘ ``` ## Data Model ### Current Model ``` User └── Device └── WgServer ``` ### Proposed Model ``` User ├── Namespace (1:1) │ ├── NamespaceUser (N:N with role) │ └── VRF (1:N) │ └── WgServer (1:N) │ └── Device (1:N) └── Device (legacy, for backward compatibility) ``` ### Database Schema ```sql -- Namespace (1 per user, or shared) CREATE TABLE namespaces ( id UUID PRIMARY KEY, name VARCHAR(64) UNIQUE NOT NULL, -- e.g., "zerocode" owner_id UUID REFERENCES users(id), created_at TIMESTAMP, updated_at TIMESTAMP ); -- Namespace users (multi-control) CREATE TABLE namespace_users ( id UUID PRIMARY KEY, namespace_id UUID REFERENCES namespaces(id), user_id UUID REFERENCES users(id), role VARCHAR(16) NOT NULL, -- admin, operator, viewer created_at TIMESTAMP, UNIQUE(namespace_id, user_id) ); -- VRF (per namespace) CREATE TABLE vrfs ( id UUID PRIMARY KEY, namespace_id UUID REFERENCES namespaces(id), name VARCHAR(64) NOT NULL, -- e.g., "main", "isolated" table_id INTEGER NOT NULL, -- routing table ID created_at TIMESTAMP, UNIQUE(namespace_id, name) ); -- WgServer (per VRF) ALTER TABLE wg_servers ADD COLUMN vrf_id UUID REFERENCES vrfs(id); ALTER TABLE wg_servers ADD COLUMN namespace_id UUID REFERENCES namespaces(id); ``` ## API Design ### Namespace API ``` POST /api/v1/namespaces # Create namespace GET /api/v1/namespaces # List namespaces (admin only) GET /api/v1/namespaces/:name # Get namespace details DELETE /api/v1/namespaces/:name # Delete namespace POST /api/v1/namespaces/:name/users # Add user to namespace DELETE /api/v1/namespaces/:name/users/:id # Remove user PUT /api/v1/namespaces/:name/users/:id # Update user role ``` ### VRF API ``` POST /api/v1/ns/:namespace/vrfs # Create VRF GET /api/v1/ns/:namespace/vrfs # List VRFs GET /api/v1/ns/:namespace/vrfs/:name # Get VRF details DELETE /api/v1/ns/:namespace/vrfs/:name # Delete VRF ``` ### Server API (Namespace-scoped) ``` POST /api/v1/ns/:namespace/servers # Create server in VRF GET /api/v1/ns/:namespace/servers # List servers GET /api/v1/ns/:namespace/servers/:id # Get server details DELETE /api/v1/ns/:namespace/servers/:id # Delete server ``` ### Device API (Namespace-scoped) ``` POST /api/v1/ns/:namespace/devices # Create device GET /api/v1/ns/:namespace/devices # List devices GET /api/v1/ns/:namespace/devices/:id # Get device details DELETE /api/v1/ns/:namespace/devices/:id # Delete device ``` ## Kernel Commands ### Create Namespace ```bash # Create namespace ip netns add ns_zerocode # Create veth pair (connect to default namespace) ip link add veth0 type veth peer name veth1 ip link set veth1 netns ns_zerocode # Configure veth in default namespace ip addr add 10.0.0.1/24 dev veth0 ip link set veth0 up # Configure veth in namespace ip netns exec ns_zerocode ip addr add 10.0.0.2/24 dev veth1 ip netns exec ns_zerocode ip link set veth1 up ip netns exec ns_zerocode ip route add default via 10.0.0.1 ``` ### Create VRF in Namespace ```bash # Create VRF ip netns exec ns_zerocode ip link add vrf:main type vrf table 100 ip netns exec ns_zerocode ip link set vrf:main up # Create WireGuard interface ip netns exec ns_zerocode ip link add wg-z-main type wireguard # Bind WG to VRF ip netns exec ns_zerocode ip link set wg-z-main vrf vrf:main # Configure WG ip netns exec ns_zerocode ip addr add 10.100.0.1/24 dev wg-z-main ip netns exec ns_zerocode wg set wg-z-main listen-port 51820 private-key /path/to/key # Add routes to VRF table ip netns exec ns_zerocode ip route add 10.100.0.0/24 dev wg-z-main table 100 ``` ### Configure nftables in Namespace ```bash # Create table in namespace ip netns exec ns_zerocode nft add table ip nexusguard # Create chains ip netns exec ns_zerocode nft add chain ip nexusguard forward '{type filter hook forward priority filter; policy accept;}' ip netns exec ns_zerocode nft add chain ip nexusguard input '{type filter hook input priority filter; policy accept;}' # Add rules ip netns exec ns_zerocode nft add rule ip nexusguard forward iifname wg-z-main accept ``` ## Use Cases ### Use Case 1: Multi-Tenant SD-WAN ``` Company A (zerocode) └── Namespace: ns_zerocode ├── VRF: production → wg-prod (10.10.0.0/24) └── VRF: staging → wg-staging (10.20.0.0/24) Company B (alice) └── Namespace: ns_alice └── VRF: main → wg-main (10.10.0.0/24) ← Same IP, isolated! ``` ### Use Case 2: Development/Testing Isolation ``` Developer: bob └── Namespace: ns_bob_dev └── VRF: dev → wg-dev (10.100.0.0/24) QA Team └── Namespace: ns_qa └── VRF: test → wg-test (10.100.0.0/24) ← Same IP, isolated! ``` ### Use Case 3: Compliance Isolation ``` PCI DSS Workload └── Namespace: ns_pci └── VRF: pci → wg-pci (10.50.0.0/24) HIPAA Workload └── Namespace: ns_hipaa └── VRF: hipaa → wg-hipaa (10.60.0.0/24) ``` ## Implementation Phases ### Phase 1: Database Schema (Week 1) - [ ] Create namespaces table - [ ] Create namespace_users table - [ ] Create vrfs table - [ ] Add VRF fields to wg_servers - [ ] Migration scripts ### Phase 2: Namespace Manager (Week 2) - [ ] Namespace CRUD operations - [ ] User-role management - [ ] API access control middleware ### Phase 3: VRF Manager (Week 3) - [ ] VRF CRUD operations - [ ] Kernel VRF commands - [ ] Routing table management ### Phase 4: WireGuard Integration (Week 4) - [ ] WG creation in namespace - [ ] WG binding to VRF - [ ] Peer management in namespace ### Phase 5: Firewall Integration (Week 5) - [ ] nftables per namespace - [ ] Rules per VRF - [ ] Cross-namespace isolation ### Phase 6: API Gateway (Week 6) - [ ] Namespace-scoped API routes - [ ] Authentication per namespace - [ ] Authorization per role ### Phase 7: Dashboard UI (Week 7) - [ ] Namespace management UI - [ ] VRF configuration UI - [ ] User-role management UI ### Phase 8: Testing & Documentation (Week 8) - [ ] Unit tests - [ ] Integration tests - [ ] Documentation - [ ] Deployment guide ## Resource Overhead | Resource | Per Namespace | Per VRF | Total (10 users, 2 VRFs each) | |----------|---------------|---------|--------------------------------| | Network namespaces | 1 | 0 | 10 | | VRF devices | 0 | 1 | 20 | | Routing tables | 1 | 1 | 30 | | nftables tables | 1 | 0 | 10 | | Memory overhead | ~1MB | ~10KB | ~12MB | ## Security Considerations 1. **Namespace isolation** — Complete network stack isolation 2. **VRF isolation** — Routing table isolation within namespace 3. **API access control** — Role-based access per namespace 4. **Audit logging** — Track all namespace/VRF operations 5. **Resource limits** — Prevent namespace exhaustion ## Comparison with Current Architecture | Aspect | Current | Namespace + VRF | |--------|---------|-----------------| | Isolation level | Routing only | Full network stack | | IP conflicts | Possible | Impossible (per namespace) | | API access | Global | Per namespace | | Resource overhead | Low | Medium | | Complexity | Low | High | | Scalability | Good | Good (with limits) | ## References - Linux Network Namespaces: `man ip-netns` - Linux VRF: `man ip-link` (vrf type) - WireGuard: `man wg` - nftables: `man nft` --- **Status**: Reference architecture — not yet implemented **Last Updated**: 2026-07-10 **Author**: NexusGuard Team