Skip to content

fix(gateway): decide port occupancy without a process's self-asserted identity - #13883

Merged
iamwhatever merged 2 commits into
mainfrom
fix/port-owner-boundness-13826
Sep 27, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
fix/port-owner-boundness-13826

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

What is the problem?

The launcher asks two different questions of a local port, and both went through
one function. classifyPortOwner decides who holds the LISTEN socket, and on
POSIX it decides that from the holder's argv as reported by ps:
isKirocrewCommand matches the basename of argv0 against KIROCREW_EXE_NAMES,
or an -m kiro_crew token for the Python form. Any process running as the same
user can present either shape and be classified kirocrew:

exec -a kirocrew <some-server> --port 5476

Four of the launcher's nine probe sites do not ask that question at all. They
compare the result against "none" and nothing else, because what they are
waiting for is the port to clear or a service manager to rebind it. Occupancy is
already answered by the kernel's pid list, so those four sites paid for an argv
judgement, discarded its identity value, and still inherited its trust in what a
process claims to be.

Why this issue matters to the user

The verdict is an input to decisions that act on the user's machine: the
boot-time conflict resolver decides whether to adopt or evict the holder of the
port the gateway lives on, and the recovery strategy decides whether a wedged
gateway may be killed. The narrower reason this change exists is that the
occupancy sites were carrying that weakness for no benefit -- a spoofed argv
could not change their verdict, but the path to their verdict read a value only
the holder controls, and the next reader of that code has no way to tell the two
questions apart.

Reaching any of this needs local code execution as the same user, which bounds
the severity: such a process can already read ~/.kiro/crew/.local_secret
directly. This is a weak identity judgement in a security-relevant position, not
a remotely reachable hole.

How our fix solves it

The chain from symptom to root cause is that one function answered two
questions, so every caller inherited the weaker one's evidence. Splitting the
questions removes the weakness from the callers that never needed it:

  • probePortBinding in gateway-stop.js answers bound / free / unknown
    from getListenPids alone. It takes no command-line reader and no identity
    predicate, so no argv reaches its verdict -- not "argv is checked more
    strictly" but "argv is not on this path".
  • probeGatewayPortBinding in gateway-supervisor.js wires it to the
    platform's pid probe and nothing else.
  • The four occupancy sites now call it: waitForPortFree, the drain-completion
    test, and both waitForServiceRebind isPortBound callbacks (boot and
    liveness). Sentinels map value for value -- === "none" became === "free",
    !== "none" became !== "free" -- so the branch each site takes is
    unchanged.

The boundary, stated

This is a partial fix and the remainder is not hidden. Four sites still resolve
identity through argv, and they are the ones whose question is genuinely "who is
the peer":

Site What it decides Still argv-dependent
waitForPortFree is the port clear yet no
drain completion is the port clear yet no
waitForServiceRebind (boot) has anything rebound no
waitForServiceRebind (liveness) has anything rebound no
resolveGatewayConflict adopt the holder, or prompt for takeover yes
liveness rebind revalidation adopt the replacement holder yes
probePrimaryPortOwner -> IPC gate 3 admit a host-capability IPC call yes
token-prompt classifyAuthBlock which prompt text, and whether to retry yes

They cannot be closed here, and the reason is structural rather than a matter of
effort. At the moment each of them runs, the holder is a process this app did not
spawn -- that is the premise of the adoption path, where gatewayProcess is
null and spawnedExecutablePaths is empty. Nothing the app already holds names
that process, so the only two remedies are a stronger self-assertion read (a
POSIX executable-path resolution, which adds a capability and would have to
change a predicate shared by eviction sites) or binding identity to the
connection the request arrives on. The second is #13862, and it is blocked on a
channel property, not on this code: the channel is TCP loopback, and Node
exposes no peer-credential API -- the only peer-related member on a connected
socket is the private _getpeername. Even with a native addon, macOS
getpeereid returns uid without pid, so "is this my own child" is unanswerable
there, and Windows AF_UNIX has no peer-credential mechanism at all.

