SSM SessionManager Helper

SSM SessionManager Helper is a tool that helps configure SSM Session Manager port-forwarded sessions. The SSM SessionManager Helper simplifies the connection process by allowing you to select the account, region and instance to connect to without having to navigate to the AWS Web console to find the instance id.

The Session Helper leverages the AWS CLI, boto3 and the AWS Session Manager Plugin to create a port-forwarded tunnel through SSM Session Manager to your local machine.

Requirements

1. Python 3.6 or later
2. AWS CLI
3. AWS Session Manager plugin

Installation

1. Call pip install -r requirements.txt

Running The SSM SessionManager Helper

1. Call python configurator.py

2. Select an active profile

   

3. From the configurator dialog, select the desired profile, region and instance by clicking on the appropriate field

   

4. Specify the remote port and local port for the connection

5. Click Connect

6. Confirm the connection details

   

7. The SSM SessionManager Helper will close and call start an ssm session with the provided details

   

   • aws ssm start-session will be called to initialize a session
   • Waiting for connections will appear when the session is created

IAM Role/User Permissions

This script will make the following boto3 calls:

1. ssm start_session
2. ec2 describe_instances

The role that is assumed by the user of this script must be configured to allow the above boto3 calls to execute.

A permissive policy that permits the necessary actions for the above boto3 calls would be as follows (it is very important that when implementing this in your account, do NOT use '*' resources in your policies):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:StartSession"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:DescribeSessions",
                "ssm:GetConnectionStatus",
                "ssm:DescribeInstanceProperties",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeInstances"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:GenerateDataKey"
            ],
            "Resource": "*"
        }
    ]
}

More details on restricting access to SSM by resource and tag values can be found in the SSM Systems Manager documentation.

Further Reading

1. SSM SessionManager Helper: How It Works - a deeper dive into how this script works
2. SSM SessionManager Helper: Future Enhancements - a list of how this script can be enhanced in the future
3. Sample IAM policies for Session Manager - official AWS documentation about restricting user access to SSM resources
4. Port Forwarding Using AWS System Manager Session Manager - a blog post about how port forwarding works with AWS Session Manager
5. Python Prompt Toolkit 3.0 - the toolkit used to implement the UI for the SSM SessionManager Helper