Skip to content

fix(cli): prove the gateway peer before CLI internal-secret sends - #23283

Merged
bolichen97 merged 1 commit into
mainfrom
fix/secret-senders-prove-peer
Oct 23, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/secret-senders-prove-peer

Conversation

@JLargent42

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The CLI commands named in #21297, plus kirocrew doctor, check that the process on the other end of the connection is this install's gateway before they send the gateway's local/internal secret.

kirocrew token, logout, stop, restart and update already send the secret through a connection-bound peer check (_owner_verified_secret_urlopen, #20993). That value is also the gateway's X-Internal-Secret. kirocrew spawn (list, run and its poll), kirocrew artifact, kirocrew file-delivery approve, the kirocrew doctor adaptive-controller read, the app-lifecycle client and the pod's Windows token mint sent it without that check. The memory-forget client carried its own copy of the socket check.

Why it matters

The internal secret admits a caller to the gateway's internal API. A sender that writes it without checking its peer can deliver it to a different local process holding the port or socket path, for example after the gateway exits. The CLI's other secret sends already refuse in that case. Until now these did not.

Not a goal

  • Senders that use the same value but also run inside agent sessions: the agent-side MCP servers, the script-mode cron helper, cron_trigger (shared by kirocrew cron trigger and the agent's cron tool) and the code-review app. Their processes may not be able to run this check. That needs a decision first, tracked in security: decide the peer proof for agent-side and app senders of the internal secret #23270.
  • Changing what the gateway admits. Only the client side changes.

What changed (motivation → approach → change)

Several CLI senders of the secret wrote it to whatever answered the port or socket. The connection-bound check was used by only six of them.

Every CLI sender now uses one shared check, from cli_server_peer:

Sender Check
kirocrew spawn, kirocrew artifact, kirocrew file-delivery approve, the kirocrew doctor adaptive read _owner_verified_secret_urlopen (unix socket when present, loopback TCP otherwise; peer proven on the connection)
app-lifecycle client, memory-forget client owner-only socket with a verify_peer hook calling _connected_unix_peer_is_recorded_gateway
pod Windows token mint tcp_verified_urlopen whose hook compares _connected_tcp_peer_pid with the pod's attested gateway pid

_connected_tcp_peer_pid is the 4-tuple resolver from _connected_peer_verdict, now in its own function in src/kiro_crew/cli_server_peer.py so the pod check can use it too. The three hook-based checks emit the same SEL allowed/denied events as the shared proof. src/kiro_crew/cli_commands.py lists the two new cli_commands_gateway_api helpers in its facade manifest. When the peer is not proven, each command reports "gateway ownership not verified" (or its own refusal type) and sends nothing. It never says the gateway is "not running", and it never falls back to another path. The CLI spec's "Owner-verified secret sends" section now lists these senders in place of the old out-of-scope note.

Backwards compatibility

Compatible: a gateway this install started passes the same peer check kirocrew token already relies on. Only a peer that cannot be proven to be the recorded gateway is refused. One case changes: file-delivery approve on POSIX now sends over TCP when there is no socket file, with the same proof. Before, it reported the gateway as not running.

Removes nothing: no command, flag, route or record is removed. The patch seam the spawn and artifact tests used moves from loopback_urlopen to _gateway_send, which is test-only surface.

Tests

  • test/test_gateway_secret_senders_prove_peer.py (new): spawn list, run and poll, artifact and file-delivery approve each send through the peer proof with the secret attached. A refusal is reported, exits 1 and sends nothing. The app-lifecycle client checks its socket peer, sends neither request to a peer other than the recorded gateway, and audits both outcomes. All go red with the source reverted.
  • test/test_cli_doctor_adaptive_live.py::test_an_unproven_peer_receives_nothing_and_is_named (new): a real loopback listener that fails the peer proof receives no request, and doctor prints one line naming why. Red on main. The existing live-server cases stand the test server in as the proven gateway.
  • test/test_pod_ownership.py::test_mint_token_uses_attested_loopback_on_windows: the Windows mint goes over the verified TCP opener and audits allowed. A different or unresolvable peer gets PodError, is audited denied, and nothing is sent. Red on main.
  • test/test_memory_forget_cli.py: the existing rebound-socket, recycled-pid and missing-record cases now go through the shared check.
  • Existing spawn/artifact/app-lifecycle/file-delivery tests are retargeted to the new seams.

Determinism: the new and changed nodes passed 20× at -n0, 10× at -n 4 --dist loadgroup --max-worker-restart=2 alongside test_cli_gateway_client.py and test_apps_uninstall_backend_stop.py, and once in a seeded shuffle (seed 15163, 24 ids).

Manual verification

N/A — unit coverage sufficient: each sender's transport and refusal are exercised through its real code path with the socket/TCP opener stubbed. The proof itself is already covered by the #20993 suite.

Related Issues

Closes #21297

Sibling sweep

Swept: git grep -nE ""X-(Local|Internal)-Secret"\s*:" -- src/
Sibling: src/kiro_crew/cli_commands_gateway_api.py -- changed here
Sibling: src/kiro_crew/cli_server.py -- changed here
Sibling: src/kiro_crew/app_lifecycle_client.py -- changed here
Sibling: src/kiro_crew/memory_forget_client.py -- changed here
Sibling: src/kiro_crew/pod/runtime_client.py -- changed here
Sibling: src/kiro_crew/cli_server_requests.py -- not affected -- already uses _owner_verified_secret_urlopen
Sibling: src/kiro_crew/cli_server_restart.py -- not affected -- already uses _owner_verified_secret_urlopen
Sibling: src/kiro_crew/cli_server_stop.py -- not affected -- already uses _owner_verified_secret_urlopen
Sibling: src/kiro_crew/cli_server_update.py -- not affected -- already uses _owner_verified_secret_urlopen
Sibling: src/kiro_crew/mcp_core.py -- tracked in #23270
Sibling: src/kiro_crew/mcp_computer.py -- tracked in #23270
Sibling: src/kiro_crew/mcp_cron_list_render.py -- tracked in #23270
Sibling: src/kiro_crew/mcp_shared_policy.py -- tracked in #23270
Sibling: src/kiro_crew/mcp_tools/browser.py -- tracked in #23270
Sibling: src/kiro_crew/cron_script.py -- tracked in #23270
Sibling: src/kiro_crew/cron_trigger.py -- tracked in #23270
Sibling: src/kiro_crew/doctor_checks/workload.py -- changed here
Sibling: src/kiro_crew/apps/builtins/code_review_sage/sage_lib/review_driver.py -- tracked in #23270

Pattern harvest

Rule candidate: semgrep
Pattern: a request carrying an X-Local-Secret / X-Internal-Secret header passed to loopback_urlopen, or to unix_socket_urlopen without verify_peer, in a CLI module

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@JLargent42
JLargent42 requested review from a team and KiroCrewCaptain as code owners October 23, 2026 01:36
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 23, 2026
@JLargent42

Copy link
Copy Markdown
Contributor Author

Local pre-push review dispositions (hand-written charters; the brief extractor reported a parity failure, so this is approximate to CI).

  • GPT charter, High: kirocrew doctor adaptive read sent the secret unverified. fixed in 9de64f5 (routed through _owner_verified_secret_urlopen; new test test_an_unproven_peer_receives_nothing_and_is_named).
  • GPT/Opus charter, SEL audit for the hook-based checks: fixed in 9de64f5 (app_lifecycle, memory_forget, pod_token_mint emit allowed/denied).
  • Opus F1, spec over-claims coverage / cron_trigger: fixed in 9de64f5. Spec names cron_trigger as not yet covered; it serves the agent-side cron tool too, so it joins security: decide the peer proof for agent-side and app senders of the internal secret #23270.
  • Opus F2, docstrings claiming one shared proof: fixed in 9de64f5.
  • Opus F3, memory-forget pre-check message: fixed in 9de64f5 (names the mismatched-record case and the restart remedy).
  • Opus F4, one SEL allowed row per spawn poll: rebutted. _owner_verified_secret_urlopen audits every connection by design (every permission decision emits an event), and the logout/token paths already do the same; thinning the audit stream is a change to the shared helper, out of this PR's goal.

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 78ba0075b7f2c3dbb24e996f086941f2749712e6 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 78ba0075b7f2c3dbb24e996f086941f2749712e6 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns. CI's pod-boot-windows job mints pod token against a real Windows pod, so the "Manual verification: N/A" trigger does not apply.

Notes

[DESIGN-REVIEWED] 78ba007

Description read

[DESCRIPTION-READ] 95ec0a8fc4b579e9b367c9880c05c61f03252ab75cd9d238d67bf4c706ba0c74

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 78ba0075b7f2c3dbb24e996f086941f2749712e6 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. The one item that goes beyond the Goal is a declared side effect of reusing the shared proof.

Notes

  • Item 6 — rides along: "file-delivery approve on POSIX now sends over TCP when there is no socket file". This reverses the deleted pin "A gateway that is gone is reported as not running rather than retried on a port". The description says so, and the pin's reason (an unverified peer on the port) is now handled by the peer proof on that connection, so this is inventory, not a blocker.

What this change ships

Inventory (8 items) — 7 justified

Intent: CLI commands that send the gateway's internal secret refuse to send it unless the peer on the connection is this install's gateway (#21297). FIX.

  1. kirocrew spawn list/run/poll and artifact refuse an unproven peer, print "gateway ownership not verified" and exit 1 — justified
  2. kirocrew doctor adaptive read refuses an unproven peer and prints one line naming why — justified
  3. App-lifecycle mint and action check the socket peer before sending and audit both outcomes — justified
  4. Memory-forget uses the shared recorded-gateway check instead of its own copy, and now audits both outcomes — justified
  5. Pod Windows token mint checks the TCP 4-tuple peer against the attested pid — justified
  6. file-delivery approve on POSIX with no socket file now goes over TCP with the proof instead of "not running" — rides along
  7. TCP peer-pid resolver pulled out of _connected_peer_verdict into its own function, with 2 callers — justified
  8. CLI spec swaps the "out of scope" note for the list of covered senders — justified

[FIRST-PRINCIPLES-REVIEWED] 78ba007

Description read

[DESCRIPTION-READ] 03308d3e99fd6496f4eb3969014ceaef7d9eadeb2344a6c80224cf6923757d1b

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 78ba0075b7f2c3dbb24e996f086941f2749712e6 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 78ba007

Verdict parsed from the review's SHA-scoped output markers for commit 78ba0075b7f2c3dbb24e996f086941f2749712e6.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 78ba0075b7f2c3dbb24e996f086941f2749712e6: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 78ba0075b7f2c3dbb24e996f086941f2749712e6 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 78ba007

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 78ba0075b7f2c3dbb24e996f086941f2749712e6: <one-sentence reason>

@JLargent42
JLargent42 force-pushed the fix/secret-senders-prove-peer branch from 9de64f5 to 93029f8 Compare October 23, 2026 02:13
@JLargent42

Copy link
Copy Markdown
Contributor Author
  • span=ff60442df971 Patch the module clock binding, not worker-wide sleep

fixed in 93029f8: the test now replaces the _time binding in cli_commands with a stub namespace instead of patching time.sleep, so no other code in the worker sees the stub.
self-added: yes

@JLargent42

Copy link
Copy Markdown
Contributor Author

CI note for head 93029f8: Backend Tests (Windows) (5) failed in test_security_sensitive_paths.py::TestHomeDirTargetsCache::test_cache_dict_is_bounded (PathResolutionStalled on the runner home). That is the open flake #23251, with a fix in #23282; this PR does not touch that test or security/paths*. Recorded on #23251; the shard gets one re-run when the run completes. Backend Tests (Windows) (7) is #23259, fixed by #23264.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 23, 2026
@JLargent42
JLargent42 force-pushed the fix/secret-senders-prove-peer branch from 93029f8 to 78ba007 Compare October 23, 2026 06:56
@JLargent42

Copy link
Copy Markdown
Contributor Author

Rebased once onto main for the #23264 Windows fix.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 23, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) October 23, 2026 17:26

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed current head 78ba0075b7f2c3dbb24e996f086941f2749712e6 as Tier 2. Deep review found no blocking issue.

Security check: secret-bearing CLI sends now prove the connected peer before sending bytes. Peer mismatch and missing identity records fail closed. Auto-merge remains subject to branch protection.

@bolichen97
bolichen97 merged commit c43ddc9 into main Oct 23, 2026
110 checks passed
@bolichen97
bolichen97 deleted the fix/secret-senders-prove-peer branch October 23, 2026 17:27
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

security: prove the gateway peer for the remaining local/internal-secret senders (follow-up to #20993)

2 participants