SSH Tunnel Manager (STM)

Version: 2.0.0

STM is a command-line interface (CLI) tool designed to simplify the management of multiple SSH tunnels, especially those requiring Two-Factor Authentication (2FA) with TOTP (Time-based One-Time Password). It securely stores your bastion passwords and TOTP secrets, automating the login process.

Features

• Multiple Tunnel Configurations: Easily define and manage several SSH tunnel setups.
• Secure Credential Storage: Bastion passwords and TOTP secrets are encrypted at rest (AES-256-GCM).
• TOTP Automation: Automatically generates and inputs TOTP codes during the SSH connection process.
• Interactive & Non-Interactive Modes: Add tunnels through an interactive prompt or directly via command-line arguments.
• Tunnel Control: Start, stop, and list your configured tunnels.
• Status Overview: Quickly see which tunnels are active and their PIDs.
• Graceful Shutdown: Automatically attempts to stop all active tunnels when the CLI is exited (e.g., via Ctrl+C).
• expect Integration: Uses expect scripts for robust automation of SSH login sequences.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: Version 18.x or later is recommended. (You can download it from nodejs.org)
• npm: Comes bundled with Node.js.
• expect: This tool is used to automate interactions with the SSH process.
  • On Debian/Ubuntu: sudo apt-get update && sudo apt-get install expect
  • On macOS (via Homebrew): brew install expect
  • On other systems, please consult your package manager.

Installation

1. Clone the repository (optional, for development or direct use):

   git clone https://github.com/mrtl-srn/stm.git
   cd stm

2. Install dependencies:

   npm install

3. Build the project (compile TypeScript to JavaScript):

   npm run build

4. Link the CLI tool to make it globally available: This step allows you to run the stm command from anywhere in your terminal.

   npm link

   (If you later wish to publish this package to npm, users could install it via npm install -g stm)

Configuration Files

STM uses two main files, which are automatically created in the root directory of your project (or where you run the stm command if installed globally and linked):

• tunnels.json: This file stores all your tunnel configurations. Sensitive information like bastion passwords and TOTP secrets are encrypted within this file.
• .tunnel_key: This file contains the encryption key used to secure the data in tunnels.json. Treat this file as highly sensitive. It's recommended to add .tunnel_key to your .gitignore file if you are managing this project with Git, to prevent accidental commits of the key.

Usage

The main command is stm. You can get help by running stm --help.

stm <command> [options]

Available Commands:

1. List Tunnels

Displays all configured tunnels along with their status (active/inactive) and PID if active.

stm list

2. Add a New Tunnel

• Interactive Mode: This mode will prompt you for all the necessary tunnel details.

  stm add --interactive

  Or simply:

  stm add

  (If not all required arguments are provided, it defaults to interactive mode).

• Non-Interactive Mode: Provide all tunnel details as command-line options.

  stm add --name "my-server-tunnel" \
          --bastion_user "myuser" \
          --bastion_password "mypassword123" \
          --bastion_host "bastion.example.com" \
          --bastion_port "22" \
          --totp_secret "YOURBASE32TOTPSECRET" \
          --remote_host "internal.db.server" \
          --remote_port "5432" \
          --local_port "15432"

  Required fields for non-interactive mode: name, bastion_user, bastion_host, bastion_port, remote_host, remote_port, local_port. bastion_password and totp_secret are optional if not needed for your connection.

3. Start a Tunnel

• By Name:

  stm start --name "my-server-tunnel"

• Interactive Selection: If no name is provided, you'll be prompted to select from a list of inactive tunnels.

  stm start

4. Stop a Tunnel

• By Name:

  stm stop --name "my-server-tunnel"

• Interactive Selection: If no name is provided, you'll be prompted to select from a list of active tunnels.

  stm stop

(Planned/Future Commands)

The following commands are planned for future versions (currently commented out in the codebase):

• stm update [options]: Update an existing tunnel configuration.
• stm remove [options]: Remove a tunnel configuration.
• stm restart [options]: Restart a tunnel.

Security

• Encryption: Bastion passwords and TOTP secrets stored in tunnels.json are encrypted using AES-256-GCM.
• Encryption Key: The encryption key is stored in the .tunnel_key file in the project's root directory.
  • IMPORTANT: Protect the .tunnel_key file. Anyone with access to this file can decrypt your stored credentials.
  • It is strongly recommended to add .tunnel_key to your project's .gitignore file to prevent it from being committed to version control.
• File Permissions: The tunnels.json configuration file and the .tunnel_key file are saved with restricted permissions (0o600) to limit access.

Development

If you want to contribute or modify the SSH Tunnel Manager:

1. Clone the repository:

   git clone <your-repository-url>
   cd ssh-tunnel-manager

2. Install dependencies:

   npm install

3. Build the project: TypeScript files in src/ are compiled to JavaScript in dist/.

   npm run build

   You can also run tsc -w in a separate terminal to watch for changes and rebuild automatically.

4. Link for local development: This allows you to use the stm command globally, pointing to your local development version.

   npm link

5. Making Changes:

   • Modify the TypeScript source files in the src directory.
   • Rebuild the project using npm run build after making changes.
   • Test your changes using the stm command.

License

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

---

For issues, feature requests, or contributions, please visit the project's repository.