ssm-connect 1.5.1
Interactive CLI to connect to AWS EC2 and RDS via SSM or SSH-over-SSM, with credential persistence and multi-session support.
License: Apache-2.0
Requires Python: >=3.8
Keywords: aws, ec2, rds, ssm, ssh, cli, session-manager, devops, cloud, sre, operations, infrastructure, port-forwarding, bastion, systems-manager, amazon-web-services, aws-ssm, remote-access, tunneling

# ssm-connect

Interactive CLI to connect to AWS EC2 instances and RDS databases via:

- **SSM Session Manager** (interactive shell)
- **SSH over SSM** (with your SSH key)
- **RDS Port Forwarding** (via EC2 bastion host)
- **File Transfer (SCP)** (Securely upload/download files)

Multiple sessions in parallel (each opens in a new terminal). Keyword search across Name, Instance ID, and all tag values. Simple, cross-platform, and secure-by-default.

## Features

- **Target Selection**: Choose to connect to EC2 instances or RDS databases
- **EC2 Connections**:
  - SSM Session Manager (interactive shell)
  - SSH over SSM (with private key authentication)
  - **SSH ProxyJump** (Connect to target host *via* bastion)
- **RDS Connections**:
  - Port forwarding to RDS databases via EC2 bastion host
  - Auto-selects available local port
- **Customization**:
  - Support for custom SSM Documents via `-d` / `--document-name` flag
- **File Transfer**:
  - Upload/Download files to/from EC2 instances using SCP
  - Uses existing SSH key configuration
- **Smart Search**: Filter instances by keywords (matches Name, InstanceId, and all tag values)
- **Multi-Session**: Opens each connection in a new terminal window (Linux, macOS, Windows) allowing for multiple simultaneous sessions.
- **AWS Session**: Automatically inherits AWS credentials
- **Security**: Automated scanning via CodeQL, Gitleaks and Pip-Audit on every PR

## Install

Latest release from PyPI: pip install --upgrade ssm-connect

Run the tool: ssm-connect


## Requirements

- **User should already be logged in to AWS**
- **AWS CLI v2**
- **SSM Session Manager plugin** ([installation guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html))
- **OpenSSH client** (`ssh` command) - for SSH over SSM
- **Python 3.8+**
- **Appropriate IAM role**
- **SSH Agent** (optional but recommended): Ensure `ssh-agent` is running to avoid repeated passphrase prompts.

### Terminal Apps

The tool automatically detects and uses available terminal emulators:

- **Windows**: Windows Terminal (`wt`), PowerShell, or `cmd`
- **macOS**: Terminal.app
- **Linux**: `gnome-terminal`, `konsole`, `xterm`, or `x-terminal-emulator`


## Usage

Start the CLI: ssm-connect


### Connection Flow

1. **Choose Target Type**:
   - `[1] EC2` - Connect directly to an EC2 instance
   - `[2] RDS` - Forward port to an RDS database via bastion
   - `[3] File Transfer` - Securely upload/download files
   - `[4] Favorites` - Quick connect to saved aliases

   **Global Option**:
   - `-d "MyDoc"` / `--document-name "MyDoc"`: Override the default SSM document used for the connection.

2. **For EC2 Connections**:
   - Choose connection type:
     - `[1] SSM` - Interactive shell via Session Manager
     - `[2] SSH over SSM` - SSH session with your private key
     - `[3] SSH ProxyJump` - Connect to remote host via this instance
   - Filter and select target EC2 instance
   - For SSH: Provide private key path and username
   - For ProxyJump: Select target from list (auto-resolves IP) or enter manually

3. **For RDS Connections**:
   - **Step 1**: Select EC2 bastion instance (must have SSM access)
   - **Step 2**: Select target RDS database
   - Connect to `localhost:[auto-selected-port]` with your database client

4. **For File Transfer (SCP)**:
   - Select remote instance
   - Choose direction (Upload / Download)
   - Specify local and remote file paths
   - Tool handles the secure copy tunneling

5. **Favorites & Aliases**:
   - **Save**: After any connection, answer `y` to "Save this connection as a favorite?"
   - **Connect**:
     - Select `[4] Favorites` from menu, OR
     - Use CLI: `ssm-connect -f <alias>` (e.g., `ssm-connect -f prod-db`)
     - Override document: `ssm-connect -f prod-db -d "OverridesSavedDoc"`

### Alternate Execution
If you cannot modify your PATH or access the `Scripts` folder, you can run the tool as a Python module:
```bash
python -m ssm_connect
```

## Troubleshooting

### Command not found
Ensure `aws`, `session-manager-plugin`, and `ssh` are installed and on PATH.

### SSO expired
Refresh your AWS SSO session: aws sso login --profile your-profile

### SSH key errors
Ensure the key exists and has proper permissions

### No terminal found (Linux)
Install a terminal emulator

### RDS connection refused
Ensure:
- The bastion EC2 instance has network connectivity to the RDS
- The bastion is running
- You have the appropriate role


## Uninstall
pip uninstall ssm-connect

## Security

### Automated Security Checks

All pull requests and merges undergo automated security analysis to ensure code quality and safety:

- **[CodeQL](https://codeql.github.com/)**: Static code analysis for security vulnerabilities and unsafe coding patterns.
- **Gitleaks**: Scans for hardcoded secrets and credentials to prevent leaks.
- **Pip-Audit**: Scans Python dependencies for known security vulnerabilities.

### Reporting Security Issues

If you discover a security vulnerability, please report it privately via GitHub's Security Advisory feature rather than opening a public issue.


## Contributing

Issues and pull requests are welcome. Please keep changes focused and include brief notes if behavior changes.


## License

Apache License 2.0. See LICENSE for details.