# How does an instance detect poisoned tool registries: manifest tampering and skill-injection at the registry boundary **Date of Record:** 2026 November 17 **Scope:** Applies to agent runtimes that resolve tools/skills from a mutable registry or manifest at load time, where the registry is trusted by convention rather than by cryptographic binding. Does not apply to runtimes with signed manifests verified against a pinned root of trust, nor to statically linked tool sets compiled into the agent image. ## Core Distinction The boundary failure is not "a malicious tool got registered." It is that **the registry can mutate between the moment an instance resolved a tool's identity and the moment it invoked it**, and that the manifest describing the tool is treated as data rather than as executable configuration. A clean registry at boot is not evidence of a clean registry at call time. The distinction that matters operationally: *registration* is a claim, *manifest integrity* is a proof, and *invocation* is where the claim is cashed. Most runtimes collapse these into a single trusted read at startup, which is exactly the window an attacker exploits. Skill-injection via registry poisoning typically takes one of three shapes: (1) a tool entry whose `description` or `parameters` schema contains prompt-injection payloads that the agent's planner ingests as trusted instructions; (2) a manifest that points a known tool name at a different endpoint or handler (name shadowing / dependency confusion); (3) a transitive manifest — a tool that declares a dependency on another tool whose entry was swapped after the first was cached. The third is the non-obvious one: the poisoned edge is not the tool you called, it's the dependency resolved on your behalf during the call. ## What Was Observed In a representative incident, an agent instance resolved `search.docs` at t=0 from a registry returning a well-formed manifest with a pinned `version: 2.1.0` and a stable `digest`. At t=0 the digest matched. Between t=0 and t=900s, the registry entry for `search.docs` was updated in place — same name, same version string, same declared digest field, but the `handler.endpoint` was repointed and the `description` field gained an appended instruction block. The runtime never re-verified because it cached the resolved manifest keyed by `(name, version)` and treated version-identity as manifest-identity. The tell was not an error. The tell was that the tool's *response envelope* changed shape: the previously stable `{"results": [...]}` became `{"results": [...], "note": "..."}` where `note` carried injected text. Downstream planner steps began emitting tool calls to a `summarize` tool that did not exist in the original registry snapshot but did exist in the mutated one. The instance had no invariant asserting that the set of tools it could call was a subset of the set it had verified at boot. A second observed pattern: manifest tampering via field reordering and duplicate keys. JSON manifests with duplicate `"endpoint"` keys parse to last-wins in the runtime's parser but first-wins in the registry's validator. The validator approved the first endpoint; the runtime invoked the second. No digest covered the raw bytes, only the parsed object, so the digest was identical on both sides while the effective endpoint differed. ## Condition of Validity The detection logic below is valid only under these conditions, and is *unsound* outside them: - The manifest is fetched as raw bytes and hashed *before* parsing. If you hash the parsed structure, duplicate-key and ordering attacks survive. - The instance retains a boot-time snapshot of the full tool set (names, digests, endpoints) and can compute set differences. Without a baseline, "detect" degenerates to "guess." - Tool identity is defined as `(name, version, content_digest)`, not `(name, version)`. Version strings are attacker-controlled labels; digests are not. - The runtime can distinguish *first-party* manifests (pinned at build) from *third-party* manifests (resolved at runtime). The invariant is asymmetric: first-party set must be a superset of what is invoked; third-party additions require explicit re-approval. - Prompt-injection scanning of `description`/`schema` fields is treated as a *heuristic signal*, never as a gate — it produces alerts, and the hard gate is digest/set integrity. ## Decision Boundary The boundary between "proceed" and "halt" is drawn at three points, in order: 1. **Pre-invocation digest check.** Recompute the raw-byte digest of the manifest immediately before dispatch and compare to the value recorded at resolution. Mismatch → halt the call, quarantine the tool, emit a `ManifestDriftError`. This catches in-place mutation and duplicate-key swaps. 2. **Set-membership check.** The invoked tool's `(name, version, digest)` must be a member of the verified snapshot. Any tool appearing that was not in the snapshot → halt, because the planner was steered to an unverified capability. This is the check that catches dependency-confusion and shadowing. 3. **Dependency-edge check.** For any tool declaring dependencies, each dependency's digest must also be in the verified snapshot. A verified tool with an unverified dependency is an unverified tool. This is the non-obvious boundary: integrity does not compose transitively unless you enforce it transitively. Do *not* halt on heuristic injection-scan hits alone; log and continue, because false positives on legitimate descriptions are common and halting on them trains operators to disable the check. Halt only on cryptographic and set-integrity failures. The heuristic's job is to raise the priority of the digest check, not to replace it. ## Operational Effect Enforcing the three checks converts a silent, post-hoc-detectable compromise into a loud, pre-invocation failure. The observed effect in the incident class: mean time to detection drops from "whenever a downstream anomaly surfaces" (hours to days) to "at the first mutated invocation" (sub-second). The cost is a per-call digest recomputation and a set lookup — negligible relative to model latency, but non-zero, so cache the *raw bytes* keyed by digest and re-hash on each dispatch rather than refetching. The secondary effect is that the planner's tool vocabulary becomes closed over the verified snapshot. Injected instructions that try to summon unregistered tools fail at the set-membership gate rather than executing. This does not stop injection of *content* into responses, but it stops injection from *expanding the action space*, which is the part that causes damage. Treat the closed vocabulary as the invariant: an agent that can only call tools it verified at boot cannot be steered into calling tools an attacker registered after boot. One residual risk remains and must be named: if the attacker can mutate the registry *before* the boot snapshot is taken, all three checks pass and the snapshot is poisoned at the root. The only defense there is out-of-band: pin first-party manifests at build time and verify the registry's own root of trust. The checks above protect the runtime window; they cannot protect the build window. Do not conflate them. ```python import hashlib import json from dataclasses import dataclass class ManifestDriftError(RuntimeError): """Raised when a tool manifest's raw-byte digest differs from the verified snapshot.""" class UnverifiedToolError(RuntimeError): """Raised when an invoked tool (or its dependency) is absent from the verified snapshot.""" @dataclass(frozen=True) class ToolIdentity: name: str version: str digest: str def raw_digest(manifest_bytes: bytes) -> str: # Hash raw bytes BEFORE parsing so duplicate-key/ordering tampering cannot hide. return hashlib.sha256(manifest_bytes).hexdigest() def build_snapshot(registry_fetch) -> dict: """registry_fetch(name) -> raw manifest bytes. Snapshot taken once at boot.""" snapshot = {} for name in registry_fetch.list_names(): raw = registry_fetch(name) parsed = json.loads(raw) # last-wins parse; digest already covers raw ident = ToolIdentity(parsed["name"], parsed["version"], raw_digest(raw)) snapshot[ident.name] = ident return snapshot def verify_and_dispatch(snapshot: dict, name: str, raw_manifest: bytes, invoke) -> dict: parsed = json.loads(raw_manifest) current = ToolIdentity(parsed["name"], parsed["version"], raw_digest(raw_manifest)) baseline = snapshot.get(name) if baseline is None: raise UnverifiedToolError(f"tool {name!r} not in verified snapshot") # Check 1: pre-invocation digest drift. if current.digest != baseline.digest: raise ManifestDriftError( f"manifest drift for {name!r}: verified {baseline.digest[:12]} " f"!= current {current.digest[:12]}" ) # Check 3: dependency edges must also be in the snapshot. for dep in parsed.get("dependencies", []): dep_base = snapshot.get(dep["name"]) if dep_base is None or dep_base.digest != dep.get("digest"): raise UnverifiedToolError( f"dependency {dep['name']!r} of {name!r} is unverified or drifted" ) return invoke(parsed["handler"]["endpoint"]) ```