Quickstart

Prerequisites

• Python 3.5+ (earlier Python 3 versions should work too)
• session-plugin-manager from AWS
• Up to date version of SSM Agent must be installed on EC2 instances we want to connect to
• Proper IAM permissions for instance profile

Installation

via pip

aws-gate is available on PyPI:

pip install aws-gate

via Homebrew

aws-gate package is available for macOS via Homebrew:

brew tap xen0l/homebrew-taps
brew install aws-gate

via Docker

aws-gate is also available as a Docker container via []Github Package Registry](https://github.com/xen0l/aws-gate/packages/):

docker pull docker.pkg.github.com/xen0l/aws-gate/aws-gate:latest

However, before you are able to download the Docker container, you need to generate a personal token and grant it the following scopes:

• repo
• packages:read

After you have a personal token generated, you will have have to log in to a Github Package Docker registry:

docker login docker.pkg.github.com -u $YOUR_GH_USERNAME -p $GH_TOKEN

NOTE: be careful that executing this command in your shell might store your token in your shell history!

Executing aws-gate as Docker container

When executing aws-gate as Docker container, we have to pass some additional arguments, so it can find aws-gate configuration as well AWS credentials/config file (~/.aws):

docker run --rm -it -v $HOME/.aws-gate/config:/root/.aws-gate/config \
                    -v $HOME/.aws-gate/config.d:/root/.aws-gate/config.d \
                    -v $HOME/.aws:/root/.aws \
                    docker.pkg.github.com/xen0l/aws-gate/aws-gate:latest session ssm-test

Docker container comes with session-manager-plugin pre-downloaded, so you don't have to worry about it.

Downloading session-manager-plugin

macOS users can use aws-gate directly to fetch session-manager-plugin. aws-gate will automatically install it (no sudo privileges required). To do so, just run

aws-gate bootstrap

On Linux platforms, you need to follow official AWS documentation:

• RPM
• DEB for Ubuntu server

In the future, session-manager-plugin bootstrap support on Linux is planned.

Updating session-manager-plugin

sesion-manager-plugin can be updated via aws-gate itself:

aws-gate bootstrap -f

EC2 Instance IAM profile configuration

In order to use SSM, EC2 instance has to use IAM profile with the AmazonSSMManagedInstanceCore managed policy attached or custom policy with similar permissions.

Ephemeral SSH key support

When using SSH ProxyCommand support, aws-gate always generates ephemeral SSH key in ~/.aws-gate/key. Then this SSH key is uploaded to the EC2 Instance metadata via SendSSHPublicKey API function (feature of EC2 Instance Connect). This means that on your EC2 instance, you need to have EC2 Instance Connect working (as simple as installing one package). Follow the instructions here.

Minimal IAM permissions for uploading ephemeral SSH keys

When using aws-gate, ensure that you have the following permissions (replace $REGION and $ACCOUNTID with correct values):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2-instance-connect:SendSSHPublicKey"
            ],
            "Resource": [
                "arn:aws:ec2:$REGION:$ACCOUNTID:instance/*"
            ],
            "Condition": {
                "StringEquals": {
                    "ec2:osuser": "ec2-user"
                }
            }
        }
    ]
}

I recommend creating a custom IAM policy and attaching it to your IAM role.