Skip to content

Commit 0eb4ce5

Browse files
qoomonqoomon
committed
refactor
1 parent 4f4f5ca commit 0eb4ce5

15 files changed

+299
-498
lines changed

‎README.md‎

Lines changed: 84 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,93 @@
1-
# aws-ssm-ec2-proxy-command [![Sparkline](https://stars.medv.io/qoomon/aws-ssm-ec2-proxy-command.svg)](https://stars.medv.io/qoomon/aws-ssm-ec2-proxy-command)
1+
# aws-ssm-ssh-proxy-command [![Sparkline](https://stars.medv.io/qoomon/aws-ssm-ssh-proxy-command.svg)](https://stars.medv.io/qoomon/aws-ssm-ssh-proxy-command)
22

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

5-
> [!Important]
6-
> Prefer [ec2-instance-connect implementation](#recommended-usage-of-ec2-instance-connectsendsshpublickey) if possible
5+
> [!Tip]
6+
> If you only need to connect to EC2 instances you could use the `ec2-instance-connect` variant of this proxy command.
7+
> This variant allows you to manage wich IAM identity can connect to which OS user on the target instance.
8+
> See [EC2 Only Variant](#ec2-only-variant)
79
8-
> [!Note]
9-
> Windows users please refere to [README.windows.md](README.windows.md)
10+
## Prerequisits
11+
- Local Setup
12+
- Install AWS CLI
13+
- [AWS Docs](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions)
14+
- **MacOS** `brew install awscli`
15+
- Install AWS CLI Session Manager Plugin
16+
- [AWS Docs](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
17+
- **MacOS** `brew install session-manager-plugin`
18+
- Install the SSM SSH Proxy Command Script
19+
- **Linux & MacOS**
20+
- Copy [aws-ssm-ssh-proxy-command.sh](aws-ssm-ssh-proxy-command.sh) into `~/.ssh/aws-ssm-ssh-proxy-command.sh`
21+
- Ensure it is executable (`chmod +x ~/.ssh/aws-ssm-ssh-proxy-command.sh`)
22+
- **Windows**
23+
- Copy [aws-ssm-ssh-proxy-command.ps1](aws-ssm-ssh-proxy-command.ps1) into `~/.ssh/aws-ssm-ssh-proxy-command.ps1`
24+
- Ensure you are allowed to execute powershell scripts (see [Set-ExecutionPolicy](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy) command)
25+
- `optional` Setup SSH Config
26+
- Add ssh config entry AWS instances to your `~/.ssh/config`.
27+
- **Linux & MacOS**
28+
```ssh-config
29+
host i-* mi-*
30+
IdentityFile ~/.ssh/id_ed25519
31+
ProxyCommand ~/.ssh/aws-ssm-ssh-proxy-command.sh %h %r %p ~/.ssh/id_ed25519.pub
32+
StrictHostKeyChecking no
33+
```
34+
- **Windows**
35+
```ssh-config
36+
host i-* mi-*
37+
IdentityFile ~/.ssh/id_ed25519
38+
ProxyCommand powershell.exe ~/.ssh/aws-ssm-ssh-proxy-command.ps1 %h %r %p ~/.ssh/id_ed25519.pub
39+
StrictHostKeyChecking no
40+
```
41+
- Adjust `IdentityFile` and corresponding publickey (last argument of `ProxyCommand`) if needed.
42+
43+
- AWS IAM Setup
44+
- Ensure IAM Permissions for Your IAM Identity
45+
- [IAM Policy Template](aws-ssm-ssh-iam-policy.json)
46+
- `ssm:StartSession` for DocumentName: `AWS-StartSSHSession` and Target Instance
47+
- [AWS Documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/getting-started-restrict-access-examples.html)
48+
- `ssm:SendCommand` for DocumentName: `AWS-RunShellScript` and Target Instance
49+
- [AWS Documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-rc-setting-up.html)
1050
11-
#### Prerequisits
12-
* Local Setup
13-
* [Install AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)
14-
* MacOS `brew install awscli`
15-
* [Install AWS CLI Session Manager Plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
16-
* MacOS `brew install session-manager-plugin`
17-
* Ensure Your IAM Permissions
18-
* [IAM Policy Example](aws-ssm-ec2-iam-policy.json)
19-
* `ssm:StartSession` for DocumentName: `AWS-StartSSHSession` and Target Instance
20-
* [AWS Documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/getting-started-restrict-access-examples.html)
21-
* `ssm:SendCommand` for DocumentName: `AWS-RunShellScript` and Target Instance
22-
* [AWS Documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-rc-setting-up.html)
23-
* Target Instance Setup
24-
* [Ensure SSM Permissions](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html) fo Target Instance Profile
25-
* Ensure SSM Agent is installed (preinstalled on all AWS Linux AMIs already)
26-
* [Install SSM Agent on Linux Instances](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-ssm-agent.html)
27-
* `yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm & service amazon-ssm-agent restart`
28-
* [SSM Agent on Windows Instances](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-ssm-win.html)
51+
- Target Instance Setup
52+
- Ensure IAM Permissions for SSM Agent Credentials
53+
- [AWS Docs](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-setting-up.html)
54+
- For EC2 Inatances use [Instance Profiles](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html)
55+
- Install SSM Agent on Linux Instances
56+
- Already preinstalled on all AWS Linux AMIs
57+
- [AWS Docs - Linux](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-managed-linux.html)
58+
- [AWS Docs - Windows](https://docs.aws.amazon.com/systems-manager/latest/userguide/hybrid-multicloud-ssm-agent-install-windows.html)
59+
60+
## Usage
61+
- Ensure AWS CLI environemnt variables are set properly
62+
- **Linux & MacOS** `export AWS_PROFILE=...` or `AWS_PROFILE=... ssh...`
63+
- **Windows** `$env:AWS_PROFILE = ...` or `$env:AWS_PROFILE = ...; ssh.exe...`
64+
- Open SSH Connection to AWS SSM connected instance
65+
- **Linux & MacOS** `ssh <INSTACEC_USER>@<INSTANCE_ID>` e.g. `ssh ec2-user@i-1234567890`
66+
- **Windows** `ssh.exe <INSTACEC_USER>@<INSTANCE_ID>` e.g. `ssh.exe ec2-user@i-1234567890`
67+
- ⚠️ 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.
68+
- [EC2 Intances Only] If default region does not match instance region you need to provide it as part of hostname
69+
- `<INSTACEC_USER>@<INSTANCE_ID>--<INSTANCE_REGION>`
70+
- e.g. `ec2-user@i-1234567890--eu-central-1`
2971
30-
#### Install SSH Proxy Command
31-
* Move proxy command script [aws-ssm-ec2-proxy-command.sh](aws-ssm-ec2-proxy-command.sh) to `~/.ssh/aws-ssm-ec2-proxy-command.sh`
32-
* Ensure it is executable (`chmod +x ~/.ssh/aws-ssm-ec2-proxy-command.sh`)
72+
#### Usage without SSH Config
73+
If you have not setup an SSH Config you can use the following ssh command options to use this proxy command.
74+
- **Linux & MacOS** `ssh -i "~/.ssh/id_ed25519" -o ProxyCommand="~/.ssh/aws-ssm-ssh-proxy-command.sh %h %r %p ~/.ssh/id_ed25519.pub" ...`
75+
- **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" ...`
3376
34-
###### Setup SSH Config [optional]
35-
* Add ssh config entry for aws ec2 instances to your `~/.ssh/config`. Adjust key file path if needed.
36-
```ssh-config
37-
host i-* mi-*
38-
IdentityFile ~/.ssh/id_rsa
39-
ProxyCommand ~/.ssh/aws-ssm-ec2-proxy-command.sh %h %r %p ~/.ssh/id_rsa.pub
40-
StrictHostKeyChecking no
41-
```
77+
## EC2 Only Variant
78+
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.
4279
43-
#### Open SSH Connection
44-
* Ensure AWS CLI environemnt variables are set properly e.g.
45-
* `export AWS_PROFILE=default` or `AWS_PROFILE=default ssh ... <INSTACEC_USER>@<INSTANCE_ID>`
46-
* If default region does not match instance region you need to provide it
47-
* e.g. `<INSTACEC_USER>@<INSTANCE_ID>--<INSTANCE_REGION>`
48-
###### SSH Command with SSH Config Setup
49-
`ssh <INSTACEC_USER>@<INSTANCE_ID>`
50-
* e.g. `ssh ec2-user@i-1234567890`
51-
###### SSH Command with ProxyCommand CLI Option
52-
```sh
53-
ssh <INSTACEC_USER>@<INSTANCE_ID> \
54-
-i "~/.ssh/id_rsa" \
55-
-o ProxyCommand="~/.ssh/aws-ssm-ec2-proxy-command.sh %h %r %p ~/.ssh/id_rsa.pub"
56-
```
80+
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`.
81+
Instead you grant `ec2-instance-connect:SendSSHPublicKey` permission and optionaly restrict it to a specific OS user e.g. `ec2-user`.
5782
58-
## Recommended Usage of `ec2-instance-connect:SendSSHPublicKey`
59-
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.
60-
Instead you only grant `ec2-instance-connect:SendSSHPublicKey` permission to a specific instance user e.g. `ec2-user`.
61-
* Ensure [Prerequisits](#prerequisits)
62-
* Follow [Install Guide](#install-ssh-proxy-command)
63-
* Use this [aws-ssm-ec2-proxy-command.sh](ec2-instance-connect/aws-ssm-ec2-proxy-command.sh) proxy command script instead
64-
* Use this [IAM Policy Example](ec2-instance-connect/aws-ssm-ec2-iam-policy.json) instead
65-
* `ssm:StartSession` for DocumentName: `AWS-StartSSHSession` and Target Instance
66-
* [AWS Documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/getting-started-restrict-access-examples.html)
67-
* `ec2-instance-connect:SendSSHPublicKey`
68-
* [AWS Documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-rc-setting-up.html)
69-
* You may need to adjust `ec2:osuser` to match your needs. Default is `ec2-user`
83+
To do so just use **Proxy Command Script** and **IAM Policy Template** from the [ec2-instance-connect folder](ec2-instance-connect) instead.
84+
- Proxy Command Script
85+
- **Linux & MacOS** [aws-ssm-ssh-proxy-command.sh](ec2-instance-connect/aws-ssm-ssh-proxy-command.sh)
86+
- **Windows** [aws-ssm-ssh-proxy-command.ps1](ec2-instance-connect/aws-ssm-ssh-proxy-command.ps1)
87+
- [IAM Policy Template](ec2-instance-connect/aws-ssm-ssh-iam-policy.json)
88+
- `ssm:StartSession` for DocumentName: `AWS-StartSSHSession` and Target Instance
89+
- [AWS Documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/getting-started-restrict-access-examples.html)
90+
- `ec2-instance-connect:SendSSHPublicKey`
91+
- [AWS Documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-rc-setting-up.html)
92+
- You may need to adjust `ec2:osuser` to match your needs. Default is `ec2-user`
7093

‎README.windows.md‎

Lines changed: 0 additions & 80 deletions
This file was deleted.

‎aws-ssm-ec2-proxy-command-start-instance.sh‎

Lines changed: 0 additions & 76 deletions
This file was deleted.

0 commit comments

Comments
 (0)