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,381 @@
|
||||
# Namespace + VRF vs Current Architecture
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document compares the current NexusGuard architecture with the proposed Namespace + VRF architecture, highlighting the benefits, trade-offs, and implementation considerations.
|
||||
|
||||
## Current Architecture
|
||||
|
||||
### Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Server (172.20.8.191) │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Default Namespace (root) │ │
|
||||
│ │ ├── eth0 (mgmt interface) │ │
|
||||
│ │ ├── wg0 (10.172.21.1/24) │ │
|
||||
│ │ │ ├── Device A: 10.172.21.2 (alice) │ │
|
||||
│ │ │ ├── Device B: 10.172.21.3 (bob) │ │
|
||||
│ │ │ └── Device C: 10.172.21.4 (charlie) │ │
|
||||
│ │ └── nftables (global rules) │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Data Model
|
||||
|
||||
```
|
||||
User
|
||||
└── Device
|
||||
└── WgServer
|
||||
```
|
||||
|
||||
### Characteristics
|
||||
|
||||
| Aspect | Current |
|
||||
|--------|---------|
|
||||
| Isolation | Routing only (nftables) |
|
||||
| IP conflicts | Possible |
|
||||
| API access | Global |
|
||||
| Resource overhead | Low |
|
||||
| Complexity | Low |
|
||||
|
||||
### Limitations
|
||||
|
||||
1. **IP conflicts** — Same IP on different WgServers causes routing issues
|
||||
2. **No user isolation** — Users can see each other's traffic
|
||||
3. **API access control** — Limited multi-user support
|
||||
4. **Scalability** — Limited by kernel routing table size
|
||||
|
||||
## Proposed Architecture: Namespace + VRF
|
||||
|
||||
### Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Linux Kernel │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Default Namespace (root) │ │
|
||||
│ │ ├── eth0 (mgmt interface) │ │
|
||||
│ │ └── wg0 (server WireGuard) │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Namespace: ns_zerocode │ │
|
||||
│ │ ├── veth0 (virtual ethernet) │ │
|
||||
│ │ ├── 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 │ │
|
||||
│ │ └── nftables (isolated rules) │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Namespace: ns_alice │ │
|
||||
│ │ ├── veth0 (virtual ethernet) │ │
|
||||
│ │ ├── VRF: vrf_main (table 100) │ │
|
||||
│ │ │ └── wg-a-main (10.100.0.1/24) ← SAMA! │ │
|
||||
│ │ │ ├── Device C: 10.100.0.2 │ │
|
||||
│ │ │ └── Device D: 10.100.0.3 │ │
|
||||
│ │ └── nftables (isolated rules) │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Data Model
|
||||
|
||||
```
|
||||
User
|
||||
├── Namespace (1:1)
|
||||
│ ├── NamespaceUser (N:N with role)
|
||||
│ └── VRF (1:N)
|
||||
│ └── WgServer (1:N)
|
||||
│ └── Device (1:N)
|
||||
└── Device (legacy, for backward compatibility)
|
||||
```
|
||||
|
||||
### Characteristics
|
||||
|
||||
| Aspect | Namespace + VRF |
|
||||
|--------|-----------------|
|
||||
| Isolation | Full network stack |
|
||||
| IP conflicts | Impossible (per namespace) |
|
||||
| API access | Per namespace |
|
||||
| Resource overhead | Medium |
|
||||
| Complexity | High |
|
||||
|
||||
### Benefits
|
||||
|
||||
1. **Complete isolation** — Full network stack isolation per namespace
|
||||
2. **No IP conflicts** — Same IP can exist in different namespaces
|
||||
3. **Multi-user API** — Role-based access per namespace
|
||||
4. **Scalability** — Limited by number of namespaces, not routing table size
|
||||
5. **Security** — Stronger isolation than nftables alone
|
||||
|
||||
## Comparison Table
|
||||
|
||||
| Feature | Current | Namespace + VRF | Winner |
|
||||
|---------|---------|-----------------|--------|
|
||||
| **Isolation level** | Routing only | Full network stack | Namespace + VRF |
|
||||
| **IP conflict prevention** | Manual | Automatic | Namespace + VRF |
|
||||
| **API access control** | Global | Per namespace | Namespace + VRF |
|
||||
| **Resource overhead** | Low | Medium | Current |
|
||||
| **Implementation complexity** | Low | High | Current |
|
||||
| **Scalability** | Good | Good | Tie |
|
||||
| **Security** | Medium | High | Namespace + VRF |
|
||||
| **Backward compatibility** | N/A | Required | Current |
|
||||
| **Learning curve** | Low | High | Current |
|
||||
| **Debugging difficulty** | Low | High | Current |
|
||||
|
||||
## Use Case Analysis
|
||||
|
||||
### Use Case 1: Multi-Tenant SD-WAN
|
||||
|
||||
**Current:**
|
||||
- All tenants share same routing domain
|
||||
- IP conflicts possible
|
||||
- No tenant isolation
|
||||
|
||||
**Namespace + VRF:**
|
||||
- Each tenant gets own namespace
|
||||
- Complete isolation
|
||||
- No IP conflicts
|
||||
|
||||
**Winner:** Namespace + VRF
|
||||
|
||||
### Use Case 2: Development/Testing
|
||||
|
||||
**Current:**
|
||||
- Dev and test share same network
|
||||
- Conflicts possible
|
||||
- No isolation
|
||||
|
||||
**Namespace + VRF:**
|
||||
- Dev and test in separate namespaces
|
||||
- Complete isolation
|
||||
- Same IPs allowed
|
||||
|
||||
**Winner:** Namespace + VRF
|
||||
|
||||
### Use Case 3: Single Tenant
|
||||
|
||||
**Current:**
|
||||
- Simple setup
|
||||
- Low overhead
|
||||
- Easy debugging
|
||||
|
||||
**Namespace + VRF:**
|
||||
- Overkill for single tenant
|
||||
- Unnecessary complexity
|
||||
- Higher resource usage
|
||||
|
||||
**Winner:** Current
|
||||
|
||||
### Use Case 4: Compliance (PCI DSS, HIPAA)
|
||||
|
||||
**Current:**
|
||||
- Shared network
|
||||
- Audit challenges
|
||||
- Compliance gaps
|
||||
|
||||
**Namespace + VRF:**
|
||||
- Isolated networks
|
||||
- Clean audit trail
|
||||
- Compliance ready
|
||||
|
||||
**Winner:** Namespace + VRF
|
||||
|
||||
## Resource Comparison
|
||||
|
||||
### Memory Usage
|
||||
|
||||
| Component | Current | Namespace + VRF |
|
||||
|-----------|---------|-----------------|
|
||||
| Per user | ~10KB | ~1MB |
|
||||
| 10 users | ~100KB | ~10MB |
|
||||
| 100 users | ~1MB | ~100MB |
|
||||
| 1000 users | ~10MB | ~1GB |
|
||||
|
||||
### CPU Usage
|
||||
|
||||
| Operation | Current | Namespace + VRF |
|
||||
|-----------|---------|-----------------|
|
||||
| Packet routing | Low | Low |
|
||||
| Namespace creation | N/A | Medium |
|
||||
| VRF creation | Low | Low |
|
||||
| nftables rules | Low | Low |
|
||||
|
||||
### Kernel Resources
|
||||
|
||||
| Resource | Current | Namespace + VRF |
|
||||
|----------|---------|-----------------|
|
||||
| Network namespaces | 1 | 1 + N users |
|
||||
| VRF devices | 0 | N per user |
|
||||
| Routing tables | 1 | 1 + N per user |
|
||||
| nftables tables | 1 | 1 + N users |
|
||||
|
||||
## Implementation Considerations
|
||||
|
||||
### Phase 1: Database Schema
|
||||
|
||||
**Changes:**
|
||||
- Add namespaces table
|
||||
- Add namespace_users table
|
||||
- Add vrfs table
|
||||
- Add VRF fields to wg_servers
|
||||
|
||||
**Effort:** 1 week
|
||||
|
||||
### Phase 2: Namespace Manager
|
||||
|
||||
**Changes:**
|
||||
- Namespace CRUD operations
|
||||
- User-role management
|
||||
- API access control middleware
|
||||
|
||||
**Effort:** 1 week
|
||||
|
||||
### Phase 3: VRF Manager
|
||||
|
||||
**Changes:**
|
||||
- VRF CRUD operations
|
||||
- Kernel VRF commands
|
||||
- Routing table management
|
||||
|
||||
**Effort:** 1 week
|
||||
|
||||
### Phase 4: WireGuard Integration
|
||||
|
||||
**Changes:**
|
||||
- WG creation in namespace
|
||||
- WG binding to VRF
|
||||
- Peer management in namespace
|
||||
|
||||
**Effort:** 1 week
|
||||
|
||||
### Phase 5: Firewall Integration
|
||||
|
||||
**Changes:**
|
||||
- nftables per namespace
|
||||
- Rules per VRF
|
||||
- Cross-namespace isolation
|
||||
|
||||
**Effort:** 1 week
|
||||
|
||||
### Phase 6: API Gateway
|
||||
|
||||
**Changes:**
|
||||
- Namespace-scoped API routes
|
||||
- Authentication per namespace
|
||||
- Authorization per role
|
||||
|
||||
**Effort:** 1 week
|
||||
|
||||
### Phase 7: Dashboard UI
|
||||
|
||||
**Changes:**
|
||||
- Namespace management UI
|
||||
- VRF configuration UI
|
||||
- User-role management UI
|
||||
|
||||
**Effort:** 1 week
|
||||
|
||||
### Phase 8: Testing & Documentation
|
||||
|
||||
**Changes:**
|
||||
- Unit tests
|
||||
- Integration tests
|
||||
- Documentation
|
||||
- Deployment guide
|
||||
|
||||
**Effort:** 1 week
|
||||
|
||||
**Total Effort:** 8 weeks
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
1. **Legacy mode** — Keep current architecture as default
|
||||
2. **Opt-in** — Users can opt-in to namespace + VRF
|
||||
3. **Migration tool** — Script to migrate existing users to namespaces
|
||||
|
||||
### Migration Steps
|
||||
|
||||
1. Create namespace for each existing user
|
||||
2. Move devices to user's namespace
|
||||
3. Create VRF in namespace
|
||||
4. Move WireGuard interfaces to VRF
|
||||
5. Update API routes
|
||||
6. Test and validate
|
||||
|
||||
### Rollback Plan
|
||||
|
||||
1. Keep legacy mode available
|
||||
2. Migration tool can reverse changes
|
||||
3. No data loss during migration
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
### Choose Current Architecture If:
|
||||
|
||||
- [ ] Single tenant deployment
|
||||
- [ ] Simple network requirements
|
||||
- [ ] Limited resources
|
||||
- [ ] Quick time-to-market
|
||||
- [ ] Low complexity tolerance
|
||||
|
||||
### Choose Namespace + VRF If:
|
||||
|
||||
- [ ] Multi-tenant deployment
|
||||
- [ ] Strong isolation requirements
|
||||
- [ ] Compliance needs (PCI DSS, HIPAA)
|
||||
- [ ] Same IP across tenants
|
||||
- [ ] Role-based API access
|
||||
|
||||
## Recommendation
|
||||
|
||||
### For Small Deployments (< 10 users)
|
||||
|
||||
**Recommendation:** Current architecture
|
||||
|
||||
**Reasons:**
|
||||
- Simpler to implement and maintain
|
||||
- Lower resource overhead
|
||||
- Faster time-to-market
|
||||
- Easier debugging
|
||||
|
||||
### For Enterprise Deployments (> 10 users)
|
||||
|
||||
**Recommendation:** Namespace + VRF
|
||||
|
||||
**Reasons:**
|
||||
- Stronger isolation
|
||||
- Better security
|
||||
- Compliance ready
|
||||
- Scalable
|
||||
|
||||
### For Multi-Tenant Deployments
|
||||
|
||||
**Recommendation:** Namespace + VRF (required)
|
||||
|
||||
**Reasons:**
|
||||
- Complete tenant isolation
|
||||
- No IP conflicts
|
||||
- Role-based access control
|
||||
- Audit trail
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Namespace + VRF architecture provides **superior isolation and security** at the cost of **increased complexity and resource usage**. It's the right choice for enterprise and multi-tenant deployments, but overkill for simple single-tenant setups.
|
||||
|
||||
**Key takeaway:** Choose the architecture that matches your deployment requirements. Don't over-engineer for simplicity, but don't under-engineer for security.
|
||||
|
||||
---
|
||||
|
||||
**Status:** Reference comparison — not yet implemented
|
||||
**Last Updated:** 2026-07-10
|
||||
**Author:** NexusGuard Team
|
||||
Reference in New Issue
Block a user