datadunia
e523398fa8
- 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
395 lines
14 KiB
Markdown
395 lines
14 KiB
Markdown
# 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
|