WebSSH - Secure Updated Docker Image

A web-based SSH client with updated security patches based on WebSSH.

What's New in This Image

Security Updates

• Alpine Linux 3.22.2 (latest stable, updated from 3.22.1)
• Python 3.13.8 (updated from 3.13.7)
• Paramiko 4.0.0 (updated from 3.5.1)
• Tornado 6.5.2 (updated from 6.5.1)
• OpenSSL 3.5.4 with CVE-2025-9230, CVE-2025-9231, CVE-2025-9232 patches
• Updated CA certificates (20250911)
• All Alpine packages updated to latest security patches

Image Details

• Base: python:3.13-alpine3.22
• WebSSH Version: 1.6.3
• Size: ~83MB (optimized from 268MB)
• Architecture: ARM64 (aarch64)

Quick Start

Basic Usage

docker run -d -p 8888:8888 --name webssh monzal/webssh:1.6.3-secure

Access WebSSH at: http://localhost:8888

Recommended Production Setup

docker run -d \
  -p 7773:8888 \
  --name webssh \
  --restart unless-stopped \
  monzal/webssh:1.6.3-secure

HTTPS Setup with Apache2 Reverse Proxy

Prerequisites

• Apache2 installed
• Domain name (e.g., ssh.yourdomain.com)
• Certbot for Let's Encrypt SSL certificates

Step 1: Start WebSSH Container

docker run -d \
  -p 127.0.0.1:7773:8888 \
  --name webssh \
  --restart unless-stopped \
  monzal/webssh:1.6.3-secure

Note: Binding to 127.0.0.1 ensures WebSSH is only accessible via reverse proxy.

Step 2: Enable Apache2 Modules

sudo a2enmod proxy proxy_http proxy_wstunnel ssl headers rewrite
sudo systemctl restart apache2

Step 3: Create Apache2 VirtualHost Configuration

Create /etc/apache2/sites-available/webssh.conf:

<VirtualHost *:80>
    ServerName ssh.yourdomain.com
    ServerAdmin webmaster@localhost

    # Redirect to HTTPS
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]

    ErrorLog ${APACHE_LOG_DIR}/webssh_error.log
    CustomLog ${APACHE_LOG_DIR}/webssh_access.log combined
</VirtualHost>

Enable the site:

sudo a2ensite webssh.conf
sudo systemctl reload apache2

Step 4: Generate SSL Certificate

sudo certbot --apache -d ssh.yourdomain.com --non-interactive --agree-tos --redirect

This creates /etc/apache2/sites-available/webssh-le-ssl.conf

Step 5: Configure HTTPS with Reverse Proxy

Edit /etc/apache2/sites-available/webssh-le-ssl.conf:

<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName ssh.yourdomain.com
    ServerAdmin webmaster@localhost

    # Reverse Proxy to WebSSH
    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:7773/
    ProxyPassReverse / http://127.0.0.1:7773/

    # WebSocket support for terminal
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) "ws://127.0.0.1:7773/$1" [P,L]

    # Security headers
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
    Header always set X-Content-Type-Options nosniff
    Header always set X-Frame-Options DENY
    Header always set X-XSS-Protection "1; mode=block"

    ErrorLog ${APACHE_LOG_DIR}/webssh_error.log
    CustomLog ${APACHE_LOG_DIR}/webssh_access.log combined

    SSLCertificateFile /etc/letsencrypt/live/ssh.yourdomain.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/ssh.yourdomain.com/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>
</IfModule>

Step 6: Test and Reload Apache2

sudo apache2ctl configtest
sudo systemctl reload apache2

Step 7: Access WebSSH

Open your browser: https://ssh.yourdomain.com

Optional: Add HTTP Basic Authentication

To protect WebSSH with password authentication:

Create password file:

sudo htpasswd -c /etc/apache2/.htpasswd yourusername

Add to VirtualHost configuration:

<Location />
    AuthType Basic
    AuthName "SSH Access Required"
    AuthUserFile /etc/apache2/.htpasswd
    Require valid-user
</Location>

Reload Apache2:

sudo systemctl reload apache2

Features

• SSH over HTTPS - Secure web-based terminal
• Password Authentication - Standard SSH password login
• Public Key Authentication - RSA, DSA, ECDSA, Ed25519 keys supported
• Encrypted Keys - Passphrase-protected keys supported
• Two-Factor Authentication - TOTP support
• WebSocket Support - Real-time terminal interaction
• Fullscreen Mode - Distraction-free terminal
• Customizable - Font size, colors, encoding

Environment Variables

docker run -d \
  -p 7773:8888 \
  -e "POLICY=reject" \
  -e "MAXCONN=20" \
  -e "DELAY=3" \
  --name webssh \
  monzal/webssh:1.6.3-secure

Available options:

• POLICY - Host key policy: warning (default), autoadd, reject
• MAXCONN - Maximum connections per IP (default: 20)
• DELAY - Delay between connections in seconds (default: 3)

Security Considerations

Private Key Handling

• SSH private keys uploaded via browser are NOT stored on disk
• Keys are kept temporarily in container memory only
• Keys are automatically deleted when session ends
• All communication must use HTTPS to protect keys in transit

Recommendations

1. Always use HTTPS in production
2. Use HTTP Basic Auth or firewall rules to restrict access
3. Bind to localhost when using reverse proxy
4. Regular updates - Rebuild image monthly for security patches
5. Monitor logs - Check Apache and Docker logs regularly

Docker Compose Example

Create docker-compose.yml:

version: '3.8'

services:
  webssh:
    image: monzal/webssh:1.6.3-secure
    container_name: webssh
    restart: unless-stopped
    ports:
      - "127.0.0.1:7773:8888"
    environment:
      - POLICY=reject
      - MAXCONN=20
      - DELAY=3
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Start with:

docker-compose up -d

Building from Source

git clone https://github.com/monzal/webssh
cd webssh/build
docker build -t webssh:1.6.3-secure .

Updating

Check for updates monthly:

docker pull monzal/webssh:latest
docker stop webssh
docker rm webssh
docker run -d -p 7773:8888 --name webssh --restart unless-stopped monzal/webssh:latest

Troubleshooting

Container won't start

docker logs webssh

Can't connect to SSH server

• Check SSH server is running: systemctl status ssh
• Verify firewall allows SSH: sudo ufw status
• Test SSH directly: ssh user@hostname

WebSocket connection fails

• Ensure proxy_wstunnel module is enabled in Apache2
• Check browser console for errors (F12)
• Verify Apache2 configuration syntax: apache2ctl configtest

SSL certificate issues

sudo certbot renew --dry-run
sudo certbot certificates

License

MIT License - Based on WebSSH

Support

• WebSSH on PyPI: https://pypi.org/project/webssh/
• GitHub: https://github.com/henosch/webssh
• Docker Hub: https://hub.docker.com/r/monzal/webssh

Changelog

See CHANGELOG.md for version history.