# Threat model `agent-sanitizer` defends the boundary where untrusted text enters an agent-driven pipeline (agent tool output, RAG retrieval, fetched web pages). It is a detect/neutralize layer, not an enforcement boundary: it makes hidden content visible-or-gone and surfaces exfil-shaped URLs, so the model and the operator see the same thing. Egress controls remain your enforcement layer. Five sanitization layers are documented below — invisible characters/ANSI (1), hidden HTML (2), exfil URLs and confusable hosts (3), secret redaction (4, an injected redactor) and injection filtering (5, an injected filter the caller wires) — plus the entry points built on them: confusable folding, instruction-file scanning, the user-prompt verdict and edit rehydration. All are independent; use only the ones your ingress needs. The README's [entry-point table](./README.md#entry-points) maps each to its import. ## Layer 1—invisible characters & ANSI (zero-dependency) **What it removes** | Category | Examples | Why it’s a payload channel | | -------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | Format chars (`Cf`) | zero-width space/joiner, bidi overrides, Unicode **tag** chars | render blank but reach the model as bytes; tags smuggle ASCII | | Variation selectors | U+FE00–FE0F, U+E0100–E01EF | not `Cf`; a run encodes a hidden payload | | Blank-rendering fillers | Hangul fillers U+115F/1160/3164/FFA0, Braille blank U+2800, zero-width combining marks (`Mn`) U+034F/17B4/17B5 | render blank, not `Cf`, so a naive `\p{Cf}` strip misses them | | Soft hyphen / interior BOM | U+00AD, interior U+FEFF | either can encode hidden instructions | | ANSI / SGR escapes | `ESC[…m`, cursor moves, OSC | repaint or hide what an operator reads in a terminal | **What it preserves** - A **single leading BOM** (a legitimate marker); interior BOMs are stripped. - **ZWNJ (U+200C) / ZWJ (U+200D)** in genuine linguistic context: between two letters of a script whose orthography requires them (Arabic, Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam, Sinhala) or inside an emoji ZWJ sequence. The carve-out fires only when **both** neighbors clearly belong to the context, and it is disabled once the total invisible count crosses a scatter floor—over-stripping beats under-stripping. - **Blank fillers doing real work in their own script**: the Braille blank (U+2800) beside a real cell, a Hangul filler beside a real jamo/syllable. A _run_ of fillers has only fillers for neighbors, so it fails the anchor and is stripped. Because U+2800 _is_ the word space of Unicode Braille and a Hangul filler completes a defective syllable, these are far denser in genuine text than joiners are, so they carry their own document-wide allowance—one preserved blank per two visible anchor-script characters, above a floor—rather than drawing on the joiner/selector preserve budget. The allowance is counted per script (a blank never anchors cross-script, so Korean prose must not fund a Braille channel). Past that ratio no blank of that script is preserved (never half-spaced) and all of them count as payload, which is the density an alternating `syllable filler …` channel needs. Contracted (grade-2) Braille sits closest to the boundary: alphabet wordsigns are single cells, so a passage of mostly one-cell words approaches 1:1 and is stripped like the channel—an accepted residual false positive inherent to a density rule, not a gap, and not worth widening the ratio to reach. **Reassembly hardening.** The two passes feed each other in _both_ directions: stripping an invisible char can reconstitute an ANSI escape its split had hidden, removing one ANSI sequence can reconstitute another, and removing an ANSI sequence can make two invisibles adjacent that were not—a joiner run the invisible pass treats as a payload channel rather than as linguistic. So Layer 1 does not run a fixed sequence of passes; it iterates the whole {ANSI, invisible} composition to a fixed point (bounded, since each round deletes at least one character), and only once that is stable does it sweep any residual raw control introducer—7-bit ESC (U+001B) or any 8-bit C1 control (U+0080–U+009F)—outright. Sweeping earlier would strand a hidden control as visible text; a final unconditional sweep after the loop keeps the no-raw-introducer guarantee independent of the iteration bound. The result carries no raw ANSI introducer for _any_ input, and re-cleaning it reproduces it exactly—the idempotence the Edit-repair rehydrator's soundness gate assumes. One tokenizer answers every ANSI question (what to splice, and whether what was removed was INERT—display-only SGR colour, or a lone 7-bit `ESC` that opened nothing at all), so the stripper and the operator warning cannot disagree about what a sequence is. That inert/injection-shaped split is one input to the [severity tier](#severity-warnings-vs-notes) that keeps the warning worth reading: a stray `ESC` sitting in a file is reported as a terse note, while a cursor move, an erase, an OSC string, or a raw C1 introducer (which no legitimate UTF-8 text carries, and which includes the DCS/SOS/PM/APC string introducers) keeps the WARNING. An `ESC` that _opened_ a CSI it never completed stays loud too: a terminal's CSI parser is stateful and keeps consuming what follows until a final byte arrives, so `ESC[12 world` shows the human `orld` while the model reads every word—the same model-sees/human-sees divergence a complete sequence buys. All five ECMA-48 control strings—OSC (titles, clickable-hyperlink URLs), DCS, SOS, PM and APC—are consumed as a whole, for every terminator form—ST (`ESC\` or 8-bit C1 ST U+009C) and the legacy BEL—and for the 8-bit C1 introducers (U+0090/0098/009D/009E/009F); an _unterminated_ introducer is dropped through end-of-string (fail-closed), so no string body survives to carry a payload. Every one of those bodies is attacker-controlled text, which is why the introducer alone is not enough to remove. ## Layer 2—hidden HTML (remark/rehype) For web/HTML ingress, splice out hidden **elements** — markup a human viewing the rendered page cannot see: - elements hidden by inline style: `display:none`, `visibility:hidden`, `content-visibility:hidden`, `opacity:0`, `filter:opacity(0)`, off-screen positioning, zero/negative sizes, `text-indent` off-screen, collapsing `clip`/`clip-path`/`transform:scale(0)`, white-on-white / transparent text, `overflow:hidden` with a zero dimension - elements hidden by attribute: `hidden` (`aria-hidden="true"` is **not** spliced — it removes an element only from the accessibility tree; a sighted human still sees it on the rendered page) Spliced ranges are replaced with a placeholder; **every byte outside a spliced range is preserved verbatim** (no re-serialization). Unclosed hidden markup extends to the end of the fragment—fail-closed for truncated input. Scripting/resource tags (`script`, `style`, `object`, `embed`, `iframe`, `svg`, `math`) and `data:` URI resources are **reported, not removed**: their bodies are page source the model may legitimately need to inspect. HTML comments (``, and the bogus ``/`` forms) are spliced like hidden elements — a human viewing the rendered page never sees them. But comments are also ubiquitous in _legitimate_ markdown/HTML (PR templates, tooling marker comments), so a destructive splice corrupts real content: an agent that reads a spliced body and writes it back persists the loss. Every Layer-2 splice is therefore **round-trippable**: the placeholder carries a content-addressed key (`[HTML comment removed #]`, `[hidden HTML removed #]`, key = first 12 hex chars of the original bytes' SHA-256), the result exposes the vetted originals in `splices`, and the hook layer persists each original beside the reveal sidecar and restores it when the model writes the placeholder back through Edit/Write. The model never sees the hidden content; the bytes are never lost. A comment-borne injection is additionally covered by Layer 3, which scans the **original** text (comments included) for exfil-shaped URLs. ## Layer 3—exfil URLs (detection only) Report—never rewrite—URLs in markdown links/images/definitions and HTML attributes (`src`/`href`/`background`/`srcset`/`ping`, form `action`/`formaction`, `meta refresh`) that are shaped to carry data off-origin: - suspicious query/fragment parameters (long base64/hex blobs, credential-shaped tokens), tuned to skip request-signing / pagination / analytics parameters that are legitimately long (`X-Amz-*`, SAS, `cursor`, `utm_*`, `gclid`, …) - oversized or active-content (`text/html`, `image/svg+xml`, JS) `data:` URIs - embedded `user:password@host` credentials - unusually long query strings or fragments - encoded-data blobs smuggled in a path segment (a beacon that avoids the query) - off-origin form actions and `meta refresh` redirects - `javascript:` / `vbscript:` targets **The digest exemption, and the switch that lifts it.** A value that is exactly one digest width of hex (32/40/56/64/96/128) under a generic parameter name reads as a fingerprint, not a payload: a cache-buster `?v=`, an ETag, a request id, a git commit, imgix's `?s=`. Under a name that already says credential the same characters read as payload and still flag. That leaves a residual, because the caller writing the URL picks the name: a payload padded to exactly one digest length rides under a generic one, buying 16 to 64 bytes per parameter. `flagDigestValues` moves the trade-off — it drops the exemption entirely, at the cost of flagging every real fingerprint — for a caller whose job is monitoring rather than presenting text to a model. Like every Layer 3 option it can only ADD detection; there is no switch that turns a report off. Each threat carries a `reason` and the destination `target` (never the payload-bearing query/fragment) — the finding is shown to the operator with the target named and the payload withheld, since re-presenting the exfil payload in the model's context would hand the model the very bytes the finding is about. It also carries `autoFetched`, which is what its [severity](#severity-warnings-vs-notes) turns on: an ``, a stylesheet ``, a `srcset`, a `ping`, a form `action` or a `meta refresh` exfiltrates the moment the content renders, with nobody deciding anything, while an `` or a markdown link cannot until the model chooses to follow it — and the sentence reporting it is precisely the instruction not to. A target whose kind cannot be resolved is treated as auto-fetched (fail closed). ### Confusable hosts The same walk feeds a second, independent detector: a URL whose **host** is a look-alike of an ASCII name (`аpple.com` with a Cyrillic а, all-Cyrillic `раураӏ.com`). It is independent of the exfil-shape test above because a homoglyph domain needs no suspicious query to be the whole attack — `https://аpple.com/docs` is reported while the exfil check stays silent on it. **Why detect and never rewrite.** The fold below rewrites confusables in tool _input_; doing that to a URL in model-facing text would rewrite the attacker's `аpple.com` to the real `apple.com`, laundering the deception into a name the model then reports with confidence. Folding is sound only where the folded value is matched against an ASCII deny target and the original bytes are re-derived. Here the URL is left byte-identical and the finding names the deception. **The rule** applies per DNS label, decoded from punycode with `domainToUnicode` (the URL parser hands back the A-label, which is the punycode rather than the deception). Its two tiers are evidential strength, not attack class — both describe a host that resolves and both deceive the same reader; they differ only in how certain the evidence is: - **WARNING** — the label holds a non-ASCII code point and its _whole_ TR39 skeleton is pure ASCII: it claims to be an ASCII name it is not. That is the same argument the fold gate makes ("folds to pure ASCII"), so it inherits the same precision story — a label keeping an unmapped glyph after skeletoning (`россия` → `poccия`) is a real word in its own script, not a disguise. - **NOTE** — the label carries a cross-script confusable but keeps an unmapped glyph, so it reads as no ASCII name. That is the "unmapped glyph spliced in to suppress the strong rule" shape, and it is equally what an ordinary word with one look-alike letter produces, so the evidence is thin and the finding stays quiet. Scored against `test/data/confusable-hosts.json`, which is the single source for both halves: **zero findings** across 52 real internationalized labels spanning Latin, Cyrillic, Greek, Han, Hiragana, Hangul, Arabic, Devanagari and Thai, and every attack label caught at its declared tier. Recall alone would reward a rule that flags everything, so the false-positive half is the half that makes the number mean anything. **Known false negatives**, each pinned as a test rather than left as a claim: - A label whose disguising glyph has no TR39 ASCII mapping at all — Cyrillic `м` in `мicrosoft`, Greek `ε` in `αρριε`. Nothing marks it as a confusable, so there is no evidence to act on. - **ASCII-only look-alikes** (`Iodash` for `lodash`, `paypaI`, `rn` for `m`) are declared out of scope, not missed by accident. Both this rule and the fold's gate open on a non-ASCII code point being present at all, and `paypaI` holds none, so the class cannot be expressed on either side. This is where the real npm/PyPI typosquats live — those registries are ASCII-only — but flagging `I` against `l` in general text is a precision catastrophe, and a detector nobody trusts is worse than no detector. - A bare URL in text carrying no markdown link and no HTML tag: the Layer-2/3 pre-gate skips the markdown parse entirely, so the walk never runs. Widening that gate would make every URL-bearing string pay the heavy parse, which is a cost for every consumer rather than a fix for this one. Where the gate does open, GFM autolink literals mean bare URLs _are_ covered. ## Layer 4—secret redaction (injected engine) The threat is the reverse of the other layers: not attacker text reaching the model, but a credential in tool output (a `.env` cat, a failing curl, a CI log) reaching a model that will paste it into the next tool call, a commit, or a bug report. **The package bundles no detector.** Layer 4 is an injected `redact(text) => {text, found, note?} | null` callback on `./output`, so the npm package ships no secret engine and a host may supply its own. The Claude Code plugin injects the Python engine from `agent-sanitizer[secrets]` (`python/agent_sanitizer/secrets/engine.py`) over a local daemon; `plugin/scripts/provision-redactor.sh` installs it at SessionStart. **It is the one fail-closed layer.** A redactor that throws — unreachable daemon, engine error — is rethrown from `sanitizeValue` as `CRITICAL: secret redaction failed …` (`src/output.mjs`), so the caller suppresses the output rather than emit a value nothing vetted. That is distinct from an engine that was never provisioned: there the hooks' posture applies, passing the output through with a loud warning by default and suppressing it under `AGENT_SANITIZER_FAIL_OPEN=0`. Either way the gap is announced, never silent. **Lone surrogates are normalized to U+FFFD before the redactor sees the text.** A secret split by an interposed lone surrogate renders as contiguous to the model but arrives broken at the redactor, so without normalization a reconstituted secret survives redaction. Both redact-input paths share one normalizer so they cannot drift. **Detection.** detect-secrets is the single oracle — its bundled plugins plus gitleaks-sourced ones for formats it lacks — extended with a regex for the unquoted `key=value` shapes the keyword detector misses, PEM block collapse, cross-line reassembly of a secret split across lines, and exact-match redaction of caller-supplied env-var **values**. Each hit becomes `[REDACTED: