ShellPoint

Professional Web-Based SSH Client

🚀 Features

🔐 Secure Authentication - JWT-based authentication with bcrypt password hashing
🔑 SSH Key Support - RSA, ED25519, and ECDSA key authentication
📑 Multiple Sessions - Handle multiple SSH connections in tabs
📁 SFTP File Manager - Visual dual-pane file manager with drag-and-drop support
- Browse local files from your computer and remote SFTP files side-by-side
- Upload/download files between local and remote
- Edit text files directly in the browser
- Change file permissions (chmod) with visual interface
- Create folders, delete files, and manage remote file system
🎨 Terminal Themes - 8 beautiful terminal color schemes (Dracula, Nord, Tokyo Night, etc.)
👤 User Profiles - Manage user settings and preferences
💾 Connection Manager - Save and organize SSH connections with descriptions
🌐 Modern UI - Beautiful, responsive interface with Material Design icons
🔒 SSH Keys Vault - Securely store and manage SSH private keys
🐳 Docker Ready - Easy deployment with Docker and docker-compose

⚡ Quick Start

Using Docker (Recommended)

# Run with docker-compose
docker-compose up -d

# Or run directly
docker run -d \
  -p 8080:8080 \
  -e JWT_SECRET="your-random-secret-key-here" \
  -v shellpoint-data:/app/data \
  ghcr.io/cognitiolabs/shellpoint:latest

Using Node.js

# Clone repository
git clone https://github.com/cognitiolabs/shellpoint.git
cd shellpoint

# Install dependencies
npm install

# Create .env file
echo "JWT_SECRET=$(node -e \"console.log(require('crypto').randomBytes(64).toString('hex'))\")" > .env

# Start application
npm start

Visit http://localhost:8080 and create your first account!

📦 Installation

Prerequisites

Node.js >= 20.x
npm >= 9.x
Docker (optional, for containerized deployment)

Local Installation

Clone the repository:

git clone https://github.com/cognitiolabs/shellpoint.git
cd shellpoint

Install dependencies:
```
npm install
```

Set up environment variables:

cp .env.example .env
# Edit .env and set JWT_SECRET

Start the application:

# Production
npm start

# Development (with auto-reload)
npm run dev

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# Required
JWT_SECRET=your-cryptographically-secure-random-key

# Optional
PORT=8080
DB_PATH=./ssh-client.db
NODE_ENV=production

Generate Secure JWT Secret

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

🎯 Usage

First Time Setup

Navigate to http://localhost:8080
Click Register and create an account
Log in with your credentials

Adding Connections

Click "Add Connection" button
Fill in connection details:
- Name: Friendly name for the connection
- Host: Server hostname or IP
- Port: SSH port (default: 22)
- Username: SSH username
- Description: Optional notes
Choose connection type:
- SSH Terminal: Interactive terminal session
- SFTP File Manager: Visual file browser
Choose authentication method:
- Password: Enter SSH password
- SSH Key: Select from vault or add new key
Click Save

Using SFTP File Manager

Create an SFTP connection (select "SFTP File Manager" as connection type)
Click the connection to open the file manager
Local Panel (left):
- Click "Upload" to add files from your computer
- Files are temporarily stored in browser for transfer
Remote Panel (right):
- Browse remote server files
- Create folders, edit files, change permissions
- Download files to your computer
File Operations:
- Edit: Click edit icon to modify text files
- Chmod: Click lock icon to change file permissions
- Download: Click download icon to save file
- Delete: Click trash icon to remove file
- Upload from Local: Select files in local panel, then click "Upload from Local" in remote panel

Managing SSH Keys

Click the key icon 🔑 in the sidebar
Click "Add SSH Key"
Provide:
- Key name
- Private key content (or upload file)
- Passphrase (if encrypted)
- Key type (RSA/ED25519/ECDSA)
Use keys in connections via SSH Key authentication

Terminal Themes

Click your username in the sidebar
Select Terminal Theme from dropdown
Choose from 8 themes:
- Default, Dracula, Monokai, Nord
- One Dark, Solarized Dark, Gruvbox, Tokyo Night

🐳 Docker Deployment

Using docker-compose (Recommended)

# Start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

# Stop and remove data
docker-compose down -v

Using Docker CLI

# Build image
docker build -t shellpoint:latest .

# Run container
docker run -d \
  --name shellpoint \
  -p 8080:8080 \
  -e JWT_SECRET="your-secret" \
  -v shellpoint-data:/app/data \
  shellpoint:latest

🏭 Production Deployment

📋 Production Checklist

For production environments, ShellPoint includes additional security, monitoring, and scaling features:

✅ Security Features:

JWT authentication with httpOnly cookies
bcrypt password hashing (salt rounds: 10)
Rate limiting on authentication endpoints
Non-root Docker container execution
Health check endpoint for monitoring
Input validation and sanitization

✅ Monitoring & Observability:

/health endpoint with comprehensive status
Prometheus metrics support
Structured JSON logging
Database connection health monitoring
Memory and resource usage tracking

✅ CI/CD Pipeline:

Automated testing on every commit
Security scanning (npm audit + Trivy)
Multi-arch Docker builds (AMD64/ARM64)
Automated deployments to staging/production
SBOM generation for compliance

🚀 Quick Production Setup

# 1. Clone repository
git clone https://github.com/cognitiolabs/shellpoint.git
cd shellpoint

