ec2-session-gate 1.0.5

Cross-platform AWS SSM tunnel/connection manager for EC2 instances

EC2 Session Gate

Secure EC2 instance management and connection gateway
A modern, cross-platform application for managing AWS EC2 instances and establishing secure connections via AWS Systems Manager Session Manager.

---

---

🚀 Overview

EC2 Session Gate simplifies secure access to your EC2 instances without exposing SSH ports or managing complex VPN configurations. Built on AWS Systems Manager Session Manager, it provides a seamless interface for SSH, RDP, and custom port forwarding connections.

Why EC2 Session Gate?

• ✅ Zero Open Ports - No need to expose SSH ports or manage security groups
• ✅ Secure by Default - Uses AWS SSM Session Manager for encrypted connections
• ✅ Cross-Platform - Works seamlessly on Windows, macOS, and Linux
• ✅ Easy to Use - Intuitive web interface with desktop app option
• ✅ Multi-Profile Support - Switch between AWS profiles effortlessly
• ✅ Auto Key Detection - Automatically finds and uses SSH keys for password decryption

---

✨ Features

Core Capabilities

• 🔐 SSH Connections
  Secure shell access via SSM port forwarding with automatic SSH key detection and path resolution

• 🖥️ RDP Support
  Remote desktop connections for Windows instances with automatic password decryption using SSH keys

• 🔌 Custom Port Forwarding
  Forward any port through SSM tunnels with flexible port selection and automatic port management

• 📊 Instance Management
  View, filter, and manage EC2 instances with real-time status updates and comprehensive instance details

• 🔑 Multi-Directory SSH Keys
  Support for multiple SSH key directories with automatic key lookup and path resolution

• ⚡ Auto-Refresh
  Automatic instance list refresh with configurable intervals

• 🎨 Modern UI
  Clean, responsive interface built with Bootstrap 5

---

📋 Prerequisites

Before you begin, ensure you have:

• Python 3.9+ installed
• AWS CLI v2 installed and configured
• AWS Session Manager Plugin installed
• AWS credentials configured (via ~/.aws/credentials or environment variables)

Installing Prerequisites

Install AWS CLI v2

macOS:

brew install awscli

Linux:

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

Windows: Windows:

choco install awscli

Download and run the installer from AWS CLI Downloads

Install Session Manager Plugin

macOS:

brew install --cask session-manager-plugin

Linux:

curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm" -o "session-manager-plugin.rpm"
sudo yum install -y session-manager-plugin.rpm

Windows:

choco install awscli-session-manager

Download and run the installer from Session Manager Plugin Downloads

---

🛠️ Installation

1. Clone the repository

   git clone https://github.com/boussaffawalid/ec2-session-gate.git
   cd ec2-session-gate
   

2. Create a virtual environment

   python -m venv .venv
   
   # Activate virtual environment
   # On macOS/Linux:
   source .venv/bin/activate
   # On Windows:
   .venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

Installing from PyPI

Alternatively, install directly from PyPI:

pip install ec2-session-gate

After installation, launch the application:

# Desktop GUI mode (default)
ec2-session-gate-gui

# Or API/server mode
APP_MODE=api ec2-session-gate

# Or web browser mode
APP_MODE=web ec2-session-gate

---

🎮 Usage

Running the Application

EC2 Session Gate supports three execution modes:

🖥️ Desktop Mode (Recommended)

Launches a native desktop window using PyWebView.

python run.py
# or explicitly:
APP_MODE=desktop python run.py

🌐 Web Browser Mode

Opens the application in your default web browser.

APP_MODE=web python run.py

🔌 API/Server Mode

Runs the Flask server only (useful for remote access or API usage).

APP_MODE=api python run.py

The application will be available at http://127.0.0.1:5000

Quick Start Guide

1. Connect to AWS

   • Select your AWS profile from the dropdown
   • Choose the AWS region
   • Click "Connect"
   • View your EC2 instances in the list

2. Start a Connection

   • SSH: Click the "SSH" button on an instance card
   • RDP: Click the "RDP" button (Windows instances only)
   • Custom Port: Click the "Port" button and specify remote/local ports

3. Manage Connections

   • View active connections in the sidebar
   • Copy connection details to clipboard
   • Terminate connections when done

Advanced Features

Instance Filtering

Use the filter box to search instances by:

• Instance name
• Instance ID
• Instance type
• Instance state
• Operating system

Supports regular expressions for advanced filtering.

Port Selection

• SSH/RDP: Automatically uses the same local port as remote port (22 for SSH, 3389 for RDP)
• Custom Ports: Uses the same local port if available, otherwise falls back to configured range
• Port Range: Configurable in Preferences with OS-specific defaults:
  • Windows: 40000-40100 (below ephemeral port range)
  • Linux/macOS: 61000-61100 (above ephemeral port range)

---

⚙️ Configuration

Preferences

Preferences are stored in:

• Linux/macOS: ~/.config/ec2-session-gate/preferences.json
• Windows: %APPDATA%\ec2-session-gate\preferences.json

Available Settings

