# 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

```bash
pip install cisco-ssm
```

**Prerequisites:** AWS CLI v2 and the [Session Manager plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) must be installed.

## Usage

After installing, the `ssm` command is available globally:

```bash
# 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
