⚡ SSM Supercharged

AWS SSM integration with OpenSSH + EC2 Instance Connect + sshuttle

This repository is linked to the research conducted in this Medium article.

Current version: 1.1.0

Lead Maintainer: Halim Qarroum

📋 Table of content

• Description
• Pre-Requisites
• Installation
• Usage
• See also

🔰 Description

This repository features a simple OpenSSH configuration file and a Bash based proxy command used to integrate OpenSSH with AWS SSM Sessions Manager for a streamlined and secure experience. The aim of this project is to provide a way to achieve one or multiple of the following :

• Keep your EC2 instances within private subnets with no inbound security group rules.
• Stop managing SSH key-pairs, and keep your instances keyless.
• Systematically tunnel SSH connections through SSM when targeting EC2 instances.
• Address EC2 instances using their instance identifiers, friendly names, public DNS names or private DNS names.
• Push just-in-time temporary SSH certificates when connecting to keyless instances using EC2 Instance Connect.
• Integrate sshuttle with SSM to establish lightweight and free VPN-like connections to a remote VPC.

🎒 Pre-Requisites

Below is a list of tools you need to have available on your development machine.

• OpenSSH client tools (ssh, ssh-keygen, etc.).
• A running ssh-agent.
• The AWS CLI configured with valid AWS credentials.
• The Sessions Manager Plugin must be installed.
• sshuttle.

🚀 Installation

The installer has been tested on Debian and MacOS and does not require root priviledges.

This repository provides a way to install and upgrade the required OpenSSH configuration on your machine through an installer that will perform the configuration automatically.

curl -o- https://raw.githubusercontent.com/HQarroum/ssm-supercharged/master/install.sh | bash

The installer will patch your OpenSSH configuration by appending the required configuration in your ~/.ssh/config, or create it if it does not exist. It will also copy the required OpenSSH ProxyCommand required to establish SSM tunnels and provision instances using EC2 Instance Connect.

Manual Installation

If you prefer to manually copy the required configuration files, or if the automated script does not work for you, please read how to manually install the ssm-supercharged configuration.

🚌 Usage

Ensure you have valid AWS credentials on your development machine before continuing. It is recommend you test the following with a small EC2 instance (e.g t2.micro) launched in a private VPC without any SSH key-pair attached for testing.

OpenSSH

First ensure that an SSH connection can be successfullly tunneled to your instance. To do so, simply enter the following command with the identifier of the EC2 instance you would like to connect to.

ssh user@i-example

You can also reference your EC2 instance through other attributes.

# Connecting using private DNS name.
ssh user@ip-172-31-1-2.us-east-1.compute.internal

# Connecting using friendly-name.
ssh user@aws-awesome-instance

Tools running over the SSH protocol such as scp, rsync, ansible should work out of the box.

sshuttle

sshuttle is a Transparent proxy server that is advertised to work as a poor man's VPN. It works by establishing an SSH connection to a remote host and routes the traffic from a local machine targeting a specific IP CIDR to a remote network such as, in our case, an AWS VPC.

To establish a sshuttle connection, you can simply reference your instance like in the previous example, as sshuttle is going to make use of your OpenSSH configuration automatically.

For example, the below example will establish a VPN-like connection between your development machine and your remote VPC - in this example, I use a VPC CIDR of 172.31.0.0/16 for the remote VPC.

sshuttle --dns -r user@i-example 172.31.0.0/16

This will cause sshuttle to tunnel all traffic targeting 172.31.0.0/16 through an SSH-over-SSM tunnel using your EC2 instance as a jump host.

Disabling EC2 Instance Connect

By default, the proxy command script provided by ssm-supercharged assumes no SSH key-pair are associated with an instance and instead generates ephemeral RSA key-pairs for each connection which are pushed to the instance using the EC2 Instance Connect service.

EC2 Instance Connect is currently only available on Ubuntu and Amazon Linux AMIs. If you are using another operating system such as RedHat, you can explicitely provide ssh with a private key you own when connecting to the instance.

ssh -i /path/to/key.pem user@i-example

If you want the ssm-supercharged proxy command script to stop using EC2 Instance Connect for all instances and rely on your provided SSH key-pairs, you can update the ~/.ssh/config file by appending a -e no option to the proxy command.

ProxyCommand ~/.ssh/initiate-ssm-connection.sh -h %h -u %r -p %p -e no

👀 See Also

• How to install the SSM Sessions Manager Plugin.
• The EC2 Instance Connect documentation.
• The sshuttle documentation.