CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

WebSSH is a web-based SSH client. A Tornado async server handles HTTP/WebSocket connections and tunnels terminal I/O to remote SSH servers via Paramiko. The browser renders the terminal using xterm.js.

Development Commands

# Install
pip install -r requirements.txt
pip install -e .            # editable install (provides `wssh` CLI entry point)

# Run
python run.py               # starts on default port 8888
python run.py --port=8888 --debug=True --data-dir=./data

# Lint
ruff check .                # or: flake8 . (max-line-length=79, see setup.cfg)

# Test
pytest                      # all tests
pytest --cov=webssh         # with coverage
pytest tests/test_app.py    # single file

Architecture

Browser (xterm.js + WebSocket) <--> Tornado (WsockHandler) <--> Paramiko SSH channel <--> Remote SSH server

Backend (webssh/)

main.py — entry point; wires routes, parses CLI options, starts Tornado IOLoop.
handler.py — all Tornado request handlers. MixinHandler is the base mixin providing IP filtering, XSRF, origin checks, and session auth. Key handlers: IndexHandler (serves UI on GET, initiates SSH on POST), WsockHandler (WebSocket relay), LoginHandler/LogoutHandler, ConnectionsHandler/ConnectionHandler.
worker.py — Worker class manages the Paramiko SSH channel lifecycle and registers its socket fd on Tornado's IOLoop for async read/write.
settings.py — CLI option definitions (Tornado define()), host key loading, SSL context setup, font defaults.
auth.py — admin user setup and password verification using PBKDF2-SHA256.
storage.py — persistent saved-connections store (connections.json) with file locking.
policy.py — thread-safe AutoAddPolicy wrapper for Paramiko host key validation.
utils.py — input parsing/validation helpers (to_str, to_bytes, to_int, to_ip_address, hostname/port validators).

Frontend (webssh/static/js/main.js, webssh/templates/)

jQuery 3 + Bootstrap 4 UI, xterm.js terminal, WebSocket bridge.
index.html — terminal page; login.html — auth page.

Data directory (~/.webssh or --data-dir): stores auth.json, connections.json, cookie secret.

Key Design Constraints

Async safety: Paramiko SSH connections are blocking. Always run them via IndexHandler.executor (ThreadPoolExecutor) to avoid blocking the Tornado IOLoop.
Thread safety: File writes to auth.json/connections.json and Paramiko host-key mutations must use threading.Lock.
New endpoints: Subclass MixinHandler. Use @tornado.web.authenticated for protected routes.
Python 3.10+ required (see setup.py classifiers).
File permissions: Database files (auth.json, connections.json) are created with mode 0o600.

Testing

Tests use pytest. tests/sshserver.py spins up a local mock SSH server (Paramiko-based) for integration testing of handler connections, password auth, key auth, and 2FA.

3.1 KiB Raw Blame History