Skip to content

feat(app-kit): add ctx.audit, the app-facing security event log seam - #9545

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
suhasaitham22:seam-d-audit
Sep 12, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
suhasaitham22:seam-d-audit

Conversation

@suhasaitham22

@suhasaitham22 suhasaitham22 commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

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 as ctx.audit, with exactly one method:

ctx.audit.record("publish", "success", resources=doc_id)
ctx.audit.record("publish", "denied", resources=doc_id, error="no edit access")

Rows land as api_access with source=app, caller=app:<name>, operation=<name>.<verb>.

Three decisions are load-bearing:

  • Attribution is SDK-minted, never a parameter. There is deliberately no caller= or source= 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 construct AuditSDK("other-app") or reach sel() directly. What the seam removes is accidental misattribution; preventing a deliberate one needs process isolation, not an in-process API.
  • operation is namespaced, so two apps cannot collide on a bare "publish".
  • record never 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.
  • outcome is not narrowed to a vocabulary. The gateway's own writers use ok, completed, rejected, allowed and 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 turns outcome from 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.py already ran _redact_and_clip on resources and error and forwarded outcome verbatim, 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. Narrowing outcome to 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_context always 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 typed AuditSDK | None to 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/events surfaces 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 reach kiro_crew.sel at 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 as sel, 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 no caller/source parameter to get wrong (asserted against the signature, so adding one later fails the test); two apps do not collide; record survives 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 gets audit with no permission declared while a capability SDK still requires its own.

test/test_sel.py (+2) — log_api_access redacts and clips outcome, 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

  • One commit, Conventional Commits title
  • New tests for the new seam
  • Docs updated in the same commit — docs/system-specs/modules/sel.md (Integration Points, the owning spec) and docs/app-kit/api-reference.md (app authors)
  • flake8 / isort / black / mypy clean; docs-lint passes
  • No secrets or internal references in the diff

@suhasaitham22
suhasaitham22 requested review from a team and pepmach September 8, 2026 21:08
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 8, 2026
@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed daf06b751b5c73ccf8f94be3b1c1312cc021a824 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] daf06b7

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of daf06b751b5c73ccf8f94be3b1c1312cc021a824 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All checks done. The design follows the merged ctx.scrub sibling pattern, the outcome-scrub lands at the shared log_api_access boundary with identity pinned for in-tree spellings, source="app" matches existing explicit-source practice (token_auth, acp also sit outside _AUDIT_SOURCES), and no prior test pinned the opposite behavior. The one open design input is demand: zero in-tree consumers and a motivating request that exists only in a non-public exchange the author explicitly asks a maintainer to confirm.

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

  • New public surface with no consumer: the PR states "nothing in-tree calls ctx.audit" and the requesting-app exchange "was not in a public thread, so I am not citing one." Once an installed app pins to record(), the signature is contract and hard to walk back — shipping it on an unconfirmed premise is the only notable risk here.
    Clears when: a maintainer confirms the #7955/#7975 review request (or names the external app) in this PR thread.

[DESIGN-REVIEWED] daf06b7

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of daf06b751b5c73ccf8f94be3b1c1312cc021a824 via the fork AI-review pipeline — 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.

All claims verified against the base tree. I have what I need for the review.

Key facts established: log_api_access (sel.py:2387) forwards outcome verbatim on base while scrubbing resources/error; _REDACTED_TEXT_FIELDS omits outcome as claimed; cron_sdk does use the app:<name> tag; ~40 built-in app files import kiro_crew.sel directly (the "built-in-only route" the description names); no in-tree caller builds a dynamic outcome (grep outcome=f" → 0 matches), supporting the no-row-changes claim; and nothing in the tree or patch calls ctx.audit outside its own tests and docs.

First-Principles-Verdict: CONCERNS

ctx.audit ships with zero consumers and its only provenance is a private review exchange the author explicitly cannot cite — a maintainer must confirm it.

Not justified as shipped

  1. Apps can write to the security event log — zero consumers; requirement rests on an uncitable non-public exchange ("I am not citing one — a maintainer should confirm").

What this change ships

Inventory (5 items) — 4 justified

Intent: give an installed app a stable way to land its own security decisions in the SEL log — an ADDITION.

  1. Apps can write audit rows via ctx.audit.record — zero consumers; provenance is an uncitable private review request (feat: add contributes.fileMenuItems app-manifest contribution #7955/feat: add contributes.panelTabs app-manifest contribution #7975 threads).
  2. log_api_access now redacts and clips outcome for every existing caller — justified
  3. Every app gets ctx.audit ungated, no permission declared — justified
  4. A failed audit write becomes a debug log line instead of an exception — justified
  5. sel.md and app-kit api-reference updated in the same commit — justified

Watch

The seam's harm is real (an app cannot write this log at all; the 40+ built-ins that import kiro_crew.sel directly ship in the wheel, external apps don't) — but the requester and consuming app exist only in the description's word. The author asked for exactly this confirmation; hold it to that.
Clears when: a maintainer confirms the #7955/#7975 review request in-thread, or names the external app that will call ctx.audit.

Subtractions

Defer apps/audit_sdk.py, the audit field on AppContext, and the outcome scrub in log_api_access (which has no cause without the seam) until the consumer is confirmed — counted consumers of AuditSDK outside tests/docs: 1, the factory itself (context.py).

[FIRST-PRINCIPLES-REVIEWED] daf06b7

@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed daf06b751b5c73ccf8f94be3b1c1312cc021a824 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] daf06b7

