README.md

aws-ssm-ec2-proxy-command

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

ⓘ Prefer ec2-instance-connect implementation if possible

ⓘ Windows users please refere to README.windows.md

Prerequisits

• 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

Install SSH Proxy Command

• 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)

Setup SSH Config [optional]

• 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

Open SSH Connection

• 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 Command with SSH Config Setup

ssh <INSTACEC_USER>@<INSTANCE_ID>

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

SSH Command with ProxyCommand CLI Option

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"

Recommended Usage of ec2-instance-connect:SendSSHPublicKey

The advantage from a security perspective is 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
• Follow Install Guide
  • 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 is ec2-user