DescriptorPin - Defensive integrity monitor for MCP tool descripto

项目说明

<di="center">

<img src="docs/assets/banner.svg" width="100%"
alt="DescriptorPin banner: defensi monitor for MCP tool descriptors, with a scan output card listing mutation, shadow, poison, and transport findings." />

DescriptorPin

*Pins the tool descriptors an MCP client trusts, then reports silent mutation,
cross-ser, instruction-shaped description text, and stdio
transport risk.*

Install &nbsp;&middot;&nbsp;
Commands &nbsp;&middot;&nbsp;
Finding classes &nbsp;&middot;&nbsp;
The pin file &nbsp;&middot;&nbsp;
Limitations

</div>

---

The descriptor trust problem

A Model Context Protocol client reads a server's tool list and shows it to a
person who approves it once. Every call after that appro tools by
name. Nothing in the protocol asks the client to notice when a description
changes, when a second ser exposing a tool with a name that is
already trusted, or when a description stops documenting a tool and starts
instructing the model that reads it.

DescriptorPin treats the appro as the anchor. It records a canonical
hash for every tool descriptor at approval time, and on each later scan it
reports the shapes that differ from that anchor. The output names fields and
servers; it ne a single opaque score.

What it checks

| Property | Mechanism |
|---|---|
| A tool that was approved, then silently changed | Canonical hash per descriptor compared by src/descriptorpin/mutation.py against the pin written by src/descriptorpin/pin.py |
| Two servers claiming the same bare tool name | Grouping across servers in src/descriptorpin/shadow.py, with the precedence risk stated |
| Description text shaped like instructions to the model | Named structural signals with weights in src/descriptorpin/poison.py |
| A ser o | Transport review in src/descriptorpin/transport.py, because a config entry can become command execution |
| Hash churn from key order or whitespace | Deterministic serialisation in src/descriptorpin/canon.py so only value changes move the hash |
| Stable, diffable reports | Line-oriented rendering in src/descriptorpin/report.py, no clock and no randomness |

Install

Standard library only. There is nothing to install at runtime and no network
access anywhere in the code.

Commands

| Command | Reads | Reports |
|---|---|---|
| pin | one in | writes a pin file recording the appro state |
| scan | a pin and an in | every finding class below |
| diff | a pin and an in | rug pull mutations only |
| shadow | one in | cross-server name collisions only |
| | nothing | the string |

Exit codes: 0 clean, 1 findings present, 2 usage or input error.

A real scan

The bundled samples ship a clean in, a pin recorded from it, and a
mutated in that differs in the ways the tool exists to catch. Running
make run on this repository prints:

One mutation, one shadow, one poison, one transport, each line naming the
tool or server it concerns. The scan exits 1.

Finding classes

| Class | Shape it describes | First action |
|---|---|---|
| MUTATION | A pinned tool whose canonical descriptor hash changed | Read the field diff, then re-approve or reject |
| ADDED | A tool present in the in but absent from the pin | Approve it explicitly or remove the server |
| SHADOW | One bare name claimed by two or more servers | Decide the resolution order or rename a tool |
| POISON | Description text that fires one or more named instruction signals | Read the fired signals and judge the text |
| TRANSPORT | A ser o | Treat the config entry as executable content |

The pin file

pin records, per tool: the ser key, the canonical descriptor
hash, a truncated digest for reading, the canonical descriptor itself, and an
appro with the approver and their note. Keeping the canonical
descriptor in the pin is what lets a later diff show the exact field that
changed, instead of only reporting that something did.

The pin is a plain JSON document. Commit it, review it in pull requests, and
treat a change to it as a change to what the client trusts.

Canonicalisation

Two servers can serialise the same descriptor with different key order or
insignificant whitespace. canon.py folds those differences before hashing,
so the pin does not churn on formatting and a real value change cannot hide
behind reordering. The fold is deterministic: identical input produces
byte-identical output, and the reports that follow sort deterministically too.

Quality gate

scripts/.py is the repository's mechanical gate. It checks the SVG
assets, the em dash sweep, the README rules, and the label o rule in
the assets. Run on this repository it prints:

make test runs the unit suite, make runs the gate, make run
reproduces the scan abo the samples.

Repository layout

Why not hash the raw descriptor bytes

Raw bytes move when key order moves, and a pin that churns on formatting is a
pin nobody reads. Folding through a canonical form first keeps the hash
sensitive to and insensitive to serialisation.

Why not one poison score

A single number invites a threshold, and a threshold invites false comfort.
poison.py reports which named signals fired, each with its own weight, and
leaves the judgement to the reader. A heuristic can fire on innocent text and
can miss a careful attacker; saying so is part of the output.

What DescriptorPin does not do

It does not contact the MCP server. It reads in files on disk, which

is why it runs in CI and on a laptop with no network.

It does not cryptographic signatures. Descriptor integrity here is

against the pin you approved, not against a signed publisher chain.

It does not classify intent. The signal and shape wording is deliberate:

the tool reports structure, and the reader judges.

It does not resol by picking a winner. The collision is the

finding; the client's resolution order decides, and that order is often
undocumented.

Contributing

One topic per commit, con prefixes, tests for behaviour changes, and
no network access in the code. Run make test and make before a
pull request. The suite is standard library unittest only.

License

MIT. See LICENSE.

项目信息

开发语言：Python

Star 数：31

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Defensive integrity monitor for MCP tool descriptors: pins canonical hashes and reports mutation, shadowing, poisoning, and stdio transport risk.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。