Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
1 change: 1 addition & 0 deletions docs/CHECKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ Drift items are emitted as SARIF/JSONL results with `ruleId = WRD-DRIFT-<CLASS>`
| `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/<name>`).
Expand Down
6 changes: 6 additions & 0 deletions docs/SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 4 additions & 0 deletions docs/WARDEN_LOCK_SCHEMA.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

---

Expand Down
12 changes: 12 additions & 0 deletions packages/lock-ts/src/drift.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
17 changes: 17 additions & 0 deletions src/mcp_warden/drift.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
32 changes: 32 additions & 0 deletions tests/test_drift.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
119 changes: 119 additions & 0 deletions vectors/cases/drift-digest-mismatch-unexplained.json
Original file line number Diff line number Diff line change
@@ -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
}
]
}
7 changes: 6 additions & 1 deletion vectors/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down
1 change: 1 addition & 0 deletions vectors/tools/generate.py
Original file line number Diff line number Diff line change
Expand Up @@ -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": {}}))),
Expand Down
Loading