Security Architecture

​

Security Overview

1. Network encryption: WireGuard encrypts all cluster communication
2. SSH authentication: Machine access controlled through SSH keys
3. TLS certificates: Automatic HTTPS for public-facing services
4. Container isolation: Docker provides process and namespace isolation
5. Firewall protection: Automatic iptables rules limit attack surface

​

WireGuard Encryption

​

Encryption Primitives

• Data encryption: ChaCha20 stream cipher
• Authentication: Poly1305 MAC
• Key exchange: Curve25519 elliptic curve Diffie-Hellman
• Handshake: Noise protocol framework
• Hashing: BLAKE2s

​

What WireGuard Protects

• Container-to-container traffic across machines
• Machine-to-machine API calls (Uncloud daemon gRPC)
• State synchronization (Corrosion gossip)
• Image transfers (Unregistry communication)

​

Key Management

1. Key generation: Each machine generates a random 32-byte private key
2. Public key derivation: Public key is derived from private key
3. Key distribution: Public keys are distributed via Corrosion state
4. Automatic configuration: Keys are configured in WireGuard without manual intervention

​

Key Storage

# Machine state file (contains private key)
/var/lib/uncloud/machine.json

​

Rotating WireGuard Keys

1. Remove the machine from the cluster: uc machine rm <name>
2. Reinitialize or add the machine: uc machine add user@host
3. This generates a new key pair and updates all peers

​

SSH Authentication

​

SSH Key Requirements

# Uses default SSH key (~/.ssh/id_ed25519)
uc machine init root@host

# Specify custom SSH key
uc machine init -i ~/.ssh/my-key root@host

​

Supported Key Types

• Ed25519 (recommended): Modern, secure, fast
• RSA 2048+: Widely compatible, requires minimum 2048-bit key
• ECDSA: Supported but Ed25519 is preferred

# Ed25519 (recommended)
ssh-keygen -t ed25519 -C "[email protected]"

# RSA 4096-bit (widely compatible)
ssh-keygen -t rsa -b 4096 -C "[email protected]"

​

SSH Key Distribution

1. Uses your SSH key to connect to the machine
2. Installs the Uncloud daemon
3. Creates a non-root uncloud user (if not root)
4. Adds your SSH public key to authorized_keys

​

Multi-User Access

# On each machine via SSH
ssh user@machine
sudo -u uncloud nano ~/.ssh/authorized_keys
# Add additional public keys

# User 1
uc --connect user@machine ps

# User 2 with different key
uc --connect user@machine -i ~/.ssh/user2-key ps

​

SSH Security Best Practices

1. Use Ed25519 keys: Stronger and faster than RSA
2. Protect private keys: Use passphrase-protected keys
3. Use SSH agent: Avoid typing passphrases repeatedly
4. Disable password auth: Ensure /etc/ssh/sshd_config has PasswordAuthentication no
5. Limit SSH access: Use firewall rules to restrict SSH to known IPs
6. Rotate keys periodically: Generate new SSH keys and update authorized_keys

​

TLS Certificates

​

Automatic HTTPS

uc run -p app.example.com:8000/https nginx

1. Receives the request for app.example.com
2. Checks if it has a valid certificate
3. If not, requests one from Let’s Encrypt using ACME HTTP-01 challenge
4. Stores the certificate locally
5. Serves HTTPS traffic with the certificate

​

Certificate Storage

/var/lib/uncloud/caddy/certificates/

​

Certificate Challenges

• HTTP-01 (default): Requires port 80 to be accessible
• TLS-ALPN-01: Uses port 443
• DNS-01: Requires DNS provider API access (for wildcards)

​

Custom Certificates

services:
  web:
    image: nginx
    labels:
      caddy: app.example.com
      caddy.tls: /path/to/cert.pem /path/to/key.pem

​

TLS Best Practices

1. Use strong ciphers: Caddy defaults to secure TLS 1.2+ ciphersuites
2. Enable HSTS: Configure Caddy to send Strict-Transport-Security headers
3. Monitor certificate expiration: Set up alerts for certificate renewal failures
4. Use certificate transparency: Let’s Encrypt certificates are automatically logged

​

Container Isolation

​

Process Isolation

• PID namespace: Container processes can’t see host processes
• Network namespace: Separate network stack per container
• Mount namespace: Isolated filesystem view
• UTS namespace: Separate hostname
• IPC namespace: Isolated inter-process communication

​

Resource Limits

services:
  web:
    image: nginx
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

​

Security Profiles

• AppArmor (Ubuntu/Debian): Confines containers with mandatory access control
• SELinux (RHEL/CentOS): Enforces security policies
• Seccomp: Filters system calls available to containers

​

User Namespaces

# On the machine via SSH
sudo nano /etc/docker/daemon.json

