docs(security): document deterministic tool-scanner detect engine (Spec 076 T022)#780
Merged
Merged
Conversation
… (Spec 076 T022) Adds docs/features/tool-scanner.md covering the offline detect engine behind the built-in tpa-descriptions scanner: - the six checks (unicode.hidden / shadowing.cross_server / payload.decoded — hard tier; directive.imperative / capability.mismatch / secret.embedded — soft tier) - the two-tier model (hard auto-quarantines; soft severity = distinct soft-check count 1->low/2->medium/3+->high; consensus adds to confidence/risk score) - the eval gate (scan-eval --gate --min-recall 0.90 --max-fp 0.05, exit 6 on breach) and its blocking CI wiring in .github/workflows/eval.yml - the offline / no-egress guarantee (no I/O, deterministic, recover-isolated) - normalization rules (raw-text hidden-Unicode + secrets, normalized phrases) Also expands the tpa-descriptions row in security-scanner-plugins.md to point at the new page, links it from Related reading, registers it in the docs sidebar, and checks off T013-T019 + T022 in the Spec 076 tasks checklist. Docs-only change (exempt from TDD per CLAUDE.md). No code touched. Related: Spec 076 (specs/076-deterministic-tool-scanner)
Deploying mcpproxy-docs with
|
| Latest commit: |
a59b4f1
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://dfd6f137.mcpproxy-docs.pages.dev |
| Branch Preview URL: | https://docs-spec076-tool-scanner-mc.mcpproxy-docs.pages.dev |
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 28316259234 --repo smart-mcp-proxy/mcpproxy-go
|
CodexReviewer review of #780: the docs overstated that tpa-descriptions is purely the new two-tier detect engine. The live scanner (internal/security/scanner/inprocess.go) still appends the legacy TPA keyword rules (tpa_hidden_instructions / prompt_injection_in_description / data_exfiltration_in_description) after the detect-engine findings, and those are ThreatLevelDangerous — they block security approve and drive the summary to dangerous (confirmed by e2e_tpa_smoke_test.go). Documents the current coexistence accurately: - tool-scanner.md: scope note on the two-tier table + a new "Coexistence with the legacy TPA rules" subsection + a plug-in-section pointer; the "soft never auto-quarantines" rule is the detect-engine's, not the legacy rules'. - security-scanner-plugins.md: tpa-descriptions row notes the still-active dangerous legacy rules. Folding the legacy rules into the detect engine remains a separate implementation change (out of scope for this docs PR). Related: Spec 076 (specs/076-deterministic-tool-scanner) Co-Authored-By: Paperclip <noreply@paperclip.ing>
![mcpproxy-gatekeeper[bot]](https://avatars.githubusercontent.com/u/216428285?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ Gatekeeper approval — Codex review verdict: ACCEPT.
This approval is posted automatically by the MCPProxy Gatekeeper App on behalf of the Codex reviewer (verdict of record lives in the Paperclip review thread). Author≠approver satisfied; QA + CI gates enforced separately.
Auto-approved per Model B (MCP-1249).
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
2 participants
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.
Summary
Completes T022 from
specs/076-deterministic-tool-scanner/tasks.md, which was not done in the implementation PRs (#769–#777). Documentation only — no code changes.Adds a dedicated
docs/features/tool-scanner.mddescribing the offline detect engine (internal/security/detect/) that powers the built-intpa-descriptionsscanner:unicode.hidden,shadowing.cross_server,payload.decoded(hard tier);directive.imperative,capability.mismatch,secret.embedded(soft tier), each with what it catches and its FP controls.scan-eval --gate --min-recall 0.90 --max-fp 0.05, exit code 6 on breach, the hard-negative-only FP gate, and the forward-compatible category gating; plus its blocking CI step in.github/workflows/eval.yml(security-d2).recover()-isolated checks.Also:
tpa-descriptionsrow insecurity-scanner-plugins.mdto summarize the two tiers and link the new page; adds it to Related reading.features/tool-scannerin the docs sidebar.Provenance
Every claim is sourced from the code on
main: check IDs/tiers frominternal/security/detect/checks/*.go, aggregation fromaggregate.go, the gate fromcmd/scan-eval/gate.go, CI wiring from.github/workflows/eval.yml, and the offline contract frominternal/security/detect/doc.go.Testing
Docs-only change (exempt from TDD per
CLAUDE.md). Pre-commit hooks (trailing whitespace, EOF, merge-conflict, gofmt) passed. No Go code touched.Related: Spec 076 — MCP-3683