{"id":23682493,"url":"https://github.com/northwood-labs/ssm-shell","last_synced_at":"2025-09-02T11:31:14.250Z","repository":{"id":57655942,"uuid":"429992969","full_name":"northwood-labs/ssm-shell","owner":"northwood-labs","description":"Simplifies the process of connecting to EC2 Instances using AWS Session Manager.","archived":false,"fork":false,"pushed_at":"2024-12-19T07:45:19.000Z","size":210,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-19T08:33:53.548Z","etag":null,"topics":["aws","aws-ec2","aws-ssm","aws-ssm-agent","session-manager"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/northwood-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-20T02:55:06.000Z","updated_at":"2024-12-19T07:45:21.000Z","dependencies_parsed_at":"2022-08-25T16:20:39.540Z","dependency_job_id":"0d1422f9-560a-40ce-9225-3e66a7cb8035","html_url":"https://github.com/northwood-labs/ssm-shell","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northwood-labs%2Fssm-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northwood-labs%2Fssm-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northwood-labs%2Fssm-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northwood-labs%2Fssm-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/northwood-labs","download_url":"https://codeload.github.com/northwood-labs/ssm-shell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231780384,"owners_count":18425540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-ec2","aws-ssm","aws-ssm-agent","session-manager"],"created_at":"2024-12-29T19:50:46.341Z","updated_at":"2024-12-29T19:50:47.097Z","avatar_url":"https://github.com/northwood-labs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv\u003e\u003cimg src=\"ssm-shell-art.jpg\"\u003e\u003c/div\u003e\n\n# SSM Shell for AWS Session Manager\n\nSimplifies the process of connecting to EC2 instances using AWS Session Manager when you have many instances.\n\n## Why this project?\n\nHonestly, because I'm tired of having to log into the AWS Console to find the EC2 Instance ID before I pass it to the AWS CLI. Secondly, using the web interface in the AWS Console is _OK_, but I prefer to use the right tool for the job — my terminal.\n\n```bash\naws ssm start-session --target i-abcdef123456\n```\n\nGiven valid AWS credentials, this will hit the EC2 API first to retrieve a list of running instances, then help you select the instance to which to connect.\n\n### Why AWS Session Manager?\n\n\u003cdetails\u003e\n\u003csummary\u003eRead more…\u003c/summary\u003e\u003cbr\u003e\n\nSSH is old-school, error-prone, and easy to get wrong.\n\nWith the ever-shifting cybersecurity landscape, older ciphers and protocols being cracked over time, and the likelihood of losing SSH keys (or someone stealing them), there are newer, better ways of connecting to EC2 instances in the cloud. AWS Session Manager uses the _AWS Systems Manager_ (SSM) agent to allow you to connect to EC2 instances using the AWS CLI instead of SSH. I'm not going to dive into that here, but here are some links if you don't know what this is:\n\n* [Setting up Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started.html)\n* [Complete Session Manager prerequisites](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-prerequisites.html)\n* [Setting up AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-prereqs.html)\n\nIf you work for a corporation with lots and lots of AWS accounts, your IT/DevOps/Cloud people are probably taking a look at this if they haven't started using it already.\n\n\u003c/details\u003e\n\n## Technical Prerequisites\n\n### AWS CLI v2\n\nInstall [aws/aws-cli](https://github.com/aws/aws-cli). If you are on macOS, this is as simple as:\n\n```bash\nbrew install awscli\n```\n\n### AWS Session Manager Plugin\n\nInstall [aws/session-manager-plugin](https://github.com/aws/session-manager-plugin). This software plugs into the AWS CLI, allowing you to connect to the instances using it. If you are on macOS, this is a 2-step process.\n\n```bash\nbrew install session-manager-plugin\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eLearn about macOS Gatekeeper…\u003c/summary\u003e\u003cbr\u003e\n\nNext, you need to understand that macOS has an agent called [Gatekeeper](https://support.apple.com/en-us/HT202491) which prevents malware by requiring applications to be [notarized](https://developer.apple.com/news/?id=10032019a). The version of the package vended by Homebrew is not notarized. The version downloaded directly from AWS’s website **is**.\n\n(Why hasn't AWS taken distribution in standard OS package managers into their own hands?)\n\nIf you prefer to use Homebrew instead of downloading from the AWS website (like me), you will need to adjust the quarantine settings on the plugin.\n\n```bash\nsudo xattr -r -d com.apple.quarantine /usr/local/bin/session-manager-plugin\n```\n\n\u003c/details\u003e\n\n### AWS Vault, AWS Okta, or similar\n\nThe **AWS CLI** is a command-line tool for interacting with AWS services. Credentials stored by AWS CLI can also be used with third-party tools which are built using the AWS SDKs. However, AWS CLI **sucks** at making those credentials available to tools other than itself.\n\n[**AWS Vault**](https://github.com/99designs/aws-vault) simplifies this process by communicating with AWS SSO (or your `~/.aws/config` file) up-front, so that you can more easily pass credentials to not just the AWS CLI, but also to any third-party tools which understand AWS credentials. When you regularly manage credentials across multiple AWS accounts, AWS Vault becomes a veritiable necessity.\n\n[**AWS Okta**](https://github.com/fiveai/aws-okta) works similarly, but focuses on vending credentials to (human) users who authenticate with AWS via Okta SSO. (It is also dramtically superior to [Nike’s “Gimme AWS Creds”](https://github.com/Nike-Inc/gimme-aws-creds) tool.)\n\n## Install as a CLI tool\n\n1. You must have the Golang toolchain installed first.\n\n    ```bash\n    brew install go\n    ```\n\n1. Add `$GOPATH/bin` to your `$PATH` environment variable. By default (i.e., without configuration), `$GOPATH` is defined as `$HOME/go`.\n\n    ```bash\n    export PATH=\"$PATH:$GOPATH/bin\"\n    ```\n\n1. Once you've done everything above, you can use `go install`.\n\n    ```bash\n    go install github.com/northwood-labs/ssm-shell@latest\n    ```\n\n## Usage\n\nThis will fetch the list of running instances over the EC2 API and present a table containing information about the running instances. Press ↑/↓ to select the instance to which you want to connect, then press `Return`, and you will connect to that instance in your terminal.\n\n\u003cdiv\u003e\u003cimg src=\"ssm-shell@2x.png\" alt=\"SSM Shell\"\u003e\u003c/div\u003e\n\nUse `Ctrl+D` to exit your session.\n\n### Using AWS Vault, AWS Okta, or similar\n\nAssuming you have all of the things working as designed — EC2 instances with SSM agents, Session Manager permissions, local tools installed, etc. — this will simplify logging into instances.\n\n```bash\naws-vault exec {profile} -- ssm-shell\n```\n\n### Using default AWS CLI profile\n\nOr, if you have credentials setup with `aws configure` using the `default` profile, you can rely on that as well.\n\n```bash\nssm-shell\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorthwood-labs%2Fssm-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnorthwood-labs%2Fssm-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorthwood-labs%2Fssm-shell/lists"}