Skip to content

feat(security): point TPA findings at the offending words, inline in the tool list - #1170

Merged
Dumbris merged 3 commits into
mainfrom
claude/tpa-scanner-ui-integration-2cb408
Sep 1, 2026
Merged

Dumbris merged 3 commits into
mainfrom
claude/tpa-scanner-ui-integration-2cb408

Conversation

@Dumbris

@Dumbris Dumbris commented Sep 1, 2026

Copy link
Copy Markdown
Member

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.Span locates a match in a raw tool text field. Offsets are UTF-16 code units (JavaScript string indices), so the Web UI's description.slice(start, end) is exactly right including across surrogate pairs. Snippet is CapEvidence-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.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.

Phase 1 needs no new endpoint and no contracts.ts regeneration — loadScanReport() already runs on mount for every tab of ServerDetail.vue, so the findings are already in the browser next to the tool list.

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 — these descriptions are attacker-authored by definition.
  • A span whose snippet no longer matches the live description is dropped, not relocated. 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 group onto tools by location, split on the last colon — server names contain dots and slashes.

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 word reason marked, 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-only labels 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 v2 0 issues · vitest 1151 passed (1151) · detection eval gate recall=1.0000, fp=0.0000 against the unmodified corpus.

Deliberately not in this PR

The shadowing.cross_server reference branch demote from hard to soft tier is approved but deferred. A tier change only reaches an install on rescan — ThreatLevel and tier are persisted as data and nothing invalidates a report when the ruleset changes — so shipping it now would fix new scans and silently leave every existing dangerous verdict 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_ReferenceOnOrdinaryProseIsSpannedAndStillHard pins 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.

…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/.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Sep 1, 2026 •

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

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

View logs

@codecov-commenter

codecov-commenter commented Sep 1, 2026 •

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 92.42424% with 10 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/security/detect/aggregate.go 87.50% 2 Missing and 2 partials ⚠️
internal/security/scanner/sarif.go 81.81% 2 Missing and 2 partials ⚠️
internal/security/detect/span.go 96.82% 1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: claude/tpa-scanner-ui-integration-2cb408

Available Artifacts

  • archive-darwin-amd64 (29 MB)
  • archive-darwin-arm64 (26 MB)
  • archive-linux-amd64 (17 MB)
  • archive-linux-arm64 (15 MB)
  • archive-windows-amd64 (29 MB)
  • archive-windows-arm64 (26 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (23 MB)
  • installer-dmg-darwin-arm64 (21 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 33529704629 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

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.
@Dumbris
Dumbris merged commit b4a586a into main Sep 1, 2026
42 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants