{"id":51433531,"url":"https://github.com/maayanyosef/herdr-aws-ssm","last_synced_at":"2026-07-05T05:30:31.207Z","repository":{"id":368659206,"uuid":"1286196167","full_name":"maayanyosef/herdr-aws-ssm","owner":"maayanyosef","description":"Pick an EC2 instance and connect over AWS SSM in a herdr --remote session - no bastion or public IP.","archived":false,"fork":false,"pushed_at":"2026-07-01T15:13:26.000Z","size":31,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-01T17:13:34.272Z","etag":null,"topics":["aws-ssm","herdr","herdr-plugin","terminal"],"latest_commit_sha":null,"homepage":"https://herdr.dev/plugins/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maayanyosef.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-01T14:34:50.000Z","updated_at":"2026-07-01T15:22:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maayanyosef/herdr-aws-ssm","commit_stats":null,"previous_names":["maayanyosef/herdr-aws-ssm"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/maayanyosef/herdr-aws-ssm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maayanyosef%2Fherdr-aws-ssm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maayanyosef%2Fherdr-aws-ssm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maayanyosef%2Fherdr-aws-ssm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maayanyosef%2Fherdr-aws-ssm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maayanyosef","download_url":"https://codeload.github.com/maayanyosef/herdr-aws-ssm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maayanyosef%2Fherdr-aws-ssm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35144844,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-ssm","herdr","herdr-plugin","terminal"],"created_at":"2026-07-05T05:30:30.777Z","updated_at":"2026-07-05T05:30:31.196Z","avatar_url":"https://github.com/maayanyosef.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# herdr-aws-ssm\n\n[![CI](https://github.com/maayanyosef/herdr-aws-ssm/actions/workflows/ci.yaml/badge.svg)](https://github.com/maayanyosef/herdr-aws-ssm/actions/workflows/ci.yaml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n![Bash 3.2+](https://img.shields.io/badge/bash-3.2%2B-4EAA25.svg)\n![herdr 0.7+](https://img.shields.io/badge/herdr-0.7%2B-8a2be2)\n![platforms: linux • macOS](https://img.shields.io/badge/platforms-linux%20%E2%80%A2%20macOS-informational)\n\n**Connect to your EC2 instances over AWS SSM without leaving your terminal — pick\nan instance from a fuzzy list and drop into a full [herdr](https://herdr.dev)\n`--remote` session, tunneled through Session Manager.** No bastion, no public IP,\nno long-lived SSH keys: authentication uses short-lived EC2 Instance Connect keys,\nand the right SSH user is detected from each instance's AMI. Works with any AWS\naccount using your existing CLI profiles.\n\n## Why you'd want it\n\n- **`herdr --remote`, over SSM.** You get herdr full thin client — remote herdr\n  install, clipboard bridge, persistent session that survives detach/reattach —\n  but the transport is an SSM `AWS-StartSSHSession` tunnel instead of a reachable\n  SSH endpoint. Private-subnet boxes with no inbound work fine.\n- **No keys to manage.** Each connection pushes an ephemeral EC2 Instance Connect\n  key (~60s), then opens the session. Nothing persists on the instance, nothing\n  sits in your repo.\n- **The right user, automatically.** Ubuntu → `ubuntu`, Amazon Linux → `ec2-user`,\n  Debian → `admin`, … detected from the instance's AMI so you don't have to\n  remember per-image logins.\n- **Safe with production.** Any profile you label `prod` is flagged in the picker\n  and requires a typed `yes-prod` before it connects — the gate fails closed.\n- **Zero config to start.** Uses your current AWS profile/region out of the box;\n  point it at more accounts when you want. Pure Bash, no build step,\n  [hardened](SECURITY.md) around your credentials.\n\n## What it does\n\n- **Discover across accounts** — lists running instances for every profile you\n  configure (Name tag, id, type, AZ), and marks each with its SSM reachability\n  (`ssm:Online`) so you don't pick a target the agent can't reach.\n- **Pick fast** — a fuzzy picker (`fzf` if installed, a numbered menu otherwise);\n  `prod`- labeled targets are flagged and gated behind a typed confirmation.\n- **Detect the SSH user** — resolves the login user from the picked instance's\n  AMI and connects as `herdr --remote \u003cuser\u003e@\u003cid\u003e`, so the login user always\n  matches the ephemeral key that was pushed.\n- **Install the transport once** — writes a managed `~/.ssh/config` block that\n  routes `Host i-* mi-*` through the SSM ProxyCommand, atomically and\n  idempotently; after that even a bare `herdr --remote i-…` tunnels over SSM.\n- **Check your setup** — `doctor` verifies the AWS CLI, Session Manager plugin,\n  `herdr`, and that each profile's credentials are live.\n\n## Quick start\n\nPrereqs: AWS CLI v2 + the Session Manager plugin installed (see\n[below](#installing-the-session-manager-plugin)), and a herdr 0.7+.\n\n```bash\n# 1. Install the plugin.\nherdr plugin install maayanyosef/herdr-aws-ssm\n\n# 2. (optional) Point it at your AWS profiles. With no config it uses your\n#    current AWS context ($AWS_PROFILE/$AWS_REGION). To search specific\n#    accounts, drop a config.env in the plugin's config dir (printed on install):\nmkdir -p ~/.config/herdr/plugins/config/herdr-aws-ssm\ncat \u003e ~/.config/herdr/plugins/config/herdr-aws-ssm/config.env \u003c\u003c'EOF'\nHERDR_SSM_PROFILES=\"dev=my-dev-profile prod=my-prod-profile\"\nHERDR_SSM_REGION=\"us-east-1\"\nHERDR_SSM_OSUSER=\"auto\"\nEOF\n\n# 3. Authenticate to AWS (any profile the picker will list).\naws sso login --profile my-dev-profile\n\n# 4. Install the ssh-config transport (once), then preflight.\nherdr plugin action invoke setup  --plugin herdr-aws-ssm\nherdr plugin action invoke doctor --plugin herdr-aws-ssm\n```\n\n`doctor` should report `ok` for `aws` / `session-manager-plugin` / `herdr` and\n`ok sso \u003cenv\u003e` for each logged-in profile. Action output goes to the herdr plugin\nlog rather than your terminal; to see the results directly, run the installed\nscript (its path is shown by `herdr plugin list`), e.g.\n`bash ~/.config/herdr/plugins/github/herdr-aws-ssm-*/bin/doctor.sh`.\n\n**5. Connect.** `connect` is interactive (it shows a picker, then hands off to\n`herdr --remote`), so run it where it has a terminal — **bind a key** and press\nit inside herdr (recommended), rather than a detached `plugin action invoke`:\n\n```toml\n# ~/.config/herdr/config.toml\n[[keys.command]]\nkey = \"prefix+e\"            # pick any free combo\ntype = \"plugin_action\"\ncommand = \"herdr-aws-ssm.connect\"\ndescription = \"SSM connect to an EC2 instance\"\n```\n\nRun `herdr server reload-config`, press your key, pick an instance — you're in.\n(No keybinding is forced by the plugin, to avoid colliding with a herdr built-in.)\n\nOnce `setup` has run, a bare `herdr --remote \u003cinstance-id\u003e` also works, e.g.\n`herdr --remote i-0123456789abcdef0`. Production targets (any profile labelled\n`prod`) require typing `yes-prod` before they connect.\n\n## Actions\n\n| Action                           | id        | What it does                                                                        |\n|----------------------------------|-----------|-------------------------------------------------------------------------------------|\n| **SSM connect (herdr --remote)** | `connect` | List instances → pick → detect user → confirm prod → `herdr --remote \u003cuser\u003e@\u003cid\u003e`   |\n| **SSM: install ssh config**      | `setup`   | Write the managed `~/.ssh/config` block + a starter config; run once                |\n| **SSM: doctor / preflight**      | `doctor`  | Verify AWS CLI, `session-manager-plugin`, `herdr`, and live credentials per profile |\n\n## How it works\n\n1. **`setup`** writes an `~/.ssh/config` block routing `Host i-* mi-*` through\n   `bin/proxy.sh`. The write is atomic (temp file + `mv`) and idempotent (a\n   delimited managed block), so it never duplicates or truncates your config.\n2. **`bin/proxy.sh`** (the ssh `ProxyCommand`) pushes an ephemeral public key with\n   `ec2-instance-connect send-ssh-public-key`, then execs\n   `aws ssm start-session --document-name AWS-StartSSHSession`. ssh runs its\n   handshake over that SSM channel.\n3. **`connect`** lists instances across your profiles, lets you pick one, detects\n   the SSH user from its AMI, gates production, and launches\n   `herdr --remote \u003cuser\u003e@\u003cid\u003e` — so ssh's login user and the pushed key agree.\n\n## Prerequisites\n\n- AWS CLI v2 + `session-manager-plugin` (see below); `fzf` optional (numbered\n  menu otherwise).\n- An authenticated AWS profile (`aws sso login --profile \u003cp\u003e`, or any credential\n  source the AWS CLI understands).\n- Instances: SSM agent running + an instance profile with\n  `AmazonSSMManagedInstanceCore`.\n- IAM: `ssm:StartSession` (with the `AWS-StartSSHSession` document) and\n  `ec2-instance-connect:SendSSHPublicKey`.\n\n### Installing the AWS CLI\n\nAWS CLI v2 install instructions (all platforms):\n\u003chttps://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html\u003e\n\n```bash\n# macOS (Homebrew)\nbrew install awscli\n```\n\nVerify with `aws --version` (expect `aws-cli/2.x`).\n\n### Installing the Session Manager plugin\n\n`aws ssm start-session` needs the Session Manager plugin installed locally. Full\nper-OS instructions:\n\u003chttps://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html\u003e\n\n```bash\n# macOS (Homebrew)\nbrew install --cask session-manager-plugin\n\n# Debian / Ubuntu (x86_64)\ncurl -o /tmp/session-manager-plugin.deb \\\n  \"https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb\"\nsudo dpkg -i /tmp/session-manager-plugin.deb\n\n# RHEL / Amazon Linux (x86_64)\nsudo dnf install -y \\\n  \"https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm\"\n```\n\nVerify with `session-manager-plugin --version`. `doctor` also checks for it.\n\n## Configuration\n\nAll settings are optional. Unset values fall back to your current AWS context\n(`$AWS_PROFILE` / `$AWS_REGION`) and sensible defaults — so it works with no\nconfiguration at all.\n\n| Var                  | Default                                             | Meaning                                     |\n|----------------------|-----------------------------------------------------|---------------------------------------------|\n| `HERDR_SSM_PROFILES` | `default=$AWS_PROFILE` (or `default`)               | Space-separated `env=aws-profile` pairs     |\n| `HERDR_SSM_REGION`   | `$AWS_REGION` → `$AWS_DEFAULT_REGION` → `us-east-1` | AWS region to search/connect in             |\n| `HERDR_SSM_OSUSER`   | `auto`                                              | SSH login user; `auto` detects from the AMI |\n\n- **`HERDR_SSM_PROFILES`** — each `env` label is arbitrary. Any label named\n  exactly `prod` is treated as production and requires a typed `yes-prod`\n  confirmation before connecting. Example:\n  `HERDR_SSM_PROFILES=\"dev=my-dev-sso prod=my-prod-sso\"`.\n- **`HERDR_SSM_OSUSER=auto`** maps the instance's AMI to a login user\n  (Ubuntu → `ubuntu`, Amazon Linux → `ec2-user`, Debian → `admin`, …), falling\n  back to `ec2-user`. Set a fixed value to skip detection.\n\nSet these two ways:\n\n- **Local development:** copy `.env.example` to `.env` (git-ignored) and edit.\n- **Installed plugin:** `setup` writes a `config.env` into the plugin's config\n  dir; edit it there.\n\n## Security\n\nThe plugin runs as you, with your AWS credentials, and is not sandboxed. It uses\nephemeral keys, keeps no secrets in the repo, only calls read-only AWS APIs for\ndiscovery, and gates production. See **[SECURITY.md](SECURITY.md)** for the full\nthreat model and how to report a vulnerability.\n\n## Development\n\nPure Bash, no build step. The test suite uses a tiny in-repo harness (no `bats`)\nand stubs `aws`/`herdr` on `PATH`, so it needs no AWS access:\n\n```bash\nfor t in tests/*_test.sh; do bash \"$t\" || exit 1; done\n```\n\nCI runs the suite on Linux (bash 5) and macOS (bash 3.2, the compatibility floor)\nand lints with `shellcheck`. Releases are cut by pushing a `vX.Y.Z` tag matching\n`herdr-plugin.toml` (see `.github/workflows/`).\n\n## License\n\n[MIT](LICENSE) © herdr-aws-ssm contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaayanyosef%2Fherdr-aws-ssm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaayanyosef%2Fherdr-aws-ssm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaayanyosef%2Fherdr-aws-ssm/lists"}