@pepmach pepmach 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.

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.

@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 9, 2026
@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 11, 2026
@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 11, 2026
@suhasaitham22

Copy link
Copy Markdown
Contributor Author

Maintainer confirmation requested — this is the only thing still blocking

Everything mechanical on this PR is green (tests, lint, type check, coverage, build, the ratchet gates), and it is rebased onto current main. The single remaining blocker is the First Principles review's zero-consumer finding, and its clearing condition is explicit:

Clears when: a maintainer confirms the #7955/#7975 request on this PR, or a consumer lands alongside the seam.

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 outcome field reaching the append-only SEL log unscrubbed. Those are fixed and covered by tests either way.

@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 11, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 11, 2026
@suhasaitham22

Copy link
Copy Markdown
Contributor Author

On "a consumer lands alongside the seam" — I checked, and that path is not available

The zero-consumer blocker offers two ways out: a maintainer confirming the request, or a named consumer landing with the seam. An earlier round suggested issue_radar adopting ctx.scrub as its first consumer. I went and tried to do that rather than argue, and it does not work. Recording why, so the option is not left on the table as though it were open:

  • issue_radar never receives an AppContext. It has no hooks.py — only backend/ — and its entry point is register_routes(app: web.Application) -> None. Its own docstring notes that signature "matches every other builtin app … confirmed against the real call site in dashboard/server.py (_mod.register_routes(app), single argument)".
  • The semantically right site, _comment_text(body: str) -> str in backend/azure_client.py ("the vetted text for a comment this app is about to publish"), is a module-level function. Reaching it from a context means threading an AppContext down through an unrelated app's backend.
  • No builtin uses any ctx.<sdk> outside hooks. The only in-tree consumers of sibling SDKs are mochi/hooks.py (ctx.spawn) and crew_companion/hooks.py (ctx.events).
  • mochi is the one app with in-gateway hooks, and it is the wrong consumer: redact.py::redact_tree is deliberately a leaf module ("so both importers can take it at module scope without a circular import"), it walks JSON rather than publishing a string, and its sinks are browser surfaces and persisted state — not off-machine sends. ctx.scrub.outbound is fail-closed by design (it propagates PlatformCompositionError), so routing persisted UI state through it would convert a redaction miss into a crash on a render path. That is a regression dressed as an adoption.
  • For ctx.audit there is no candidate at all. Builtins reach sel() directly and are right to: they ship in the same wheel as sel, so they have no version-skew problem.

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 kiro_crew.security / kiro_crew.sel across an upgrade, and cannot reach the active CredentialPolicy. Anything shipped in-tree has neither problem. Migrating one would make the API read as non-speculative while changing nothing real — satisfying the gate rather than the concern it encodes, which I would rather not do.

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.
@suhasaitham22

Copy link
Copy Markdown
Contributor Author

The zero-consumer blocker has been answered by #9544 merging

The First Principles blocker on this PR states its clearing condition as:

Clears when: a maintainer confirms the #7955/#7975 request on this PR, or a named installed-app consumer exists.

The first condition is now met, on the repo rather than in a thread. #9544 — ctx.scrub, the sibling seam — was merged as 6575bee00. It carried the identical property this blocker objects to:

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:

  1. An earlier round objected that the seam rested on "symmetry with a ctx.scrub sibling that does not exist in base (grep scrub in apps/context.py: 0)". It exists in base now — this PR's rebase places audit directly beneath it on the same dataclass.
  2. The consumer-adoption escape hatch is closed, and I verified that rather than asserting it — see my previous comment. No builtin can honestly consume either seam, because builtins ship in the same wheel as sel and have neither the version-skew nor the credential-policy problem the seams exist for.

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 ctx.audit closes is strictly worse than the one ctx.scrub closed, and it is now the only half of the pair that is missing.

Current state: rebased onto 6575bee00, both seams coexisting on AppContext; every test shard, lint, type check, coverage, build and ratchet gate passes; the Opus, GPT 5.6, Security-Scope and UX reviews all pass. The outcome scrub in log_api_access is unchanged by the rebase and still has no upstream equivalent (_REDACTED_TEXT_FIELDS still omits outcome on current main).

@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 11, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 12, 2026 00:01
@bolichen97
bolichen97 merged commit 6cbe641 into kirodotdev:main Sep 12, 2026
76 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants