Getting Started

Table of contents

1. Prerequisites
   1. Required IAM Permissions
2. Installation
   1. Rust
   2. Python
3. Usage
   1. Interactive Shell
   2. Port Forwarding
   3. Python Async
4. Configuration
   1. Timeouts
   2. Feature Flags
5. Next Steps

---

Prerequisites

• AWS Credentials with SSM permissions
• Target with SSM agent installed (EC2, ECS, or on-premises)
• Rust 1.81+ or Python 3.8+

Required IAM Permissions

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": ["ssm:StartSession", "ssm:TerminateSession"],
        "Resource": "*"
    }]
}

---

Installation

Rust

[dependencies]
aws-ssm-bridge = "0.1"
tokio = { version = "1", features = ["full"] }

Python

pip install aws-ssm-bridge

---

Usage

Interactive Shell

use aws_ssm_bridge::interactive::{InteractiveShell, InteractiveConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = InteractiveConfig::default();
    let mut shell = InteractiveShell::new(config)?;
    
    // Connect and run interactive session
    // Handles raw mode, resize (SIGWINCH), signals (Ctrl+C/D/Z)
    shell.connect("i-0123456789abcdef0").await?;
    shell.run().await?;
    Ok(())
}

Port Forwarding

use aws_ssm_bridge::{SessionManager, PortForwardConfig, PortForwarder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let manager = SessionManager::new().await?;
    
    let forwarder = PortForwarder::new(&manager, PortForwardConfig {
        target: "i-0123456789abcdef0".into(),
        local_port: 8080,
        remote_port: 80,
        ..Default::default()
    }).await?;
    
    println!("Forwarding localhost:8080 -> remote:80");
    forwarder.wait().await?;
    Ok(())
}

Python Async

import asyncio
from aws_ssm_bridge import SessionManager

async def main():
    manager = await SessionManager.new()
    
    async with await manager.start_session(target="i-0123456789abcdef0") as session:
        await session.send(b"whoami\n")
        async for chunk in await session.output():
            print(chunk.decode(), end="")

asyncio.run(main())

---

Configuration

Timeouts

use aws_ssm_bridge::SessionConfig;
use std::time::Duration;

let config = SessionConfig {
    target: "i-xxx".into(),
    connect_timeout: Duration::from_secs(30),
    idle_timeout: Duration::from_secs(20 * 60),
    max_duration: Some(Duration::from_secs(3600)),
    ..Default::default()
};

Feature Flags

[dependencies]
aws-ssm-bridge = { version = "0.1", default-features = false, features = ["interactive"] }

Feature	Description	Default
interactive	Terminal handling	✅
python	Python bindings	❌

---

Next Steps

• Architecture - Design overview
• Security - Threat model and mitigations
• Binary Protocol - Wire format details
• Protocol Flow - Sequence diagrams