gatewayOwnership's reused-local and reused-service remain derived from the
argv predicate through classifyAdoptedGateway, unchanged by this PR.

One behaviour change worth naming

On those four sites a ps failure used to propagate: classifyPortOwner calls
getCommand without a try, so a rejection escaped waitForPortFree to its
caller. The new path never runs ps, so that failure mode is gone from them. It
is a strict reduction in failure modes, not a suppressed error -- an unreadable
pid list still returns unknown, and waitForPortFree still falls back to its
HTTP probe on unknown exactly as before.

What tests we did

A new pin, website/electron/test/port-owner-self-asserted-identity.test.js. It
LISTS the decisions rather than discovering them, and guards the list so nothing
can be missing from it quietly. Each entry is the decision's exact source text and
the number of times it appears, grouped into the occupancy decisions, the identity
ones, and the sentinel uses that are not about a port at all.

Two guards make the list safe to trust. The first scans probe CALLS: a verdict can
only enter the file by calling a probe, and a call has exactly one syntax, so no
comparison shape evades it. The second scans sentinel string literals. Anything
either net finds that no list claims is a FAILURE naming its line, so an
unclassifiable use is denied rather than allowed. It also keeps both probes'
dependency sets asserted structurally and pins classifyPortOwner's refusal to
guess when it cannot look.

An earlier revision of this pin parsed the source for comparison shapes instead.
That version read two shapes and passed a third in silence, which is a pin that
fails open; it is gone, and the mutation table below is the evidence that its
replacement does not have that hole.

Unknown-shape proof, a fifth decision added in five syntaxes the pin is not
written to understand, each proven applied by git hash-object:

Fifth decision written as Applied Pin
control, unmutated 37bfac74 GREEN
a switch on the identity probe 37bfac74 -> 7e473fb7 RED
["none","unknown"].includes(...) 37bfac74 -> 8ee16135 RED
a ternary chain 37bfac74 -> 98592e34 RED
an object-map lookup on bare keys 37bfac74 -> 6172da30 RED
a Map.get lookup 37bfac74 -> 4491f11e RED

The last two are why the call scan exists. A guard that read only string literals
passed the object map, because bare keys are not literals. The call scan holds all
five.

Regression matrix on the listed sites, same hash discipline:

Mutation Applied Pin
waitForPortFree to the identity probe 37bfac74 -> 07dc9cfe RED
boot isPortBound to the identity probe 37bfac74 -> 7e6639a9 RED
drain completion to the identity probe 37bfac74 -> 66f0988a RED
liveness isPortBound to the identity probe 37bfac74 -> df17f946 RED
one occupancy comparison deleted 37bfac74 -> 6d9ea5a1 RED
probePortBinding's body consults getCommand 5807a08e -> 6fe6926a RED
the wrapper injects psCommand 37bfac74 -> 21657629 RED

Existing suites that own the changed files: gateway-stop.test.js,
gateway-supervisor.test.js, gateway-recovery.test.js -- 110 passing with 1
pre-existing skip on the merge base, 117 with the same single skip here.

The tradeoff this pin accepts

A list of exact source strings is brittle to benign rewording: reformat a listed
line and the pin fails until someone updates the entry. That is deliberate, and it
is the price of failing closed -- the alternative is a parser that tolerates
rewording and, as the earlier revision showed, tolerates a new decision it cannot
read. The cost is a small edit with a forced reading of what the site now decides.

Writing the lists out also produced a finding of its own. Two identity sites were
never mentioned by the parsing version: the remote-host short-circuits at boot and
at the token prompt, which substitute foreign and never probe. They are now
named.

The two advisory reviews, and what came of them

The reviews on an earlier head disagreed from opposite ends, and both were right
about the same thing. Design Review said the pin failed open because its scanner
read only two comparison shapes. First Principles said the parsing engine was
machinery for future sites that did not exist and adjudicated four known
comparisons today. Together: the engine paid for generality and did not deliver
it, because a third shape slipped through silently.

The first attempt at Design Review's finding bolted a fail-closed branch onto the
engine, which kept the machinery First Principles objected to in order to patch a
hole an explicit list does not have. That was the wrong shape and was replaced by
what is described above.

