| Name | pyssm-client JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Enhanced Python AWS SSM Session Manager client with interactive sessions, exec, and file transfer support |
| upload_time | 2025-09-04 05:00:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | Apache-2.0 |
| keywords |
aws
ec2
session-manager
ssh
ssm
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PySSM Client
Enhanced Python AWS SSM Session Manager client with interactive sessions, exec, and file transfer support. It speaks the same binary protocol as the official Go plugin and provides additional functionality like library imports and extended CLI commands.
Highlights:
- Interactive SSH-like sessions via SSM (`ssh` subcommand)
- Direct connect to an existing SSM data channel (`connect` subcommand)
- Proper ack/seq handling, terminal raw mode, signal forwarding (Ctrl-C/Z/\), and periodic resize updates
- Minimal logging by default; verbose traces with `-v`
## Installation
Install from PyPI:
```bash
pip install pyssm-client
```
Or with uv:
```bash
uv add pyssm-client
```
## Requirements
- Python 3.12+
- AWS credentials discoverable via environment or `~/.aws/credentials`
## Quick Start
```bash
# Interactive SSH-like session
pyssm ssh --target i-0123456789abcdef0
# Execute single command
pyssm exec --target i-0123456789abcdef0 --command "ls -la"
# Copy files
pyssm copy ./local-file.txt i-0123456789abcdef0:/tmp/remote-file.txt
```
## CLI Usage
The CLI provides four subcommands: `connect`, `ssh`, `exec`, and `copy`.
### `ssh`: Start an SSM session to a target
Starts a new SSM session using `boto3` and connects interactively.
```bash
pyssm ssh \
--target i-0123456789abcdef0 \
--region us-west-2 \
--profile myprofile
```
Options:
- `--target` (required): EC2 instance ID (`i-*`) or managed instance ID (`mi-*`)
- `--document-name`: SSM document (defaults to the agent’s standard shell doc)
- `--parameters`: JSON object of document parameters
- `--profile`, `--region`, `--endpoint-url`: AWS settings for `boto3`
Global options (apply to all commands):
- `-v/--verbose`: enable DEBUG logging
- `--log-file PATH`: log to file in addition to stderr
- `--coalesce-input [auto|on|off]` (default `auto`): input batching
- `auto`: enabled for non‑TTY stdin (piped input), disabled for interactive TTYs
- `on`: always enable (tunable with `--coalesce-delay-ms`)
- `off`: always disabled
- `--coalesce-delay-ms FLOAT` (default 10.0): coalescing delay when enabled
Behavior:
- Terminal set to cbreak, `-echo -isig` (no double echo; signals forwarded to remote)
- Periodic terminal size updates (500ms) and on resize (SIGWINCH)
- Ctrl-C (0x03), Ctrl-\ (0x1c), Ctrl-Z (0x1a) forwarded to remote
- `exit` cleanly closes the session and the CLI
### `exec`: Execute a single command
Execute a single command on a target instance and return the results with proper exit codes.
```bash
pyssm exec \
--target i-0123456789abcdef0 \
--command "ls -la /tmp" \
--region us-west-2 \
--profile myprofile
```
Options:
- `--target` (required): EC2 instance ID (`i-*`) or managed instance ID (`mi-*`)
- `--command` (required): Shell command to execute
- `--timeout`: Command timeout in seconds (default: 600)
- `--profile`, `--region`, `--endpoint-url`: AWS settings for `boto3`
This command:
- Executes the command and captures stdout/stderr separately
- Returns the actual exit code of the executed command
- Filters shell noise (prompts, command echoes) from output
- Useful for scripting and automation
### `copy`: File transfer via SSM
Transfer files to/from targets using base64 encoding over SSM sessions.
```bash
# Upload local file to remote
pyssm copy \
./local-file.txt i-0123456789abcdef0:/tmp/remote-file.txt \
--region us-west-2 \
--profile myprofile
# Download remote file to local
pyssm copy \
i-0123456789abcdef0:/tmp/remote-file.txt ./local-file.txt \
--region us-west-2 \
--profile myprofile
```
Options:
- `--verify-checksum` (default: on): Verify file integrity using MD5/SHA256
- `--encoding` (default: base64): Transfer encoding (base64, raw, uuencode)
- `--chunk-size`: Transfer chunk size in bytes (default: 8192)
- `--profile`, `--region`, `--endpoint-url`: AWS settings for `boto3`
Features:
- Automatic checksum verification to ensure file integrity
- Progress reporting during transfer
- Support for binary files via base64 encoding
- Works with any file size (chunked transfer)
### `connect`: Attach to an existing SSM data channel
Connects using session parameters you already have (typical when called by AWS CLI). You can pass a single JSON blob or individual flags.
JSON form (mimics the AWS CLI invocation):
```bash
pyssm connect '{
"SessionId": "dacort-abc123",
"StreamUrl": "wss://ssmmessages.us-west-2.amazonaws.com/v1/data-channel/dacort-abc123?...",
"TokenValue": "...",
"target": "i-0123456789abcdef0",
"sessionType": "Standard_Stream"
}'
```
Flag form:
```bash
pyssm connect \
--session-id dacort-abc123 \
--stream-url wss://... \
--token-value ... \
--target i-0123456789abcdef0 \
--session-type Standard_Stream
```
Notes:
- The CLI validates parameters and will emit friendly errors if missing or invalid.
- Global logging and coalescing options work here too.
## Using as a Library
You can embed the plugin in your own Python program. There are four convenient levels: file transfer, exec API, high-level (CLI coordinator), and low-level (session + data channel).
### File Transfer API: Upload/download files
For programmatic file transfers with progress tracking and verification:
```python
from pyssm_client.file_transfer import FileTransferClient
from pyssm_client.file_transfer.types import FileTransferOptions
client = FileTransferClient()
# Upload file
options = FileTransferOptions(verify_checksum=True)
success = await client.upload_file(
local_path="./local-file.txt",
remote_path="/tmp/remote-file.txt",
target="i-0123456789abcdef0",
options=options,
region="us-west-2",
profile="myprofile"
)
# Download file
success = await client.download_file(
remote_path="/tmp/remote-file.txt",
local_path="./downloaded-file.txt",
target="i-0123456789abcdef0",
options=options,
region="us-west-2",
profile="myprofile"
)
```
### Exec API: Single command execution
For simple command execution with clean stdout/stderr separation:
```python
from pyssm_client.exec import run_command, run_command_sync
# Async version
result = await run_command(
target="i-0123456789abcdef0",
command="ls -la /tmp",
region="us-west-2",
profile="myprofile"
)
print(f"Exit code: {result.exit_code}")
print(f"Stdout: {result.stdout.decode('utf-8')}")
print(f"Stderr: {result.stderr.decode('utf-8')}")
# Sync version
result = run_command_sync(
target="i-0123456789abcdef0",
command="sha256sum /path/to/file"
)
if result.exit_code == 0:
checksum = result.stdout.decode('utf-8').strip().split()[0]
```
### High-level: reuse the CLI coordinator
```
import asyncio
from pyssm_client.cli.types import ConnectArguments
from pyssm_client.cli.main import SessionManagerPlugin
from pyssm_client.utils.logging import setup_logging
setup_logging() # or logging.DEBUG for verbose
args = ConnectArguments(
session_id="dacort-abc123",
stream_url="wss://...",
token_value="...",
target="i-0123456789abcdef0",
session_type="Standard_Stream",
)
plugin = SessionManagerPlugin()
exit_code = asyncio.run(plugin.run_session(args))
```
### Low-level: wire session + data channel yourself
```
import asyncio
from pyssm_client.session.session_handler import SessionHandler
from pyssm_client.communicator.utils import create_websocket_config
from pyssm_client.communicator.data_channel import SessionDataChannel
async def main():
handler = SessionHandler()
# Create session (without executing) from your already-resolved params
session = await handler.validate_input_and_create_session({
"sessionId": "dacort-abc123",
"streamUrl": "wss://...",
"tokenValue": "...",
"target": "i-0123456789abcdef0",
"sessionType": "Standard_Stream",
})
# Create data channel and wire handlers
ws_cfg = create_websocket_config(stream_url="wss://...", token="...")
dc = SessionDataChannel(ws_cfg)
dc.set_input_handler(lambda b: sys.stdout.buffer.write(b) or sys.stdout.flush())
# Optional: closed and coalescing handlers
dc.set_closed_handler(lambda: print("\n[session closed]\n"))
# dc.set_coalescing(True, delay_sec=0.01) # for piped input
session.set_data_channel(dc)
await session.execute() # open websocket + handshake
# then run your own event loop + stdin handling as needed
asyncio.run(main())
```
Tips:
- For custom UIs, provide your own `input_handler` (bytes from the agent) and feed `send_input_data()` with bytes from your UI.
- Use `send_terminal_size(cols, rows)` whenever your layout changes.
- On shutdown, call `await session.terminate_session()`.
## Development
Run tests:
```
uv run pytest -q
```
Formatting & linting:
```
uv run black .
uv run ruff check .
uv run mypy .
```
Logging:
- By default, logs are minimal. Use `-v` or set up `setup_logging(level=logging.DEBUG)` programmatically for detailed traces.
## Architecture
The codebase has been recently refactored for better maintainability and reliability:
- **Clean message handling**: AWS SSM protocol messages are parsed by dedicated `MessageParser` and routed to specialized handlers (`HandshakeHandler`, `StreamHandler`, `ControlHandler`)
- **Reliable file transfers**: Fixed line ending normalization issues that caused checksum mismatches
- **Modular design**: Session management, WebSocket communication, and CLI coordination are cleanly separated
- **Type safety**: Full mypy type checking with modern Python type hints
This provides a solid foundation for extending functionality while maintaining compatibility with the AWS SSM protocol.
## Known Limitations
- KMS encryption handshake is not implemented; sessions requiring encryption will not negotiate keys.
- Port/InteractiveCommands sessions are stubbed and not fully implemented.
Raw data
{
"_id": null,
"home_page": null,
"name": "pyssm-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "aws, ec2, session-manager, ssh, ssm",
"author": null,
"author_email": "Damon Cortesi <d.lifehacker@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b3/d0/f0602592611f244641f0041fb148b0875279c0193c7c885051d2e7ffdb1d/pyssm_client-0.1.0.tar.gz",
"platform": null,
"description": "# PySSM Client\n\nEnhanced Python AWS SSM Session Manager client with interactive sessions, exec, and file transfer support. It speaks the same binary protocol as the official Go plugin and provides additional functionality like library imports and extended CLI commands.\n\nHighlights:\n- Interactive SSH-like sessions via SSM (`ssh` subcommand)\n- Direct connect to an existing SSM data channel (`connect` subcommand)\n- Proper ack/seq handling, terminal raw mode, signal forwarding (Ctrl-C/Z/\\), and periodic resize updates\n- Minimal logging by default; verbose traces with `-v`\n\n\n## Installation\n\nInstall from PyPI:\n\n```bash\npip install pyssm-client\n```\n\nOr with uv:\n\n```bash\nuv add pyssm-client\n```\n\n## Requirements\n\n- Python 3.12+\n- AWS credentials discoverable via environment or `~/.aws/credentials`\n\n## Quick Start\n\n```bash\n# Interactive SSH-like session\npyssm ssh --target i-0123456789abcdef0\n\n# Execute single command\npyssm exec --target i-0123456789abcdef0 --command \"ls -la\"\n\n# Copy files\npyssm copy ./local-file.txt i-0123456789abcdef0:/tmp/remote-file.txt\n```\n\n\n## CLI Usage\n\nThe CLI provides four subcommands: `connect`, `ssh`, `exec`, and `copy`.\n\n### `ssh`: Start an SSM session to a target\n\nStarts a new SSM session using `boto3` and connects interactively.\n\n```bash\npyssm ssh \\\n --target i-0123456789abcdef0 \\\n --region us-west-2 \\\n --profile myprofile\n```\n\nOptions:\n- `--target` (required): EC2 instance ID (`i-*`) or managed instance ID (`mi-*`)\n- `--document-name`: SSM document (defaults to the agent\u2019s standard shell doc)\n- `--parameters`: JSON object of document parameters\n- `--profile`, `--region`, `--endpoint-url`: AWS settings for `boto3`\n\nGlobal options (apply to all commands):\n- `-v/--verbose`: enable DEBUG logging\n- `--log-file PATH`: log to file in addition to stderr\n- `--coalesce-input [auto|on|off]` (default `auto`): input batching\n - `auto`: enabled for non\u2011TTY stdin (piped input), disabled for interactive TTYs\n - `on`: always enable (tunable with `--coalesce-delay-ms`)\n - `off`: always disabled\n- `--coalesce-delay-ms FLOAT` (default 10.0): coalescing delay when enabled\n\nBehavior:\n- Terminal set to cbreak, `-echo -isig` (no double echo; signals forwarded to remote)\n- Periodic terminal size updates (500ms) and on resize (SIGWINCH)\n- Ctrl-C (0x03), Ctrl-\\ (0x1c), Ctrl-Z (0x1a) forwarded to remote\n- `exit` cleanly closes the session and the CLI\n\n\n### `exec`: Execute a single command\n\nExecute a single command on a target instance and return the results with proper exit codes.\n\n```bash\npyssm exec \\\n --target i-0123456789abcdef0 \\\n --command \"ls -la /tmp\" \\\n --region us-west-2 \\\n --profile myprofile\n```\n\nOptions:\n- `--target` (required): EC2 instance ID (`i-*`) or managed instance ID (`mi-*`)\n- `--command` (required): Shell command to execute\n- `--timeout`: Command timeout in seconds (default: 600)\n- `--profile`, `--region`, `--endpoint-url`: AWS settings for `boto3`\n\nThis command:\n- Executes the command and captures stdout/stderr separately\n- Returns the actual exit code of the executed command\n- Filters shell noise (prompts, command echoes) from output\n- Useful for scripting and automation\n\n\n### `copy`: File transfer via SSM\n\nTransfer files to/from targets using base64 encoding over SSM sessions.\n\n```bash\n# Upload local file to remote\npyssm copy \\\n ./local-file.txt i-0123456789abcdef0:/tmp/remote-file.txt \\\n --region us-west-2 \\\n --profile myprofile\n\n# Download remote file to local \npyssm copy \\\n i-0123456789abcdef0:/tmp/remote-file.txt ./local-file.txt \\\n --region us-west-2 \\\n --profile myprofile\n```\n\nOptions:\n- `--verify-checksum` (default: on): Verify file integrity using MD5/SHA256\n- `--encoding` (default: base64): Transfer encoding (base64, raw, uuencode)\n- `--chunk-size`: Transfer chunk size in bytes (default: 8192)\n- `--profile`, `--region`, `--endpoint-url`: AWS settings for `boto3`\n\nFeatures:\n- Automatic checksum verification to ensure file integrity \n- Progress reporting during transfer\n- Support for binary files via base64 encoding\n- Works with any file size (chunked transfer)\n\n\n### `connect`: Attach to an existing SSM data channel\n\nConnects using session parameters you already have (typical when called by AWS CLI). You can pass a single JSON blob or individual flags.\n\nJSON form (mimics the AWS CLI invocation):\n\n```bash\npyssm connect '{\n \"SessionId\": \"dacort-abc123\",\n \"StreamUrl\": \"wss://ssmmessages.us-west-2.amazonaws.com/v1/data-channel/dacort-abc123?...\",\n \"TokenValue\": \"...\",\n \"target\": \"i-0123456789abcdef0\",\n \"sessionType\": \"Standard_Stream\"\n}'\n```\n\nFlag form:\n\n```bash\npyssm connect \\\n --session-id dacort-abc123 \\\n --stream-url wss://... \\\n --token-value ... \\\n --target i-0123456789abcdef0 \\\n --session-type Standard_Stream\n```\n\nNotes:\n- The CLI validates parameters and will emit friendly errors if missing or invalid.\n- Global logging and coalescing options work here too.\n\n\n## Using as a Library\n\nYou can embed the plugin in your own Python program. There are four convenient levels: file transfer, exec API, high-level (CLI coordinator), and low-level (session + data channel).\n\n### File Transfer API: Upload/download files\n\nFor programmatic file transfers with progress tracking and verification:\n\n```python\nfrom pyssm_client.file_transfer import FileTransferClient\nfrom pyssm_client.file_transfer.types import FileTransferOptions\n\nclient = FileTransferClient()\n\n# Upload file\noptions = FileTransferOptions(verify_checksum=True)\nsuccess = await client.upload_file(\n local_path=\"./local-file.txt\",\n remote_path=\"/tmp/remote-file.txt\", \n target=\"i-0123456789abcdef0\",\n options=options,\n region=\"us-west-2\",\n profile=\"myprofile\"\n)\n\n# Download file\nsuccess = await client.download_file(\n remote_path=\"/tmp/remote-file.txt\",\n local_path=\"./downloaded-file.txt\",\n target=\"i-0123456789abcdef0\", \n options=options,\n region=\"us-west-2\",\n profile=\"myprofile\"\n)\n```\n\n### Exec API: Single command execution\n\nFor simple command execution with clean stdout/stderr separation:\n\n```python\nfrom pyssm_client.exec import run_command, run_command_sync\n\n# Async version\nresult = await run_command(\n target=\"i-0123456789abcdef0\",\n command=\"ls -la /tmp\",\n region=\"us-west-2\",\n profile=\"myprofile\"\n)\nprint(f\"Exit code: {result.exit_code}\")\nprint(f\"Stdout: {result.stdout.decode('utf-8')}\")\nprint(f\"Stderr: {result.stderr.decode('utf-8')}\")\n\n# Sync version \nresult = run_command_sync(\n target=\"i-0123456789abcdef0\",\n command=\"sha256sum /path/to/file\"\n)\nif result.exit_code == 0:\n checksum = result.stdout.decode('utf-8').strip().split()[0]\n```\n\n### High-level: reuse the CLI coordinator\n\n```\nimport asyncio\nfrom pyssm_client.cli.types import ConnectArguments\nfrom pyssm_client.cli.main import SessionManagerPlugin\nfrom pyssm_client.utils.logging import setup_logging\n\nsetup_logging() # or logging.DEBUG for verbose\n\nargs = ConnectArguments(\n session_id=\"dacort-abc123\",\n stream_url=\"wss://...\",\n token_value=\"...\",\n target=\"i-0123456789abcdef0\",\n session_type=\"Standard_Stream\",\n)\n\nplugin = SessionManagerPlugin()\nexit_code = asyncio.run(plugin.run_session(args))\n```\n\n### Low-level: wire session + data channel yourself\n\n```\nimport asyncio\nfrom pyssm_client.session.session_handler import SessionHandler\nfrom pyssm_client.communicator.utils import create_websocket_config\nfrom pyssm_client.communicator.data_channel import SessionDataChannel\n\nasync def main():\n handler = SessionHandler()\n # Create session (without executing) from your already-resolved params\n session = await handler.validate_input_and_create_session({\n \"sessionId\": \"dacort-abc123\",\n \"streamUrl\": \"wss://...\",\n \"tokenValue\": \"...\",\n \"target\": \"i-0123456789abcdef0\",\n \"sessionType\": \"Standard_Stream\",\n })\n\n # Create data channel and wire handlers\n ws_cfg = create_websocket_config(stream_url=\"wss://...\", token=\"...\")\n dc = SessionDataChannel(ws_cfg)\n dc.set_input_handler(lambda b: sys.stdout.buffer.write(b) or sys.stdout.flush())\n # Optional: closed and coalescing handlers\n dc.set_closed_handler(lambda: print(\"\\n[session closed]\\n\"))\n # dc.set_coalescing(True, delay_sec=0.01) # for piped input\n\n session.set_data_channel(dc)\n await session.execute() # open websocket + handshake\n # then run your own event loop + stdin handling as needed\n\nasyncio.run(main())\n```\n\nTips:\n- For custom UIs, provide your own `input_handler` (bytes from the agent) and feed `send_input_data()` with bytes from your UI.\n- Use `send_terminal_size(cols, rows)` whenever your layout changes.\n- On shutdown, call `await session.terminate_session()`.\n\n\n## Development\n\nRun tests:\n\n```\nuv run pytest -q\n```\n\nFormatting & linting:\n\n```\nuv run black .\nuv run ruff check .\nuv run mypy .\n```\n\nLogging:\n- By default, logs are minimal. Use `-v` or set up `setup_logging(level=logging.DEBUG)` programmatically for detailed traces.\n\n\n## Architecture\n\nThe codebase has been recently refactored for better maintainability and reliability:\n\n- **Clean message handling**: AWS SSM protocol messages are parsed by dedicated `MessageParser` and routed to specialized handlers (`HandshakeHandler`, `StreamHandler`, `ControlHandler`)\n- **Reliable file transfers**: Fixed line ending normalization issues that caused checksum mismatches\n- **Modular design**: Session management, WebSocket communication, and CLI coordination are cleanly separated\n- **Type safety**: Full mypy type checking with modern Python type hints\n\nThis provides a solid foundation for extending functionality while maintaining compatibility with the AWS SSM protocol.\n\n\n## Known Limitations\n\n- KMS encryption handshake is not implemented; sessions requiring encryption will not negotiate keys.\n- Port/InteractiveCommands sessions are stubbed and not fully implemented.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Enhanced Python AWS SSM Session Manager client with interactive sessions, exec, and file transfer support",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"aws",
" ec2",
" session-manager",
" ssh",
" ssm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "00c6bfb532938b414c3617e8ca0d5516ffed46ccbb19d3ba40b4fa2a331123ca",
"md5": "ce4f65304eab572e8881ed193a96f6c9",
"sha256": "de97cfe0ed99a06f37b79c354db1db1aecc338f4975b2b35492e3c3a28c93dac"
},
"downloads": -1,
"filename": "pyssm_client-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ce4f65304eab572e8881ed193a96f6c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 58770,
"upload_time": "2025-09-04T05:00:11",
"upload_time_iso_8601": "2025-09-04T05:00:11.937503Z",
"url": "https://files.pythonhosted.org/packages/00/c6/bfb532938b414c3617e8ca0d5516ffed46ccbb19d3ba40b4fa2a331123ca/pyssm_client-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b3d0f0602592611f244641f0041fb148b0875279c0193c7c885051d2e7ffdb1d",
"md5": "2f3811f85bba7ac06590bce2b34d3d88",
"sha256": "7ddc1a4abe932f2a2d16b2014c8510adb4a5e3bf2d69161ff31bcc53bd29aef6"
},
"downloads": -1,
"filename": "pyssm_client-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2f3811f85bba7ac06590bce2b34d3d88",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 102973,
"upload_time": "2025-09-04T05:00:13",
"upload_time_iso_8601": "2025-09-04T05:00:13.359220Z",
"url": "https://files.pythonhosted.org/packages/b3/d0/f0602592611f244641f0041fb148b0875279c0193c7c885051d2e7ffdb1d/pyssm_client-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 05:00:13",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pyssm-client"
}
