Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bertrandmartel/aws-ssm-session
Javascript library for starting an AWS SSM session compatible with Browser and NodeJS
https://github.com/bertrandmartel/aws-ssm-session
aws aws-ssm javascript nodejs shell ssm terminal web websocket xterm-js
Last synced: 4 days ago
JSON representation
Javascript library for starting an AWS SSM session compatible with Browser and NodeJS
- Host: GitHub
- URL: https://github.com/bertrandmartel/aws-ssm-session
- Owner: bertrandmartel
- License: mit
- Created: 2020-04-05T00:34:03.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-05-02T06:57:03.000Z (over 1 year ago)
- Last Synced: 2024-11-04T18:12:07.255Z (9 days ago)
- Topics: aws, aws-ssm, javascript, nodejs, shell, ssm, terminal, web, websocket, xterm-js
- Language: JavaScript
- Homepage:
- Size: 414 KB
- Stars: 50
- Watchers: 7
- Forks: 9
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# AWS SSM Session for Javascript
 [](LICENSE.md)
[](https://lgtm.com/projects/g/bertrandmartel/aws-ssm-session/alerts/) [](https://lgtm.com/projects/g/bertrandmartel/aws-ssm-session/context:javascript)
Javascript library for starting an AWS SSM session compatible with Browser and NodeJS
[](https://www.npmjs.com/package/ssm-session)
| Start a shell session in the Browser | Start a shell session using NodeJS |
| :---------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------: |
|  |  |
## About AWS System Manager Session Manager
> Session Manager is a fully managed AWS Systems Manager capability that lets you manage your Amazon EC2 instances, on-premises instances, and virtual machines (VMs) through an interactive one-click browser-based shell or through the AWS CLI. Session Manager provides secure and auditable instance management without the need to open inbound ports, maintain bastion hosts, or manage SSH keys. Session Manager also makes it easy to comply with corporate policies that require controlled access to instances, strict security practices, and fully auditable logs with instance access details, while still providing end users with simple one-click cross-platform access to your managed instances.
## Quick Start
### NodeJS
```bash
git clone [email protected]:bertrandmartel/aws-ssm-session.git
cd aws-ssm-session
npm i
npm run build
node ./examples/node/app.js
```
You will be prompted for AWS Region, AWS profile (default if not specified), choose your instance and a session is started directly
### Browser
We need to generate the Websocket stream URL and token value using AWS API using a NodeJS script :
```bash
git clone [email protected]:bertrandmartel/aws-ssm-session.git
cd aws-ssm-session
npm i
npm run build
node scripts/generate-session.js
```
In another shell start the local webserver
```bash
cd examples/web
npm start
```
Go to http://localhost:8080 and enter your token & stream value from the output of the first shell then click "start session"
## Installation
From npm :
```bash
npm i --save ssm-session
```
## Usage
```javascript
const { ssm } = require("ssm-session");
```
or
```javascript
import { ssm } from "ssm-session";
```
## Example
### Browser
The following code starts a session and use [Xterm.js](https://xtermjs.org/) to write the result and listen to key events, checkout the [`web` directory](https://github.com/bertrandmartel/aws-ssm-session/tree/master/web)
```javascript
import { Terminal } from "xterm";
import "xterm/css/xterm.css";
import { ssm } from "ssm-session";
var socket;
var terminal;
const textDecoder = new TextDecoder();
const textEncoder = new TextEncoder();
const termOptions = {
rows: 34,
cols: 197,
fontFamily: "Fira Code, courier-new, courier, monospace",
};
$(document).ready(function () {
$(".toast").toast({
delay: 3500,
});
});
$("#startSessionBtn").click(startSession);
$("#stopSessionBtn").click(stopSession);
function startSession() {
var tokenValue = document.getElementById("tokenValue").value;
var websocketStreamURL = document.getElementById("websocketStreamURL").value;
if (!tokenValue) {
showMessage("Token value is required to start session");
return;
}
if (!websocketStreamURL) {
showMessage("Websocket stream URL is required to start session");
return;
}
socket = new WebSocket(websocketStreamURL);
socket.binaryType = "arraybuffer";
initTerminal();
socket.addEventListener("open", function (event) {
ssm.init(socket, {
token: tokenValue,
termOptions: termOptions,
});
});
socket.addEventListener("close", function (event) {
showMessage("Websocket closed");
});
socket.addEventListener("message", function (event) {
var agentMessage = ssm.decode(event.data);
ssm.sendACK(socket, agentMessage);
if (agentMessage.payloadType === 1) {
terminal.write(textDecoder.decode(agentMessage.payload));
} else if (agentMessage.payloadType === 17) {
ssm.sendInitMessage(socket, termOptions);
}
});
}
function stopSession() {
if (socket) {
socket.close();
}
terminal.dispose();
}
function showMessage(message) {
$("#toastMessage").text(message);
$("#alertMessage").toast("show");
}
function initTerminal() {
terminal = new Terminal(termOptions);
terminal.open(document.getElementById("terminal"));
terminal.onData(function (data) {
ssm.sendText(socket, textEncoder.encode(data));
});
terminal.focus();
}
```
### NodeJS
The following code uses [ws](https://github.com/websockets/ws) as websocket client and listens to key events, from the [examples/node](https://github.com/bertrandmartel/aws-ssm-session/tree/master/examples/node) directory :
```javascript
"use strict";
const session = require("../../scripts/aws-get-session");
const WebSocket = require("ws");
const readline = require("readline");
const { ssm } = require("ssm-session");
const util = require("util");
const textDecoder = new util.TextDecoder();
const textEncoder = new util.TextEncoder();
const termOptions = {
rows: 34,
cols: 197,
};
(async () => {
var startSessionRes = await session();
const rl = readline.createInterface({
input: process.stdin,
output: null,
});
readline.emitKeypressEvents(process.stdin);
const connection = new WebSocket(startSessionRes.StreamUrl);
process.stdin.on("keypress", (str, key) => {
if (connection.readyState === connection.OPEN) {
ssm.sendText(connection, textEncoder.encode(str));
}
});
connection.onopen = () => {
ssm.init(connection, {
token: startSessionRes.TokenValue,
termOptions: termOptions,
});
};
connection.onerror = (error) => {
console.log(`WebSocket error: ${error}`);
};
connection.onmessage = (event) => {
var agentMessage = ssm.decode(event.data);
ssm.sendACK(connection, agentMessage);
if (agentMessage.payloadType === 1) {
process.stdout.write(textDecoder.decode(agentMessage.payload));
} else if (agentMessage.payloadType === 17) {
ssm.sendInitMessage(connection, termOptions);
}
};
connection.onclose = () => {
console.log("websocket closed");
};
})();
```
## ECS tasks
This library also works with [ECS Tasks execute commands](https://aws.amazon.com/fr/blogs/containers/new-using-amazon-ecs-exec-access-your-containers-fargate-ec2/) on Fargate and Amazon EC2.
You can use the nodejs script to generate the session details:
```
node ./scripts/generate-session-ecs.js
```
It will prompt user with aws region, aws profile, ecs cluster, tasks, containers and will generate the session details including Token and websocket stream URL.
Note that ECS restricts by default a maximum of 2 simultaneous connections. You will need to explicitely terminate the connections by listing and deleting them if necessary (see [Terminating the connections](#terminating-the-connections-))
- list ssm sessions that are targetting ECS tasks:
```bash
aws ssm describe-sessions --state Active | jq -r '.Sessions[] | select(.Target | startswith("ecs:")) | .SessionId'
```
- delete one session by session ID:
```bash
aws ssm terminate-session --session-id [SESSION_ID]
```
Note: For EC2 instance, the target is the instance ID. For ECS taks, the target is a concatenation of cluster name, task ID and container ID, see [this](https://github.com/aws/aws-cli/blob/45b0063b2d0b245b17a57fd9eebd9fcc87c4426a/awscli/customizations/ecs/executecommand.py#L70-L72)
## Terminating the connections
To terminate the connection, one would either execute the `exit` command or use the CLI/API with :
- list ssm sessions:
```bash
aws ssm describe-sessions --state Active | jq -r '.Sessions[] | .SessionId'
```
- delete one session by session ID:
```bash
aws ssm terminate-session --session-id [SESSION_ID]
```
## How it works ?
The flow is the following :
- get the SSM Managed instance list using AWS API : [ssm describe-instances-information](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeInstanceInformation.html)
- call the start session API on one target instance using AWS API : [ssm start-session API](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartSession.html). This gives you the websocket URL and a Token value that will be used for authentication
- open a websocket connection on this URL
- send an authentication request composed of the following JSON stringified :
```json
{
"MessageSchemaVersion": "1.0",
"RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"TokenValue": ""
}
```
From this moment the protocol is not JSON anymore. It is implemented in the offical [Amazon SSM agent](https://github.com/aws/amazon-ssm-agent) which is required if you want start a SSM session from the AWS CLI. The payload must be sent & receive according [this binary format](https://github.com/aws/amazon-ssm-agent/blob/c65d8ac29a8bbe6cd3f7cea778c1eeb1b06d49a3/agent/session/contracts/agentmessage.go)
Also more specifically from [amazon-ssm-agent source code](https://github.com/aws/amazon-ssm-agent/blob/c65d8ac29a8bbe6cd3f7cea778c1eeb1b06d49a3/agent/session/contracts/agentmessage.go):
```
// HL - HeaderLength is a 4 byte integer that represents the header length.
// MessageType is a 32 byte UTF-8 string containing the message type.
// SchemaVersion is a 4 byte integer containing the message schema version number.
// CreatedDate is an 8 byte integer containing the message create epoch millis in UTC.
// SequenceNumber is an 8 byte integer containing the message sequence number for serialized message streams.
// Flags is an 8 byte unsigned integer containing a packed array of control flags:
// Bit 0 is SYN - SYN is set (1) when the recipient should consider Seq to be the first message number in the stream
// Bit 1 is FIN - FIN is set (1) when this message is the final message in the sequence.
// MessageId is a 16 byte UTF-8 string containing a random UUID identifying this message.
// Payload digest is a 32 byte containing the SHA-256 hash of the payload.
// Payload Type is a 4 byte integer containing the payload type.
// Payload length is an 4 byte unsigned integer containing the byte length of data in the Payload field.
// Payload is a variable length byte data.
```
In Javascript it gives the following :
```javascript
var agentMessage = {
headerLength: getInt(buf.slice(0, 4)), // 4 bytes
messageType: getString(buf.slice(4, 36)).trim(), // 32 bytes
schemaVersion: getInt(buf.slice(36, 40)), // 4 bytes
createdDate: getLong(buf.slice(40, 48)), // 8 bytes
sequenceNumber: getLong(buf.slice(48, 56)), // 8 bytes
flags: getLong(buf.slice(56, 64)), // 8 bytes
messageId: parseUuid(buf.slice(64, 80)), // 16 bytes
payloadDigest: getString(buf.slice(80, 112)), // 32 bytes
payloadType: getInt(buf.slice(112, 116)), // 4 bytes
payloadLength: getInt(buf.slice(116, 120)), // 4 bytes
payload: buf.slice(120, buf.byteLength), //variable length
};
```
Byte order is Big endian
For the communication part :
- each message with type "output_stream_data" must be acknowledged using an "acknowledge" type message which is referencing the messageID (uuid) of the message that has been received.
- when you send text, you send a message with type "input_stream_data", this message must be sent with an incremental sequence number (note the sequenceNumber field in the model above). The message will then be acknowledged by the server
There are possibly some features I didn't implement, for instance I didn't implement yet the ping message which is used to prevent the shell from being terminated due to inactivity
## Note about simultaneous terminal session
There is this sequence number that is required and re-initiliazed to 0 each time you call the `init()` function. If you need to have more than 1 terminal at the same time, there will be an issue because each session must have its own sequential number.
One way is to use you own sequential number and set it to 0 before the call to `init()` and increment it before calling `sendText()`. It will be like this :
In websocket open :
```javascript
customSeqNum = 0;
ssm.init(connection, {
token: startSessionRes.TokenValue,
termOptions: termOptions,
});
```
When you write text:
```javascript
ssm.sendText(connection, str, customSeqNum);
```
So this way you can open any number of sessions simultaneously
## Dependencies
- An embedded version of sha256: https://github.com/geraintluff/sha256
## License
The MIT License (MIT) Copyright (c) 2020 Bertrand Martel