Open an SSH connection to your ec2 instances via AWS SSM without the need to open any ssh port in you security groups.

In order to use this project on Windows refer to README.windows.md

• Local Setup
  • Install AWS CLI
    • MacOS brew install awscli
  • Install AWS CLI Session Manager Plugin
    • MacOS brew install session-manager-plugin
• Ensure Your IAM Permissions
  • IAM Policy Example
  • ssm:StartSession for DocumentName: AWS-StartSSHSession and Target Instance
    • AWS Documentation
  • ssm:SendCommand for DocumentName: AWS-RunShellScript and Target Instance
    • AWS Documentation
• Target Instance Setup
  • Ensure SSM Permissions fo Target Instance Profile
  • Ensure SSM Agent is installed (preinstalled on all AWS Linux AMIs already)
    • Install SSM Agent on Linux Instances
      • yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm & service amazon-ssm-agent restart
    • SSM Agent on Windows Instances

• Move proxy command script aws-ssm-ec2-proxy-command.sh to ~/.ssh/aws-ssm-ec2-proxy-command.sh
• Ensure it is executable (chmod +x ~/.ssh/aws-ssm-ec2-proxy-command.sh)

• Add ssh config entry for aws ec2 instances to your ~/.ssh/config. Adjust key file path if needed.

  host i-* mi-* IdentityFile ~/.ssh/id_rsa ProxyCommand ~/.ssh/aws-ssm-ec2-proxy-command.sh %h %r %p ~/.ssh/id_rsa.pub StrictHostKeyChecking no

• Ensure AWS CLI environemnt variables are set properly e.g.
  • export AWS_PROFILE=default or AWS_PROFILE=default ssh ... <INSTACEC_USER>@<INSTANCE_ID>
• If default region does not match instance region you need to provide it
  • e.g. <INSTACEC_USER>@<INSTANCE_ID>--<INSTANCE_REGION>

ssh <INSTACEC_USER>@<INSTANCE_ID>

• e.g. ssh ec2-user@i-1234567890

ssh <INSTACEC_USER>@<INSTANCE_ID> \ -i "~/.ssh/id_rsa" \ -o ProxyCommand="~/.ssh/aws-ssm-ec2-proxy-command.sh %h %r %p ~/.ssh/id_rsa.pub"

The advantage from security perspective it that you don't need to grant ssm:SendCommand to users and there by the permission to execute everything as root. Instead you only grant ec2-instance-connect:SendSSHPublicKey permission to a specific instance user e.g. ec2-user.

• Ensure Prerequisits
• Use this aws-ssm-ec2-proxy-command.sh proxy command script instead
• Use this IAM Policy Example instead
  • ssm:StartSession for DocumentName: AWS-StartSSHSession and Target Instance
    • AWS Documentation
  • ec2-instance-connect:SendSSHPublicKey
    • AWS Documentation
    • You may need to adjust ec2:osuser to match your needs. Default osuser is ec2-user
• Follow Install Guide