krikri-aws-ssm
krikri-aws-ssm
Native AWS Systems Manager (SSM) Session Manager client in pure Crystal, for krikri-playbook. It speaks the SSM data-channel protocol itself, so the controller needs no AWS CLI and no session-manager-plugin - only the SSM agent on the target and the usual AWS permissions.
Status: scaffold. The protocol implementation lands incrementally; see docs/protocol.md for the wire format and the design notes it is built from.
What it does
ssm:StartSession/ResumeSession/TerminateSession, SigV4-signed (JSON 1.1), with an endpoint override.- The Session Manager data channel: 120-byte binary framing, handshake, sequenced input/output with acknowledgements and retransmission, liveness.
- KMS session encryption (accounts whose Session Manager preferences mandate it), AES-256-GCM.
- The standard AWS credential chain: environment, shared profiles (
credential_process,role_arn+source_profile/credential_source,web_identity_token_file/IRSA), SSO cache +sso:GetRoleCredentials, IMDSv2, ECS container credentials.
It is a byte-stream session library: the Ansible-shaped shell protocol, file transfer and error text live in krikri, not here.
Not in scope
- The AWS CLI and
session-manager-plugin(by design). - S3 file staging (krikri moves bytes through the session itself).
- Port forwarding / smux,
AWS-StartSSHSession, Windows sessions. - MFA-token AssumeRole (planned follow-up).
Requirements and permissions
- Controller: Crystal
>= 1.13.0, egress tossm.<region>.amazonaws.comand the data-channel host returned inStreamUrl. - Target: SSM agent, registered as a managed node.
- Caller:
ssm:StartSession,ssm:ResumeSession,ssm:TerminateSession, thessmmessageschannel actions, andkms:GenerateDataKeywhen sessions are encrypted (the target's instance profile needskms:Decrypt).
Usage (sketch)
require "krikri-aws-ssm"
settings = KrikriAwsSsm::Settings.new(
target: "i-0123456789abcdef0",
region: "us-east-2",
)
session = KrikriAwsSsm::Session.open(settings)
session.write("printf 'hello\\n'\n".to_slice)
while output = session.read?
print String.new(output.bytes)
end
session.terminate
The public API is being built out; see the specs for the current surface.
Development
shards install
crystal spec # full suite
just test # parallel spec run
crystal tool format src spec --check
crystal lib/ameba/bin/ameba.cr
Live tests against a real SSM target are opt-in (KRIKRI_SSM_LIVE=1, SSM_TARGET, SSM_REGION) and never run in CI.
Development deps mirror krikri: ameba 1.7.0 and the weirdbricks/minitest.cr fork (v1.7.0-weirdbricks.2).
License and provenance
MIT (see LICENSE). This is a derivative of the open-source reference implementations, not a clean-room project - see NOTICE for the sources and attribution.
krikri-aws-ssm
- 0
- 0
- 0
- 0
- 3
- about 1 hour ago
- November 21, 2026
MIT License
Sat, 21 Nov 2026 08:25:15 GMT