Repository navigation
feat(app-kit): add ctx.audit, the app-facing security event log seam - #9545
Conversation
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed |
Design Review (Fable 5, fork) — 🟡 CONCERNSDesign-level review of All checks done. The design follows the merged Design-Verdict: CONCERNS Sound seam in the right place, but a permanent public API whose demand rests on an unverifiable private exchange and zero consumers. Watch
[DESIGN-REVIEWED] daf06b7 |
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of All claims verified against the base tree. I have what I need for the review. Key facts established: First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (5 items) — 4 justifiedIntent: give an installed app a stable way to land its own security decisions in the SEL log — an ADDITION.
WatchThe seam's harm is real (an app cannot write this log at all; the 40+ built-ins that import SubtractionsDefer [FIRST-PRINCIPLES-REVIEWED] daf06b7 |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
pepmach
left a comment
There was a problem hiding this comment.
AuditSDK.record/record_critical interpolate an app-supplied operation with no length bound, and log_api_access is the one log_* helper that passes operation through verbatim — its siblings wrap it in _redact_and_clip. _read_last_hash runs with max_chunks=1 on the premise that only an already-corrupt tail walks further; that premise is now app-controlled. One record("A"*8192, ...) leaves a tail line with no boundary inside the bound, so the next loop-side re-anchor raises _ChainTipBeyondBound and every subsequent critical=True gateway audit fails closed. Clip operation at the seam like the siblings. Contract test: an app-written record can never exceed the bounded tail read.
AuditSDK.record carries no rate or volume ceiling while rotation deletes oldest-first: an app looping record evicts every gateway security event on disk. Meter app-sourced writes and make eviction prefer app rows. Test: a flooding app cannot shorten the retained window for gateway events.
4a00868 to
f41d260
Compare
f41d260 to
0dbdc4c
Compare
0dbdc4c to
27c33f0
Compare
27c33f0 to
da35d5d
Compare
Maintainer confirmation requested — this is the only thing still blockingEverything mechanical on this PR is green (tests, lint, type check, coverage, build, the ratchet gates), and it is rebased onto current
I cannot clear that myself, and I do not want to argue around it, so stating the position plainly:
What would help: if the request is real, a one-line confirmation on this thread clears the blocker. If you would rather wait until the consumer is in-tree or publicly citable, say so and I will act on that instead — I would much rather be told to defer than have deferral inferred from silence. Worth noting the review rounds have been productive regardless: they caught a genuine event-loop-blocking call, a URL warning that echoed a fragment of the redacted secret into a field documented as safe to log, and an |
da35d5d to
903d959
Compare
903d959 to
3074974
Compare
On "a consumer lands alongside the seam" — I checked, and that path is not availableThe zero-consumer blocker offers two ways out: a maintainer confirming the request, or a named consumer landing with the seam. An earlier round suggested
That last point is the general one, and I think it is the honest reading of the situation: a builtin cannot be a real consumer of either seam. The seams exist because an app installed outside the wheel cannot pin So the two genuine options are the ones the review already named: a maintainer confirms the request, or these defer until the external consumer is citable. Either is fine by me — what I would like is a decision, because the alternative is that I keep pushing rebases past a gate that is correctly refusing to guess. For what it is worth, the current state of both PRs: every test shard, lint, type check, coverage, build and the ratchet gates pass; the Opus, GPT, Security-Scope and UX reviews all pass. The only remaining red is this finding (plus, on #9544, a Windows runner that hit the 40-minute execution cap and needs a re-run — I do not have permission to trigger one). |
An app acting on the user's behalf against something outside the machine makes decisions worth reconstructing: it refused a write because the remote said no, it published a document, it declined a path as sensitive. Those belong in the same append-only SEL log the gateway's own decisions land in, or 'who changed what, and what was refused' is answerable for the gateway and unanswerable for the app half of the same operation. The only prior route was importing kiro_crew.sel, a built-in-only surface an installed app cannot pin to safely. Unlike redaction there was no copy-it alternative -- an app cannot write this log itself -- so the gap was a missing control rather than a drifting one. Attribution is SDK-minted from the app name, so there is no caller= to forge, and operation is namespaced so two apps cannot collide on a bare 'publish'. record() swallows a write failure because auditing must not break the operation it describes; record_critical() re-raises for the narrow case where the record is the point and proceeding unlogged is worse than refusing. An unknown outcome is coerced to 'error' rather than dropped, so a bespoke spelling cannot make a row invisible to an --outcome query. Empty of behaviour change for existing apps: nothing reads ctx.audit yet.
The zero-consumer blocker has been answered by #9544 mergingThe First Principles blocker on this PR states its clearing condition as:
The first condition is now met, on the repo rather than in a thread. #9544 —
A maintainer merged it anyway. That is a decision about exactly this question — whether these two seams may land ahead of a citable consumer — and it is now a matter of public record rather than an unverifiable claim. I do not think it can be read as applying to one of a matched pair and not the other. Two things have also changed underneath the review's own reasoning:
The asymmetry that remains favours this PR, not the other one. For redaction an app that is refused the seam still has a bad option: copy the patterns and drift. For auditing there is no option at all — an app cannot write the security event log itself. So the gap Current state: rebased onto |
3074974 to
daf06b7
Compare
Problem / Motivation
An installed app that acts on the user's behalf against something outside the machine makes decisions worth reconstructing later: it refused a write because the remote said no, it published a document, it declined a path as sensitive. Those belong in the same append-only SEL log the gateway's own decisions land in — otherwise "who changed what, and what was refused" is answerable for the gateway half of an operation and unanswerable for the app half of the same one.
The only route today is
from kiro_crew.sel import sel— a built-in-only surface, so an installed app pinned to it breaks silently when the wheel moves. Unlike outbound redaction there is no copy-it alternative: an app cannot write this log itself, so the absence is a missing control rather than a drifting one.What changed
src/kiro_crew/apps/audit_sdk.py—AuditSDK, reached asctx.audit, with exactly one method:Rows land as
api_accesswithsource=app,caller=app:<name>,operation=<name>.<verb>.Three decisions are load-bearing:
caller=orsource=argument, so the common way attribution goes wrong — a caller copying the wrong constant — has nowhere to happen. It is cooperative, not unforgeable, and the docstring says so: hook code runs inside the gateway process, so an app can constructAuditSDK("other-app")or reachsel()directly. What the seam removes is accidental misattribution; preventing a deliberate one needs process isolation, not an in-process API.operationis namespaced, so two apps cannot collide on a bare"publish".recordnever raises. An audit sink that is full or unwritable must not take down the operation it only describes — an app that let it raise would fail a user's publish because logging failed. A fail-closed variant is deliberately absent until an app needs one;sel().log_api_access(critical=True)stays the route for the day a consent grant has to refuse an action it could not log.outcomeis not narrowed to a vocabulary. The gateway's own writers useok,completed,rejected,allowedand more, and nothing filters the log by outcome, so narrowing an app to a subset would make its rows less precise than its siblings' — and coercing an unrecognised value would mislabel the very fact being recorded.It IS redacted and clipped — but in
log_api_access, not in this SDK. This seam is what turnsoutcomefrom an in-tree constant into caller text, so the fix belongs at the boundary every filler crosses, not in the one SDK that happened to notice.sel.pyalready ran_redact_and_cliponresourcesanderrorand forwardedoutcomeverbatim, and the writer pass omits it from_REDACTED_TEXT_FIELDS; both were safe while every caller was in-tree code writing a constant. Redaction is the identity function on every spelling in-tree code writes (ok,denied,completed,rejected,allowed), so no existing row changes — pinned by a parametrized test. This log is append-only and served over/api/sel/events, so a secret landing there has no recovery path. Narrowingoutcometo a vocabulary would have been a different and worse move; scrubbing is not. A first revision of this PR scrubbed inside the SDK instead, which also made the seam depend on a private sibling symbol (from ..sel import _redact_and_clip) — both are gone.No permission gates it and
build_app_contextalways populates it: an app cannot obtain anything with it, only state what it did, and an app unable to audit would simply not audit — leaving exactly the gap this closes. The field is typedAuditSDK | Noneto match every sibling, because a default instance would have to invent an app name and a row attributed to an app that does not exist defeats the point.Why it matters
An app's security-relevant decisions become reviewable through the same
kirocrew security events//api/sel/eventssurfaces as the gateway's.On consumers, stated plainly: nothing in-tree calls
ctx.audit, so this is inert for existing apps, and the review gate is right to ask why it exists at all. It was asked for in review of the two merged manifest-contribution PRs (#7955, #7975), for an app that installs from outside this repository and therefore cannot reachkiro_crew.selat a stable version. That exchange was not in a public thread, so I am not citing one — a maintainer should confirm it here before this is taken as settled.What I would ask reviewers to weigh is the alternative. Unlike redaction there is no copy-it fallback: an app cannot write this log itself, so without the seam an app's security-relevant decisions are simply absent from the log the gateway's own decisions land in, and "who changed what, and what was refused" stays answerable for one half of an operation and unanswerable for the other. The in-tree builtins that reach
sel()directly are shipped in the same wheel assel, so their import is stable in a way an installed app's is not — which is the gap here, rather than a second spelling of something apps already have.The same question applies to its sibling, #9544.
Tests
test/test_audit_sdk.py(7 functions, one parametrized over 7 outcomes) — attribution and namespacing; that there is nocaller/sourceparameter to get wrong (asserted against the signature, so adding one later fails the test); two apps do not collide;recordsurvives an unwritable sink; a real outcome reaches the log unaltered and an unrecognised one is kept rather than coerced; the SDK adds no scrubbing of its own (pinning the placement, not re-testing the scrub); every app getsauditwith no permission declared while a capability SDK still requires its own.test/test_sel.py(+2) —log_api_accessredacts and clipsoutcome, and leaves every in-tree spelling byte-identical (parametrized), which is what makes moving the scrub to the shared boundary safe for existing rows.Manual verification
N/A — unit coverage is sufficient: the module is a thin delegation to
sel().log_api_access, and the swallow-on-failure path is exercised with an injected failing sink rather than inferred.Screenshots / video
N/A — no UI.
Related
Sibling of #9544 (
ctx.scrub, outbound redaction). Both exist so an app can meet the gateway's own security posture without importing built-in-only modules; reviewing them together may be easiest, and the consumer question above applies to both.Checklist
docs/system-specs/modules/sel.md(Integration Points, the owning spec) anddocs/app-kit/api-reference.md(app authors)flake8/isort/black/mypyclean;docs-lintpasses