Security
Netbird VPN Security Model
Threat model and security architecture for Netbird mesh VPN
Netbird provides mesh VPN connectivity for accessing tasmanian.cloud resources. This document outlines the security model for the VPN infrastructure, authentication, and network access control.
Security Goals
The Netbird security model aims to provide:
- Confidentiality — All VPN traffic encrypted with modern algorithms
- Authentication — Strong identity verification for all peers
- Authorization — Fine-grained access control based on groups and policies
- Integrity — Protection against traffic tampering
- Availability — Mesh topology provides redundancy
- Observability — All connections logged for audit
Threat Model
In Scope (Threats We Protect Against)
- Eavesdropping on VPN traffic — Interception of wire traffic
- Unauthorized peer joining — Attacker attempting to join the mesh
- Rogue access points — Compromised WiFi or network infrastructure
- Man-in-the-middle attacks — Interception or modification of handshake
- Replay attacks — Reuse of captured handshake messages
- Denial of service — Attempts to disconnect legitimate peers
- Lateral movement — Compromised peer accessing unauthorized resources
- Key compromise — Theft or leakage of private keys
Out of Scope (Threats We Do Not Protect Against)
- Compromised end devices — If a customer's laptop is compromised
- Social engineering — Phishing for VPN credentials
- Physical access to devices — Local extraction of keys
- Insider threats — Malicious users with legitimate VPN access
- Application-level attacks — Vulnerabilities in services behind VPN
- DNS leaks — Misconfigured clients bypassing VPN
- Timing attacks — Traffic analysis based on timing patterns
- Quantum computers — WireGuard's crypto is not post-quantum
External Threat Overview
Architecture Components
┌─────────────────────────────────────────────────────────────────┐
│ Internet │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Laptop │ │ Phone │ │ Server │ │
│ │ (Customer) │ │ (Customer) │ │ (Customer) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼────────────────┼────────────────┼────────────────────┘
│ │ │
└────────────────┴────────────────┘
│
┌──────▼──────┐
│ Netbird │
│ Management │
│ Server │
│ │
│ ┌─────────┐ │
│ │ Signal │ │ (Coordination)
│ │ │ Server │ │
│ └─────────┘ │
│ ┌─────────┐ │
│ │ STUN │ │ (NAT traversal)
│ │ Server │ │
│ └─────────┘ │
│ ┌─────────┐ │
│ │ TURN │ │ (Relay fallback)
│ │ Server │ │
│ └─────────┘ │
└──────┬──────┘
│
┌────────────────┼────────────────┐
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ Proxmox │ │ O2S │ │ Customer │
│ Nodes │ │ Portal │ │ VPS │
│ │ │ │ │ │
│ 10.0.20.0/24│ │ 10.0.50.0/24│ │ 10.0.40.0/22│
└─────────────┘ └─────────────┘ └─────────────┘Trust Boundaries
Untrusted:
- Public internet
- Customer devices (before authentication)
- Third-party networks (coffee shop WiFi, etc.)
Semi-Trusted:
- Netbird management server (coordinates, doesn't handle traffic)
- STUN servers (assist with NAT traversal, no key material)
Trusted:
- TURN servers (relay encrypted traffic, cannot decrypt)
- Internal infrastructure (after VPN authentication)
WireGuard Protocol
Netbird uses WireGuard for the data plane:
┌─────────────────────────────────────────────────────────────┐
│ WireGuard Packet Structure │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ IP Header (20 bytes) │ │
│ │ Source: 100.64.10.5 (VPN IP) │ │
│ │ Destination: 10.0.40.10 (Internal) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ WireGuard Header │ │
│ │ ├── Type: 4 bytes │ │
│ │ ├── Reserved: 3 bytes │ │
│ │ ├── Sender Index: 4 bytes │ │
│ │ └── Unencrypted Timestamp: 12 bytes (TAI64N) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Encrypted Payload │ │
│ │ ├── ChaCha20-Poly1305 AEAD │ │
│ │ │ └── Key: Derived from Curve25519 ECDH │ │
│ │ ├── Original IP Packet │ │
│ │ └── MAC: 16 bytes (Poly1305) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Cryptography: │
│ ├── Curve25519 for ECDH key exchange │
│ ├── ChaCha20 for symmetric encryption │
│ ├── Poly1305 for authentication │
│ └── Blake2s for hashing and key derivation │
│ │
└─────────────────────────────────────────────────────────────┘Security properties:
- No handshake required after initial setup (stealth)
- Perfect forward secrecy (new keys per session)
- Identity hiding (public keys not transmitted in cleartext)
- Deniability (anyone can forge messages)
Internal Threat Overview
Authentication Flow
Netbird supports multiple authentication methods:
1. Initial Enrollment
┌─────────────────────────────────────────────────────────────┐
│ Peer Enrollment Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. Admin generates setup key in O2S │
│ │ │
│ ▼ │
│ 2. Setup key distributed to user (secure channel) │
│ │ │
│ ▼ │
│ 3. User runs: netbird up --setup-key <key> │
│ │ │
│ ▼ │
│ 4. Peer generates WireGuard key pair │
│ ├── Private key: Stored in OS keychain │
│ └── Public key: Sent to management server │
│ │ │
│ ▼ │
│ 5. Management server validates setup key │
│ ├── Checks key validity and expiration │
│ ├── Assigns IP from allocation pool │
│ └── Associates peer with user/group │
│ │ │
│ ▼ │
│ 6. Peer receives network map │
│ ├── List of authorized peers │
│ ├── Allowed IPs per peer │
│ └── Public keys for all peers │
│ │
└─────────────────────────────────────────────────────────────┘2. Ongoing Authentication
Peers authenticate using JWT tokens:
- Tokens issued by Netbird's integrated IdP or external SSO
- Short-lived (1 hour expiry)
- Refresh tokens (7 days)
- Bound to peer's public key
Access Control (ACLs)
Netbird uses group-based access control:
# Example ACL configuration
peers:
- name: developer-laptop
groups: ["developers", "engineering"]
ip: 100.64.10.5
- name: production-server
groups: ["infrastructure", "production"]
ip: 10.0.40.10
acls:
- name: allow-dev-to-prod
src: ["developers"]
dst: ["production"]
proto: "tcp"
ports: ["22", "443"]
action: "accept"
- name: deny-all-other
src: ["*"]
dst: ["*"]
action: "deny"Default deny: All traffic denied unless explicitly allowed.
Network Map Distribution
The management server distributes network configuration:
{
"peers": [
{
"publicKey": "abc123...",
"allowedIps": ["100.64.10.5/32"],
"endpoint": "203.0.113.42:51820",
"relay": false
},
{
"publicKey": "def456...",
"allowedIps": ["10.0.40.10/32"],
"endpoint": null,
"relay": true
}
],
"relays": [
{
"uri": "turn:turn.tasmanian.cloud:3478",
"username": "nb:user:abc123",
"password": "..."
}
]
}Security properties:
- Network map signed by management server
- Peers verify signature before applying
- Updates pushed in real-time
- Old network maps expire quickly
Key Management
| Key Type | Storage | Rotation | Notes |
|---|---|---|---|
| WireGuard private key | OS keychain (Keychain, GNOME Keyring) | On reinstall | Never leaves device |
| WireGuard public key | Management server | With private key | Used by peers |
| JWT access token | Memory only | 1 hour | Short-lived |
| JWT refresh token | Secure storage | 7 days | Single-use |
| Setup key | Management server | Per enrollment | One-time use |
Attack Scenarios and Mitigations
Scenario 1: Stolen Laptop
Attack: Attacker steals laptop with Netbird installed.
Mitigations:
- Private key protected by OS keychain (encrypted)
- Full disk encryption recommended
- Admin can revoke peer immediately via O2S
- Short-lived tokens limit window of abuse
Scenario 2: Rogue Peer
Attack: Attacker obtains valid setup key and joins network.
Mitigations:
- Setup keys expire (configurable, default 24 hours)
- One-time use per key
- Admin approval required for some keys
- Peer visible in dashboard, easily identified and removed
Scenario 3: Management Server Compromise
Attack: Attacker compromises Netbird management server.
Mitigations:
- Management server never sees traffic (only coordinates)
- Peers continue to communicate (mesh topology)
- Compromise would allow DoS (kick peers) but not eavesdropping
- Regular backups, quick recovery
Scenario 4: Relay Server Compromise
Attack: Attacker compromises TURN relay server.
Mitigations:
- Traffic encrypted end-to-end (WireGuard)
- Relay cannot decrypt traffic
- Direct connections preferred (relay fallback only)
- Multiple relay servers available
Security Controls Summary
| Control | Implementation | Verification |
|---|---|---|
| Encryption | WireGuard (ChaCha20-Poly1305) | Protocol audit |
| Key exchange | Curve25519 ECDH | Cryptographic review |
| Authentication | JWT tokens + setup keys | Penetration testing |
| Authorization | Group-based ACLs | Policy review |
| Key storage | OS keychain | Device security audit |
| Network isolation | Default deny ACLs | Connectivity testing |
| Audit logging | All connections logged | SIEM integration |
| Relay security | TURN with authentication | Server hardening |
Best Practices for Customers
Device Security
- Enable full disk encryption
- Use strong device passwords
- Keep OS and Netbird client updated
- Report lost/stolen devices immediately
Key Management
- Don't share setup keys
- Use one key per device
- Revoke unused peers promptly
- Use SSO/MFA when available
Network Hygiene
- Use specific ACLs (not "allow all")
- Segment by groups (dev, prod, admin)
- Regular access reviews
- Monitor connection logs