aws-ssm-bridge

A Rust implementation of the AWS Systems Manager Session Manager protocol, with async Python bindings.

Not affiliated with AWS. This is an independent implementation of a documented-by-observation protocol, not endorsed or sponsored by Amazon Web Services, Inc.

What this is for

The official session-manager-plugin is a CLI binary: you shell out to it, hand it JSON on argv, and parse whatever it prints. That is fine for a terminal and awkward for everything else.

aws-ssm-bridge is a library. Open sessions, stream bytes and forward ports from inside your own async application — no subprocess, no plugin to install, no output scraping.

use aws_ssm_bridge::SessionBuilder;
use futures_util::StreamExt;

let session = SessionBuilder::new("i-0123456789abcdef0").start().await?;
session.wait_ready().await?;

let mut output = session.output();
session.send(&b"uname -a\r"[..]).await?;

while let Some(chunk) = output.next().await {
    print!("{}", String::from_utf8_lossy(&chunk));
}
session.terminate().await?;

Install

cargo add aws-ssm-bridge
cargo add tokio --features rt-multi-thread,macros

pip install aws-ssm-bridge

Requires the same IAM permissions as the official plugin: ssm:StartSession on the target, and ssm:TerminateSession on your own sessions.

Capabilities

Verified against a live SSM agent (3.3.3572.0): the SigV4-signed data-channel upgrade, shell sessions, the handshake, concurrent multiplexed TCP streams, and clean teardown.

Guided tour

Shell session

use aws_ssm_bridge::SessionBuilder;
use futures_util::StreamExt;

let session = SessionBuilder::new("i-0123456789abcdef0")
    .region("eu-central-1")
    .reason("incident 4711")     // recorded in CloudTrail
    .start()
    .await?;

let mut output = session.output();   // subscribe *before* sending
session.wait_ready().await?;
session.send(&b"df -h\r"[..]).await?;

Send \r, not \n: a remote pty maps carriage return to newline, but Windows shells behind winpty do not accept a bare line feed.

Port forwarding

use std::sync::Arc;
use aws_ssm_bridge::{
    documents::PortForwardingToRemoteHost, install_signal_handlers,
    PortForwardConfig, PortForwarder, SessionBuilder, ShutdownSignal,
};

let shutdown = ShutdownSignal::new();
install_signal_handlers(shutdown.clone());

let session = Arc::new(
    SessionBuilder::new("i-0123456789abcdef0")
        .document(PortForwardingToRemoteHost::new("db.internal", 5432))
        .start()
        .await?,
);

let forwarder = PortForwarder::bind(PortForwardConfig {
    local_addr: "127.0.0.1:15432".parse()?,
    ..Default::default()
})
.await?;

println!("psql -h 127.0.0.1 -p {}", forwarder.local_addr().port());
forwarder.forward(session, shutdown).await?;

Each accepted connection becomes its own smux stream inside one WebSocket, so concurrent connections neither block nor corrupt each other.

Typed documents

use aws_ssm_bridge::documents::*;

PortForwardingSession::new(3306)                            // port on the instance
PortForwardingToRemoteHost::new("db.internal", 5432)        // through the instance
SshSession::new()                                           // ssh ProxyCommand transport
InteractiveCommand::new("top")                              // with a pty
NonInteractiveCommand::new("systemctl status nginx")        // without a pty

Python

import asyncio
from aws_ssm_bridge import SessionManager

async def main():
    manager = await SessionManager.new(region="eu-central-1")
    async with await manager.start_session("i-0123456789abcdef0") as session:
        await session.send(b"uname -a\r")
        async for chunk in session.output():
            print(chunk.decode(errors="replace"), end="")

asyncio.run(main())

Session lifetime

A session is either running or closed. Every way it can end — a clean terminate(), the agent hanging up, a dead network, a protocol violation — resolves Session::closed() and records a CloseReason.

tokio::select! {
    () = session.closed() => eprintln!("gone: {}", session.close_reason().unwrap()),
    result = do_work(&session) => result?,
}

That one guarantee is what makes the layers above it work: the port forwarder stops accepting when the tunnel dies, the pool reaps dead entries, and ReconnectingSession knows when to rebuild. There is no state in which the handle looks alive but nothing is running.

Reconnection resumes the session where it can: ssm:ResumeSession keeps the same session and the same remote process, so the shell survives the gap. When the session has timed out rather than merely disconnected, it cannot be resumed and a new one is started instead — a new process, so shell state and anything printed while disconnected are gone. ReconnectEvent tells the two apart: Resumed carries the same session ID, Reconnected a new one.

Feature flags

Built without kms, a session whose account mandates encryption fails the handshake with an explicit error instead of quietly running in plaintext.

extension-module is deliberately separate from python: it leaves the CPython symbols for the interpreter to resolve at load time, which is right for a wheel and fatal for a test binary. Because --all-features would enable it, name the features you want instead — --features interactive,kms is what CI runs.

Examples

Python equivalents live in python_examples/.

Documentation

Full documentation: hupe1980.github.io/aws-ssm-bridge

The site is built with Zola from site/; just site serves it locally.

Security

• unsafe_code = "forbid" for the whole crate, so any unsafe fails the build.
• The session token travels only in the data-channel open message — never in a URL, where proxies and traces would record it.
• The data-channel WebSocket upgrade is signed with SigV4 over ssmmessages, matching the reference plugin. A presigned stream URL, and a session opened with Session::attach, are sent unsigned.
• SHA-256 payload digests are verified, matching the reference implementation; a mismatch ends the session rather than delivering corrupt bytes.
• The data channel refuses any endpoint that is not an AWS SSM messages host.
• KMS session encryption is AES-256-GCM with a per-message nonce, and a client that cannot negotiate it fails the handshake rather than downgrading.

See the security model for the threat model and what is explicitly not defended against.

Development

just                # list every recipe
just check          # what CI runs: fmt, clippy, tests, docs
just matrix         # every feature combination
just bench          # framing and reliability micro-benchmarks
just fuzz           # cargo-fuzz over the network-facing parsers
just python         # build and install the wheel
just site           # serve the documentation site locally
just release-check  # everything above, plus MSRV, --locked, publish dry run
SSM_TARGET=i-… just live-smoke   # the pre-release check against a real instance

The MSRV is set by the AWS SDK, not by this crate's own code. just msrv verifies it against the committed lockfile — which is the only way the check means anything, since an unlocked resolve pulls in dependencies that need a newer toolchain than users actually get.

License

MIT. See LICENSE.