security

security model

funnel currently uses a simple security model: anyone who knows your server address can connect and create tunnels. this is suitable for development environments but requires additional protection for production use.

current security features

🔐 tls encryption

automatic https certificates via let's encrypt

🆔 tunnel id validation

basic format validation and uniqueness checking

📋 comprehensive logging

detailed logging for monitoring connections

🔒 modern tls

secure tls configuration with modern ciphers

what's not included

no built-in access control

the server does not have built-in authentication, authorization, or user management. protection must be implemented at the network or proxy level.

current limitations:

no authentication - no user accounts, tokens, or passwords
no authorization - anyone can connect if they know the server address
no rate limiting - no built-in protection against abuse
no ip restrictions - accepts connections from any ip address

tls encryption

https is supported

the server has built-in support for automatic tls certificate generation using let's encrypt.

enable automatic tls with let's encrypt:

docker run -d --name funnel-server \
  -p 80:8080 \
  -p 443:8443 \
  -v $(pwd)/dns-providers.json:/etc/funnel/dns-providers.json \
  -v funnel-certs:/var/lib/funnel/certs \
  -e FUNNEL_ENABLE_TLS=true \
  -e FUNNEL_LETSENCRYPT_EMAIL=your-email@example.com \
  -e FUNNEL_DNS_PROVIDERS_CONFIG=/etc/funnel/dns-providers.json \
  ghcr.io/karol-broda/funnel-server:latest

requires dns provider configuration for certificate validation.

use your own certificates:

docker run -d --name funnel-server \
  -p 443:8443 \
  -v /path/to/certs:/var/lib/funnel/certs \
  -e FUNNEL_ENABLE_TLS=true \
  ghcr.io/karol-broda/funnel-server:latest

automatic certificate features:

on-demand generation - certificates created on first request
automatic renewal - renewed before expiration
wildcard support - can generate *.domain.com certificates
secure storage - stored in docker volume

deployment security

since the server lacks built-in access control, secure deployment requires external protection:

network-level protection

use firewall rules to restrict access:

# allow public access to tunnel traffic
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# restrict websocket connections to trusted networks
sudo ufw allow from 192.168.1.0/24 to any port 8080
sudo ufw deny 8080/tcp

sudo ufw enable

firewall strategy

allow public access to ports 80/443 for tunnel traffic, but restrict the websocket port (8080) to trusted networks only.

reverse proxy with authentication

use nginx or similar to add authentication:

server {
    listen 443 ssl;
    server_name tunnel.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    # require basic auth for websocket connections
    location ~ ^/\?id= {
        auth_basic "Tunnel Access";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
    
    # public access to tunnels
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

basic auth

this adds basic authentication to websocket connections while keeping tunnel traffic public.

vpn or private network

deploy the server in a private network:

use a vpn to access the server
deploy on a private subnet
use ssh tunneling for connections

private deployment

the most secure approach is to deploy in a private network and use vpn/ssh for access.

monitoring

built-in logging

the server provides comprehensive logging for monitoring connections and tunnel activity.

monitor these events:

# view real-time connection logs
docker logs -f funnel-server

# search for specific events
docker logs funnel-server | grep -i "websocket\|tunnel"

key events to monitor:

websocket connection attempts
tunnel creation and removal
failed connection attempts

# monitor certificate activities
docker logs funnel-server | grep -i "certificate\|tls\|acme"

certificate-related events:

certificate generation
renewal activities
tls handshake errors

# monitor errors and failures
docker logs funnel-server | grep -i "error\|failed\|rejected"

important errors:

connection failures
invalid tunnel ids
certificate issues

future security features

roadmap

we plan to add built-in authentication and authorization features in future releases.

planned features:

authentication tokens - api keys for client connections
user management - user accounts and permissions
rate limiting - protection against abuse
ip allowlists - built-in ip-based access control

security updates

stay updated

regularly update to get the latest security patches and features.

check for updates

monitor github releases for new versions.

update procedure

# pull latest image
docker pull ghcr.io/karol-broda/funnel-server:latest

# restart with new image
docker stop funnel-server
docker rm funnel-server
docker run -d --name funnel-server [your-config] ghcr.io/karol-broda/funnel-server:latest

Last updated: July 18, 2025

by karol-broda

🔐 tls encryption

🆔 tunnel id validation

📋 comprehensive logging

🔒 modern tls

On this page