ssm-cli 1.1.0

CLI tool to help with SSM functionality, aimed at adminstrators

SSM CLI

A tool to make common tasks with SSM easier. The goal of this project is to help with the Session Manager, the tool tries to keep the access it requires to a minimum.

Installation & Setup

It can be installed with pip install ssm-cli, however most features rely on the session-manager-plugin being installed as well, this is the standard way to make SSM connections. So a quick few steps here should be followed to avoid any issues.

Step 1. Install Session Manager Plugin

You should be able to install it following the AWS documentation. Please see AWS documentation, to install it. Install the Session Manager plugin for the AWS CLI.

Step 2 (Optional). Install tkinter

ssm-cli makes use of tkinter for the UI selector, on windows this usualy comes pre built with the python binary. On WSL/Linux/MacOS you may need to install it using the package manager for your distro, (for example with ubuntu sudo apt install python3-tk), further UI issues may occur with WSL, please see WSLg documentation on this gui-apps

Step 3. Install ssm-cli

You can install this tool to a venv and it will work perfectly fine as well. However I recommend using the global or user space to install it as it makes the ssm command available in default path.

pip install ssm-cli

Step 4. run setup

[!IMPORTANT] Do not skip this step!

The tool installs without any default config and will cause errors when it cannot find the config. To configure the tool you must run the setup action. It will prompt asking for your grouping tag, more infomation on this below.

ssm setup
# or
python -m ssm_cli setup

AWS permissions

The tool uses boto3, so any standard AWS_ environment variables can be used. Also the --profile option can be used similarly to aws cli.

You will need access to a few aws actions, below is a policy which should cover all features used by the tool. However I recommend using conditions in some way to control fine grained access.

{
    "Version": "2012-10-17",
    "Statement": [
        {
        "Sid": "FirstStatement",
        "Effect": "Allow",
        "Action": [
            "resourcegroupstaggingapi:GetResources",
            "ssm:DescribeInstanceInformation",
            "ssm:StartSession"
        ],
        "Resource": "*"
        }
    ]
}

Config

This tool uses XDG standards on where to store its configuration. Typically this is ~/.config/ssm-cli/ but when running setup it will output the location.

Windows note: the config does not go in AppData like most Windows apps, it lives at ~\.config\ssm-cli\ssm.yaml.

The following files are created by ssm setup:

• ~/.config/ssm-cli/ssm.yaml, main config (group tag, AWS profile)
• ~/.config/ssm-cli/hostkey.pem, SSH host key used by the proxy feature

If something goes wrong, check the log file at ~/.local/state/ssm-cli/.

Grouping tag

The selecting of instances revolves around a tag on the instance, the tag key can be configured using group_tag_key. The easiest way to test this is setup properly is to use the list command:

# first list all groups
ssm list
# then list instances in those groups
ssm list my-group

Shell sessions

To connect to an instance:

ssm shell my-group

To exit the session, type exit in the remote shell. Ctrl+C is intentionally passed through to the remote instance rather than closing the session, so it won't disconnect you.

SSH Proxy

The SSH proxy feature lets you use ssm-cli as a transparent tunnel for any tool that supports SSH — including DataGrip, DBeaver, MySQL Workbench, and the regular ssh command. You don't need a traditional bastion host or open inbound ports; traffic routes entirely through AWS SSM.

It works by acting as a local SSH server. When a tool connects through it, ssm-cli opens an SSM port-forwarding session to the target host and bridges the connection.

SSH Config Setup

Add an entry to your SSH config (~/.ssh/config):

Host bastion
    ProxyCommand ssm sshproxy bastion_group

This tells SSH that whenever you connect to bastion, it should launch ssm sshproxy as the connection method. You can optionally pass --profile if you use a named AWS profile:

Host bastion
    ProxyCommand ssm sshproxy bastion_group --profile your-profile

Using with DataGrip / DBeaver

Tools like DataGrip support SSH tunnels for database connections. Once the SSH config entry above is in place:

1. In DataGrip, open your data source and go to the SSH/SSL tab
2. Check Use SSH tunnel
3. Set Host to bastion, Port to 22, Username to firstname.lastname
4. Set Authentication type to OpenSSH config and authentication agent
5. DataGrip will pick up the ProxyCommand from your SSH config automatically

The database host field should still point to the internal hostname (e.g. mydb.service.internal), not 127.0.0.1 — DataGrip handles the port forwarding through the tunnel itself.

Using with the ssh command

# forward local port 3306 to an internal database, -N keeps it open without a shell
ssh bastion -L 3306:mydb.service.internal:3306 -N

# then connect to it locally
mysql -h 127.0.0.1 -P 3306