Nexus-Guard-Suite/reference/namespace-vrf/security.md

# Namespace + VRF Security Considerations

## Overview

This document covers security aspects of the Namespace + VRF architecture, including isolation guarantees, attack surfaces, and best practices.

## Isolation Guarantees

### Network Namespace Isolation

**What's isolated:**
- Network interfaces
- Routing tables
- iptables/nftables rules
- Socket bindings
- `/proc/net` entries
- Firewall rules

**What's NOT isolated:**
- Kernel (shared)
- Process IDs (different namespace, but visible with `nsenter`)
- Filesystem (shared unless `--mount` used)
- Users (shared unless `--user` used)

**Guarantee Level:** HIGH

```
┌─────────────────────────────────────────────────────────┐
│  Namespace Isolation                                     │
│                                                         │
│  ✅ Network interfaces (complete isolation)             │
│  ✅ Routing tables (complete isolation)                 │
│  ✅ nftables rules (complete isolation)                 │
│  ✅ Socket bindings (complete isolation)                │
│  ⚠️  Kernel (shared)                                   │
│  ⚠️  Filesystem (shared)                               │
│  ⚠️  Process IDs (visible with nsenter)                │
└─────────────────────────────────────────────────────────┘
```

### VRF Isolation

**What's isolated:**
- Routing tables
- Gateway routes
- Policy routing

**What's NOT isolated:**
- Network interfaces (shared within namespace)
- Kernel (shared)
- nftables rules (shared within namespace)

**Guarantee Level:** MEDIUM

```
┌─────────────────────────────────────────────────────────┐
│  VRF Isolation                                           │
│                                                         │
│  ✅ Routing tables (complete isolation)                 │
│  ✅ Gateway routes (complete isolation)                 │
│  ⚠️  Network interfaces (shared within namespace)       │
│  ⚠️  Kernel (shared)                                   │
│  ⚠️  nftables rules (shared within namespace)           │
└─────────────────────────────────────────────────────────┘
```

## Attack Surfaces

### 1. Cross-Namespace Attacks

**Risk:** LOW

**Attack Vector:**
- Attacker gains access to one namespace
- Attempts to access other namespaces

**Mitigation:**
- Network namespace isolation prevents direct access
- No routing between namespaces without explicit veth pairs
- nftables rules can block cross-namespace traffic

**Detection:**
```bash
# Monitor cross-namespace attempts
ip netns exec ns_test tcpdump -i any -n | grep -v "ns_test"
```

### 2. VRF Escape Attacks

**Risk:** LOW

**Attack Vector:**
- Attacker in one VRF attempts to access another VRF
- Uses routing table manipulation

**Mitigation:**
- VRF isolation prevents routing table access
- Each VRF has separate routing table
- No shared routing state

**Detection:**
```bash
# Monitor VRF routing changes
ip netns exec ns_test ip route show table 100
ip netns exec ns_test ip route show table 200
```

### 3. Kernel Exploits

**Risk:** MEDIUM

**Attack Vector:**
- Kernel vulnerability allows namespace escape
- Shared kernel between all namespaces

**Mitigation:**
- Keep kernel updated
- Use kernel security modules (SELinux, AppArmor)
- Limit namespace capabilities

**Detection:**
```bash
# Monitor kernel messages
dmesg | grep -i "namespace\|vrf\|escape"
```

### 4. Resource Exhaustion

**Risk:** MEDIUM

**Attack Vector:**
- Attacker creates excessive namespaces/VRFs
- Exhausts kernel resources

**Mitigation:**
- Limit number of namespaces per user
- Monitor resource usage
- Implement quotas

**Detection:**
```bash
# Monitor namespace count
ip netns list | wc -l

# Monitor VRF count
ip link show type vrf | wc -l
```

### 5. API Access Control Bypass

**Risk:** LOW

**Attack Vector:**
- Attacker bypasses namespace-scoped API
- Accesses other namespaces via API

**Mitigation:**
- Middleware validates namespace access
- Role-based access control
- JWT tokens with namespace claims

**Detection:**
```bash
# Monitor API access
journalctl -u nexusguard-server | grep "namespace"
```

## Security Best Practices

### 1. Namespace Creation