Any other suggestions on the work

One remaining site has a remedy that needs a scope decision rather than new
machinery, so it is called out rather than taken unilaterally. IPC gate 3
accepts kirocrew or service, and when gatewayOwnership === "spawned" the
shell holds gatewayProcess.pid -- so the gate could require that pid to be
among the port's listeners and consult no argv. That does not cover the adopted
case: reused-local and reused-service were themselves derived from the argv
verdict, so the gate would still admit a spoofed adoption. Closing it
structurally therefore means deciding that an adopted gateway is not eligible
for host-capability IPC, which narrows a capability real users have today.

Pattern harvest

Rule candidate: semgrep

Pattern: a name taken from a process's own command line -- ps -o command=,
argv[0], or the Windows command-line properties -- used as the evidence for a
trust or authorisation decision. Anyone who can exec chooses that value, so
matching it against a set of expected names is an identity check the checked
party controls. This is a class, not a one-off: the shape recurs wherever a
process name gates behaviour, and the four sites fixed here were not even the
ones that wanted the identity -- they inherited the weakness by sharing a
function with the sites that did.

A rule should flag at the READ rather than at each decision, because the read is
where the value stops being trustworthy and the decision can be arbitrarily far
away. Concretely: a command-line string obtained from a process inspection
reaching a membership test against a name set, which is exactly
isKirocrewCommand matching KIROCREW_EXE_NAMES against a basename from ps.
Two qualifiers keep it honest. A command line used for a LOG line or a human
message is fine and must not be flagged. And a path-bound comparison is a
different thing: the Windows branch here canonicalises an absolute executable
path against a trusted set, which is weaker than a kernel-supplied credential
but is not the forgeable-name pattern.

Fixes #13826

… identity

The launcher asks two different questions of a local port: whether anything
holds it, and who holds it. Both went through classifyPortOwner, whose POSIX
identity judgement rests on the holder's argv as reported by ps -- which the
holder's own owner chooses. Four of the launcher's probe sites compare the
result against "none" and nothing else, so they paid for an argv judgement and
discarded it, while still inheriting its trust in what a process claims to be.

Add probePortBinding, which answers bound/free/unknown from the kernel's pid
list alone, and route those four sites to it. Their verdicts are now
structurally unable to depend on argv: nothing on that path reads a command
line. The sites that genuinely need the holder's identity are unchanged and
still behind the same weakness.

Pin enumerates the sites from source by the shape of each comparison rather
than by a list, resolving every sentinel comparison back to the probe that
produced it, so reintroducing the identity probe at an occupancy decision
fails it.
@chenmingwei23
chenmingwei23 requested review from a team and dwu96 September 25, 2026 17:11
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 5583d77474f0349d4775932a515353bc95a2b4d6 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check. This diff changes only Electron launcher internals and a test — no user-visible control, string, or state is added or changed, so no screenshot evidence is required.

[UX-REVIEWED] 5583d77

@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 Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 5583d77474f0349d4775932a515353bc95a2b4d6 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5583d77

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

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 5583d77474f0349d4775932a515353bc95a2b4d6 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 5583d77

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 5583d77474f0349d4775932a515353bc95a2b4d6 — 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/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The pin's second net byte-pins five supervisor lines unrelated to any port decision, and none of the PR's own 12 proven mutants needs that net.

Not justified as shipped

  • Item 4 — oversized: the "no sentinel literal is unclaimed" net forces NON_PORT_SITES to pin lines like req.on("error", () => resolve("unknown")); byte-exact with counts, so any rewording of five non-port lines in an ~1800-line file reds this pin forever; by the description's own tables, all 12 hash-proven mutants (5 evasion syntaxes + 7 regressions) are already caught by the call-scan net, the exact-count site list, or the dependency-set assertions — I counted 0 that require the literal net.
    Subtraction: delete the sentinel-literal test and the NON_PORT_SITES list from port-owner-self-asserted-identity.test.js, keeping the call-scan net, the two site lists, and the body/wiring assertions.
    Clears when: that deletion is made, or one hash-proven mutant is shown that only the sentinel-literal net turns red (e.g. a stored verdict compared against a sentinel away from any probe call).