{
  "userns-remap": "default"
}

sudo systemctl restart docker

​

Read-Only Root Filesystem

services:
  api:
    image: myapp/api
    read_only: true
    tmpfs:
      - /tmp
      - /var/run

​

Network Security

​

Firewall Rules

1. Accept WireGuard traffic: Allow UDP port 51820 from anywhere
2. Accept Unregistry traffic: Allow TCP port 5000 from cluster machines
3. Accept cluster traffic: Allow traffic from WireGuard mesh network
4. Drop other traffic: Default deny for other incoming connections

# On the machine via SSH
sudo iptables -L -v -n

​

Port Exposure

services:
  # Private: Only accessible within cluster
  database:
    image: postgres:16

  # Public: Exposed via Caddy HTTPS
  web:
    image: nginx
    labels:
      caddy: app.example.com
      caddy.reverse_proxy: "{{upstreams 80}}"

​

Network Segmentation

services:
  web:
    image: nginx
    networks:
      - frontend

  api:
    image: myapp/api
    networks:
      - frontend
      - backend

  database:
    image: postgres:16
    networks:
      - backend

networks:
  frontend:
  backend:

​

Restricting Outbound Traffic

# On the machine via SSH
sudo iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A OUTPUT -d <allowed-ip> -j ACCEPT
sudo iptables -A OUTPUT -j DROP

​

Best Practices for Production

​

1. Minimize Attack Surface

• Run only necessary services
• Disable unused features (for example, SSH password auth)
• Keep software updated (OS, Docker, Uncloud)
• Remove default accounts and weak credentials

​

2. Use Strong Authentication

• Use Ed25519 SSH keys
• Protect private keys with passphrases
• Rotate SSH keys periodically
• Use multi-factor authentication for SSH (for example, Google Authenticator)

​

3. Enable Logging and Monitoring

# Centralize logs from all machines
sudo journalctl -u uncloud -f
sudo journalctl -u docker -f

• Monitor for failed authentication attempts
• Alert on suspicious activity (unusual process, network connections)
• Retain logs for forensic analysis

​

4. Secure Container Images

• Scan images for vulnerabilities (for example, docker scan, Trivy)
• Use minimal base images (Alpine, distroless)
• Don’t include secrets in images
• Regularly update base images
• Sign images for integrity verification

​

5. Implement Defense in Depth

• Network segmentation (Docker networks)
• Resource limits (CPU, memory)
• Read-only filesystems where possible
• Principle of least privilege
• Regular security audits

​

6. Protect Sensitive Data

services:
  api:
    image: myapp/api
    environment:
      - DATABASE_URL=/run/secrets/db_url
    secrets:
      - db_url

secrets:
  db_url:
    file: ./secrets/db_url.txt

• Use Docker secrets for sensitive configuration
• Encrypt data at rest (for example, encrypted volumes)
• Use TLS for all external communication
• Rotate secrets regularly

​

7. Plan for Incident Response

• Document incident response procedures
• Practice disaster recovery scenarios
• Maintain backups of critical data
• Have a process for patching vulnerabilities quickly

​

8. Network Isolation

• Run Uncloud cluster on a private network
• Use VPN or bastion hosts for SSH access
• Implement network policies to restrict traffic
• Use dedicated security machines as entry points

​

9. Regular Security Audits

# Check for outdated packages
ssh user@machine
sudo apt update && sudo apt list --upgradable

# Verify firewall rules
sudo iptables -L -v -n

# Review active connections
sudo ss -tuln

# Check running containers
docker ps

# Scan for vulnerabilities
docker scan myapp/image:latest

​

10. Keep Uncloud Updated

# Update Uncloud CLI
brew upgrade uncloud
# or
curl -fsS https://get.uncloud.run/install.sh | sh

# Update daemon on machines
uc machine upgrade

​

Security Limitations

​

What Uncloud Protects Against

• External attackers intercepting cluster traffic
• Unauthorized access to machines (via SSH)
• Man-in-the-middle attacks on cluster communication
• Container breakout (via Docker isolation)

​

What Uncloud Doesn’t Protect Against

• Malicious cluster administrators with SSH access
• Compromised SSH keys
• Vulnerabilities in container applications
• Social engineering attacks
• Physical access to machines

​

Compliance Considerations

1. Data encryption: WireGuard provides encryption in transit; use encrypted volumes for data at rest
2. Access control: Implement strict SSH key management and logging
3. Audit trails: Enable comprehensive logging and retain for required periods
4. Data residency: Deploy machines in compliant regions
5. Vulnerability management: Establish patching procedures and scan images regularly

​

Reporting Security Issues

1. Do not open a public GitHub issue
2. Email security details to the maintainer (check GitHub profile)
3. Include steps to reproduce and potential impact
4. Allow time for a fix before public disclosure