```bash
# DO: Create namespace with limited capabilities
ip netns add ns_test

# DO: Set resource limits
ulimit -n 65535

# DON'T: Use --privileged flag in containers
docker run --privileged ...  # BAD

# DO: Use specific capabilities
docker run --cap-add=NET_ADMIN --cap-add=SYS_ADMIN ...  # GOOD
```

### 2. VRF Configuration

```bash
# DO: Use separate routing tables
ip link add vrf:main type vrf table 100
ip link add vrf:isolated type vrf table 200

# DO: Add routes to correct table
ip route add 10.100.0.0/24 dev wg0 table 100

# DON'T: Share routing tables between VRFs
# BAD: Using same table ID for different VRFs
```

### 3. nftables Rules

```bash
# DO: Create per-namespace tables
ip netns exec ns_test nft add table ip nexusguard

# DO: Set default DROP policy
ip netns exec ns_test nft add chain ip nexusguard forward '{type filter hook forward priority filter; policy drop;}'

# DO: Allow only necessary traffic
ip netns exec ns_test nft add rule ip nexusguard forward iifname wg0 accept

# DON'T: Use default ACCEPT policy
# BAD: policy accept;
```

### 4. WireGuard Configuration

```bash
# DO: Use strong keys
wg genkey | wg pubkey

# DO: Use preshared keys
wg genpsk

# DO: Limit allowed IPs
wg set wg0 peer <pubkey> allowed-ips 10.100.0.2/32

# DON'T: Use 0.0.0.0/0 for allowed IPs
# BAD: allowed-ips 0.0.0.0/0
```

### 5. API Authentication

```go
// DO: Validate namespace access
func (h *Handler) ValidateNamespaceAccess(userID, namespaceID uuid.UUID) error {
    var nsUser models.NamespaceUser
    if err := h.db.Where("user_id = ? AND namespace_id = ?", userID, namespaceID).
        First(&nsUser).Error; err != nil {
        return fmt.Errorf("access denied")
    }
    return nil
}

// DO: Check role permissions
func (h *Handler) CheckPermission(namespaceID, userID uuid.UUID, requiredRole string) error {
    var nsUser models.NamespaceUser
    if err := h.db.Where("user_id = ? AND namespace_id = ?", userID, namespaceID).
        First(&nsUser).Error; err != nil {
        return fmt.Errorf("access denied")
    }
    
    if !hasPermission(nsUser.Role, requiredRole) {
        return fmt.Errorf("insufficient permissions")
    }
    return nil
}
```

## Compliance Considerations

### PCI DSS

**Requirements:**
- Network segmentation
- Access control
- Audit logging

**Implementation:**
```bash
# Create PCI-compliant namespace
ip netns add ns_pci

# Isolate PCI workloads
ip link add vrf:pci type vrf table 300

# Add strict firewall rules
ip netns exec ns_pci nft add table ip pci
ip netns exec ns_pci nft add chain ip pci forward '{type filter hook forward priority filter; policy drop;}'
ip netns exec ns_pci nft add rule ip pci forward iifname wg-pci accept

# Enable logging
ip netns exec ns_pci nft add rule ip pci forward log prefix "PCI: " accept
```

### HIPAA

**Requirements:**
- Data isolation
- Access control
- Audit trails

**Implementation:**
```bash
# Create HIPAA-compliant namespace
ip netns add ns_hipaa

# Isolate healthcare data
ip link add vrf:hipaa type vrf table 400

# Add strict access controls
ip netns exec ns_hipaa nft add table ip hipaa
ip netns exec ns_hipaa nft add chain ip hipaa forward '{type filter hook forward priority filter; policy drop;}'
ip netns exec ns_hipaa nft add rule ip hipaa forward iifname wg-hipaa accept

# Enable audit logging
ip netns exec ns_hipaa nft add rule ip hipaa forward log prefix "HIPAA: " accept
```

### SOC 2

**Requirements:**
- Security controls
- Monitoring
- Incident response

**Implementation:**
```bash
# Create SOC 2-compliant namespace
ip netns add ns_soc2

# Add monitoring
ip netns exec ns_soc2 tcpdump -i any -w /var/log/soc2/capture.pcap

# Add alerting
ip netns exec ns_soc2 nft add rule ip soc2 forward log prefix "SOC2: " accept
```

