Repository navigation
feat(shared-crew): share a Crew over AWS SSM with an invite-only link - #29923
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: giving SSM its own port is the only signal a header-less loopback forward has, and the guest never enters the token flow. Notes
[DESIGN-REVIEWED] 9f45f7b Description read[DESCRIPTION-READ] 049babf7cf5aa6934ea42374d17f76424c05950bdf47e5c5c7e43d1170a859cb That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks. Fourteen screenshots cover every new control and state, and the blind reader read each primary control (AWS SSM tab, "Make link", "Copy SSM invite", the Advanced switch) correctly. Notes
[UX-REVIEWED] 9f45f7b Description read[DESCRIPTION-READ] ca203b46414a01165c839f136f96d3c356585a4ef8eeafde62f4d8bd049e1df0 That sha256 names everything this verdict read: the PR description, plus the 17 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS One undeclared relabel of the existing Tailscale copy button; it is a note, not a blocker. Every other item is new SSM surface behind a flag that is off by default, or a refusal for SSM guests. Notes
What this change shipsInventory (10 items) — 9 justifiedIntent: an owner shares a Crew on EC2 with named, revocable teammates over SSM port forwarding instead of handing out the owner token. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 9f45f7b Description read[DESCRIPTION-READ] e0d2f6832f988c66de42cf92abb5fbb97c0f72c8968908db30338f6b997735cc That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
99cc6e4 to
49f6a75
Compare
84ea409 to
d6e324e
Compare
d6e324e to
080ffb1
Compare
0fc013d to
4eaa100
Compare
7edb9fd to
45fe6bd
Compare
45fe6bd to
5890817
Compare
5890817 to
c62c1c0
Compare
c62c1c0 to
5da39f5
Compare
5da39f5 to
9a3b09a
Compare
| # withholds a Strict cookie from the redirected request of a cross-site navigation, so | ||
| # the page it lands on would refuse the guest. Lax still holds back the cookie from | ||
| # cross-site POSTs and subresources; the origin allowlist covers writes as before. | ||
| response.set_cookie(cookie_name(request), credential, httponly=True, samesite="Lax", path="/") |
| # withholds a Strict cookie from the redirected request of a cross-site navigation, so | ||
| # the page it lands on would refuse the guest. Lax still holds back the cookie from | ||
| # cross-site POSTs and subresources; the origin allowlist covers writes as before. | ||
| response.set_cookie(cookie_name(request), credential, httponly=True, samesite="Lax", path="/") |
Disposition: UX lane, "Let teammates join over AWS SSM" switch (Settings > Advanced)Owner ruling (Bolin), recorded here by the agent working this PR on Bolin's instruction. The current design of the switch stands. No further change to it on this PR. Why: across four heads the UX lane asked for four different things about this one switch, and the later asks contradict the earlier ones.
Head What the switch does today: it reuses the existing restart pattern. If the UX lane blocks only on this switch at the current head, the next comment is an |
buluoray
left a comment
There was a problem hiding this comment.
🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:
Verdict: NEEDS_OWNER. The code does what it says and I found no defect. Two security-design choices still need a maintainer decision, and nothing records one: issue #29552 is labelled parked, and docs/decisions holds no SSM entry.
Owner question, in two sentences: an enterprise that pins capabilities.tailnet_origin off has no matching switch to forbid SSM sharing, because SsmGate starts whenever ssm is on and no dashboard_origins policy refuses its two loopback origins. Should SSM sharing be behind a governance capability before it ships, and is it acceptable that a permanent, reusable bearer link with no expiry, which anyone holding it can open from any number of browsers, is the only thing standing in for a membership boundary?
What it does for users: an owner running a Crew on EC2 can share it with named, revocable teammates who reach it through an AWS Session Manager port forward, without handing out the owner's dashboard credential.
What I verified in source at this head
- Who can mint or revoke an invite. All three routes in shared_crew/routes_ssm.py go through routes_invites._owner_refusal. They answer 404 without the preview and 404 while governance withdraws the SSM origins (routes_ssm.py:85-97). An SSM guest is subject ssm:, so is_owner_dashboard_request (source_providers.py:880-889) can never match the owner_id or the local-app and local-startup subjects.
- How an invite is bound. The credential is <12-hex id>.<32 random URL-safe bytes>. Only a SHA-256 of the secret is stored, under .vault/shared-crew-ssm, owner-only (ssm_invites.py:93-110). The compare runs in constant time and does dummy work on a miss (ssm_invites.py:126-140). An invite can be used more than once and has no expiry. The PR states both, and they are a design choice, not a bug. Revoke deletes the record. The next request is refused, an open response is closed by the re-verify watcher within 15 s (ssm_gate.py:174-196), and the revoke route closes the person's dashboard sockets (routes_ssm.py:139-170). The store holds at most 64 invites.
- What a guest can reach. ssm_gate.admit (ssm_gate.py:199-243) sets the same request keys as the tailnet direct listener (dashboard auth middleware, lines 316-321), plus the SSM marker. A guest therefore gets the same collaborator reach a Tailscale direct guest gets today. It also gets an empty Apps list (apps/routes_listing.py), it is never direct-local (origin.py:134), and it cannot mint a bearer link (_shared_access.py:218-224). Strict internal paths and any X-Internal-Secret header are refused before the invite is checked. A dashboard credential, an app credential or the internal secret on this port is ignored, because the hook runs ahead of the normal credential flow (dashboard auth middleware, lines 327-339).
- Off by default and behind the preview.
ssmdefaults to false, and only a literal true turns it on (sections_shared_crew.py, SHARED_CREW_EXPOSURE_FLAGS). The gate ref is created only when the Shared Crew preview is on (server.py:1086-1093). - Bind address. The listener binds only 127.0.0.1:<ssm_port> and refuses the dashboard port (ssm_gate.py:268-308). SsmGate.owns keys on the local sockname, which must be loopback and on the SSM port (ssm_gate.py:69-86), so the request itself cannot claim to be SSM. The canonical-host redirect is skipped on this port, so the invite query never follows a redirect to another loopback family (security_middleware.py:572-594).
- Where the credential can end up. The invite reaches the gateway once as ?ssm_invite=. It is stored in an HttpOnly, SameSite=Lax cookie, and the browser is sent to a 302 without the query, with Referrer-Policy: no-referrer and no-store. The auth audit records request.path without the query (the auth audit helper, _log_auth). The aiohttp access logger runs at INFO, under the root WARNING level set in cli_logging.py, so the request line never reaches gateway.log. The credential stays in the invitee's browser history, and because cookies are not port-scoped, the cookie is sent to every localhost port on the invitee's machine. The PR states both.
Tests and mutations
- 219 passed across test_shared_crew_ssm.py, test_ssm_loopback_trust_sites.py, test_governance_remote_access_keys.py, test_shared_crew_access.py and test_shared_crew_advanced_settings_write.py. The full suite was not run.
- Frontend: 137 passed in SsmInvite.test.tsx, TailscaleInvites.test.tsx and PeoplePanel.test.tsx.
- Mutation 1, the invite check: I removed the secret-digest compare in ssm_invites.verify, so a known id with any secret is accepted. Two tests went red: test_an_invite_verifies_until_it_is_revoked_and_stores_only_a_hash and test_an_invite_reads_joined_once_someone_opens_it_and_names_their_person.
- Mutation 2, the direct-local refusal: I dropped is_ssm_request from origin.is_direct_local_request. Two tests went red: test_an_ssm_request_is_never_direct_local[guest-mark] and test_an_ssm_request_is_never_direct_local[admitted-mark].
- CI on this head: 85 checks succeeded, 11 were skipped and none failed. PR Readiness and both CodeBuild statuses are success. The merge-tree check against main is clean. The Design, UX, First Principles, Opus and GPT lanes all PASS on this head.
- CodeQL flags "cookie built from user input" at ssm_gate.py:168. The cookie value is set only after it matches the issued shape and verifies against a live invite. The cookie name takes only digits from the Host port. I judge it a false positive.
What I did not run: a live Session Manager forward, IMDSv2 on a real EC2 host, and the gateway start path (start_after_bind). The PR says the same.
Follow-ups, non-blocking
- Revoking an SSM person does not yet pause the schedules that person created. Their schedules keep running on this Crew until #29609 lands and api_revoke calls pause_revoked_schedules.
- governance.md is unchanged. If SSM stays outside a capability pin, governance.md should say plainly that capabilities.tailnet_origin does not cover SSM and that dashboard_origins is the only ceiling.
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved by Crew Captain for the on-call, with a maintainer design sign-off for the linked issue. Review lanes clean on this head.
Problem / Motivation
Goal: An owner can share a Crew that runs on an AWS machine with teammates who reach it through AWS Systems Manager (SSM), each one named and revocable, with the same parts Shared Crew gives Tailscale.
Today only Tailscale can name a teammate. An SSM Session Manager port forward reaches the gateway as a plain loopback connection with no forwarding header, which is exactly what the owner's own browser looks like, and the guide says such teammates are "credited to whoever runs the Crew".
Why it matters
Teams that run a Crew on EC2 already have SSM access control and often cannot use Tailscale. Without this, sharing there means handing out the owner's dashboard token, which makes every teammate the owner.
Not a goal
--slack-onlyAPI server.What changed (motivation → approach → change)
Merge order: #29592 (People single invite) has merged, so this PR is the SSM commit alone on
main. It depends on #29609 (guest permissions) for one follow-up: once that lands,routes_ssm.api_revokecalls itspause_revoked_schedules(principal_ids)so removing a person pauses the schedules they created (the helper is not copied here). The remove-confirmation copy is People's shared key. Issue: #29552.Approach. A forwarded connection cannot be told from the owner's by its address, so the port says it: with
dashboard.shared_crew.ssmon, the gateway also binds127.0.0.1:<ssm_port>(default 5477). Every request on that port is decided indashboard/ssm_gate.pyand never enters the token flow. Only a Crew invite opens it; the owner's token, app tokens and the internal secret mean nothing there, so a forwarded connection is never the owner.Parity with Tailscale:
ssmsetup path andGET /api/shared-crew/ssm: state, reason, node id, regionssmandssm_portin People > Advanced, off by defaultaws ssm start-sessionargument list plushttp://localhost:<port>/?ssm_invite=…Provenance.SSM_INVITE)RevokeControl: "Remove" on every non-owner row, joined or not, Tailscale or SSM; open connections close within 15 sshared-crew.md, the remote-access guide, security, config and token-auth specsChange. The node id comes from
KIROCREW_SSM_TARGETor IMDSv2; nothing reads or writes AWS configuration and no process is started. Invites live in.vault/shared-crew-ssm/as a SHA-256 of the secret plus an alias, with ajoinedflag set on first use.origin.is_direct_local_requestanswers False for an SSM request,_caller_boundslends it no bearer-link lifetime, andtest_ssm_loopback_trust_sites.pylists every peer-address trust site so a new one must be classified. In the dashboard, SSM is a tab in the Invite dialog, shown only when Tailscale invites are on too; unopened invites are Not joined rows and a joined person's row carries the Remove control.Files:
config-baseline.json(regenerated),src/kiro_crew/change_card_catalog_kinds.py,src/kiro_crew/config/sections_shared_crew.py,src/kiro_crew/shared_crew/access.py,src/kiro_crew/shared_crew/access_set.py,src/kiro_crew/shared_crew/collaborators.py,src/kiro_crew/shared_crew/contracts.py,src/kiro_crew/shared_crew/identity.py,src/kiro_crew/shared_crew/routes_ssm.py,src/kiro_crew/shared_crew/ssm.py,src/kiro_crew/shared_crew/ssm_invites.py,website/src/api/client/sharedCrew.ts,website/src/api/sharedCrew.ts,website/src/api/sharedCrewSsm.ts,website/src/api/sharedCrewUi.ts,website/src/i18n/en.context.json,website/src/test/ApiClient.refactor.surface.test.ts. The People commit (#29592) is the other half of the diff:src/kiro_crew/shared_crew/routes_invites.py,src/kiro_crew/shared_crew/tailscale_invites.py,website/src/api/sharedCrewInvites.ts,website/src/api/sharedCrewUi.test.ts,website/src/components/SharedCrewReadFailures.test.tsx,website/src/i18n/sharedCrewHonestCopy.test.ts,website/src/test/settingsCoverage.test.ts.Judgment calls. A separate port rather than a header or token check, because loopback gives nothing to check.
KIROCREW_SSM_TARGETfor hosts without IMDS, instead of another config field. The confirm text of Remove is the People wording for both transports. The owner-side AWS CLI check was dropped from the UI: the teammate's machine needs the tools, so the invite message ends with the guide link.Accepted trade-offs. No expiry: a link is permanent until removed, one link is one identity, and a removal takes up to 15 s to close an open connection. The
mc_ssmcookie is host-scoped, so a browser sends it to anylocalhostport (cookies are not port-scoped); it is the invite, so treat the link like a password. A teammate with a Session Manager shell document already has host access; the guide tells owners to scope IAM to a custom document with a fixedportNumber.Backwards compatibility
Compatible: everything is off by default (
ssmreads false unless a literaltrue); the only change to existing behaviour is thatorigin.is_direct_local_requestand the bearer-link mint now refuse a request the SSM listener admitted, which no existing path produces.Removes nothing: the guide sentence that credited SSM teammates to the owner described a path that still needs a dashboard token; it now points at the SSM link.
Tests
Proof: not provable -- other: a new transport with no fix to revert; the gate test is mutation-checked instead (below).
test/test_shared_crew_ssm.pyruns the real token middleware on two real loopback sites. The owner's token, cookie, internal secret and both together on the SSM port are refused or never the owner, while the same token on the dashboard port is the owner (mutation-checked: removing the gate hook fails 7 tests). It also covers invites, revoke while a request is open,joined, and the first-share 409.test/test_ssm_loopback_trust_sites.pypins the SSM refusal in every peer-address check and the bearer-mint refusal.website/src/pages/settings/SsmInvite.test.tsxcovers tabs, status reasons, the first-share dialog, rows, the same Remove wording, and no loss of a link on a late read or a tab switch.-n0, 10 at-n 4 --dist loadgroupwith sibling files, and one shuffled order (seed 7712), all green.gen:ui, tsc, eslint, i18n check and render pass. Not green locally and not from this change:person_remove*Hindi register (from fix(shared-crew): one invite entry and one People row per person #29592),test:electron(environment),navLabelstimeout (also on fix(shared-crew): one invite entry and one People row per person #29592), and the scoped-backend runner timed out, so related backend tests were run by node set instead (7,500 passed).Manual verification
The gateway-start path (
start_after_bind) and a live Session Manager forward were not run: this host is not an SSM node. Everything on the gate is exercised with real sockets in tests.ssm.read_imds, IMDSv2 token then instance id and region) is covered by fakes only. It fails closed tono_target, andKIROCREW_SSM_TARGET/KIROCREW_SSM_REGIONbypass it. One run on EC2 with thessmswitch on and a teammate'saws ssm start-sessionis the remaining check.The one change outside the SSM path: the Tailscale "Copy invite message" button now reads "Copy Tailscale invite" (copy icon), because the SSM tab has its own "Copy SSM invite" and the two copy different text; the owner asked for the two to be named by transport.
Screenshots / video
Captured from the current head with the shared-crew fixtures stubbed (
temp-screenshots/ssm/capture.mjs).Setup page before anything is turned on: Tailscale, AWS SSM ("Teammates in your AWS account. Needs SSM on this machine." and its guide link) and Kiro login:
People, Advanced expanded: the switch is named for its result, "Let teammates join over AWS SSM", off:
Same switch on: the existing "changes need a restart" pill shows beside it and the help line says Invite then has an AWS SSM tab:
Invite dialog, Tailscale tab:
Invite dialog, AWS SSM tab:
First link: the one-time Share this Crew? confirmation, worded for SSM:
A link just made: shown once, with one copy action that holds the link and the port-forward command (Copy SSM invite):
A link just made, dark:
People list: a joined SSM person (Dana, with Remove) and an unopened SSM invite under Invites (Lee); the share card's button reads Copy Tailscale invite:
Same list, dark:
Remove on a joined person:
Remove on an unopened SSM invite:
No SSM node found for this machine:
The SSM status read fails: a notice with Try again on the People page, instead of the SSM controls vanishing:
Related Issues
Closes #29552
Pattern harvest
Not generalizable: this adds a transport; the one reusable lesson, that a loopback peer address is not proof of the owner, is pinned by
test_ssm_loopback_trust_sites.py.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.