Awesome

aws-ssm-ssh-proxy-command

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

[!Tip] If you only need to connect to AWS EC2 instances you could use the ec2-instance-connect variant of this proxy command. This variant allows you to manage wich IAM identity can connect to which OS user on the target instance. See EC2 Only Variant

Prerequisits

• Local Setup

  • Install AWS CLI
    • AWS Docs
    • MacOS brew install awscli
  • Install AWS CLI Session Manager Plugin
    • AWS Docs
    • MacOS brew install session-manager-plugin
  • Install the SSM SSH Proxy Command Script
    • Linux & MacOS
      • Copy aws-ssm-ssh-proxy-command.sh into ~/.ssh/aws-ssm-ssh-proxy-command.sh
      • Ensure it is executable (chmod +x ~/.ssh/aws-ssm-ssh-proxy-command.sh)
    • Windows
      • Copy aws-ssm-ssh-proxy-command.ps1 into ~/.ssh/aws-ssm-ssh-proxy-command.ps1
      • Ensure you are allowed to execute powershell scripts (see Set-ExecutionPolicy command)
  • recommended Setup SSH Config
    • Add ssh config entry AWS instances to your ~/.ssh/config.
      • Linux & MacOS

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

      • Windows

        host i-* mi-*
          IdentityFile ~/.ssh/id_ed25519
          ProxyCommand powershell.exe ~/.ssh/aws-ssm-ssh-proxy-command.ps1 %h %r %p ~/.ssh/id_ed25519.pub
          StrictHostKeyChecking no
        

    • Adjust IdentityFile and corresponding publickey (last argument of ProxyCommand) if needed.

• AWS IAM Setup

  • Ensure IAM Permissions for Your IAM Identity
    • IAM Policy Template
      • 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 IAM Permissions for SSM Agent
    • AWS Docs
    • For EC2 Instances use Instance Profiles
  • Install SSM Agent on Linux Instances
    • Already preinstalled on all AWS Linux AMIs
    • AWS Docs - Linux
    • AWS Docs - Windows

Usage

• Ensure AWS CLI environemnt variables are set properly
  • Linux & MacOS export AWS_PROFILE=... or AWS_PROFILE=... ssh...
  • Windows $env:AWS_PROFILE = ... or $env:AWS_PROFILE = ...; ssh.exe...
• Open SSH Connection to AWS SSM connected instance
  • Linux & MacOS ssh <INSTACEC_USER>@<INSTANCE_ID> e.g. ssh ec2-user@i-1234567890
  • Windows ssh.exe <INSTACEC_USER>@<INSTANCE_ID> e.g. ssh.exe ec2-user@i-1234567890
    • ⚠️ Unfortunately on Windows is not possible to show output while running ProxyCommand, script output is interpreted as SSH banner which is available with SSH verbose options.
• [EC2 Intances Only] If default region does not match instance region you need to provide it as part of hostname
  • <INSTACEC_USER>@<INSTANCE_ID>--<INSTANCE_REGION>
  • e.g. ec2-user@i-1234567890--eu-central-1

Usage without SSH Config

If you have not setup an SSH Config you can use the following ssh command options to use this proxy command.

• Linux & MacOS ssh -i "~/.ssh/id_ed25519" -o ProxyCommand="~/.ssh/aws-ssm-ssh-proxy-command.sh %h %r %p ~/.ssh/id_ed25519.pub" ...
• Windows ssh.exe -i "~/.ssh/id_ed25519" -o ProxyCommand="powershell.exe ~/.ssh/aws-ssm-ssh-proxy-command.ps1 %h %r %p ~/.ssh/id_ed25519.pub" ...

EC2 Only Variant

If you only want to connect to EC2 instances you can make use of EC2 Instance Connect SendSSHPublicKey command as a drop in replacement for the SSM SendCommand to temporary add your public key to the target instance.

The advantage from this variant is that you don't need to grant ssm:SendCommand to users and there by the permission to execute everything as ssm-user or root. Instead you grant ec2-instance-connect:SendSSHPublicKey permission and optionaly restrict it to a specific OS user e.g. ec2-user.

To do so just use Proxy Command Script and IAM Policy Template from the ec2-instance-connect folder instead.

• Proxy Command Script
  • Linux & MacOS aws-ssm-ssh-proxy-command.sh
  • Windows aws-ssm-ssh-proxy-command.ps1
• IAM Policy Template
  • 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