ssmx — a smarter AWS SSM CLI

Why: three commands become one

Tunnelling to a private RDS database with the plain AWS CLI means looking up the endpoint, looking up the bastion’s instance ID, and then pasting both into a JSON parameter blob:

aws rds describe-db-instances --db-instance-identifier prod-db \
  --query 'DBInstances[0].Endpoint'                  # 1. find host + port
aws ec2 describe-instances --filters Name=tag:Name,Values=bastion-1 \
  --query 'Reservations[].Instances[].InstanceId'    # 2. find instance ID
aws ssm start-session --target i-0abc1234def5678ab \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"host":["prod-db.abc123.eu-west-1.rds.amazonaws.com"],
    "portNumber":["5432"],"localPortNumber":["5432"]}'  # 3. open tunnel

ssmx forward bastion-1 --to prod-db
# prod-db (rds:postgres) -> prod-db.abc123.eu-west-1.rds.amazonaws.com:5432
# forwarding localhost:5432 via bastion-1 (i-0abc1234def5678ab) - Ctrl+C to stop

How it works

ssmx is a single Python file on top of boto3. It does the lookups itself, then hands the finished session to the aws CLI and the Session Manager plugin — the same path you would take by hand, with the same profile and region.

Because the connection runs through Systems Manager, the bastion needs no inbound security-group rules and nobody needs SSH keys. What the bastion does need is a network path to the database: its security group must be allowed into the database’s security group on the database port.

Install

Prerequisites

• Python 3.9+
• AWS CLI v2
• Session Manager plugin — needed for connect and forward
• Target instances must be SSM-managed: SSM Agent running, and an instance profile with AmazonSSMManagedInstanceCore

Recommended: pipx

An isolated install that puts ssmx on your PATH.

pipx install git+https://github.com/originalpages/ssmx.git

Or pip

pip install git+https://github.com/originalpages/ssmx.git

Or just the script

It is a single file with one dependency.

pip install boto3
curl -L https://raw.githubusercontent.com/originalpages/ssmx/main/ssmx.py -o ~/.local/bin/ssmx
chmod +x ~/.local/bin/ssmx

Check it works

ssmx --version
ssmx list

Usage, command by command

Find instances

ssmx list                  # all running, SSM-managed instances
ssmx ls -f api             # filter by Name tag or ID substring
ssmx list -o json | jq     # machine-readable

$ ssmx list
NAME         INSTANCE ID           TYPE          PRIVATE IP       PING
api-1        i-0abc1234def5678ab   t3.medium     10.0.1.12        Online
bastion-1    i-0fed9876cba54321f   t3.micro      10.0.0.5         Online

Open a shell

ssmx connect api-1                      # by Name tag
ssmx c i-0abc1234def5678ab              # or by instance ID

Run a one-off command

ssmx run api-1 -- systemctl status nginx
ssmx run api-1 -- tail -n 100 /var/log/app.log
ssmx run api-1 --timeout 600 -- ./long-job.sh

stdout and stderr come back to your terminal, and the remote exit code becomes ssmx’s exit code — so it works in scripts and && chains.

Port forward — the smart part

--to takes a name and works out what it is. It tries these in order and uses the first match:

1. host:portUsed as-is — anything TCP: OpenSearch, Kafka, an internal ALB…
2. RDS instanceInstance endpoint and port
3. Aurora / RDS clusterWriter endpoint
4. ElastiCache replication groupPrimary endpoint, or configuration endpoint in cluster mode
5. ElastiCache cache clusterRedis, Valkey or Memcached node endpoint

ssmx forward bastion-1 --to prod-db                 # RDS: finds host + port
ssmx fwd bastion-1 --to orders-aurora               # Aurora cluster
ssmx fwd bastion-1 --to sessions-redis              # ElastiCache
ssmx fwd bastion-1 --to prod-db --local 15432       # pick your own local port
ssmx fwd bastion-1 --to search.internal:9200        # explicit host:port

The local port defaults to the remote port. Then, in another terminal:

$ psql -h localhost -p 5432 -U admin mydb
$ redis-cli -p 6379

Check what a name resolves to

Useful before connecting, or in scripts.

ssmx resolve prod-db
ssmx resolve api-1 --ec2
ssmx resolve prod-db -o json

