Repository navigation
feat(app-kit): add ctx.scrub, the app-facing outbound redaction seam - #9544
Conversation
Design Review (Fable 5, fork) — 🟡 CONCERNSDesign-level review of All key claims verified against the base tree: Design-Verdict: CONCERNS Sound seam with minimal surface, but it ships unwithdrawable public API for a consumer only a private, unconfirmable review exchange attests to. Watch
Suggestions
[DESIGN-REVIEWED] 1ddf377 |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed Review detailsBoth underlying redactors return No findings. [OPUS-REVIEWED] 1ddf377 |
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of All verification is done. Final assessment: the First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (6 items) — 5 justifiedIntent: give installed apps the gateway's own outbound credential/exfil redaction without copying it — an ADDITION, with a standalone fix riding along.
Watch
Subtractions
[FIRST-PRINCIPLES-REVIEWED] 1ddf377 |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsFINDING -- src/kiro_crew/security/init.py:787 -- |
b42e9f4 to
2dd512c
Compare
2dd512c to
ff7406c
Compare
ff7406c to
eafc4f7
Compare
eafc4f7 to
0af9d0e
Compare
0af9d0e to
1db4ac5
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 |
An app that sends content off the machine needs the same credential and exfiltration-URL redaction the gateway applies on its own boundaries. The only routes to it were importing kiro_crew.security -- a built-in-only surface, so an installed app pinned to it breaks silently when the wheel moves -- or copying the patterns, which is worse: a pattern set that drifts from the enforced one is a control that looks present and is not. ScrubSDK wraps redact_credentials, redact_exfiltration_urls and is_sensitive_path BY REFERENCE, reached as ctx.scrub, so an app picks up a tightened pattern with the wheel. outbound() applies URLs then credentials in that order: redacting a credential first leaves a partial token inside a URL the exfiltration matcher would no longer recognise. No permission gates it and it is never None. It only removes data, so there is nothing to withhold, and an app refused the seam would ship its own regexes -- the outcome this exists to prevent -- while a None branch would become a silent no-redaction path. Empty of behaviour change for existing apps: nothing reads ctx.scrub yet.
1db4ac5 to
1ddf377
Compare
Security Scope Review (fork) — 🟡 CONCERNSWhich legitimate operations does the reviewer's own judgement; no confirmed regression Scope-Verdict: CONCERNS TIGHTENING: The redaction pass ordering at the two onboarding-import sanitization sites ( ADJUDICATED: 13 candidates, 0 confirmed newly-refused PLATFORM COVERAGE: posix rows cover the interpreter path ( UNADJUDICATED: The tightening this change actually makes lives entirely outside the shell deny composite, so no classifier verdict exists for it and the empty adjudicated set above is not evidence it is well scoped.
[SCOPE-REVIEWED] 1ddf377Security scope review -- adjudicated candidates
No candidate flipped from allowed to refused. |
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). |
…irodotdev#9544) An app that sends content off the machine needs the same credential and exfiltration-URL redaction the gateway applies on its own boundaries. The only routes to it were importing kiro_crew.security -- a built-in-only surface, so an installed app pinned to it breaks silently when the wheel moves -- or copying the patterns, which is worse: a pattern set that drifts from the enforced one is a control that looks present and is not. ScrubSDK wraps redact_credentials, redact_exfiltration_urls and is_sensitive_path BY REFERENCE, reached as ctx.scrub, so an app picks up a tightened pattern with the wheel. outbound() applies URLs then credentials in that order: redacting a credential first leaves a partial token inside a URL the exfiltration matcher would no longer recognise. No permission gates it and it is never None. It only removes data, so there is nothing to withhold, and an app refused the seam would ship its own regexes -- the outcome this exists to prevent -- while a None branch would become a silent no-redaction path. Empty of behaviour change for existing apps: nothing reads ctx.scrub yet. Co-authored-by: Suhas Aitham <suhasaitham22@users.noreply.github.com>
Problem / Motivation
An installed app that sends content off the machine — to an external document store, a ticket, a wiki — needs the same credential and exfiltration-URL redaction the gateway applies on its own boundaries. Today it has two options, and both are bad:
from kiro_crew.security import …— a built-in-only surface. Built-ins move in lockstep with the wheel; an installed app does not, so an app pinned to it breaks silently for anyone who upgrades. It is also the companion-blind baseline, so an app wiring it up directly gets weaker redaction than the gateway's own egress sites on any host with an edition companion loaded.What changed
Two pieces. The first stands on its own and fixes an existing defect.
1.
security.redact_with_findings— one home for the pass orderBeside
security.redact, returning(text, credential_warnings, url_warnings)instead of discarding what each pass reported.redact()now delegates to it, so the order the two passes run in lives in exactly one place.That order is a security property: exfiltration URLs run first because that pass matches whole URLs, and a credential replaced ahead of it leaves a placeholder inside one that the URL matcher then fails to recognise.
Both lists hold the warning strings the underlying passes emit. Note these are not uniformly payload-free: the credential pass reports shapes only (
"Redacted credential pattern (20 chars)"), but_exfil_url_warningembeds the offending domain in every branch and, on the long-query branch, the first 60 characters of path+query. That is fine for in-tree callers that already handle the text itself; it is why the app seam below reports counts instead.Two existing callers migrate to it in this PR —
onboarding_import.py:896(_sanitize_text) and:1341(skill-asset screening). Both ran credentials-then-URLs, i.e. the unsafe order, so this is a behaviour fix and not just a refactor.Correcting an earlier claim in this description: I previously wrote that the repo held "7 reversed sequences across 6 files". That was wrong by roughly an order of magnitude. Counting chained
redact_credentials→redact_exfiltration_urlson the same value, the residue is on the order of ~70 sequences across ~37 files, of which a substantial number do consume the findings and stay reversed — includingvoice_reply.py:987and:1629,snapshot_redact.py:304(whose docstring calls credential-first "the order the rest of the repo applies"),dashboard/handlers/prompts.py:864and:1739, andapps/builtins/aws_control/backend/routes.py:1256.That residue is deferred, not fixed here, and stated so deliberately rather than left implied. Two consequences worth being explicit about: the two migrated sites are a sample, not the class, so this PR does not make the repo consistent; and
snapshot_redact.py's docstring means the credential-first order is currently documented as the convention, so flipping ~70 sites is a decision about which order the repo endorses and belongs in its own change with its own review, not smuggled in behind a new app seam. What this PR does claim is narrower:redact_with_findingsgives that eventual migration a single destination that already encodes the safe order.2.
ctx.scrub— the app-facing seamsrc/kiro_crew/apps/scrub_sdk.py, with exactly one method:Decisions that are load-bearing:
platform.context.redact_via_context, the canonical shim every egress site routes through, so a loaded companion's extra token and cookie regexes apply. The baseline pass runs first only to count what it recognised, and the policy pass runs over its result — so an app's published text is never less redacted than the gateway's own boundaries. Routing an app-facing egress helper throughsecurity.redact*alone would have been companion-blind, and the resulting exposure is irreversible.redact_via_contextre-raisesPlatformCompositionErroron a host that could not compose its companion, andoutboundpropagates it rather than silently downgrading. Documented for app authors as "abandon the publish".credentials_removed/urls_removed, because the exfiltration warning carries a fragment of the URL it just removed — exactly where a token that escaped the credential patterns sits — and handing that to an app as "safe to log" would relocate a secret from the published text into the app's log. A count cannot carry a payload however core later phrases a warning, so the property does not depend on that phrasing.test_nothing_the_seam_reports_can_carry_a_payloadpins it, and asserts core's raw warning really does echo the secret so the hazard is documented rather than assumed.redactedis set by the SDK, not derived fromtext != original, and accounts for the policy as well as the baseline: a companion can remove a token the baseline never counted, soredactedmay beTruewith both counts at zero. It is neverFalsewhen something was removed.is_sensitive_path) transitively made a bounded-but-blockingfuture.result(timeout=2.0)reachable from an app's async handler.test_the_seam_exposes_only_the_combined_passpins the surface so a second spelling cannot accrete.None. Every other SDK onAppContextgrants a capability and staysNoneuntil the manifest asks. This one only ever removes data from a string the app already holds, so there is nothing to withhold — and a gate would be actively harmful: an app refused the seam does not stop sending the content, it ships its own regexes. ANonefield would also make theelsebranch a silent no-redaction path. It carries no app name either, because nothing it does is attributed.security_posture.pylistsapps/scrub_sdk.pyinNON_EGRESS_REDACTION_MODULESrather than as a sink: the seam owns no output, and registering it would count an egress path as covered on the strength of a call the app may never make. The sink-or-allowlist pin intest_security_posture.pyrequires one or the other.redact_with_findingsis also registered in that test's_BASELINE_REDACTORSset, since it is a new companion-blind entry point.Why it matters
It closes the gap between "the gateway redacts its own output" and "an app redacts the content it publishes on the user's behalf" — at the same strength, through the same active policy — without asking app authors to own a copy of a security control.
On consumers, stated plainly: nothing in-tree calls
ctx.scrubyet. 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 can neither pinkiro_crew.securityat a stable version nor reach the active credential policy. 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: without the seam that app either copies the patterns (a control that drifts) or imports the baseline directly (companion-blind), and both are outcomes this repo's own posture module treats as findings. Theredact_with_findingshalf is independent of that question and lands a real fix either way.Tests
test/test_scrub_sdk.py(9) — a credential is removed and counted; nothing the seam reports can carry a payload (pinned against core's raw warning, which does echo the secret); ordinary prose stays byte-identical (an app may fingerprint what it sent); the seam finishes through the active policy (a companion-only token is removed, andredactedisTruewith both counts at zero); a failed companion composition propagates rather than downgrading; the seam wraps core rather than copying it; the seam owns no ordering of its own; the public surface is exactlyoutbound; every app getsscrubwith no permission declared while a capability SDK still requires its own.Manual verification
N/A — unit coverage is sufficient: the module is a thin, side-effect-free delegation, and each property that could regress silently (companion routing, fail-closed propagation, reference-vs-copy, pass ordering) is pinned by a test rather than by inspection.
Screenshots / video
N/A — no UI.
Related
Sibling of #9545 (
ctx.audit). Both exist so an app can meet the gateway's own security posture without importing built-in-only modules; the consumer question above applies to both.Checklist
docs/system-specs/modules/security.md(the owning spec) anddocs/app-kit/api-reference.md(app authors)flake8/isort/black/mypyclean;docs-lintand the ratchet gates pass