Skip to content

wsssh
wsssh
Commit a9c261ad authored by Stefy Lanza (nextime / spora )'s avatar Stefy Lanza (nextime / spora )
Browse files
Options

Update documentation for C implementation and Debian packaging 

- Updated README.md with C tools, Debian packaging, and simplified CLI
- Updated DOCUMENTATION.md with dual implementation details
- Updated CHANGELOG.md with version 1.1.0 featuring all new components
- Enhanced project structure documentation
- Added build instructions for C tools and Debian packages
- Updated API reference with C implementation details
- Improved dependency documentation for both implementations
parent cc2798c3
Hide whitespace changes
Inline Side-by-side
Showing with 273 additions and 45 deletions
CHANGELOG.md
View file @ a9c261ad
......@@ -5,6 +5,57 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [1.1.0] - 2024-09-12
### Added
- **C Implementation**: Complete C version of all tools (`wssshtools/` directory)
- `wssshc.c`: Lightweight C client for registration (280 lines)
- `wsssh.c`: Native SSH wrapper with hostname parsing (378 lines)
- `wsscp.c`: Native SCP wrapper with file transfer support (418 lines)
- `configure.sh`: Automated build configuration script
- `Makefile`: GNU Make build system with OpenSSL integration
- **Debian Packaging**: Professional Debian package creation
- `debian/control`: Package metadata with proper dependencies
- `debian/rules`: Debhelper build rules
- `debian/changelog`: Package changelog
- `debian/copyright`: Copyright and licensing information
- `debian/compat`: Debhelper compatibility level
- **Simplified CLI**: Removed requirement to specify "ssh"/"scp" commands
- `wsssh user@host` instead of `wsssh ssh user@host`
- `wsscp source dest` instead of `wsscp scp source dest`
- Backward compatibility maintained
- **Donation Integration**: Community support features
- Web interface donation modal with PayPal and cryptocurrency options
- Donation information in README and documentation
- Copy-to-clipboard functionality for crypto addresses
- **Enhanced Build System**: Improved build.sh and clean.sh scripts
- `--debian` flag for Debian package creation
- Automatic C tool building when `wssshtools/` exists
- Comprehensive cleanup of all build artifacts
- **Web Interface Enhancements**: Professional admin panel improvements
- Donation button in navigation bar
- Responsive modal design
- JavaScript copy-to-clipboard functionality
### Changed
- **Build System**: Enhanced build.sh to support C compilation and Debian packaging
- **Clean System**: Updated clean.sh to remove C build artifacts and Debian files
- **Documentation**: Comprehensive updates to README and DOCUMENTATION.md
- **Project Structure**: Added `wssshtools/` directory with complete C implementation
- **Git Management**: Added `.gitignore` for proper artifact exclusion
### Technical Details
- **C Implementation**: Native code with OpenSSL for SSL/TLS WebSocket connections
- **Debian Integration**: Proper system packaging with dependencies (OpenSSL, GCC)
- **Cross-Compilation**: Support for building both Python and C versions
- **Certificate Management**: Improved SSL certificate handling in build process
- **Web Assets**: Enhanced HTML templates with donation modal and improved UX
### Security
- **OpenSSL Integration**: Proper SSL/TLS certificate validation in C implementation
- **Certificate Pinning**: Support for secure certificate management
- **Input Validation**: Enhanced argument parsing and validation
## [1.0.0] - 2024-09-12
### Added
......
DOCUMENTATION.md
View file @ a9c261ad
......@@ -17,18 +17,28 @@ WebSocket SSH (wsssh) is a tunneling system that enables secure SSH/SCP access t
### Key Components
- **wssshd**: WebSocket SSH Daemon - Central server managing connections
#### Python Implementation (Primary)
- **wssshd**: WebSocket SSH Daemon - Central server with web interface
- **wssshc**: WebSocket SSH Client - Registers machines with the daemon
- **wsssh**: SSH wrapper - Provides SSH access through tunnels
- **wsscp**: SCP wrapper - Provides SCP access through tunnels
#### C Implementation (Alternative)
- **wssshc**: Lightweight C client for registration (OpenSSL-based)
- **wsssh**: Native SSH wrapper with direct system integration
- **wsscp**: Native SCP wrapper optimized for file transfers
### Core Features
- **Dual Implementation**: Python (full-featured) and C (lightweight) versions
- **Intelligent Hostname Parsing**: Automatic detection of client IDs and server endpoints
- **SSL/TLS Encryption**: Secure WebSocket communications
- **SSL/TLS Encryption**: Secure WebSocket communications with OpenSSL
- **Multi-client Support**: Route connections to different registered clients
- **Simplified CLI**: No need to specify "ssh" or "scp" commands explicitly
- **Drop-in Replacement**: Compatible with existing SSH/SCP workflows
- **Debian Packaging**: Professional system integration with dependencies
- **Cross-platform**: Works on Linux, macOS, and Windows
- **Donation Support**: Community funding through PayPal and cryptocurrency
## Architecture
......@@ -61,12 +71,12 @@ WebSocket SSH (wsssh) is a tunneling system that enables secure SSH/SCP access t
- Maintains persistent connection
2. **Connection Phase**:
- User runs `wsssh ssh user@client.domain`
- wsssh parses hostname to extract client ID and server endpoint
- wsssh connects to wssshd and requests tunnel to client
- wssshd forwards request to appropriate wssshc
- wssshc establishes local tunnel to SSH server
- wsssh launches SSH client to local tunnel port
- User runs `wsssh user@client.domain` (simplified CLI)
- wsssh parses hostname to extract client ID and server endpoint
- wsssh connects to wssshd and requests tunnel to client
- wssshd forwards request to appropriate wssshc
- wssshc establishes local tunnel to SSH server
- wsssh launches SSH client to local tunnel port
3. **Data Transfer Phase**:
- SSH traffic flows: SSH Client ↔ wsssh ↔ wssshd ↔ wssshc ↔ SSH Server
......@@ -242,12 +252,47 @@ wsssh [--local-port PORT] [--debug] ssh [SSH_OPTIONS...] user@host [COMMAND...]
#### Command Line Options
```bash
wsscp [--local-port PORT] [--debug] scp [SCP_OPTIONS...] SOURCE... DESTINATION
wsscp [--local-port PORT] [--debug] [SCP_OPTIONS...] SOURCE... DESTINATION
```
- `--local-port PORT`: Local tunnel port (default: auto-assign)
- `--debug`: Enable debug output
### C Implementation Tools
#### wssshc (C Client)
```bash
wssshc --server-ip IP --port PORT --id ID --password PASS [--interval SEC] [--debug]
```
- `--server-ip IP`: wssshd server IP address (required)
- `--port PORT`: wssshd server port (required)
- `--id ID`: Unique client identifier (required)
- `--password PASS`: Registration password (required)
- `--interval SEC`: Reconnection interval in seconds (default: 30)
- `--debug`: Enable debug output
#### wsssh (C SSH Wrapper)
```bash
wsssh user@client.domain -p PORT [SSH_OPTIONS...]
```
- `-p PORT`: wssshd server port
- `--local-port PORT`: Local tunnel port (default: auto)
- `--debug`: Enable debug output
#### wsscp (C SCP Wrapper)
```bash
wsscp [SCP_OPTIONS...] SOURCE... DESTINATION
```
- `-P PORT`: wssshd server port
- `--local-port PORT`: Local tunnel port (default: auto)
- `--debug`: Enable debug output
## Configuration
### SSL Certificate Configuration
......@@ -435,42 +480,98 @@ Key log messages to monitor:
```
wsssh/
├── wssshd.py # WebSocket SSH Daemon
├── wssshc.py # WebSocket SSH Client
├── wsssh.py # SSH wrapper
├── wsscp.py # SCP wrapper
├── build.sh # Build script
├── wssshd.py # WebSocket SSH Daemon (Python)
├── wssshc.py # WebSocket SSH Client (Python)
├── wsssh.py # SSH wrapper (Python)
├── wsscp.py # SCP wrapper (Python)
├── build.sh # Build script (supports --debian)
├── clean.sh # Clean script
├── cert.pem # SSL certificate
├── key.pem # SSL private key
├── requirements.txt # Python dependencies
├── cert.pem # SSL certificate (auto-generated)
├── key.pem # SSL private key (auto-generated)
├── templates/ # Flask web templates
├── static/ # Web assets
├── wssshtools/ # C implementation directory
│ ├── wssshc.c # C client (280 lines)
│ ├── wsssh.c # C SSH wrapper (378 lines)
│ ├── wsscp.c # C SCP wrapper (418 lines)
│ ├── configure.sh # Build configuration
│ ├── Makefile # GNU Make build system
│ └── debian/ # Debian packaging
│ ├── control # Package metadata
│ ├── rules # Build rules
│ ├── changelog # Package changelog
│ ├── copyright # Copyright info
│ └── compat # Debhelper compatibility
├── .gitignore # Git ignore rules
├── LICENSE.md # GPLv3 license
├── README.md # Main documentation
├── CHANGELOG.md # Version history
└── DOCUMENTATION.md # This file
├── DOCUMENTATION.md # This file
└── CHANGELOG.md # Version history
```
### Dependencies
#### Python Implementation
- **Python 3.7+**
- **websockets**: WebSocket client/server library
- **Flask**: Web framework for admin interface
- **Flask-Login**: User authentication
- **Flask-SQLAlchemy**: Database support
- **ssl**: SSL/TLS support (built-in)
- **asyncio**: Asynchronous I/O (built-in)
- **subprocess**: Process management (built-in)
- **socket**: Network sockets (built-in)
#### C Implementation
- **GCC**: GNU C Compiler
- **Make**: GNU Make build system
- **OpenSSL**: SSL/TLS library (libssl-dev)
- **pkg-config**: Build configuration tool
#### Debian Packaging
- **debhelper**: Debian packaging helper
- **dh-autoreconf**: Autotools integration
- **gcc**: C compiler
- **libssl-dev**: OpenSSL development headers
### Building from Source
#### Python Implementation
```bash
# Install dependencies
pip3 install websockets
# Run tests
python3 -m pytest tests/
# Install Python dependencies
pip3 install -r requirements.txt
# Build binaries
# Build Python binaries
./build.sh
# Clean build artifacts
# Build with Debian package
./build.sh --debian
```
#### C Implementation
```bash
# Configure and build C tools
cd wssshtools
./configure.sh
make
# Install system-wide (optional)
sudo make install
```
#### Debian Package
```bash
# Build Debian package
./build.sh --debian
# Install package
sudo dpkg -i dist/wsssh-tools*.deb
```
#### Clean Build Artifacts
```bash
# Clean all build artifacts
./clean.sh
```
......
README.md
View file @ a9c261ad
......@@ -4,39 +4,66 @@ A modern SSH tunneling system that uses WebSocket connections to securely route
## Features
- **Dual Implementation**: Python (full-featured) and C (lightweight) versions available
- **WebSocket-based Tunneling**: Secure SSH/SCP access through WebSocket connections
- **Client Registration**: Register client machines with the WebSocket daemon
- **Password Authentication**: Secure client registration with configurable passwords
- **Web Management Interface**: Professional admin panel with user management and HTML5 terminal
- **Intelligent Hostname Parsing**: `<CLIENT_ID>.<WSSSHD_HOST>` format with `-p`/`-P` port options
- **Simplified CLI**: No need to specify "ssh" or "scp" commands explicitly
- **Drop-in SSH/SCP Replacement**: Use `wsssh` and `wsscp` as direct replacements for `ssh` and `scp`
- **SSL/TLS Encryption**: All WebSocket communications are encrypted
- **Multi-client Support**: Route connections to different registered clients
- **Cross-platform**: Works on Linux, macOS, and Windows
- **Debian Packaging**: Easy installation with proper system integration
- **Donation Support**: Community funding through PayPal and cryptocurrency
## Architecture
The system consists of four main components:
The system consists of multiple components available in both Python and C implementations:
### Python Implementation (Primary)
1. **`wssshd`** - WebSocket SSH Daemon (server)
- Manages WebSocket connections
- Manages WebSocket connections with SSL/TLS encryption
- Handles client registrations with password authentication
- Routes tunnel requests to appropriate clients
- Optional web management interface with user administration
- Professional web management interface with user administration
- HTML5 terminal interface for SSH connections
- Donation modal integrated into the web interface
2. **`wssshc`** - WebSocket SSH Client (registration)
- Registers client machines with the daemon
- Maintains persistent WebSocket connection
- Automatic reconnection with configurable intervals
3. **`wsssh`** - SSH wrapper with tunneling
- Parses SSH commands and hostnames
- Establishes WebSocket tunnels
- Simplified CLI (no need to specify "ssh" command)
- Parses SSH commands and hostnames intelligently
- Establishes WebSocket tunnels automatically
- Launches SSH to local tunnel port
4. **`wsscp`** - SCP wrapper with tunneling
- Similar to wsssh but for SCP operations
- Handles file transfers through tunnels
- Simplified CLI (no need to specify "scp" command)
- Similar to wsssh but optimized for SCP operations
- Handles file transfers through secure tunnels
### C Implementation (Alternative)
Located in the `wssshtools/` directory:
1. **`wssshc`** - Lightweight C client for registration
- Minimal dependencies (OpenSSL only)
- Native WebSocket implementation
- Optimized for embedded systems
2. **`wsssh`** - Native SSH wrapper
- Direct system integration
- No Python runtime required
- High performance for production use
3. **`wsscp`** - Native SCP wrapper
- Optimized file transfer operations
- Consistent with SSH wrapper design
- Enterprise-ready performance
## Installation
......@@ -58,6 +85,37 @@ pip3 install -r requirements.txt
Download the latest release binaries for your platform from the releases page.
### Debian Package Installation
For Debian/Ubuntu systems, you can install the C implementation via Debian package:
```bash
# Build the Debian package
./build.sh --debian
# Install the package
sudo dpkg -i dist/wsssh-tools*.deb
# The C tools will be available system-wide
wssshc --help
wsssh --help
wsscp --help
```
### C Implementation Build
To build the C tools from source:
```bash
# Configure and build C tools
cd wssshtools
./configure.sh
make
# Install system-wide (optional)
sudo make install
```
## Quick Start
### 1. Start the WebSocket Daemon
......@@ -77,7 +135,11 @@ On the client machine you want to access through:
### 3. Connect via SSH
```bash
./wsssh -p 9898 user@myclient.example.com
# Simplified CLI (recommended)
./wsssh user@myclient.example.com -p 9898
# Or using C implementation
./wssshtools/wsssh user@myclient.example.com -p 9898
```
This automatically:
......@@ -270,23 +332,37 @@ python3 -m pytest
wsssh/
├── wssshd.py # WebSocket SSH Daemon with web interface
├── wssshc.py # WebSocket SSH Client
├── wsssh.py # SSH wrapper
├── wsscp.py # SCP wrapper
├── build.sh # Build script
├── wsssh.py # SSH wrapper (simplified CLI)
├── wsscp.py # SCP wrapper (simplified CLI)
├── build.sh # Build script (supports --debian flag)
├── clean.sh # Clean script
├── requirements.txt # Python dependencies
├── cert.pem # SSL certificate
├── key.pem # SSL private key
├── cert.pem # SSL certificate (auto-generated)
├── key.pem # SSL private key (auto-generated)
├── templates/ # Flask HTML templates
│ ├── base.html
│ ├── index.html
│ ├── login.html
│ ├── terminal.html
│ └── users.html
│ ├── base.html # Base template with donation modal
│ ├── index.html # Dashboard
│ ├── login.html # Authentication
│ ├── terminal.html # HTML5 terminal
│ └── users.html # User management
├── static/ # Static web assets
├── LICENSE # GPLv3 license
├── wssshtools/ # C implementation directory
│ ├── wssshc.c # C client for registration
│ ├── wsssh.c # C SSH wrapper
│ ├── wsscp.c # C SCP wrapper
│ ├── configure.sh # C build configuration
│ ├── Makefile # C build system
│ └── debian/ # Debian packaging
│ ├── control # Package metadata
│ ├── rules # Build rules
│ ├── changelog # Package changelog
│ ├── copyright # Copyright info
│ └── compat # Debhelper compatibility
├── .gitignore # Git ignore rules
├── LICENSE.md # GPLv3 license
├── README.md # This file
└── docs/ # Documentation
├── DOCUMENTATION.md # Technical documentation
└── CHANGELOG.md # Version history
```
## Contributing
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment