- Notifications
You must be signed in to change notification settings - Fork41
Better AWS SSM Session manager CLI client
License
xen0l/aws-gate
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
AWS SSM Session manager client
I am using AWS a lot and I am tired of dealing with everything that comes with the bastion host (additional instance one has to maintain, distribute SSH keys (shared SSH keys are not an option for me), exposing SSH to the network). A while ago, Amazon released a service to fix this -AWS Systems Manager Session Manager. However, CLI user experience of Session Manager is limited and lacks some features:
- ability to connect to instances by other means (e.g. DNS, IP, tag, instance name, autoscaling group) as aws cli supports only connecting by instance IDs
- configuration file support for storing connection information via Session Manager
aws-gate tries to address these issues.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
- Python 3.5+ (earlier Python 3 versions should work too)
- session-plugin-manager from AWS
- SSM Agent version 2.3.68.0 or later must be installed on EC2 instances we want to connect to
- Proper IAM permissions for instance profile
Via pip
pip install aws-gateor via Homebrew
brew tap xen0l/homebrew-tapsbrew install aws-gate# For installing session-manager-plugin via Homebrew (optional)brew install --cask session-manager-pluginor via Docker
docker login docker.pkg.github.com -u $YOUR_GH_USERNAME -p $GH_TOKENdocker pull docker.pkg.github.com/xen0l/aws-gate/aws-gate:latestYou can store information about to connect to your instance (name, region and profile) andaws-gate will do everything for you. The config file is stored in~/.aws-gate/config and has the following YAML syntax:
hosts: - alias: backend-pre name: backend profile: preproduction region: eu-west-1 - alias: backend-pro name: backend profile: production region: eu-west-1defaults: profile: development region: eu-west-1wherehosts stores connection information anddefaults default configuration settings to use. To connect to instancebackend-pre, execute:
aws-gate session backend-preYou can place additional configuration files in~/.aws-gate/config.d. This is ideal when you are working on different projects or when you need to share configuration inside your team.
aws-gate supports querying for instances with following identifiers:
- instance id
aws-gate session i-0772e4c1dcdd763b6- DNS name
aws-gate session ec2-34-245-174-132.eu-west-1.compute.amazonaws.com- private DNS name
aws-gate session ip-172-31-35-113.eu-west-1.compute.internal- IP address
aws-gate session 34.245.174.13- private IP address
aws-gate session 172.31.35.113- tags
aws-gate session Name:SSM-test- name (uses tag identifier under the hood)
aws-gate session SSM-test- autoscaling group name (uses tag identifier under the hood)
aws-gate session asg:dummy-v001AWS SSM Session Manager supports tunneling SSH sessions over it. Moreover,aws-gate supports generating ephemeral SSHkeys and uploading them via EC2 Instance Connect API. However, to use this functionality,EC2 Instance Connectsetup is needed.
To use this functionality, simply runaws-gate ssh-config, which will generate the required~/.ssh/config snippet for you:
% aws-gate ssh-configHost *.eu-west-1.defaultIdentityFile /Users/xenol/.aws-gate/keyIdentitiesOnly yesUser ec2-userPort 22ProxyCommand sh -c "aws-gate ssh-proxy -p `echo %h | sed -Ee 's/^(.*)\.(.*)\.(.*)$/\\3/g'` -r `echo %h | sed -Ee 's/^(.*)\.(.*)\.(.*)$/\\2/g'` `echo %h | sed -Ee 's/^(.*)\.(.*)\.(.*)$/\\1/g'`"Store the snippet inside~/.ssh/config:
% aws-gate ssh-config >> ~/.ssh/configThen connect viassh:
% ssh ssm-test.eu-west-1.defaultLast login: Fri Oct 4 17:17:02 2019 from localhost __| __|_ ) _| ( / Amazon Linux 2 AMI ___|\___|___|https://aws.amazon.com/amazon-linux-2/1 package(s) needed for security, out of 20 availableRun "sudo yum update" to apply all updates.[ec2-user@ip-172-31-35-173 ~]$SSH session to instancessm-test in eu-west-1 AWS region viadefault AWS profile is opened.
scp works the same way (both ways):
% # local to remote% scp test_file ssm-test.eu-west-1.glovoapp:test_file test_file 100% 0 0.0KB/s 00:00 %% # remote to local% scp ssm-test.eu-west-1.glovoapp:test_file test_filetest_file 100% 0 0.0KB/s 00:00Please, also note that whilescp over SSM works, it can beextremely slow. This is because of the underlying SSM limitations and not caused byaws-gate itself.
aws-gate provides a way to open SSH session on the instance directly. This is achieved by wrapping aroundssh under the hood.Simply runaws-gate ssh <instance_identifier>:
% aws-gate ssh ssm-testLast login: Sat Nov 9 10:23:11 2019 from localhost __| __|_ ) _| ( / Amazon Linux 2 AMI ___|\___|___|https://aws.amazon.com/amazon-linux-2/28 package(s) needed for security, out of 56 availableRun "sudo yum update" to apply all updates.[ec2-user@ip-172-31-35-173 ~]$If you wish to execute a specific command (or plug it into your shell pipelines):
% aws-gate ssh ssm-test uname -aLinux ip-172-31-35-173.eu-west-1.compute.internal 4.14.123-111.109.amzn2.x86_64 #1 SMP Mon Jun 10 19:37:57 UTC 2019 x86_64 x86_64 x86_64 GNU/LinuxLocal ports can be forwarded to another host and port relative to the target instance. This works as if by using ssh's-L option. Instead of executing a command,aws-gate establishes a forwarding session that can be used by other local applications.
For example, you can use this to connect to a private web server by forwarding the instance's local port.
# Terminal 1% aws-gate ssh -L 8888:localhost:80 ssh-test# Terminal 2% curl localhost:8888<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> <title>Test Page for the Nginx HTTP Server on Amazon Linux</title>...Or you can use it to connect to a private RDS instance by forwarding the remote address and remote port.
# Terminal 1% aws-gate ssh -L 3306:privatedb.abcdef123456.eu-west-1.rds.amazonaws.com:3306 ssm-test# Terminal 2% mysql -h 127.0.0.1 -u root -P 3306 -p -e "SELECT User from mysql.user;"Enter password: +------------------+| User |+------------------+| root || mysql.infoschema || mysql.session || mysql.sys || rdsadmin |+------------------+If you run into issues, you can get detailed debug log by settingGATE_DEBUG environment variable:
export GATE_DEBUG=1After setting the environment variable, the debug mode will be automatically enabled:
% aws-gate session test2019-05-26 01:18:23,535 - aws_gate.config - DEBUG - Located config file: /Users/xenol/.aws-gate/config2019-05-26 01:18:23,538 - aws_gate.utils - DEBUG - Obtaining boto3 session object2019-05-26 01:18:23,549 - aws_gate.utils - DEBUG - Obtained configured AWS profiles: default development preproduction production2019-05-26 01:18:23,550 - aws_gate.utils - DEBUG - Obtaining boto3 session object2019-05-26 01:18:23,560 - aws_gate.utils - DEBUG - Obtained configured AWS profiles: default development preproduction production2019-05-26 01:18:23,560 - aws_gate.utils - DEBUG - Obtaining boto3 session object2019-05-26 01:18:23,574 - aws_gate.utils - DEBUG - Obtaining ssm client2019-05-26 01:18:23,608 - aws_gate.utils - DEBUG - Obtaining boto3 session object2019-05-26 01:18:23,636 - aws_gate.utils - DEBUG - Obtaining ec2 boto3 resource2019-05-26 01:18:23,694 - aws_gate.query - DEBUG - Querying EC2 API for instance identifier: SSM-test2019-05-26 01:18:24,029 - aws_gate.query - DEBUG - Found 1 maching instances2019-05-26 01:18:24,030 - aws_gate.query - DEBUG - Matching instance: i-0772e4c1dcdd763b62019-05-26 01:18:24,030 - aws_gate.session - INFO - Opening session on instance i-0772e4c1dcdd763b6 (eu-west-1) via profile default2019-05-26 01:18:24,030 - aws_gate.session - DEBUG - Creating a new session on instance: i-0772e4c1dcdd763b6 (eu-west-1)...Debug mode also enables printing of Python stack traces if there is a crash or some other problem.
This project is licensed under the BSD License - see theLICENSE.md file for details
About
Better AWS SSM Session manager CLI client