Repository navigation
fix(gateway): decide port occupancy without a process's self-asserted identity - #13883
Conversation
… 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.
UX Review (Fable 5) — ✅ PASSUX-level review of 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 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 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: |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] 5583d77 |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of 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
What this change shipsInventory (4 items) — 3 justifiedIntent: 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
[FIRST-PRINCIPLES-REVIEWED] 5583d77 |
Opus 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: |
…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.
a2ccb97 to
5583d77
Compare
|
First Principles asked, on GitHub's own file list for this PR returns three files and nothing else:
What produced the appearance: No action taken, because there is nothing to declare or revert. Recorded so the |
|
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 |
What is the problem?
The launcher asks two different questions of a local port, and both went through
one function.
classifyPortOwnerdecides who holds the LISTEN socket, and onPOSIX it decides that from the holder's argv as reported by
ps:isKirocrewCommandmatches the basename of argv0 againstKIROCREW_EXE_NAMES,or an
-m kiro_crewtoken for the Python form. Any process running as the sameuser can present either shape and be classified
kirocrew: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 arewaiting 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_secretdirectly. 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:
probePortBindingingateway-stop.jsanswersbound/free/unknownfrom
getListenPidsalone. It takes no command-line reader and no identitypredicate, so no argv reaches its verdict -- not "argv is checked more
strictly" but "argv is not on this path".
probeGatewayPortBindingingateway-supervisor.jswires it to theplatform's pid probe and nothing else.
waitForPortFree, the drain-completiontest, and both
waitForServiceRebindisPortBoundcallbacks (boot andliveness). Sentinels map value for value --
=== "none"became=== "free",!== "none"became!== "free"-- so the branch each site takes isunchanged.
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":
waitForPortFreewaitForServiceRebind(boot)waitForServiceRebind(liveness)resolveGatewayConflictprobePrimaryPortOwner-> IPC gate 3classifyAuthBlockThey 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
gatewayProcessisnull and
spawnedExecutablePathsis empty. Nothing the app already holds namesthat 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, macOSgetpeereidreturns uid without pid, so "is this my own child" is unanswerablethere, and Windows AF_UNIX has no peer-credential mechanism at all.
gatewayOwnership'sreused-localandreused-serviceremain derived from theargv predicate through
classifyAdoptedGateway, unchanged by this PR.One behaviour change worth naming
On those four sites a
psfailure used to propagate:classifyPortOwnercallsgetCommandwithout atry, so a rejection escapedwaitForPortFreeto itscaller. The new path never runs
ps, so that failure mode is gone from them. Itis a strict reduction in failure modes, not a suppressed error -- an unreadable
pid list still returns
unknown, andwaitForPortFreestill falls back to itsHTTP probe on
unknownexactly as before.What tests we did
A new pin,
website/electron/test/port-owner-self-asserted-identity.test.js. ItLISTS 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 toguess 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:37bfac74switchon the identity probe37bfac74->7e473fb7["none","unknown"].includes(...)37bfac74->8ee1613537bfac74->98592e3437bfac74->6172da30Map.getlookup37bfac74->4491f11eThe 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:
waitForPortFreeto the identity probe37bfac74->07dc9cfeisPortBoundto the identity probe37bfac74->7e6639a937bfac74->66f0988aisPortBoundto the identity probe37bfac74->df17f94637bfac74->6d9ea5a1probePortBinding's body consultsgetCommand5807a08e->6fe6926apsCommand37bfac74->21657629Existing suites that own the changed files:
gateway-stop.test.js,gateway-supervisor.test.js,gateway-recovery.test.js-- 110 passing with 1pre-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
foreignand never probe. They are nownamed.
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
kirocreworservice, and whengatewayOwnership === "spawned"theshell holds
gatewayProcess.pid-- so the gate could require that pid to beamong the port's listeners and consult no argv. That does not cover the adopted
case:
reused-localandreused-servicewere themselves derived from the argvverdict, 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 atrust or authorisation decision. Anyone who can
execchooses that value, somatching 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
isKirocrewCommandmatchingKIROCREW_EXE_NAMESagainst a basename fromps.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