# LazySSH
A comprehensive SSH toolkit for managing connections, tunnels, and remote sessions with a modern CLI interface.
## Overview
LazySSH simplifies SSH connection management with an elegant CLI interface. It helps you manage multiple connections, create tunnels, transfer files, and automate common SSH tasks.
### Key Features
- **Interactive Command Interface**: Smart command mode with tab completion and guided workflows
- **Connection Management**: Handle multiple SSH connections with control sockets
- **Saved Configurations**: Save and reuse connection configurations with TOML-based storage
- **Tunneling**: Create forward and reverse tunnels with simple commands
- **Dynamic Proxy**: Set up SOCKS proxy for secure browsing
- **SCP Mode**: Transfer files securely with rich visualization and progress tracking
- **Terminal Integration**: Open terminal sessions directly with runtime method switching
- **Plugin System**: Extend functionality with custom Python or shell scripts
- **Wizard Workflows**: Guided interactive workflows for complex operations
- **Rich Visual Elements**: Color coding, progress bars, and tree visualizations
## Quick Start
### Installation
```bash
# Install globally
pip install lazyssh
# Or with pipx (recommended)
pipx install lazyssh
# Or install for the current user only
pip install --user lazyssh
```
### Basic Usage
```bash
# Start LazySSH
lazyssh
# Create a new connection
lazyssh> lazyssh -ip 192.168.1.100 -port 22 -user admin -socket myserver
# Create a connection with dynamic SOCKS proxy
lazyssh> lazyssh -ip 192.168.1.100 -port 22 -user admin -socket myserver -proxy 8080
# Create a tunnel
lazyssh> tunc myserver l 8080 localhost 80
# Open a terminal
lazyssh> open myserver
# Transfer files (SCP mode)
lazyssh> scp myserver
# Use plugins for automation
lazyssh> plugin list # List available plugins
lazyssh> plugin run enumerate myserver # Run system enumeration
# Use wizard for guided workflows
lazyssh> wizard lazyssh
lazyssh> wizard tunnel
# In SCP mode: visualize remote directory tree
scp myserver:/home/user> tree
# Download files
scp myserver:/home/user> get config.json
```
## Plugin System
LazySSH features an extensible plugin system that allows you to run custom Python or shell scripts through established SSH connections. This enables automation, reconnaissance, and custom workflows without leaving LazySSH.
### Built-in Plugins
#### Enumerate Plugin
Performs comprehensive system enumeration including:
- OS and kernel information
- User accounts and groups
- Network configuration (interfaces, routes, listening ports)
- Running processes and services
- Installed packages (apt/yum/pacman)
- Filesystem information and mounts
- Environment variables
- Scheduled tasks (cron, systemd timers)
- Security configurations (firewall, SELinux/AppArmor)
- System logs
- Hardware information
```bash
lazyssh> plugin run enumerate myserver
```
### Using Plugins
```bash
# List all available plugins
lazyssh> plugin list
# Get detailed information about a plugin
lazyssh> plugin info enumerate
# Run a plugin on an established connection
lazyssh> plugin run <plugin-name> <socket-name>
```
### Creating Custom Plugins
Plugins are simple Python or shell scripts that can execute commands through SSH control sockets. See `src/lazyssh/plugins/README.md` for a comprehensive plugin development guide.
**Quick Example:**
```python
#!/usr/bin/env python3
# PLUGIN_NAME: my-plugin
# PLUGIN_DESCRIPTION: My custom automation script
# PLUGIN_VERSION: 1.0.0
import os
import subprocess
import sys
# LazySSH provides connection info via environment variables
host = os.environ.get("LAZYSSH_HOST")
user = os.environ.get("LAZYSSH_USER")
socket_path = os.environ.get("LAZYSSH_SOCKET_PATH")
# Execute commands on remote host using SSH control socket
cmd = ["ssh", "-S", socket_path, "-o", "ControlMaster=no",
f"{user}@{host}", "your-command-here"]
result = subprocess.run(cmd, capture_output=True, text=True)
print(result.stdout)
```
Place your plugin in `src/lazyssh/plugins/`, make it executable (`chmod +x`), and it will be automatically discovered.
For detailed plugin development instructions, examples, and best practices, see the [Plugin Development Guide](src/lazyssh/plugins/README.md).
## Documentation
For detailed documentation, please see the [docs directory](docs/):
- [User Guide](docs/user-guide.md): Comprehensive guide to using LazySSH
- [Command Reference](docs/commands.md): Details on all available commands
- [SCP Mode Guide](docs/scp-mode.md): How to use the file transfer capabilities
- [Tunneling Guide](docs/tunneling.md): Creating and managing SSH tunnels
- [Troubleshooting](docs/troubleshooting.md): Common issues and solutions
- [Development Guide](docs/development.md): Information for contributors
- [Publishing Guide](docs/publishing.md): How to publish the package
## Requirements
- Python 3.11+
- OpenSSH client
### Optional Dependencies
- **Terminator terminal emulator** - For opening terminals in external windows. If not installed, LazySSH will use a native terminal that runs in the current terminal window.
### Platform Support
LazySSH is compatible with:
- **Linux** - Full support
- **macOS** - Full support
**Windows Users:** Windows OpenSSH does not support SSH master mode (`-M` flag) which is required for LazySSH's persistent connection functionality. Windows users should use [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install) to run LazySSH with full functionality.
## Terminal Methods
LazySSH supports two methods for opening SSH terminal sessions:
### Native Terminal (Default)
The native terminal method runs SSH as a subprocess in your current terminal window. This requires no external dependencies and works out of the box. **Important:** You can exit the SSH session (using `exit` or `Ctrl+D`) and return to LazySSH without closing the SSH connection, allowing you to manage multiple sessions easily.
### Terminator Terminal
If you have Terminator installed, LazySSH can open SSH sessions in new Terminator windows. This is useful if you want to keep multiple terminals open simultaneously.
### Configuration
You can control which terminal method to use either at runtime or via environment variable:
**Runtime configuration (recommended):**
```bash
# From command mode
lazyssh> terminal native # Set terminal method to native
lazyssh> terminal auto # Set terminal method to auto
lazyssh> terminal terminator # Set terminal method to terminator
```
**Environment variable:**
```bash
# Automatically select best available method (default)
# Tries Terminator first, falls back to native
export LAZYSSH_TERMINAL_METHOD=auto
# Force native terminal (runs in current window)
export LAZYSSH_TERMINAL_METHOD=native
# Force Terminator (requires Terminator to be installed)
export LAZYSSH_TERMINAL_METHOD=terminator
```
**Default behavior (auto):**
- If Terminator is installed: Opens terminals in new Terminator windows
- If Terminator is not installed: Uses native terminal in current window
- Falls back gracefully if the preferred method fails
**Features:**
- Native terminal allows returning to LazySSH after exiting the SSH session
- Terminal method can be changed at runtime without restarting LazySSH
- Terminal method is displayed in the SSH connections status table
## Saved Connection Configurations
LazySSH allows you to save connection configurations for quick reuse. Configurations are stored securely in TOML format at `/tmp/lazyssh/connections.conf` with owner-only permissions (600).
### Saving Connections
After creating a successful connection, LazySSH will prompt you to save it:
```bash
lazyssh> lazyssh -ip server.example.com -port 22 -user admin -socket myserver
# After connection succeeds
Save this connection configuration? (y/N): y
Enter config name [myserver]: prod-server
✓ Configuration saved as 'prod-server'
```
Or save manually from command mode:
```bash
lazyssh> save-config prod-server
```
### Using Saved Configurations
**View saved configurations:**
```bash
lazyssh> config
# Displays table of all saved configurations
```
**Connect using a saved configuration:**
```bash
lazyssh> connect prod-server
```
**Delete a saved configuration:**
```bash
lazyssh> delete-config prod-server
```
### Configuration File Format
Configurations are stored in TOML format at `/tmp/lazyssh/connections.conf`:
```toml
[prod-server]
host = "server.example.com"
port = 22
username = "admin"
ssh_key = "/home/user/.ssh/id_rsa"
[dev-server]
host = "192.168.1.100"
port = 2222
username = "developer"
proxy_port = 9050
```
### Security Considerations
- **File Permissions**: Config file is automatically set to mode 600 (owner read/write only)
- **Location**: Files are stored in `/tmp/lazyssh/` which is cleared on system reboot
- **SSH Keys**: Only paths to SSH keys are stored, not the keys themselves
- **Sensitive Data**: Consider using SSH keys instead of password authentication
- **Manual Editing**: You can safely edit the TOML file directly if needed
### CLI Flag
View configurations at startup:
```bash
lazyssh --config
```
Or specify a custom config file path:
```bash
lazyssh --config /path/to/custom/connections.conf
```
## License
MIT License
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": null,
"name": "lazyssh",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "ssh, tunnel, proxy, socks, terminal, connection, management",
"author": null,
"author_email": "Bochner <lazyssh@example.com>",
"download_url": "https://files.pythonhosted.org/packages/ab/eb/8ec5ad5f567ec0ae6c14a8fa9e26e15fba6ef821371837e21dc29bda60fa/lazyssh-1.5.0.tar.gz",
"platform": null,
"description": "# LazySSH\n\nA comprehensive SSH toolkit for managing connections, tunnels, and remote sessions with a modern CLI interface.\n\n\n\n## Overview\n\nLazySSH simplifies SSH connection management with an elegant CLI interface. It helps you manage multiple connections, create tunnels, transfer files, and automate common SSH tasks.\n\n### Key Features\n\n- **Interactive Command Interface**: Smart command mode with tab completion and guided workflows\n- **Connection Management**: Handle multiple SSH connections with control sockets\n- **Saved Configurations**: Save and reuse connection configurations with TOML-based storage\n- **Tunneling**: Create forward and reverse tunnels with simple commands\n- **Dynamic Proxy**: Set up SOCKS proxy for secure browsing\n- **SCP Mode**: Transfer files securely with rich visualization and progress tracking\n- **Terminal Integration**: Open terminal sessions directly with runtime method switching\n- **Plugin System**: Extend functionality with custom Python or shell scripts\n- **Wizard Workflows**: Guided interactive workflows for complex operations\n- **Rich Visual Elements**: Color coding, progress bars, and tree visualizations\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install globally\npip install lazyssh\n\n# Or with pipx (recommended)\npipx install lazyssh\n\n# Or install for the current user only\npip install --user lazyssh\n```\n\n### Basic Usage\n\n```bash\n# Start LazySSH\nlazyssh\n\n# Create a new connection\nlazyssh> lazyssh -ip 192.168.1.100 -port 22 -user admin -socket myserver\n\n# Create a connection with dynamic SOCKS proxy\nlazyssh> lazyssh -ip 192.168.1.100 -port 22 -user admin -socket myserver -proxy 8080\n\n# Create a tunnel\nlazyssh> tunc myserver l 8080 localhost 80\n\n# Open a terminal\nlazyssh> open myserver\n\n# Transfer files (SCP mode)\nlazyssh> scp myserver\n\n# Use plugins for automation\nlazyssh> plugin list # List available plugins\nlazyssh> plugin run enumerate myserver # Run system enumeration\n\n# Use wizard for guided workflows\nlazyssh> wizard lazyssh\nlazyssh> wizard tunnel\n\n# In SCP mode: visualize remote directory tree\nscp myserver:/home/user> tree\n\n# Download files\nscp myserver:/home/user> get config.json\n```\n\n## Plugin System\n\nLazySSH features an extensible plugin system that allows you to run custom Python or shell scripts through established SSH connections. This enables automation, reconnaissance, and custom workflows without leaving LazySSH.\n\n### Built-in Plugins\n\n#### Enumerate Plugin\n\nPerforms comprehensive system enumeration including:\n- OS and kernel information\n- User accounts and groups\n- Network configuration (interfaces, routes, listening ports)\n- Running processes and services\n- Installed packages (apt/yum/pacman)\n- Filesystem information and mounts\n- Environment variables\n- Scheduled tasks (cron, systemd timers)\n- Security configurations (firewall, SELinux/AppArmor)\n- System logs\n- Hardware information\n\n```bash\nlazyssh> plugin run enumerate myserver\n```\n\n### Using Plugins\n\n```bash\n# List all available plugins\nlazyssh> plugin list\n\n# Get detailed information about a plugin\nlazyssh> plugin info enumerate\n\n# Run a plugin on an established connection\nlazyssh> plugin run <plugin-name> <socket-name>\n```\n\n### Creating Custom Plugins\n\nPlugins are simple Python or shell scripts that can execute commands through SSH control sockets. See `src/lazyssh/plugins/README.md` for a comprehensive plugin development guide.\n\n**Quick Example:**\n\n```python\n#!/usr/bin/env python3\n# PLUGIN_NAME: my-plugin\n# PLUGIN_DESCRIPTION: My custom automation script\n# PLUGIN_VERSION: 1.0.0\n\nimport os\nimport subprocess\nimport sys\n\n# LazySSH provides connection info via environment variables\nhost = os.environ.get(\"LAZYSSH_HOST\")\nuser = os.environ.get(\"LAZYSSH_USER\")\nsocket_path = os.environ.get(\"LAZYSSH_SOCKET_PATH\")\n\n# Execute commands on remote host using SSH control socket\ncmd = [\"ssh\", \"-S\", socket_path, \"-o\", \"ControlMaster=no\",\n f\"{user}@{host}\", \"your-command-here\"]\n\nresult = subprocess.run(cmd, capture_output=True, text=True)\nprint(result.stdout)\n```\n\nPlace your plugin in `src/lazyssh/plugins/`, make it executable (`chmod +x`), and it will be automatically discovered.\n\nFor detailed plugin development instructions, examples, and best practices, see the [Plugin Development Guide](src/lazyssh/plugins/README.md).\n\n## Documentation\n\nFor detailed documentation, please see the [docs directory](docs/):\n\n- [User Guide](docs/user-guide.md): Comprehensive guide to using LazySSH\n- [Command Reference](docs/commands.md): Details on all available commands\n- [SCP Mode Guide](docs/scp-mode.md): How to use the file transfer capabilities\n- [Tunneling Guide](docs/tunneling.md): Creating and managing SSH tunnels\n- [Troubleshooting](docs/troubleshooting.md): Common issues and solutions\n- [Development Guide](docs/development.md): Information for contributors\n- [Publishing Guide](docs/publishing.md): How to publish the package\n\n## Requirements\n\n- Python 3.11+\n- OpenSSH client\n\n### Optional Dependencies\n\n- **Terminator terminal emulator** - For opening terminals in external windows. If not installed, LazySSH will use a native terminal that runs in the current terminal window.\n\n### Platform Support\n\nLazySSH is compatible with:\n- **Linux** - Full support\n- **macOS** - Full support\n\n**Windows Users:** Windows OpenSSH does not support SSH master mode (`-M` flag) which is required for LazySSH's persistent connection functionality. Windows users should use [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install) to run LazySSH with full functionality.\n\n## Terminal Methods\n\nLazySSH supports two methods for opening SSH terminal sessions:\n\n### Native Terminal (Default)\nThe native terminal method runs SSH as a subprocess in your current terminal window. This requires no external dependencies and works out of the box. **Important:** You can exit the SSH session (using `exit` or `Ctrl+D`) and return to LazySSH without closing the SSH connection, allowing you to manage multiple sessions easily.\n\n### Terminator Terminal\nIf you have Terminator installed, LazySSH can open SSH sessions in new Terminator windows. This is useful if you want to keep multiple terminals open simultaneously.\n\n### Configuration\n\nYou can control which terminal method to use either at runtime or via environment variable:\n\n**Runtime configuration (recommended):**\n```bash\n# From command mode\nlazyssh> terminal native # Set terminal method to native\nlazyssh> terminal auto # Set terminal method to auto\nlazyssh> terminal terminator # Set terminal method to terminator\n```\n\n**Environment variable:**\n```bash\n# Automatically select best available method (default)\n# Tries Terminator first, falls back to native\nexport LAZYSSH_TERMINAL_METHOD=auto\n\n# Force native terminal (runs in current window)\nexport LAZYSSH_TERMINAL_METHOD=native\n\n# Force Terminator (requires Terminator to be installed)\nexport LAZYSSH_TERMINAL_METHOD=terminator\n```\n\n**Default behavior (auto):**\n- If Terminator is installed: Opens terminals in new Terminator windows\n- If Terminator is not installed: Uses native terminal in current window\n- Falls back gracefully if the preferred method fails\n\n**Features:**\n- Native terminal allows returning to LazySSH after exiting the SSH session\n- Terminal method can be changed at runtime without restarting LazySSH\n- Terminal method is displayed in the SSH connections status table\n\n## Saved Connection Configurations\n\nLazySSH allows you to save connection configurations for quick reuse. Configurations are stored securely in TOML format at `/tmp/lazyssh/connections.conf` with owner-only permissions (600).\n\n### Saving Connections\n\nAfter creating a successful connection, LazySSH will prompt you to save it:\n\n```bash\nlazyssh> lazyssh -ip server.example.com -port 22 -user admin -socket myserver\n# After connection succeeds\nSave this connection configuration? (y/N): y\nEnter config name [myserver]: prod-server\n\u2713 Configuration saved as 'prod-server'\n```\n\nOr save manually from command mode:\n\n```bash\nlazyssh> save-config prod-server\n```\n\n### Using Saved Configurations\n\n**View saved configurations:**\n```bash\nlazyssh> config\n# Displays table of all saved configurations\n```\n\n**Connect using a saved configuration:**\n```bash\nlazyssh> connect prod-server\n```\n\n**Delete a saved configuration:**\n```bash\nlazyssh> delete-config prod-server\n```\n\n### Configuration File Format\n\nConfigurations are stored in TOML format at `/tmp/lazyssh/connections.conf`:\n\n```toml\n[prod-server]\nhost = \"server.example.com\"\nport = 22\nusername = \"admin\"\nssh_key = \"/home/user/.ssh/id_rsa\"\n\n[dev-server]\nhost = \"192.168.1.100\"\nport = 2222\nusername = \"developer\"\nproxy_port = 9050\n```\n\n### Security Considerations\n\n- **File Permissions**: Config file is automatically set to mode 600 (owner read/write only)\n- **Location**: Files are stored in `/tmp/lazyssh/` which is cleared on system reboot\n- **SSH Keys**: Only paths to SSH keys are stored, not the keys themselves\n- **Sensitive Data**: Consider using SSH keys instead of password authentication\n- **Manual Editing**: You can safely edit the TOML file directly if needed\n\n### CLI Flag\n\nView configurations at startup:\n\n```bash\nlazyssh --config\n```\n\nOr specify a custom config file path:\n\n```bash\nlazyssh --config /path/to/custom/connections.conf\n```\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive SSH toolkit for managing connections and tunnels",
"version": "1.5.0",
"project_urls": {
"Bug Tracker": "https://github.com/Bochner/lazyssh/issues",
"Documentation": "https://github.com/Bochner/lazyssh",
"Homepage": "https://github.com/Bochner/lazyssh",
"Source Code": "https://github.com/Bochner/lazyssh"
},
"split_keywords": [
"ssh",
" tunnel",
" proxy",
" socks",
" terminal",
" connection",
" management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "559c411b5d1cb3aa2277bed11bffe1d7d7fceb44669aa5c2e951e2b4bf54c442",
"md5": "9e6b99e662dc6d2717031008f792d7fe",
"sha256": "d31448989b4216ee972728616e7daa12723fce6c96c07aa074f7e4d456fd858a"
},
"downloads": -1,
"filename": "lazyssh-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e6b99e662dc6d2717031008f792d7fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 75809,
"upload_time": "2025-10-13T15:22:33",
"upload_time_iso_8601": "2025-10-13T15:22:33.288713Z",
"url": "https://files.pythonhosted.org/packages/55/9c/411b5d1cb3aa2277bed11bffe1d7d7fceb44669aa5c2e951e2b4bf54c442/lazyssh-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "abeb8ec5ad5f567ec0ae6c14a8fa9e26e15fba6ef821371837e21dc29bda60fa",
"md5": "91277a716084272ce421d6322dc51565",
"sha256": "0fc23e941fe5fd36349580bd0e3b06753df1a419df2e61b09a2401d11728313c"
},
"downloads": -1,
"filename": "lazyssh-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "91277a716084272ce421d6322dc51565",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 83838,
"upload_time": "2025-10-13T15:22:34",
"upload_time_iso_8601": "2025-10-13T15:22:34.949632Z",
"url": "https://files.pythonhosted.org/packages/ab/eb/8ec5ad5f567ec0ae6c14a8fa9e26e15fba6ef821371837e21dc29bda60fa/lazyssh-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-13 15:22:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Bochner",
"github_project": "lazyssh",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "colorama",
"specs": [
[
">=",
"0.4.6"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "pexpect",
"specs": [
[
">=",
"4.8.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "prompt_toolkit",
"specs": [
[
">=",
"3.0.39"
],
[
"<",
"3.1.0"
]
]
},
{
"name": "wcwidth",
"specs": [
[
">=",
"0.2.5"
]
]
},
{
"name": "art",
"specs": [
[
">=",
"5.9"
]
]
},
{
"name": "paramiko",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "tomli-w",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "lazyssh"
}
JSON
