monzal/webssh repository overview

⁠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

⁠Changelog

All notable changes to this project will be documented in this file.

⁠[1.6.3-secure] - 2025-10-10

⁠Security Updates

⁠Alpine Linux

• Updated from Alpine Linux 3.22.1 to 3.22.2
• Applied all security patches as of October 8, 2025

⁠OpenSSL

• Updated from OpenSSL 3.5.1 to 3.5.4
• Fixed CVE-2025-9230: CMS message decryption vulnerability
• Fixed CVE-2025-9231: Password-based encryption denial of service
• Fixed CVE-2025-9232: Attacker-supplied code execution risk

⁠Python & Dependencies

• Updated Python from 3.13.7 to 3.13.8
• Updated Paramiko from 3.5.1 to 4.0.0
• Updated Tornado from 6.5.1 to 6.5.2

⁠System Packages

• Updated CA certificates from 20250619 to 20250911
• Updated busybox from 1.37.0-r18 to 1.37.0-r19
• Updated ssl_client from 1.37.0-r18 to 1.37.0-r19
• Updated apk-tools from 2.14.9-r2 to 2.14.9-r3

⁠Added

• Comprehensive README.md with production deployment guide
• Apache2 reverse proxy configuration examples
• HTTPS/SSL setup instructions with Let's Encrypt
• HTTP Basic Authentication setup guide
• Docker Compose example configuration
• Security considerations documentation
• Troubleshooting section

⁠Changed

• Base image: python:3.13-alpine3.22 (ensures latest Alpine 3.22.x)
• Installation method: Using PyPI package instead of git clone
• Optimized Dockerfile: Reduced image size by 69% (268MB → 83MB)
  • Combined RUN layers to reduce size
  • Added cache cleanup (rm -rf /var/cache/apk/* /root/.cache)
  • Removed unnecessary dependencies (git)
  • Used virtual build-deps for easier cleanup
• Improved Dockerfile with security best practices

⁠Image Details

• Size: ~83MB (optimized from 268MB)
• Architecture: ARM64 (aarch64)
• Base: Alpine Linux 3.22.2
• WebSSH Version: 1.6.3
• Build Date: 2025-10-10

⁠Security Notes

• All known CVEs patched as of October 10, 2025
• Alpine Linux security repository fully synced
• Recommended for production use with HTTPS reverse proxy
• Monthly rebuilds recommended to stay current with security patches

⁠[Original austozi/webssh:1.6.3] - 2025-08-XX

⁠Initial Release

• Alpine Linux 3.22.1
• Python 3.13.7
• Paramiko 3.5.1
• Tornado 6.5.1
• WebSSH 1.6.3

⁠Update Schedule

This image should be rebuilt monthly to incorporate:

• Alpine Linux security updates
• Python security patches
• Dependency updates (Paramiko, Tornado)
• OpenSSL security fixes

⁠Versioning

This project follows the versioning scheme:

• [WebSSH Version]-[Security Status]
• Example: 1.6.3-secure

Tags:

• 1.6.3-secure - Specific secure build
• latest - Always points to most recent secure build
• 1.6.3 - Original WebSSH version without security updates

⁠Upgrade Path

⁠From austozi/webssh:1.6.3

# Stop old container
docker stop webssh
docker rm webssh

# Pull and run updated image
docker pull monzal/webssh:1.6.3-secure
docker run -d -p 7773:8888 --name webssh --restart unless-stopped monzal/webssh:1.6.3-secure

No configuration changes required - drop-in replacement.