$ ssmx resolve prod-db
prod-db (rds:postgres) -> prod-db.abc123.eu-west-1.rds.amazonaws.com:5432
$ ssmx resolve api-1 --ec2
api-1 -> i-0abc1234def5678ab

Parameter Store

ssmx param get /myapp/prod/DB_PASSWORD                   # decrypts SecureString
export DB_PASS=$(ssmx param get /myapp/prod/DB_PASSWORD)

ssmx param list /myapp/prod/

ssmx param put /myapp/prod/API_URL https://api.example.com --type String
ssmx param put /myapp/prod/DB_PASSWORD - --overwrite < secret.txt   # '-' = read stdin
ssmx param delete /myapp/prod/OLD_KEY                    # asks for confirmation; -y to skip

param put defaults to SecureString. Prefer the - (stdin) form for secrets so the value does not end up in your shell history.

Profiles, regions and SSO

ssmx uses the standard AWS credential chain via boto3, and passes the same profile and region to the aws CLI when it opens a session. Global options (--profile, --region, --no-cache, --cache-ttl) go before the command.

ssmx --profile prod connect api-1
ssmx --region us-east-1 list
AWS_PROFILE=staging ssmx fwd bastion-1 --to staging-db

# IAM Identity Center / SSO
aws sso login --profile prod
ssmx --profile prod list

The lookup cache

Resolving names costs one or more AWS API calls, so ssmx caches successful lookups and repeat commands start instantly.

• What is cached: Name tag → instance ID, and resource name → host/port. Never credentials, parameter values or command output.
• Where: ~/.cache/ssmx/cache.json (respects XDG_CACHE_HOME), file mode 600.
• Scope: per profile + region, so prod and dev never mix.
• Lifetime: 5 minutes by default. ssmx list also warms the cache.

ssmx --no-cache connect api-1          # bypass once
ssmx --cache-ttl 3600 fwd b-1 --to db    # longer TTL for this call
export SSMX_CACHE_TTL=0                # disable entirely
ssmx cache clear                       # wipe it
ssmx cache path                        # show location

If an instance was replaced and a cached ID is stale, the session fails fast; run ssmx cache clear (or wait for the TTL) and retry.

IAM permissions

Same APIs, same permissions as the AWS CLI. Minimum actions for the caller, per command:

forward also needs ssm:StartSession on the document AWS-StartPortForwardingSessionToRemoteHost. A starting-point policy covering every command — tighten the Resource entries for production:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Discovery",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ssm:DescribeInstanceInformation",
        "rds:DescribeDBInstances",
        "rds:DescribeDBClusters",
        "elasticache:DescribeReplicationGroups",
        "elasticache:DescribeCacheClusters"
      ],
      "Resource": "*"
    },
    {
      "Sid": "Sessions",
      "Effect": "Allow",
      "Action": "ssm:StartSession",
      "Resource": [
        "arn:aws:ec2:*:*:instance/*",
        "arn:aws:ssm:*::document/AWS-StartPortForwardingSessionToRemoteHost",
        "arn:aws:ssm:*:*:document/SSM-SessionManagerRunShell"
      ]
    },
    {
      "Sid": "EndOwnSessions",
      "Effect": "Allow",
      "Action": ["ssm:TerminateSession", "ssm:ResumeSession"],
      "Resource": "arn:aws:ssm:*:*:session/${aws:userid}-*"
    },
    {
      "Sid": "RunCommand",
      "Effect": "Allow",
      "Action": "ssm:SendCommand",
      "Resource": [
        "arn:aws:ec2:*:*:instance/*",
        "arn:aws:ssm:*::document/AWS-RunShellScript"
      ]
    },
    {
      "Sid": "RunCommandOutput",
      "Effect": "Allow",
      "Action": "ssm:GetCommandInvocation",
      "Resource": "*"
    },
    {
      "Sid": "ParameterStore",
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter",
        "ssm:PutParameter",
        "ssm:DeleteParameter",
        "ssm:DescribeParameters"
      ],
      "Resource": "*"
    }
  ]
}

Tag conditions and path-scoped Parameter Store examples are in docs/iam.md.

Troubleshooting

Source, issues and pull requests: github.com/originalpages/ssmx.