Repository navigation
fix: name the refused file in the flagged-file delivery audit trail - #13311
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify no third-party app read [DESIGN-REVIEWED] 7b8310c |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The allowed-read audit row rides along with no provenance: the fix is complete without it, and it writes to an append-only log forever. Not justified as shipped
What this change shipsInventory (10 items) — 7 justifiedIntent: let the owner see which file the credential scanner refused to deliver — a FIX.
[FIRST-PRINCIPLES-REVIEWED] 7b8310c |
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: |
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: |
UX Review (Fable 5) — ⏭️ skippedRevision |
354d440 to
93242bd
Compare
3c84711 to
a06fa87
Compare
9010716 to
bd8863f
Compare
The credential scanner refuses to deliver a flagged file and records that a refusal happened, but not WHICH file it held back, so an owner reviewing the security log can see what left under a grant and not what was stopped. Every grantable leg now names the refused file in that log through one helper, and the shared channel-upload gate names it in the tool-invocation entry it already writes, since its structural guarantee is that it references no consent state. The download leg's gate has two conjuncts: it honours a grant, but only for the owner. Its entry now says which one refused and names the requester when another authenticated principal reached for a file the owner's grant covers, because audit_decision stamps every refusal "gateway", which is the process and not who asked. The name composes last: audit_decision clips the detail at 200 characters and the name is the only field with no length bound, so composed name-first a long name pushes the reason and the caller off the end. GET /api/sel/events is now owner-only, and that is the premise of the change rather than scope growth: the endpoint ran no identity check, so writing refused filenames into the log would have handed one principal another's audit trail, and the same hole was already serving main's delivered entries. The denial goes through _owner_denial_response, the tail every other owner gate shares, so a session signed before an owner was configured gets 401 stale_session_reauth instead of a generic 403 -- that caller is the owner, and re-signing in is the remedy. Fixes #9091
bd8863f to
7b8310c
Compare
…irodotdev#13311) The credential scanner refuses to deliver a flagged file and records that a refusal happened, but not WHICH file it held back, so an owner reviewing the security log can see what left under a grant and not what was stopped. Every grantable leg now names the refused file in that log through one helper, and the shared channel-upload gate names it in the tool-invocation entry it already writes, since its structural guarantee is that it references no consent state. The download leg's gate has two conjuncts: it honours a grant, but only for the owner. Its entry now says which one refused and names the requester when another authenticated principal reached for a file the owner's grant covers, because audit_decision stamps every refusal "gateway", which is the process and not who asked. The name composes last: audit_decision clips the detail at 200 characters and the name is the only field with no length bound, so composed name-first a long name pushes the reason and the caller off the end. GET /api/sel/events is now owner-only, and that is the premise of the change rather than scope growth: the endpoint ran no identity check, so writing refused filenames into the log would have handed one principal another's audit trail, and the same hole was already serving main's delivered entries. The denial goes through _owner_denial_response, the tail every other owner gate shares, so a session signed before an owner was configured gets 401 stale_session_reauth instead of a generic 403 -- that caller is the owner, and re-signing in is the remedy. Fixes kirodotdev#9091
What is the problem?
When the credential scanner refuses to deliver a file, nothing records which file it
was. The consent audit trail records a flagged file that went OUT under a grant
(
detail=f"file_send: {clean_name}"), and it records grants, revocations andnon-owner denials. It records nothing at all on the refusal. The only place the
refused file's name appears is the error string returned to the calling agent.
So the asymmetry is: an incident review can see which flagged files left, and cannot
see which ones were stopped. And the owner standing in front of the
Settings > Security > Flagged-file deliverypanel, being asked to allow delivery,has no way to find out what was flagged.
Writing the name into the audit log turned out to expose a second, older problem in
the same sentence:
GET /api/sel/eventsserved that log to any authenticateddashboard session, not to the owner. See "The endpoint gate" below.
Why this issue matters to the user
The owner is the one who decides. The panel asks them to allow delivery of
scanner-flagged files to this machine's outbox and their own dashboard, and the whole
step-up around it -- the masked nonce, the host
kirocrew file-delivery approvecommand, the safety epoch -- exists so that the decision is genuinely theirs. A
decision they cannot inform is a weaker decision, however well the mechanism is
protected: they either allow it blind or refuse work they would have allowed.
The error string cannot serve them. It is returned to the AGENT, and the agent is
exactly the party the consent constrains.
How our fix solves it
Symptom: the owner cannot learn which file was refused.
One step up: the name is not in any record. The refusal sites hold the name in a
local variable and write a SEL tool-invocation entry that omits it
(
error="sensitive_content_detected").Root cause: the refusal was treated as not worth recording, on the ground that it was
"self-evident in the tool's error string" -- which is true only for the agent that
receives the string, not for the owner.
audit_decision's own docstring said so.The fix records the name at every refusal the scanner causes, under a new
refusedoutcome. No new store and no new endpoint:
audit_decisionalready redacts thedetail before clipping it, and its entries already reach the owner over
GET /api/sel/events. Recording a refused name is therefore the same disclosureclass through the same channel as the
deliveredentry that already names a flaggedfile.
The sites, and what each one covers:
file_send(tool)audit_refusalapi_outbox_notifyaudit_refusalapi_outbox_downloadaudit_refusal_gate_upload_file(Slack, channel)_sel()audit_refusalis the single spelling of the entry for the three grantable-classlegs, so they cannot drift into several vocabularies an owner would have to learn.
The shared channel-upload gate is deliberately NOT one of them. That function carries
a structural guarantee -- it is the single admission gate both third-party legs pass
through, and because it contains no reference to the consent store, no grant can reach
the Slack or channel leg by any code path. A test asserts that property on the real
source. Routing its refusals through the consent module would have broken it for an
audit write that needs nothing from that module, so the gate names the refused file in
the tool-invocation entry it already writes, in the
code: detailshape itsneighbouring refusals already use. The legs it serves can hold no grant, so a consent
decision is not what those entries record anyway.
Refusals caused by shape rather than by the scanner -- a missing field, a path
outside the allowed roots, an oversized read, a type off the binary allowlist, a
redaction failure -- record no file name, because none was flagged and an entry would
claim the scanner stopped something it never looked at.
Which refusal, and by whom
Two of the seven sites sit behind a gate with TWO conjuncts: the outbox download
honours a grant, but only for the owner, and it refuses on text and on binary content
separately. A single refusal entry served both failures, so the
owner's trail read the same whether the scanner had held a file back or another
authenticated principal had reached for a file the owner's own grant covers -- and the
second, read as the first, says the owner's grant lapsed while naming the other
principal nowhere. Identity is what the entry now reports, and it carries the
requester:
audit_decisionstamps every refusalgateway, which is the process, notwho asked. The five single-principal sites carry no caller clause,
because an entry trailing a bare
caller=would read as an identity the log failed tocapture.
Why the file name composes last.
audit_decisionclips the detail at 200characters, and the name is the only field in the entry with no length bound: an
outbox name arrives in the request path and is resolved inside the outbox, never
measured. Composed name-first, a long enough name pushes the reason and then the
caller off the end, and what survives reads exactly like a plain scanner hold-back
with no identity -- the reading the caller field exists to prevent, on the one leg
where the requester is recorded nowhere else. So the leg, the reason and the caller
compose ahead of the name: the fields that say what happened and to whom always fit,
and the name degrades to a prefix, which is honest.
The discriminator is identity, not the grant. The gate's conjunction
short-circuits, so in the default no-grant state a non-owner is refused before the
owner check is ever evaluated. Keyed off the grant, that caller would be recorded as
an ordinary scanner hold-back -- byte-identical to the owner's own -- so the entry
would lose its attribution in the configuration almost every install runs, which is
the one case it exists for.
_requester_is_not_the_owner()answers in everyconfiguration and needs no thread, being attribute reads over the request's claims and
the in-memory owner id, unlike the grant's store read.
The endpoint gate
This part is outside the original issue, and here is why it is in this PR. The
fix above rests on one claim: the audit log is a surface the OWNER reads. That claim
was false.
api_sel_eventsran no identity check and returnedrecent()rowsverbatim to any authenticated session, and a dashboard session is not by itself the
owner -- the messaging bridges mint a presigned token whose subject is the allowed
user's own id. Writing refused filenames into that log would have handed one
principal another's audit trail, and the same hole was already serving main's
deliveredentries, which name a flagged file too.So the gate is not scope growth bolted on; it is the premise of the change, and
leaving it for later would have shipped the disclosure and called it a disclosure to
the owner. The read is now gated on
is_owner_dashboard_request, the rule the secretsvault and the delivery-consent surface already follow, rather than a second
hand-rolled check that could drift from them. The refusal is audited: an ungated read
attempt against the security log is itself an event an operator wants, and the denial
row names the calling app, never a credential.
Nothing in the product consumed the endpoint -- there are zero callers in the
frontend -- so the gate closes a hole without taking a reader away from anyone.
GET /api/sel/verifyis untouched: it returns an integrity verdict, not rows.The denial tail, for the one caller who can act on it. A dashboard session signed
before an owner was configured keeps its bootstrap subject, and a token refresh
preserves the subject, so the real owner keeps failing this gate until they sign in
again. A generic 403 tells them nothing they can act on, so the denial goes through
_owner_denial_response, the tail every other owner gate in the dashboard shares: itrelabels exactly that class
401 stale_session_reauthand leaves every other refusedcaller on the generic 403, since an unsigned or app-token caller must not learn which
denial class it hit. The audit is written first, so the relabel changes the response
and not the recorded decision.
Why the name stays off the consent card. The issue asks for three steps: capture,
a read endpoint, and rendering on the card. The read endpoint already exists, so step
2 needs no new route. Step 3 is deliberately not done. The primary refusal runs in the
agent-side MCP process, so the name is text the agent chose; putting it on the grant
surface would let a prompt-injected agent display a reassuring name to coax a
standing grant, in the product's own voice, on the one surface whose design exists to
make that coaxing hard. The grant also covers the whole destination class rather than
one file, so a single name on the card would imply a per-file scope that does not
exist. An owner who wants to know what was refused reads the security event log,
which now names it -- and which now only they can read.
Comments that asserted the refusal is deliberately unrecorded were corrected in the
same change, since they are the prose form of the bug.
The gate is the shared one, and why the allow row stays
The owner check, the refusal audit and the stale-session relabel are all
require_owner_dashboard_request, the helper ~103 other owner-only dashboardsurfaces call. An earlier revision hand-rolled those three steps inline, including a
cold-path thread hop around the SEL singleton; the helper does the same work and
relies on the startup warm (
sel.warm_sel_singleton) instead, guarded so a failedwarm cannot change the outcome. There is no difference the helper cannot provide, so
the second spelling is gone along with the two cold/warm hop tests that only existed
to describe it. The denial code is therefore the standard
owner_only, and sel.mdsays so.
The
allowedrow is kept, and it is kept on a named requirement rather than oncompleteness for its own sake. GPT 5.6 blocked the immediately preceding revision on
exactly this: a successful owner read left no row anywhere, which its adjudication
upheld as security-class against the
backend-security-controlsanchor. No denial rowcan answer that -- a denial says who was turned away, never that the log was read --
and this endpoint is the one that serves the audit trail itself, so reading it is a
security event in a way that reading an ordinary owner surface is not. Deleting the
row would re-open a finding already adjudicated as blocking.
The owner has to be able to READ the name
Writing the name is only half of it.
audit_decisionputs it in the SELresourcesfield, and
kirocrew security events-- the read path an owner actually has, since theendpoint is owner-only and there is no audit UI -- printed timestamp, source, event
type, operation, outcome, caller,
erroranddownstream_service, and droppedresources. So every refusal said that a refusal happened and never said what wasrefused. The renderer now prints
resources, which also makes thedeliveredrowsalready on main legible for the first time. It is a small change in an otherwise
untouched file and it is in scope because without it this change does not reach the
person it is for.
Printing that field safely is part of the same step. A refused file name is text the
AGENT chose, a POSIX name may carry ESC/OSC bytes, and nothing upstream removes them:
the consent module's redaction and SEL's own write-path pass both police credentials and
length, not control sequences. Raw, those bytes execute in the owner's terminal -- the
one place this trail is read. Both untrusted fields the renderer prints,
resourcesandthe pre-existing
error, now go throughsafe_terminal_line, the shared stdlib-onlypolicy other CLI surfaces already use.
erroris included rather than left alonebecause this change is what routes agent-chosen file names into it, at the
channel-upload gate's four denial entries.
That guard is applied to the WHOLE row, not only the two fields the refused name
lands in. SEL's
_REDACTED_TEXT_FIELDSnamesoperationbesideresourcesanderror, andlog_api_accessdocumentsoutcomethe same way, because an installedapp reaches it through
ctx.audit-- so the summary line one row above carried thesame exposure and is sanitized too. The same helper also coerces before sanitizing:
recent()validates only that a line is a dict, the log is sandbox read-write, andsafe_terminal_linehands its argument tore.sub, so a forged line with anon-string field would have aborted the listing and hidden every other event.
One doc claim went with it. The app-kit reference said an app "cannot read it back",
four lines above its own statement that hook code runs inside the gateway and can
reach the log directly. The endpoint is owner-gated; in-process app code is not
isolated from the log, and the page now says that instead.
The allow row is written AFTER the rows are captured, not before.
recent()opens withflush(), so a row enqueued first reaches disk in time to come back as the newestrecord: the owner would have received their own audit row in place of a real event, and
a
limit=1read would have returned nothing else. Captured first, the payload is realevents only.
Disposition: the advisory CONCERNS on a second SEL row (withdrawn upstream)
On an earlier head First Principles asked for
audit_refusaland its call sites to be deleted, withthe name appended to the
log_tool_invocationdenied row each site already writes --the shape the channel-upload gate uses in this same diff. Its facts are right: every
site does sit beside a denied row, one base row already carries the name
(
error=f"sensitive_filename: {redact(clean_name)}"), both families reach the sameowner-read log, and the gate here does take the one-row route.
The reason to keep the separate entry is what that family already holds.
granted,revokedanddeliveredare allfile_delivery_consent.*entries on the base --deliveredat two sites, naming the flagged file that went OUT.refusedis thecounterpart of that
deliveredrow, and the asymmetry between what left and what wasstopped is the whole complaint this change answers. Collapsing the refusal into
log_tool_invocationputs the pair in two different families: the delivery in theper-destination-class decision history, the refusal in per-tool-call telemetry. An
owner asking "what did I grant, what went out, what was held back" then reads two
vocabularies to reassemble one class's history, which is the same asymmetry in a new
place.
The channel-upload gate is not a concession to the contrary. It takes the one-row
route because a structural test forbids it referencing consent state at all -- it
serves legs a grant can never cover -- so it was never eligible for this family.
Superseded on the rebased head. That verdict re-sampled to a different finding:
the notify leg's own binary-content refusal named no file. It was the twin of the
download branch and the omission was real, so it is fixed rather than argued, and the
per-leg count pin moved from two to three so the gap cannot reappear silently. The
subtraction above is no longer asked for on the current head; the reasoning is kept
here because the entry it defends is still the one this change ships.
Rebased onto the restructured gates
#13269landed on main after this branch was cut and rewrote the same deliverygates: the grant read moved into a thread, the two-conjunct owner test became the
_grant_permits_this_handoverclosure, and a wide-encoding scan plus a binary-contentscan were added on both owner-facing legs. This branch is rebased onto that work
rather than around it -- main's control flow is kept everywhere the two touched the
same lines, and this change re-applies on top of it.
Consequences for the count. Both owner-facing legs now refuse on binary content as
well as text: download carries TWO refusal entries and both discriminate the conjunct
that failed, and notify carries THREE (name, text content, binary content). The upload
gate now has four scanner denials to name rather than three, the new one being the
wide-encoding scan. The per-leg count test pins each number, so a scan added without
an entry reddens it. Both owner-facing legs gained that binary scan, so notify carries THREE entries
and download TWO, and
audit_refusalhas seven call sites.#13269shipped its two new denials without the file name, so namingthem is the same gap this change closes, in code that did not exist when it was
opened.
What tests we did
Every run named its file and passed an explicit
-n0.test/test_file_delivery_consent.py, the three classes this change touches(
TestARefusalNamesTheFileItHeldBack,TestConsentedDownloadRequiresOwnerIdentity,TestEveryScannerRefusalRecordsTheName): 14 passed. They cover the refusal helper'srecorded fields, the primary tool leg end to end, a flagged name recorded without
reproducing it, the negative direction (a granted delivery records no refusal), the
per-leg count of refusal entries, which upload-gate entries carry the file name, the
pre-existing structural guarantee that the upload gate references no consent store,
the caller clause in both directions (named on the two-conjunct leg, absent on a
single-principal leg), that the download entry says which conjunct refused, and that
a 4000-character name still cannot clip the reason or the caller off the row, and that
both download branches -- text and binary -- discriminate the conjunct.
test/test_dashboard_handlers_core_coverage.py::TestSelEndpoints: 15 passed. Threeowner reads; four non-owner classes that must fail closed -- a different user, no
user claim, an app token, and an absent app claim -- each asserted to return 403 and
to leave
recent()uncalled, so a 403 whose body still carried the rows could notpass; both bootstrap subjects asserted to get
401 stale_session_reauthwithrecent()still uncalled; and the negative, that a caller under NO configured ownerkeeps the generic 403 rather than being told to re-authenticate.
test/test_sel_dashboard_offload.py: 5 passed. Its fake request carries the owneridentity the endpoint requires, and the denial audit is asserted to hop off the loop
when the SEL singleton is cold and to stay inline when it is warm.
Mutation-verified against the code as it now stands, each mutation applied alone and
the file restored byte-identically afterwards (asserted by hash): with the download
refusal collapsed back to one reason string, the conjunct test reddens; with the
detail composed name-first again, four row-shape tests redden; with the notify
binary-content entry removed, the per-leg count test reddens; with the refusal
attributed by the grant instead of identity, the conjunct test reddens; with the
allow row deleted, the two read-audit tests redden; with that row moved back ahead of
the read, the ordering test reddens; with the renderer's
resourcesline removed, thevisibility test reddens; with that line printing the field raw instead of through
safe_terminal_line, the control-byte test reddens; with the summary line'soperationread raw again, the summary-line test reddens; and with the coercionremoved so
re.submeets a non-string, the forged-row test reddens. The owner decision and the denialaudit are no longer mutated here because they are no longer this handler's code -- they
belong to the shared gate, which its own ~103 callers cover.
Unmutated, the three handler/consent files are 289 passed and the CLI file's event
renderer tests 12 passed. Behaviour, not just source shape:
the primary delivery leg is driven end to end (
file_sendon a flagged file with nogrant) and its entry asserted verbatim, and the helper's two entry shapes are asserted
on the recorded row.
Gates:
flake8andisortclean over every Python file in the change;scripts/check_black_formatting.pyandscripts/check_comment_history.pyboth passover the change scope.
Any other suggestions on the work
The recorded decision, restated: capture only, through the existing audit channel; no
new store, no new route, no card field. The endpoint gate was added on top of that
decision once the premise it rested on turned out to be untrue.
Rejected, and why:
own three steps). It adds agent-chosen text to the owner's security-decision
surface, implies a per-file scope the grant does not have, and ships a route that is
awkward to withdraw.
the path in, so it already knows the name; this creates no owner-readable record.
naturally -- one vocabulary for every refusal -- but it breaks that gate's
structural guarantee for an audit write needing nothing from the module.
this PR started as, and it is what made the change unsafe rather than neutral.
audit gap.
Worth a follow-up, out of scope here: the security event log still has no in-product
reader. A security-event view would make this entry, and every other one already
written, visible to the owner without reading the log file.
Pattern harvest
Rule candidate: review checklist, and a grep-able one for the second half.
Pattern: a change justified by "this channel is already read only by X" without X's
gate being read in code. The capture half of this PR was sound and its premise was
not: the audit log's read route had no identity check at all, so adding a filename to
it widened a cross-principal disclosure instead of informing the owner. The general
form is that an audience claim about an existing surface is a claim about that
surface's authorization code, and is verified there, not from the surface's purpose or
its docstring.
The narrower, mechanical half: a handler under
dashboard/handlersthat servessecurity-audit or credential-adjacent rows and never calls
is_owner_dashboard_request(or the shared owner gate) is worth flagging. Every othersuch surface in this tree -- the secrets vault, the delivery-consent endpoints, the
source-provider reads -- routes through that one predicate, which is what made this
endpoint's silence detectable once anyone looked.
Also, but already enforced: adding a call into a function that carries a source-text
structural fence. The existing test caught that within one CI round, so it needs no
new rule.
Closes #9091