From ad5335049399939274c7688506cf618e0bb8fe3b Mon Sep 17 00:00:00 2001 From: Ernest Provo Date: Sat, 24 Oct 2026 19:57:11 +0000 Subject: [PATCH 1/2] fix(drift): a digest mismatch with no per-item diff is drift, never clean (DSE-2125) compute_drift short-circuited only on a digest match. When overall_digest differed but name-keyed indexing collapsed duplicate entries (or a digest- covered field had no item-level check) on an unapproved baseline, it returned [] and check exited 0. After all item diffs, if nothing fired and the digests differ, emit digest-mismatch-unexplained (high). Tests: duplicate-name baseline and a forced digest both yield non-empty drift (both fail without the fix); the finding is not added when items already explain the mismatch. SPEC 6.2 and CHANGELOG updated. Claude-Session: https://claude.ai/code/session_01AsS8oRVvT4oiSCHmk4fkEm --- CHANGELOG.md | 6 ++++++ docs/WARDEN_LOCK_SCHEMA.md | 4 ++++ src/mcp_warden/drift.py | 17 +++++++++++++++++ tests/test_drift.py | 32 ++++++++++++++++++++++++++++++++ 4 files changed, 59 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 45d8ab1..3e952d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,12 @@ Streamable HTTP; the v0.3 `guard` proxy adds deterministic runtime *result* insp ## [Unreleased] +### Fixed + +- `check` no longer passes when `overall_digest` differs but no per-entry drift fires + (e.g. a baseline lock with duplicate tool/resource/prompt keys): it now reports + `digest-mismatch-unexplained` (high) and exits non-zero (DSE-2125). + ## [2.2.0] — 2026-10-24 ### Community corpus layout (DSE-2143) diff --git a/docs/WARDEN_LOCK_SCHEMA.md b/docs/WARDEN_LOCK_SCHEMA.md index 1b90d3b..55576b7 100644 --- a/docs/WARDEN_LOCK_SCHEMA.md +++ b/docs/WARDEN_LOCK_SCHEMA.md @@ -254,6 +254,7 @@ stored `warden.lock`. Drift classes and severities: | **Capability removed** | same `name`, a flag dropped from `capabilities` | **medium** | non-zero | | **Description modified** | same `name`, `description_hash` differs, schema + caps unchanged | **low** | non-zero | | **Resource/prompt add/remove/modify** | analogous to tools (added=medium, removed=low, modified=low) | as noted | non-zero | +| **Digest mismatch, unexplained** | `overall_digest` differs but no per-entry item above fired (e.g. duplicate keys collapsed by name-keyed indexing) | **high** | non-zero | | **No drift** | every entry_digest matches AND `overall_digest` matches | — | **zero** | **Schema drift (SCHEMA_VERSION 2, #15).** When `input_schema_hash` differs *and* both the @@ -299,6 +300,9 @@ Notes: - Drift is computed **per entry** so the SARIF output points at the exact tool that changed. The `overall_digest` is a fast-path: if it matches, there is provably no drift and per-entry diffing can be skipped. +- A digest mismatch is itself drift. If `overall_digest` differs and the per-entry diff + produced no item, `check` emits `digest-mismatch-unexplained` (high, target + `lock/overall_digest`) so a changed surface can never yield a clean verdict. --- diff --git a/src/mcp_warden/drift.py b/src/mcp_warden/drift.py index 15a4432..8a76041 100644 --- a/src/mcp_warden/drift.py +++ b/src/mcp_warden/drift.py @@ -208,6 +208,8 @@ def compute_drift(baseline: WardenLock, current: WardenLock) -> list[DriftItem]: """Compute the full drift set between a baseline lock and a current lock. Fast path: if ``overall_digest`` matches, there is provably no drift (§6.2). + Conversely a digest mismatch is itself drift: when no per-entry item explains + it, a ``digest-mismatch-unexplained`` (high) item is emitted (DSE-2125). Args: baseline: The stored ``warden.lock`` baseline. @@ -281,5 +283,20 @@ def compute_drift(baseline: WardenLock, current: WardenLock) -> list[DriftItem]: ) ) + # Backstop (DSE-2125): a differing overall_digest means the surface changed. + # If no item-level diff explained it (name-keyed indexing collapsed duplicate + # entries, or a digest-covered field has no item-level check), the verdict must + # still never be clean -- fail closed with an explicit unexplained finding. + if not items: + items.append( + DriftItem( + "digest-mismatch-unexplained", + "high", + "lock/overall_digest", + "overall_digest differs from the baseline but no per-entry change was identified " + "(e.g. duplicate tool/resource/prompt keys in a lock); review the surface and re-pin", + ) + ) + items.sort(key=lambda d: (d.target, d.drift_class)) return items diff --git a/tests/test_drift.py b/tests/test_drift.py index 7048834..83eaee3 100644 --- a/tests/test_drift.py +++ b/tests/test_drift.py @@ -253,3 +253,35 @@ def test_relaxed_ref_def_across_v2_v3_boundary_blocks_high(monkeypatch): assert any( d.target == "tools/t" and d.drift_class == "schema-constraint-relaxed" for d in drift ) + + +def test_digest_mismatch_without_item_diff_is_drift_unapproved(): + """DSE-2125: duplicate-name entries collapse in the name-keyed index, so a change to the + shadowed (first) duplicate moves overall_digest with no per-item diff. Must not be clean.""" + def tools(first_desc): + return [ + CapturedTool(name="a", description=first_desc, input_schema={}), + CapturedTool(name="a", description="same", input_schema={}), + ] + base = _lock(_surface(tools("one"))) + cur = _lock(_surface(tools("two"))) + assert base.overall_digest != cur.overall_digest + assert not base.pin.approved + drift = compute_drift(base, cur) + unexplained = [d for d in drift if d.drift_class == "digest-mismatch-unexplained"] + assert drift and unexplained and unexplained[0].severity == "high" + + +def test_digest_mismatch_without_item_diff_is_drift_forced_digest(): + s = _surface([CapturedTool(name="read_file", description="d", input_schema={})]) + base = _lock(s) + cur = _lock(s).model_copy(update={"overall_digest": "0" * 64}) + drift = compute_drift(base, cur) + assert [d.drift_class for d in drift] == ["digest-mismatch-unexplained"] + + +def test_unexplained_finding_not_added_when_items_explain_the_mismatch(): + base = _lock(_surface([CapturedTool(name="a", input_schema={})])) + cur = _lock(_surface([CapturedTool(name="a", input_schema={}), CapturedTool(name="b", input_schema={})])) + classes = {d.drift_class for d in compute_drift(base, cur)} + assert "tool-added" in classes and "digest-mismatch-unexplained" not in classes From 8126bd0f135bb11181d7a4ede6e1548e29eb7b6e Mon Sep 17 00:00:00 2001 From: Ernest Provo Date: Sat, 24 Oct 2026 20:06:34 +0000 Subject: [PATCH 2/2] fix(drift): TS verifier parity, conformance vector, spec rows (DSE-2125) CSO review: the TypeScript verifier shared the fail-open. Add the same digest-mismatch-unexplained backstop to packages/lock-ts, a drift conformance vector (duplicate-name baseline) generated from the Python reference, and the SPEC section 8 / CHECKS 2.1 entries. The schema-version-migrated advisory still counts as explaining the mismatch: a legacy unapproved lock differs by format alone and already exits non-zero. Claude-Session: https://claude.ai/code/session_01AsS8oRVvT4oiSCHmk4fkEm --- docs/CHECKS.md | 1 + docs/SPEC.md | 6 + packages/lock-ts/src/drift.ts | 12 ++ .../drift-digest-mismatch-unexplained.json | 119 ++++++++++++++++++ vectors/manifest.json | 7 +- vectors/tools/generate.py | 1 + 6 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 vectors/cases/drift-digest-mismatch-unexplained.json diff --git a/docs/CHECKS.md b/docs/CHECKS.md index da5c4b8..529302b 100644 --- a/docs/CHECKS.md +++ b/docs/CHECKS.md @@ -69,6 +69,7 @@ Drift items are emitted as SARIF/JSONL results with `ruleId = WRD-DRIFT-` | `WRD-DRIFT-SCHEMA-COSMETIC-MODIFIED` | note (low) | schema bytes differ, structure identical | | `WRD-DRIFT-SCHEMA-MODIFIED` | error (high) | v1-lock fallback / **unresolvable** opaque-leaf `$ref` change | | `WRD-DRIFT-SCHEMA-VERSION-MIGRATED` | note (low) | lock schema-format upgrade (v2→v3) moved the digest; advisory only (#29) | +| `WRD-DRIFT-DIGEST-MISMATCH-UNEXPLAINED` | error (high) | `overall_digest` differs but no per-entry item explains it (e.g. duplicate keys); never a clean verdict (DSE-2125) | Schema-drift results additionally carry `properties.detail` (a compact, non-secret summary, e.g. `maxLength 64→4096`) and `properties.schemaPath` (the changed entry, `tools/`). diff --git a/docs/SPEC.md b/docs/SPEC.md index 64e6ff8..8308494 100644 --- a/docs/SPEC.md +++ b/docs/SPEC.md @@ -252,6 +252,12 @@ emit low `schema-out-cosmetic-modified`; missing skeletons fall back to high `schema-out-modified`. SARIF prefixes these with `WRD-DRIFT-`, including `WRD-DRIFT-SCHEMA-OUT-TYPE-BROADENED`. +A differing `overall_digest` is itself drift. If it differs and the per-entry diff produced +no item (for example a baseline with duplicate tool/resource/prompt keys, which name-keyed +indexing collapses), an implementation MUST emit high `digest-mismatch-unexplained` (target +`lock/overall_digest`) so the verdict is never clean. Any other item, including the +`schema-version-migrated` advisory, already explains the mismatch and suppresses it. + ### 8.1 Overall digest diff --git a/packages/lock-ts/src/drift.ts b/packages/lock-ts/src/drift.ts index 9fe6b3b..640ac89 100644 --- a/packages/lock-ts/src/drift.ts +++ b/packages/lock-ts/src/drift.ts @@ -331,6 +331,18 @@ export function computeDrift(baseline: Lock, current: BuiltLock): DriftItem[] { } } + // Backstop (DSE-2125): a digest mismatch no item explains must never verify clean. + if (items.length === 0) { + items.push( + item( + "digest-mismatch-unexplained", + "high", + "lock/overall_digest", + "overall_digest differs from the baseline but no per-entry change was identified (e.g. duplicate tool/resource/prompt keys in a lock); review the surface and re-pin", + ), + ); + } + items.sort((x, y) => cmpCodepoint(x.target, y.target) || cmpCodepoint(x.drift_class, y.drift_class)); return items; } diff --git a/vectors/cases/drift-digest-mismatch-unexplained.json b/vectors/cases/drift-digest-mismatch-unexplained.json new file mode 100644 index 0000000..4c3bdd4 --- /dev/null +++ b/vectors/cases/drift-digest-mismatch-unexplained.json @@ -0,0 +1,119 @@ +{ + "id": "drift/digest-mismatch-unexplained", + "kind": "drift", + "description": "A baseline with duplicate tool names: the shadowed first duplicate changes, name-keyed diffing sees nothing, yet overall_digest differs -> digest-mismatch-unexplained (high), never a clean verdict.", + "lock": { + "schema_version": 4, + "warden_version": "0.0.0", + "server": { + "command": "python", + "args": [ + "server.py" + ], + "url": null, + "command_digest": "sha256:b42e4fe9ab2871e34b4115b0f7a8a762c2e2fd3712805c4e323da999456eeb77" + }, + "tools": [ + { + "name": "a", + "description_hash": "sha256:49e9fcfb5617aad332d56d58ffd0c7020d29ec1d0d0a03b7d7c47f268820acf3", + "input_schema_hash": "sha256:efddc7bd8bbcef73a14eb1ace1ffdaec81e518ef1e13c1e9271d0b8acb694a49", + "capabilities": [], + "schema_skeleton": { + "props": { + "$root": { + "type": [ + "object" + ], + "required": false, + "enum": null, + "constraints": { + "additionalProperties": true + } + } + } + }, + "annotations_hash": "sha256:74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b", + "output_schema_hash": "sha256:74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b", + "output_schema_skeleton": null, + "entry_digest": "sha256:2d8c4084daa010804bd17d176ad23efd75cb5a090341e68e7ea1dd0d48a9fcf4" + }, + { + "name": "a", + "description_hash": "sha256:106c4202d3d02a3ff34000f19889ac489e6a40f2ee68ea9e3984633ab059dd4d", + "input_schema_hash": "sha256:efddc7bd8bbcef73a14eb1ace1ffdaec81e518ef1e13c1e9271d0b8acb694a49", + "capabilities": [], + "schema_skeleton": { + "props": { + "$root": { + "type": [ + "object" + ], + "required": false, + "enum": null, + "constraints": { + "additionalProperties": true + } + } + } + }, + "annotations_hash": "sha256:74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b", + "output_schema_hash": "sha256:74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b", + "output_schema_skeleton": null, + "entry_digest": "sha256:3ec940342d024cc39e7567d7e044d7932b8f1292dde0686df95feec2b0d4d851" + } + ], + "resources": [], + "prompts": [], + "findings": [], + "overall_digest": "sha256:e39b92e8eee4119c53c7f63034babc49b719de4c79b357d40b0cdf0022f1d0af", + "pin": { + "created_at": "2026-01-01T00:00:00Z", + "warden_version": "0.0.0", + "mcp_protocol_version": "2025-06-18", + "approved": false, + "approver": null, + "approved_at": null, + "approved_digest": null, + "provenance_version": 1, + "pinner": null, + "attestations": [], + "rotated_at": null, + "rotation_count": 0 + } + }, + "surface": { + "command": "python", + "args": [ + "server.py" + ], + "tools": [ + { + "name": "a", + "description": "two", + "inputSchema": { + "type": "object", + "properties": {} + } + }, + { + "name": "a", + "description": "same", + "inputSchema": { + "type": "object", + "properties": {} + } + } + ], + "resources": [], + "prompts": [] + }, + "expect": [ + { + "drift_class": "digest-mismatch-unexplained", + "severity": "high", + "target": "lock/overall_digest", + "detail": null + } + ] +} diff --git a/vectors/manifest.json b/vectors/manifest.json index a54964a..a752f60 100644 --- a/vectors/manifest.json +++ b/vectors/manifest.json @@ -2,7 +2,7 @@ "format": "mcp-lock-v1", "schema_version": 4, "generator": "vectors/tools/generate.py", - "count": 111, + "count": 112, "vectors": [ { "id": "canonical/sorted-keys-utf16", @@ -149,6 +149,11 @@ "kind": "drift", "file": "cases/drift-server-identity-url.json" }, + { + "id": "drift/digest-mismatch-unexplained", + "kind": "drift", + "file": "cases/drift-digest-mismatch-unexplained.json" + }, { "id": "drift/tool-added", "kind": "drift", diff --git a/vectors/tools/generate.py b/vectors/tools/generate.py index 0bd90b8..52aad8a 100644 --- a/vectors/tools/generate.py +++ b/vectors/tools/generate.py @@ -361,6 +361,7 @@ def schema_pair( ("no-drift", "Identical surface: overall_digest matches, the drift set is empty.", _SIMPLE, _SIMPLE), ("server-identity", "argv changed -> server-identity (critical).", one_tool_surface(obj({}), args=["server.py"]), one_tool_surface(obj({}), args=["other.py"])), ("server-identity-url", "HTTP endpoint changed -> server-identity (critical).", one_tool_surface(obj({}), url="https://a.example.com/mcp"), one_tool_surface(obj({}), url="https://b.example.com/mcp")), + ("digest-mismatch-unexplained", "A baseline with duplicate tool names: the shadowed first duplicate changes, name-keyed diffing sees nothing, yet overall_digest differs -> digest-mismatch-unexplained (high), never a clean verdict.", surface([tool("a", obj({}), "one"), tool("a", obj({}), "same")]), surface([tool("a", obj({}), "two"), tool("a", obj({}), "same")])), ("tool-added", "A new tool name -> tool-added (high).", surface([tool("a", obj({}))]), surface([tool("a", obj({})), tool("b", obj({}))])), ("tool-removed", "A tool disappeared -> tool-removed (medium).", surface([tool("a", obj({})), tool("b", obj({}))]), surface([tool("a", obj({}))])), ("capability-added", "A command-like property appears -> capability-added shell-exec (high) plus the schema facts.", one_tool_surface(obj({"x": {}})), one_tool_surface(obj({"command": {}}))),