Setting	Description	Default
Port Range	Port range for port forwarding	OS-specific (Windows: 40000-40100, Linux/macOS: 61000-61100)
SSH Key Folders	Directories where SSH keys are stored (one per line)	~/.ssh
Logging Level	Application log level	INFO

SSH Key Configuration

Configure multiple SSH key directories in Preferences:

• Each folder path on its own line
• Supports ~ expansion (e.g., ~/.ssh)
• Keys are automatically searched when decrypting Windows passwords
• SSH commands include the key path automatically

Example:

~/.ssh
~/Projects/keys
/path/to/custom/keys

---

📁 Project Structure

ec2-session-gate/
├── src/                          # Source code
│   ├── app.py                    # Flask app factory + blueprints
│   ├── api.py                    # REST API endpoints
│   ├── ui.py                     # UI routes
│   ├── aws_manager.py            # AWS SSM connection management
│   ├── preferences_handler.py    # User preferences
│   ├── health.py                 # Health check utilities
│   ├── utils.py                  # Utility functions
│   └── static/                   # Frontend assets
│       ├── css/                  # Stylesheets
│       ├── js/                   # JavaScript
│       └── templates/            # HTML templates
├── run.py                        # Application launcher
├── requirements.txt              # Python dependencies
├── pyproject.toml               # Project metadata
└── tests/                        # Test files

---

🔧 Development

Running Tests

python -m pytest tests/

Building Desktop App

Using PyInstaller (Standalone Executable)

# Install PyInstaller
pip install pyinstaller

# Build standalone executable
python build_standalone.py

# Or manually:
pyinstaller --onefile \
    --windowed \
    --add-data "src/static:src/static" \
    --add-data "src/defaults.json:src" \
    --add-data "src/logging.yaml:src" \
    --hidden-import=webview \
    --hidden-import=flask \
    run.py

The executable will be created in the dist/ directory:

• Windows: dist/ec2-session-gate.exe
• macOS: dist/ec2-session-gate.app
• Linux: dist/ec2-session-gate

Project Dependencies

• Flask>=2.3 - Web framework
• boto3>=1.34 - AWS SDK for Python
• botocore>=1.34 - AWS SDK core library
• PyYAML>=6.0 - YAML parsing for configuration
• pywebview>=4.0 - Desktop application framework
• cryptography>=41.0 - Password decryption for Windows instances
• psutil>=5.9.0 - Process management and cleanup

---

🐛 Troubleshooting

Common Issues

AWS CLI not found

Solution: Install AWS CLI v2 and ensure it's in your PATH.

Verify installation:

aws --version

Session Manager Plugin missing

Solution: Install the AWS Session Manager Plugin.

Verify installation:

session-manager-plugin

No AWS credentials detected

Solution: Configure AWS credentials via aws configure or environment variables.

aws configure
# or set environment variables:
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

Port already in use

Solution: Adjust port range in Preferences or specify a different local port when starting a connection.

SSH key not found

Solution: Add SSH key directories in Preferences. Ensure keys have correct permissions:

chmod 600 ~/.ssh/your-key.pem

Logs

Application logs are written to:

• Development: src/app.log
• Production: ~/.config/ec2-session-gate/logs/app.log

View logs:

tail -f src/app.log

---

🤝 Contributing

Contributions, feedback, and improvement ideas are welcome!

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Contact

• Maintainer: Walid Boussafa
• Email: [e-mail]
• GitHub: @boussaffawalid

---

📝 License

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

---

📦 Publishing to PyPI

Installing from PyPI

Once published, users can install the package using:

pip install ec2-session-gate

After installation, the application can be launched with:

# Desktop GUI mode (default)
ec2-session-gate-gui

# Or API/server mode
APP_MODE=api ec2-session-gate

# Or web browser mode
APP_MODE=web ec2-session-gate

Publishing a New Version

1. Update version in setup.py and pyproject.toml

2. Install build tools:

   pip install build twine
   

3. Build the package:

   make build
   # or: python -m build
   

4. Test on TestPyPI (optional):

   make publish-test
   # or: twine upload --repository testpypi dist/*
   

5. Publish to PyPI:

   make publish
   # or: twine upload dist/*
   

Standalone Executable Distribution

To create standalone executables for distribution:

# Build standalone executable
make build-standalone
# or: python build_standalone.py

The executables will be in the dist/ directory and can be distributed independently without requiring Python installation.

---

📚 Additional Resources

• AWS Systems Manager Documentation
• AWS Session Manager User Guide
• AWS CLI Documentation

---

🎯 Roadmap

• Enhanced connection history
• Connection templates/presets
• Batch operations on instances
• Export connection details
• Dark mode support
• Mobile-responsive improvements

---

🙏 Acknowledgments

This project was inspired by SSM Manager, a Windows desktop application for managing AWS SSM sessions. EC2 Session Gate extends this concept with cross-platform support and additional features.

Built with:

• Flask - Web framework
• Bootstrap - UI framework
• Boto3 - AWS SDK
• PyWebView - Desktop app framework

---

Made with ❤️ for the AWS community