Metadata-Version: 2.4
Name: cisco-ssm
Version: 1.0.0
Summary: SSM — like SSH, but through AWS Systems Manager. Auto Duo SSO re-login, auto root escalation, port forwarding, tunneling, and multi-host run.
Project-URL: Homepage, https://pypi.org/project/cisco-ssm/
Author-email: Supratim Sircar <ssircar@cisco.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: aws,cisco,duo,ec2,session-manager,ssh,ssm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Requires-Dist: boto3
Description-Content-Type: text/markdown

# 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
