timmy-academy/docs/SECURITY.md

Security Configuration

Network Binding

By default, Timmy Academy binds to 127.0.0.1 (localhost only) for security.

• Telnet: 127.0.0.1:4000
• Web Client: 127.0.0.1:4001

This prevents unauthorized external access.

External Access with TLS

For external access, use a reverse proxy with TLS:

Option 1: Nginx

# /etc/nginx/sites-available/timmy-academy
server {
    listen 443 ssl;
    server_name academy.timmy.foundation;

    ssl_certificate /etc/letsencrypt/live/academy.timmy.foundation/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/academy.timmy.foundation/privkey.pem;

    # Web client
    location / {
        proxy_pass http://127.0.0.1:4001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }

    # Telnet via WebSocket (if needed)
    location /telnet {
        proxy_pass http://127.0.0.1:4000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name academy.timmy.foundation;
    return 301 https://$server$request_uri;
}

Option 2: Caddy

# /etc/caddy/Caddyfile
academy.timmy.foundation {
    reverse_proxy localhost:4001
}

Caddy automatically handles TLS certificates.

SSH Tunnel (Development)

For development access without setting up a reverse proxy:

# From your local machine
ssh -L 4000:127.0.0.1:4000 -L 4001:127.0.0.1:4001 user@server

# Then connect to localhost:4000 (telnet) or localhost:4001 (web)

Firewall Rules

If you must bind to 0.0.0.0 (NOT RECOMMENDED), use firewall rules:

# UFW (Ubuntu)
sudo -S -p '' ufw allow from 10.0.0.0/8 to any port 4000
sudo -S -p '' ufw allow from 10.0.0.0/8 to any port 4001

# iptables
iptables -A INPUT -p tcp --dport 4000 -s 10.0.0.0/8 -j ACCEPT
iptables -A INPUT -p tcp --dport 4000 -j DROP

Why This Matters

• Telnet transmits passwords in plaintext
• Web client without TLS exposes session cookies
• 0.0.0.0 binds to ALL network interfaces
• Attackers can intercept credentials on shared networks

References

• Issue #9: [academy] Telnet and web client on 0.0.0.0 — no TLS
• Genome #678: Security audit findings