## Monitoring and Alerting

### Namespace Monitoring

```bash
# Monitor namespace creation
ip netns list | while read ns; do
    echo "Namespace: $ns"
    ip netns exec "$ns" ip link show | grep -v "lo:"
done

# Monitor namespace resource usage
for ns in $(ip netns list | awk '{print $1}'); do
    echo "=== $ns ==="
    ip netns exec "$ns" cat /proc/net/dev
done
```

### VRF Monitoring

```bash
# Monitor VRF creation
ip link show type vrf | grep "vrf:" | awk '{print $2}'

# Monitor VRF routing tables
for vrf in $(ip link show type vrf | grep "vrf:" | awk '{print $2}' | cut -d: -f1); do
    echo "=== $vrf ==="
    ip route show table all | grep "$vrf"
done
```

### Security Monitoring

```bash
# Monitor cross-namespace attempts
ip netns exec ns_test tcpdump -i any -n 2>&1 | \
    grep -v "ns_test" | \
    logger -t "namespace-security"

# Monitor VRF escape attempts
ip netns exec ns_test ip route show table all | \
    grep -v "table 100" | \
    logger -t "vrf-security"
```

## Incident Response

### Namespace Compromise

**Detection:**
```bash
# Check for suspicious activity
ip netns exec ns_test tcpdump -i any -n -c 1000 > /tmp/suspicious.pcap

# Check for unauthorized access
ip netns exec ns_test ss -tulpn

# Check for unusual processes
ip netns exec ns_test ps aux
```

**Response:**
```bash
# Isolate namespace
ip netns exec ns_test nft add chain ip nexusguard isolate '{type filter hook forward priority 0; policy drop;}'

# Capture forensics
ip netns exec ns_test tcpdump -i any -w /forensics/ns_test.pcap

# Reset namespace
ip netns del ns_test
ip netns add ns_test
```

### VRF Escape

**Detection:**
```bash
# Monitor routing table changes
ip netns exec ns_test ip route show table all | \
    awk 'NR>1{print $1}' | sort | uniq -c | sort -rn

# Check for unauthorized routes
ip netns exec ns_test ip route show table 100 | grep -v "10.100.0.0/24"
```

**Response:**
```bash
# Flush VRF routes
ip netns exec ns_test ip route flush table 100

# Recreate VRF
ip netns exec ns_test ip link del vrf:main
ip netns exec ns_test ip link add vrf:main type vrf table 100
ip netns exec ns_test ip link set vrf:main up
```

## Security Auditing

### Audit Commands

```bash
# List all namespaces
ip netns list

# List all VRFs
ip link show type vrf

# List all WireGuard interfaces
ip netns exec ns_test wg show

# List all nftables rules
ip netns exec ns_test nft list ruleset

# Check namespace permissions
psql -U nexusguard -d nexusguard -c "
SELECT n.name, nu.role, u.username 
FROM namespaces n
JOIN namespace_users nu ON n.id = nu.namespace_id
JOIN users u ON nu.user_id = u.id
ORDER BY n.name, nu.role;
"
```

### Audit Logging

```bash
# Enable audit logging
auditctl -w /var/run/netns -p wa -k namespace
auditctl -w /etc/netns -p wa -k namespace

# Check audit logs
ausearch -k namespace --interpret
```

### Security Scanning

```bash
# Scan for open ports
ip netns exec ns_test ss -tulpn

# Scan for vulnerabilities
ip netns exec ns_test lynis audit system

# Check for misconfigurations
ip netns exec ns_test nft list ruleset | \
    grep -E "(policy accept|0.0.0.0/0)"
```

## Conclusion

The Namespace + VRF architecture provides **strong isolation guarantees** for network workloads. Key security considerations:

1. **Namespace isolation** is HIGH — complete network stack isolation
2. **VRF isolation** is MEDIUM — routing table isolation within namespace
3. **Attack surfaces** are limited but exist (kernel, filesystem)
4. **Compliance** is achievable with proper implementation
5. **Monitoring** is essential for security assurance

**Recommendation:** Implement with security best practices and regular auditing.

---

**Status:** Security reference — not yet implemented
**Last Updated:** 2026-07-10
**Author:** NexusGuard Team