What this change ships

Inventory (4 items) — 3 justified

Intent: make the launcher's "is the port occupied" waits independent of the holder's self-reported command line — a FIX (declared partial; the four remaining argv sites match my grep: 4 callers of probeGatewayPortOwner remain).

  1. The four port waits (port-clear, drain completion, boot and liveness rebind) now decide from the kernel pid list, never argv — justified
  2. A ps failure no longer aborts those waits (getCommand at gateway-stop.js:583 is un-tried) — justified
  3. New probePortBinding helper plus supervisor wrapper beside classifyPortOwner — justified
  4. New source-text pin failing on any change to 15 listed supervisor lines or any unclaimed sentinel literal — oversized: the literal net's whole-file tax on non-port lines has no demonstrated catch (0 of 12 mutants)

[FIRST-PRINCIPLES-REVIEWED] 5583d77

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 5583d77474f0349d4775932a515353bc95a2b4d6 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5583d77

Verdict parsed from the review's SHA-scoped output markers for commit 5583d77474f0349d4775932a515353bc95a2b4d6.

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

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 25, 2026
…ails closed

The pin previously discovered its own subject by parsing the supervisor for
comparison shapes. That carried the cost of generality without the benefit: the
scanner read two shapes, so a decision written as a switch, a ternary chain, an
includes() over a sentinel array or an object-map lookup on bare keys was passed
in silence. A pin that silently passes what it cannot classify fails open.

List the decisions instead, each as its exact source text and the number of times
it appears, and guard the list with two nets. The first scans probe CALLS: a
verdict can only enter the file through a call, and a call has one syntax, so no
comparison shape can evade it. The second scans sentinel string literals. A site
either net finds that no list claims is a FAILURE naming its line, so an
unclassifiable use is denied rather than allowed, and a fifth decision cannot
join the file without someone deciding which list it belongs to.

Writing the lists out also named two identity sites the scanner never mentioned:
the remote-host short-circuits that substitute foreign without probing at all, at
boot and at the token prompt.
@chenmingwei23
chenmingwei23 force-pushed the fix/port-owner-boundness-13826 branch from a2ccb97 to 5583d77 Compare September 25, 2026 19:16
@chenmingwei23

chenmingwei23 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author

First Principles asked, on a2ccb971558b81835259d9d91b79b2bf9841d14a, that the
solo-spawn-gate RFC hunks be verified byte-identical to main's #13705. Checked, and
the answer is stronger than byte-identical: those hunks are not in this PR.

GitHub's own file list for this PR returns three files and nothing else:

website/electron/gateway-stop.js                                 43 +   0 -
website/electron/gateway-supervisor.js                           19 +   6 -
website/electron/test/port-owner-self-asserted-identity.test.js 313 +   0 -

git diff --name-only $(git merge-base origin/main HEAD) HEAD -- docs/ is empty, so
the branch touches no documentation at all.

What produced the appearance: rfc-solo-spawn-gate.md reads status: superseded at
this branch's merge base c6b1ebf24 and status: in-progress on current main
07a05a2b1, because main's #13705 flipped it after this branch was cut. A diff taken
against a base that has since moved -- or against the merge ref rather than the PR's
own change -- renders main's newer commits as hunks belonging to the branch. The same
artifact showed 75 changed files here earlier tonight until the diff was re-taken
against the merge base.

No action taken, because there is nothing to declare or revert. Recorded so the
request is not left open on the record.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 25, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Sep 27, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Maintainer sweep (2026-09-27, on behalf of @bolichen97): readiness and the required check are green on 5583d77, but this head is 239 commits behind main and website/electron/gateway-supervisor.js was changed on main (#13268, #13207) after this head's CI ran, so the green run does not cover the tree it would land on. Please rebase onto current main and let CI re-run; I will approve on the new head.

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: POSIX port-owner classification trusts argv0, so a same-user process can present itself as ours

3 participants