cisco-ssm 1.0.0

SSM — like SSH, but through AWS Systems Manager. Auto Duo SSO re-login, auto root escalation, port forwarding, tunneling, and multi-host run.

cisco-ssm

SSM — like SSH, but through AWS Systems Manager.

Drop-in replacement for SSH when connecting to EC2 instances via AWS SSM. Just type ssm <hostname> and you're in — with auto Duo SSO re-login, automatic root escalation, port forwarding, tunneling, and multi-host command execution.

Install

pip install cisco-ssm

Prerequisites: AWS CLI v2 and the Session Manager plugin must be installed.

Usage

After installing, the ssm command is available globally:

# Interactive shell (auto-escalates to root)
ssm myserver
ssm myserver@use1                     # shell in us-east-1

# Run a command (SSH-style)
ssm myserver -- uname -a
ssm myserver -c "uname -a"

# Port forward (like ssh -L)
ssm myserver -L 8080                  # same local & remote port
ssm myserver -L 8080:3000             # local 8080 → remote 3000

# Tunnel via jump EC2 to private services (RDS, OpenSearch, etc.)
ssm myserver -L 9443:rds.host:443

# Multi-host run
ssm h1 h2 h3 -c "uptime"
ssm -f hosts.txt -c "df -h"

# Disable auto root escalation
ssm myserver --no-sudo

Identifiers

The TARGET can be any of:

• EC2 Name tag (e.g. myserver)
• FQDN (e.g. myserver.example.com)
• Private or public IP (e.g. 172.22.6.230)
• Instance ID (e.g. i-0623d1bb65aecbb84)

Features

• SSH-like simplicity — ssm host and you're connected
• Auto Duo SSO re-login — expired token? The script runs duo-sso for you automatically
• Auto root escalation — sudo su - is sent automatically after the shell prompt appears (disable with --no-sudo)
• Read-only mode detection — automatically uses the read-only SSM document when your Duo role is read-only
• Region shortcuts — ssm host@use1 for us-east-1, @euw1 for eu-west-1, @aps1 for ap-southeast-1
• Port forwarding — SSH-style -L flag for direct and tunnel forwarding
• Multi-host run — run commands across many servers with batched resolution and SSM Online filtering
• Spinner + colors — clean, informative terminal output

Environment Variables

Variable	Description	Default
AWS_REGION	Default AWS region	us-east-1
SSM_MODE	Force mode: readonly, devops, admin	auto-detected
SSM_DUO_CMD	Duo SSO re-login command	duo-sso --session-duration 3600
SSM_TIMEOUT_SECONDS	Run command timeout	3600

License

Apache 2.0