feat: add ESP32 embedded agent + namespace VRF reference docs + update android-agent submodule
- apps/device-agent-embedded/: ESP32 WireGuard agent (C, ESP-IDF, mbedTLS) - reference/namespace-vrf/: Linux namespace/VRF network isolation docs - apps/android-agent: VPN permission check, StartResult sealed class
This commit is contained in:
datadunia
@@ -0,0 +1,394 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user