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,253 @@
|
||||
# Namespace + VRF Summary
|
||||
|
||||
> Enterprise Network Isolation for NexusGuard SD-WAN — Reference Architecture
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document provides a high-level summary of the Namespace + VRF architecture for enterprise-grade network isolation in NexusGuard.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### 1. Network Namespace
|
||||
|
||||
**What:** Complete network stack isolation at kernel level
|
||||
|
||||
**Benefits:**
|
||||
- Isolated network interfaces
|
||||
- Isolated routing tables
|
||||
- Isolated nftables rules
|
||||
- Isolated socket bindings
|
||||
|
||||
**Use Case:** Multi-tenant SD-WAN, compliance isolation
|
||||
|
||||
### 2. VRF (Virtual Routing and Forwarding)
|
||||
|
||||
**What:** Routing table isolation within a namespace
|
||||
|
||||
**Benefits:**
|
||||
- Multiple routing tables per namespace
|
||||
- Same IP across different VRFs
|
||||
- Policy routing support
|
||||
|
||||
**Use Case:** Development/testing isolation, network segmentation
|
||||
|
||||
### 3. Multi-User API Access
|
||||
|
||||
**What:** Role-based access control per namespace
|
||||
|
||||
**Benefits:**
|
||||
- Multiple users per namespace
|
||||
- Different permission levels (admin, operator, viewer)
|
||||
- Audit trail per user
|
||||
|
||||
**Use Case:** Enterprise deployments, team collaboration
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Linux Kernel │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Default Namespace (root) │ │
|
||||
│ │ └── eth0, wg0 (server mgmt) │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ 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 │ │
|
||||
│ │ └── nftables (isolated rules) │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Namespace: ns_alice │ │
|
||||
│ │ ├── 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) │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Document Index
|
||||
|
||||
| Document | Description | Key Topics |
|
||||
|----------|-------------|------------|
|
||||
| [architecture.md](architecture.md) | Main architecture document | Concept, data model, API design |
|
||||
| [quick-reference.md](quick-reference.md) | Kernel commands cheat sheet | Namespace, VRF, WireGuard commands |
|
||||
| [comparison.md](comparison.md) | Comparison with current architecture | Pros/cons, use cases, decision matrix |
|
||||
| [implementation-guide.md](implementation-guide.md) | Step-by-step implementation | Database, API, testing, deployment |
|
||||
| [troubleshooting.md](troubleshooting.md) | Troubleshooting guide | Common issues, debugging, logs |
|
||||
| [security.md](security.md) | Security considerations | Isolation, attacks, compliance |
|
||||
| [performance.md](performance.md) | Performance considerations | Overhead, benchmarks, optimization |
|
||||
|
||||
## Key Features
|
||||
|
||||
### 1. Complete Isolation
|
||||
|
||||
```
|
||||
✅ Network interfaces (per namespace)
|
||||
✅ Routing tables (per VRF)
|
||||
✅ nftables rules (per namespace)
|
||||
✅ Socket bindings (per namespace)
|
||||
✅ API access (per namespace)
|
||||
```
|
||||
|
||||
### 2. IP Conflict Prevention
|
||||
|
||||
```
|
||||
✅ Same IP across different namespaces
|
||||
✅ Same IP across different VRFs
|
||||
✅ Automatic isolation
|
||||
✅ No manual configuration
|
||||
```
|
||||
|
||||
### 3. Multi-User Access
|
||||
|
||||
```
|
||||
✅ Role-based access control
|
||||
✅ Multiple users per namespace
|
||||
✅ Admin, operator, viewer roles
|
||||
✅ Audit trail per user
|
||||
```
|
||||
|
||||
### 4. Compliance Ready
|
||||
|
||||
```
|
||||
✅ PCI DSS isolation
|
||||
✅ HIPAA data isolation
|
||||
✅ SOC 2 monitoring
|
||||
✅ Audit logging
|
||||
```
|
||||
|
||||
## Implementation Timeline
|
||||
|
||||
| Phase | Description | Duration | Status |
|
||||
|-------|-------------|----------|--------|
|
||||
| Phase 1 | Database schema | 1 week | Not started |
|
||||
| Phase 2 | Namespace manager | 1 week | Not started |
|
||||
| Phase 3 | VRF manager | 1 week | Not started |
|
||||
| Phase 4 | WireGuard integration | 1 week | Not started |
|
||||
| Phase 5 | Firewall integration | 1 week | Not started |
|
||||
| Phase 6 | API gateway | 1 week | Not started |
|
||||
| Phase 7 | Dashboard UI | 1 week | Not started |
|
||||
| Phase 8 | Testing & documentation | 1 week | Not started |
|
||||
| **Total** | | **8 weeks** | |
|
||||
|
||||
## Resource Requirements
|
||||
|
||||
### Small Deployment (< 10 users)
|
||||
|
||||
```
|
||||
CPU: 2 cores
|
||||
RAM: 4GB
|
||||
Network: 1Gbps
|
||||
Storage: 50GB
|
||||
```
|
||||
|
||||
### Medium Deployment (10-100 users)
|
||||
|
||||
```
|
||||
CPU: 8 cores
|
||||
RAM: 16GB
|
||||
Network: 10Gbps
|
||||
Storage: 200GB
|
||||
```
|
||||
|
||||
### Large Deployment (100-1000 users)
|
||||
|
||||
```
|
||||
CPU: 32 cores
|
||||
RAM: 64GB
|
||||
Network: 40Gbps
|
||||
Storage: 1TB
|
||||
```
|
||||
|
||||
## Performance Impact
|
||||
|
||||
| Metric | Current | Namespace + VRF | Overhead |
|
||||
|--------|---------|-----------------|----------|
|
||||
| Memory per user | ~10KB | ~1.1MB | +10x |
|
||||
| Routing latency | ~0.1ms | ~0.2ms | +100% |
|
||||
| Throughput | ~950Mbps | ~900Mbps | -5% |
|
||||
| Setup time | ~5ms | ~15ms | +200% |
|
||||
|
||||
## Security Guarantees
|
||||
|
||||
| Aspect | Isolation Level | Notes |
|
||||
|--------|-----------------|-------|
|
||||
| Network interfaces | HIGH | Complete per namespace |
|
||||
| Routing tables | HIGH | Complete per VRF |
|
||||
| nftables rules | HIGH | Complete per namespace |
|
||||
| Kernel | LOW | Shared |
|
||||
| Filesystem | LOW | Shared |
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Multi-Tenant SD-WAN
|
||||
|
||||
```
|
||||
Company A → ns_company_a → vrf_main → wg-a-main
|
||||
Company B → ns_company_b → vrf_main → wg-b-main
|
||||
Same IP, complete isolation!
|
||||
```
|
||||
|
||||
### 2. Development/Testing
|
||||
|
||||
```
|
||||
Developer → ns_dev → vrf_dev → wg-dev
|
||||
QA Team → ns_qa → vrf_test → wg-test
|
||||
Same IPs, no conflicts!
|
||||
```
|
||||
|
||||
### 3. Compliance Isolation
|
||||
|
||||
```
|
||||
PCI DSS → ns_pci → vrf_pci → wg-pci
|
||||
HIPAA → ns_hipaa → vrf_hipaa → wg-hipaa
|
||||
Isolated workloads!
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review** — Read all reference documents
|
||||
2. **Decide** — Choose architecture based on requirements
|
||||
3. **Plan** — Create detailed implementation plan
|
||||
4. **Implement** — Follow implementation guide
|
||||
5. **Test** — Verify isolation and performance
|
||||
6. **Deploy** — Roll out to production
|
||||
|
||||
## 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