# 2. Setup environment
cp .env.production.example .env.production
# Edit .env.production with your secure secrets

# 3. Deploy with production optimizations
docker-compose up -d

# 4. Verify deployment
curl http://localhost:8080/health

# 5. Setup reverse proxy for HTTPS (nginx/traefik recommended)

🔒 Security Configuration

Generate secure secrets:

# JWT Secret (REQUIRED for production)
JWT_SECRET=$(node -e "console.log(require('crypto').randomBytes(64).toString('hex'))")

# Optional database encryption key
DB_ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")

Reverse proxy with HTTPS (nginx example):

server {
    listen 443 ssl http2;
    server_name shellpoint.yourdomain.com;

    ssl_certificate /path/to/your/cert.pem;
    ssl_certificate_key /path/to/your/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

📊 Monitoring Setup

Health Check Endpoint:

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "uptime": 3600,
  "environment": "production",
  "version": "1.3.0",
  "memory": {"used": 45, "total": 512},
  "database": {"status": "connected", "userCount": 15}
}

Prometheus Metrics:

# Enable metrics in environment
METRICS_ENABLED=true
METRICS_PORT=9090

# Access metrics
curl http://localhost:9090/metrics

🔄 Deployment Strategies

1. Automated Deployment Script:

# Deploy to staging
./deploy.sh staging v1.3.0

# Deploy to production (requires confirmation)
./deploy.sh production v1.3.0

2. CI/CD Pipeline:

Push to main → Automated tests
Create tag (v1.3.0) → Build + deploy to staging
Manual approval → Deploy to production

3. Blue-Green Deployment:

# Deploy to staging first
docker-compose -f docker-compose.staging.yml up -d

# Test staging environment
curl -f https://staging.yourdomain.com/health

# Switch traffic to production
docker-compose -f docker-compose.prod.yml up -d

💾 Backup & Recovery

Automated daily backup:

# Backup script included in deployment
./deploy.sh production

# Manual backup
docker run --rm \
  -v shellpoint-data:/source:ro \
  -v $(pwd):/backup \
  alpine:latest \
  tar czf "backup-$(date +%Y%m%d).tar.gz" -C /source .

Restore from backup:

docker-compose down
docker run --rm \
  -v shellpoint-data:/target \
  -v $(pwd):/backup \
  alpine:latest \
  tar xzf backup-20240101.tar.gz -C /target
docker-compose up -d

📱 Scaling Considerations

Single Instance (Small Teams):

1 container, 512MB RAM, 1 CPU
SQLite database (built-in)
Suitable for 1-50 concurrent users

Multi-Instance (Medium Teams):

3 containers behind load balancer
PostgreSQL database (recommended)
Suitable for 50-200 concurrent users

High Availability (Large Teams):

5+ containers with health checks
External database with read replicas
Redis for session storage
Suitable for 200+ concurrent users

🚀 Docker Images

Production-ready images available:

Docker Hub: cognitiolabs/shellpoint:latest
GitHub Registry: ghcr.io/cognitiolabs/shellpoint:latest

Multi-architecture support:

linux/amd64 (Intel/AMD)
linux/arm64 (ARM64/Apple Silicon)

Image tags:

latest - Latest stable release
v1.3.0 - Specific version
v1.2 - Latest patch release
v1 - Latest minor release

📚 Production Documentation

For comprehensive production setup, see:

🛠️ Development

Project Structure

shellpoint/
├── server.js              # Express server & WebSocket
├── public/
│   ├── index.html        # Frontend UI
│   ├── app.js            # Client-side logic
│   └── style.css         # Additional styles
├── .env.example          # Example environment config
├── Dockerfile            # Docker image definition
├── docker-compose.yml    # Docker compose config
└── docs/
    └── knowledge-base.md # Development documentation

Tech Stack

Backend: Node.js, Express, WebSocket (ws), SSH2, Better-SQLite3, bcrypt, JWT

Frontend: Vanilla JavaScript, Tailwind CSS, xterm.js, Material Design Icons

🔒 Security

Current Security Features

✅ JWT authentication with httpOnly cookies ✅ bcrypt password hashing (salt rounds: 10) ✅ Secure cookie flags (secure, sameSite) ✅ Input validation (port range, host format) ✅ Password strength requirements (min 8 chars, letter + number) ✅ Environment-based JWT secret

Production Recommendations

⚠️ Database Encryption: Currently, SSH keys and passwords are stored in plaintext in SQLite. For production use, implement encryption at rest.

⚠️ HTTPS: Always use HTTPS in production. Use a reverse proxy (nginx/Traefik) with valid SSL certificates.

⚠️ Rate Limiting: Implement rate limiting on authentication endpoints to prevent brute force attacks.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

xterm.js - Terminal emulator
SSH2 - SSH client library
Tailwind CSS - CSS framework
Material Icons - Icon library

📞 Support

Issues: GitHub Issues
Website: https://www.cognitiolabs.eu
Email: info@cognitiolabs.eu

Made with ❤️ by CognitioLabs

Website · GitHub · Documentation

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
.github		.github
assets		assets
docs		docs
public		public
.dockerignore		.dockerignore
.env.example		.env.example
.env.production.example		.env.production.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
deploy.sh		deploy.sh
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js

License

cognitolabs-ai/Shellpoint

Folders and files

Latest commit

History

Repository files navigation