Repository navigation
feat(security): point TPA findings at the offending words, inline in the tool list - #1170
Merged
Merged
Conversation
…the tool list
A scan finding named a tool it would not link to, and quoted a sentence the
scanner had written rather than the words the attacker did. Reading one finding
cost four hops to a report page, and the trail ended there.
Findings now carry a text span, and the server's Tools tab renders the tool's
own description with the flagged passage marked in place.
Backend — spans through the finding chain:
- detect.Span locates a match in a RAW tool text field. Offsets are UTF-16
code units, i.e. JavaScript string indices, so the Web UI's
description.slice(start, end) is exactly right including across surrogate
pairs. Snippet is CapEvidence-escaped and is a staleness checksum only; the
UI renders live text, never the snippet.
- The raw-text checks already had the offsets and discarded them:
tpa_bundle.go computed FindStringIndex to slice evidence, and shadowing's
reference branch used FindAllString where FindAllStringIndex costs nothing.
- aggregate() unions spans across every signal rather than taking the primary
one. It emits a single Finding per tool, so primary-wins would silently
swallow half the marks on a description that trips two checks.
- The clone branch deliberately emits no span: its evidence is token-set
containment over the whole description, not a located substring, and
marking an arbitrary word would claim a precision it does not have.
Frontend — highlighting that cannot become the attack:
- segmentByFindings is a boundary sweep, not interval nesting: overlapping
spans collapse into one segment carrying several sources, so text is never
dropped, duplicated or nested. A unit test pins segments.join('') === text.
- Every upstream character reaches the DOM through interpolation. No v-html
anywhere, guarded by a test that reads the component source, because these
descriptions are attacker-authored by definition.
- A span whose snippet no longer matches the live description is dropped, not
relocated. There is no indexOf fallback: a short token in a long
description makes guessing a coin flip that confidently marks innocent
prose. Stale spans degrade to today's plain rendering plus a note.
- Findings for a server group onto its tools by location, split on the last
colon — server names contain dots and slashes.
Verified end to end against a live instance: the whole <IMPORTANT> block on a
poisoned tool and the single word "reason" on a false positive both mark
correctly, two bundle rules matching one range collapse to one mark, and an
unflagged description renders byte-identical to before.
The shadowing.cross_server reference demote to soft tier is approved but not in
this change: a tier change only reaches an install on rescan, and nothing
invalidates a report when the ruleset changes. It ships with the Phase 3
rescan trigger. Design and rationale in docs/research/.
Deploying mcpproxy-docs with
|
| Latest commit: |
af020b6
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://cfc2aef0.mcpproxy-docs.pages.dev |
| Branch Preview URL: | https://claude-tpa-scanner-ui-integr.mcpproxy-docs.pages.dev |
|
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
Contributor
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 33529704629 --repo smart-mcp-proxy/mcpproxy-go
|
CodeQL alert 534 (js/incomplete-multi-character-sanitization) on the guard's comment strip was correct, and the consequence was worse than the rule implies. The guard ran each component through /<!--[\s\S]*?-->/g before asserting that no `v-html=` appears, so the component's own header comment — which names v-html in order to forbid it — would not trip the test. A single-pass strip is defeatable: a source containing the literal `<!--` in a string, a real `v-html=` after it, and a `-->` later had the real usage deleted before matching. Demonstrated: raw contains v-html= : true OLD guard (after strip) sees it : false NEW guard (raw) sees it : true So the guard could be silenced by the very code it guards, on the one component that renders attacker-authored tool descriptions. The stripping was never needed. Both patterns require characters the prohibition prose does not contain — `v-html=` needs the equals sign, and no comment in these files mentions innerHTML — so the raw sources match neither. Assert on the raw source and the sanitizer disappears along with its hole. The trade is now a false alarm rather than a silent gap: a future comment written as `v-html=` will fire the guard. The header comment says so, and that is the right direction to fail in.
…trust an unverified one
Two rounds of cross-model review found three ways a STALE span could pass
verification and mark description text that no rule matched. All three shared a
root cause: the checksum did not determine what produced it.
Round 1 - the snippet was ambiguous.
CapEvidence escapes a control rune to the six characters
but leaves an
existing backslash alone, so an escaped newline and the LITERAL text
are indistinguishable in its output. Two different 7-unit strings - a newline
followed by the literal characters, and the literal characters followed by a
vertical tab - produced the same snippet. A description mutating from one to
the other kept its checksum.
Truncation was also SNIFFED rather than declared: any snippet ending in an
ellipsis was prefix-compared, and a tool description may legitimately end a
matched passage that way ("read the docs..."), so a later description sharing
only the prefix verified.
Fixed at the source. CapSpanSnippet escapes the backslash and uses fixed-width
escapes per plane, making the per-rune encoding prefix-free: equal snippets
now imply equal inputs. Truncation is a declared field. detect.CapEvidence is
untouched - it feeds Signal.Evidence, which has real Go consumers, and the
browser never sees that value.
Round 2 - an absent checksum was a free pass.
isSpanUsable returned true when a span carried no snippet. That is reachable,
not theoretical: ScanFinding.Spans is `json:"spans,omitempty"` and
engine.parseResults unmarshals a THIRD-PARTY scanner's report straight into
[]ScanFinding, so "no snippet" is exactly the wire shape of a span this proxy
never computed. Such a span rendered a dangerous mark over arbitrary offsets
with no verification at all.
Closed at both ends. The renderer refuses any description span it cannot
verify, and refuses a truncated snippet shorter than the cap - one matching
character must not license a mark of any length. The backend drops spans
decoded from external scanner output; no bundled scanner emits any, so nothing
real is lost, and detect.DescriptionSpan stays the only producer.
The test helpers defaulted to snippet-less spans, so ten tests had been
exercising the trusted path while reading as though they covered the rendered
one. They now carry the checksum the backend would really have shipped, and the
test that asserted the old free pass asserts its opposite.
Also verified and left alone: aggregate's structural span guard is a real
backstop rather than a duplicate of DescriptionSpan; the claimed excerpt
surrogate-duplication does not reproduce (segmentByFindings never emits two
adjacent unmarked segments); UTF16Offsets("x",2,2) does not panic.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The problem
A scan finding named a tool it would not link to, and quoted a sentence the scanner had written rather than the words the attacker did. Reading one finding cost four hops — Dashboard → Security → scan history → report → expand — and the trail ended at an inert
<code>block:Location: com.googleapis.sqladmin/mcp:create_user.What changes
Findings carry a text span, and the server's Tools tab renders the tool's own description with the flagged passage marked in place.
Backend — spans through the finding chain
detect.Spanlocates a match in a raw tool text field. Offsets are UTF-16 code units (JavaScript string indices), so the Web UI'sdescription.slice(start, end)is exactly right including across surrogate pairs.SnippetisCapEvidence-escaped and serves as a staleness checksum only — the UI renders live text, never the snippet.The raw-text checks already had the offsets and threw them away:
tpa_bundle.gocomputedFindStringIndexto slice evidence, and shadowing's reference branch usedFindAllStringwhereFindAllStringIndexcosts nothing.aggregate()unions spans across every signal rather than taking the primary one. It emits a singleFindingper tool, so primary-wins would silently swallow half the marks on a description that trips two checks.The clone branch deliberately emits no span: its evidence is token-set containment over the whole description, not a located substring.
Phase 1 needs no new endpoint and no
contracts.tsregeneration —loadScanReport()already runs on mount for every tab ofServerDetail.vue, so the findings are already in the browser next to the tool list.Frontend — highlighting that cannot become the attack
segmentByFindingsis a boundary sweep, not interval nesting: overlapping spans collapse into one segment carrying several sources, so text is never dropped, duplicated or nested. A unit test pinssegments.join('') === text.v-htmlanywhere, guarded by a test that reads the component source — these descriptions are attacker-authored by definition.indexOffallback: a short token in a long description makes guessing a coin flip that confidently marks innocent prose. Stale spans degrade to today's plain rendering plus a note.Verification
End to end against a live instance with two throwaway stdio servers:
fetch_notes— the whole<IMPORTANT>…read ~/.ssh/id_rsa…</IMPORTANT>block marked; two bundle rules matching the identical range collapsed into one mark carrying both check ids.create_user— just the wordreasonmarked, at[161,167).list_buckets— unflagged, renders byte-identical to before (110 chars in, 110 out).Round-trip holds against the live DOM: stripping
sr-onlylabels and glyphs returns the API's description character-for-character. An emoji-prefix probe emits offset 30 where the byte offset is 34 and the rune offset is 29 — genuinely UTF-16.go build ./...clean ·./internal/security/...green with-race· golangci-lint v20 issues· vitest1151 passed (1151)· detection eval gaterecall=1.0000, fp=0.0000against the unmodified corpus.Deliberately not in this PR
The
shadowing.cross_serverreference branch demote from hard to soft tier is approved but deferred. A tier change only reaches an install on rescan —ThreatLevelandtierare persisted as data and nothing invalidates a report when the ruleset changes — so shipping it now would fix new scans and silently leave every existingdangerousverdict standing. The stale direction is the safe one (over-flagging), and the measured blast radius is 7 of 947 findings across 3 of 19 scanned servers. It ships with the Phase 3 bundle-fingerprint rescan trigger, which has to invalidate stale reports anyway.TestShadowing_ReferenceOnOrdinaryProseIsSpannedAndStillHardpins today's behaviour and names itself as the test to flip.Design, rationale and the phase plan:
docs/research/tpa-scanner-inline-ui-design.md.