Metadata-Version: 2.4
Name: ssm-cli
Version: 1.1.0
Summary: CLI tool to help with SSM functionality, aimed at adminstrators
Author-email: Simon Fletcher <simon.fletcher@lexisnexisrisk.com>
License: MIT License
        
        Copyright (c) 2025 Simon Fletcher
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/risk-ins/ins-datahub-app-ssm-cli
Project-URL: Issues, https://github.com/risk-ins/ins-datahub-app-ssm-cli/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: boto3
Requires-Dist: paramiko
Requires-Dist: rich
Requires-Dist: readchar
Requires-Dist: confclasses>=0.3.2
Requires-Dist: xdg_base_dirs
Requires-Dist: rich-click
Requires-Dist: psutil
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# 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](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html).

### 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](https://learn.microsoft.com/en-us/windows/wsl/tutorials/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.

```bash
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](#grouping-tag).
```bash
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.
```json
{
    "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:
```bash
# first list all groups
ssm list
# then list instances in those groups
ssm list my-group
```

## Shell sessions

To connect to an instance:
```bash
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

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


