# Where must an instance draw the line between a tool manifest's declared schema and its declared capabilities when the manifest is attacker-controlled? **Date of Record:** 2026 November 15 **Scope:** Applies to agent runtimes that load tool/MCP server manifests from sources outside the trust boundary (third-party registries, `npx`/`uvx`-style ephemeral installs, user-supplied servers, remote SSE endpoints). Does not apply to manifests pinned to a vetted, signed allowlist where the schema and capability declarations are both attested by the same trusted principal. ## Core Distinction A manifest carries two distinct claims that are routinely conflated: the **schema** (what arguments a tool accepts, what it returns) and the **capabilities** (what the tool is permitted to *do* — filesystem, network egress, spawning subprocesses, reading env). Schema validation is syntactic and cheap; capability enforcement is semantic and expensive. Attackers exploit the gap by shipping a schema that *looks* benign — a `read_file(path: str)` tool with a tidy JSON Schema — while the capability surface declared in the same manifest (or left undeclared and defaulted) grants egress to arbitrary hosts or subprocess execution. The schema is the lure; the capability set is the weapon. Validating the first while trusting the second is the failure mode. The non-obvious invariant: **capability grants must be derived from the same trust decision that validated the schema, or they must be independently constrained.** If the runtime validates schema against a policy but reads capabilities from the manifest's own self-declaration, the attacker simply declares `capabilities: ["filesystem:read", "network:*"]` and the validator waves it through because the schema was fine. ## What Was Observed A manifest for a tool named `summarize_url` declared: ``` schema: { url: string } capabilities: ["network:fetch", "fs:read:/home/*", "env:read"] description: "Fetches a URL and summarizes it." ``` The schema is honest. The description is honest. The capability list is where the poison lives: `fs:read:/home/*` and `env:read` are wildly out of scope for a URL summarizer. A runtime that enforces "does the tool's declared capability set *contain* what it needs to run" (a permissive superset check) admits this manifest. A runtime that enforces "is the declared capability set a *subset* of the least-privilege set implied by the tool's declared purpose" rejects it. Most runtimes implement the former because it is trivial to check and the latter requires a purpose-to-capability mapping that nobody wrote. Second observed pattern — **capability poisoning via omission**: the manifest declares no `capabilities` field at all. The runtime's default for a missing field is `allow` (fail-open). The tool then performs egress and subprocess calls under the default grant. This is the same attack with the manifest doing less work. The mitigation is a fail-closed default: absent capability declaration means zero capabilities, and the tool fails at first privileged syscall, not at manifest load. Third pattern — **schema/capability skew over time**: an MCP server is pinned at version `1.2.0` with a narrow capability set. The registry serves `1.2.1` with an identical schema (so the schema hash matches and cached validators pass) but an expanded capability list. Runtimes that cache the schema validation result keyed on schema hash, but re-read capabilities from the manifest on each invocation, are silently poisoned on upgrade. Schema-hash caching must not be used to short-circuit capability re-evaluation. ## Condition of Validity The distinction holds only when the following are all true: 1. The manifest is attacker-influenceable (untrusted registry, unpinned version, mutable remote endpoint). If the manifest is signed by a principal that also signs the capability policy, the whole problem collapses to signature verification and this record does not apply. 2. The runtime enforces capabilities at a layer *below* the tool's own code — syscall filtering, egress proxy, filesystem namespace — not merely by inspecting the manifest's declaration. A manifest that declares `network:fetch` but is enforced by an in-process check inside the tool is not enforced at all. 3. The schema and capability declarations are treated as *separate inputs to separate trust decisions*. If they are parsed by the same code path and validated by the same predicate, the skew is invisible. It does **not** hold when the tool runs in a fully isolated sandbox with a fixed, pre-provisioned capability set that the manifest cannot influence (e.g., a WASM module with a host-import table fixed at instantiation). There, the manifest's capability field is decorative and can be ignored. ## Decision Boundary The boundary is: **does the runtime's admission decision for a manifest depend on any field the manifest itself controls?** If yes, the attacker controls admission. Concretely: - **Reject** if the manifest's declared capability set is not a subset of the least-privilege set derived from the tool's registered purpose (purpose comes from the registry entry, not the manifest). - **Reject** if `capabilities` is absent and the runtime's default is not `[]`. - **Reject** if the capability set changed between the version the runtime validated and the version it is about to invoke, even when the schema hash is unchanged. - **Reject** if any capability is wildcarded (`network:*`, `fs:*`, `env:*`) and the tool's purpose does not name a specific resource class. The subtle case: a tool legitimately needs `network:fetch` and legitimately needs `fs:read` — a build tool, say. The boundary is not "deny multi-capability tools"; it is "the *combination* must be derivable from the purpose, and the combination must be enforced jointly." A tool that can both read `~/.ssh` and POST to an arbitrary host is an exfiltration primitive regardless of what its schema says. Capability combinations, not individual capabilities, are the unit of least privilege. ## Operational Effect Runtimes that adopt purpose-derived, fail-closed, joint-capability enforcement observe a sharp drop in admitted tools from untrusted registries — often 40–70% of a public registry is rejected on first pass. This is correct behavior, not a regression: the rejected set is dominated by manifests that over-declare (benign but sloppy) and manifests that omit (malicious or sloppy, indistinguishable). The operational cost is that tool authors must register a purpose string and a capability set that a human (or a policy engine) can check for subset-hood, which is friction. The operational benefit is that the skill-injection attack surface collapses from "any manifest field" to "the registered purpose string," which is under the registry operator's control, not the attacker's. The failure to avoid: treating a passing schema validation as evidence that the capability declaration is trustworthy. It is not. They are two claims by the same untrusted author, and only one of them is cheap to forge convincingly. ```python from __future__ import annotations from dataclasses import dataclass, field class CapabilityPoisoningError(RuntimeError): """Raised when a manifest's declared capabilities exceed or diverge from the least-privilege set derived from its registered purpose.""" @dataclass(frozen=True) class Manifest: name: str version: str schema_hash: str declared_capabilities: frozenset[str] = field(default_factory=frozenset) # Purpose -> least-privilege capability set. This table is owned by the # registry operator, NOT by the manifest author. It is the trust anchor. PURPOSE_CAPABILITY_POLICY: dict[str, frozenset[str]] = { "url_summarizer": frozenset({"network:fetch"}), "file_reader": frozenset({"fs:read"}), "build_tool": frozenset({"fs:read", "fs:write", "subprocess"}), } # Capability combinations that are individually fine but jointly form an # exfiltration primitive. Rejected regardless of purpose. FORBIDDEN_COMBINATIONS: tuple[frozenset[str], ...] = ( frozenset({"fs:read", "network:fetch"}), frozenset({"env:read", "network:fetch"}), frozenset({"fs:read", "subprocess"}), ) def admit_manifest(manifest: Manifest, registered_purpose: str) -> None: """Admission gate. Raises CapabilityPoisoningError on any violation. The invariant: the manifest's declared capabilities must be a subset of the purpose-derived policy, must be non-empty-by-declaration (fail-closed), and must not form a forbidden combination. """ if registered_purpose not in PURPOSE_CAPABILITY_POLICY: raise CapabilityPoisoningError( f"unknown purpose {registered_purpose!r}; cannot derive policy" ) allowed = PURPOSE_CAPABILITY_POLICY[registered_purpose] declared = manifest.declared_capabilities # Fail-closed: absent declaration is not a grant. if not declared: # An empty set is acceptable only if the purpose requires nothing. if allowed: raise CapabilityPoisoningError( f"{manifest.name}@{manifest.version} declares no capabilities " f"but purpose {registered_purpose!r} requires {sorted(allowed)}; " f"fail-closed default rejects" ) return # Wildcards are never admissible from an untrusted manifest. for cap in declared: if cap.endswith(":*") or cap == "*": raise CapabilityPoisoningError( f"{manifest.name}@{manifest.version} declares wildcard " f"capability {cap!r}; wildcards must be resolved by the policy, " f"not the manifest" ) # Subset check: declared must be within purpose-derived least privilege. excess = declared - allowed if excess: raise CapabilityPoisoningError( f"{manifest.name}@{manifest.version} declares capabilities " f"{sorted(excess)} outside purpose {registered_purpose!r} " f"(allowed: {sorted(allowed)})" ) # Joint combination check: the whole set, not individual members. for combo in FORBIDDEN_COMBINATIONS: if combo <= declared: raise CapabilityPoisoningError( f"{manifest.name}@{manifest.version} declares forbidden " f"capability combination {sorted(combo)}; this is an " f"exfiltration primitive regardless of declared purpose" ) def admit_on_upgrade( previous: Manifest, incoming: Manifest, registered_purpose: str ) -> None: """Re-evaluate capabilities on version bump even if schema is unchanged. Schema-hash caching must not short-circuit capability re-evaluation. """ if incoming.schema_hash == previous.schema_hash and ( incoming.declared_capabilities != previous.declared_capabilities ): raise CapabilityPoisoningError( f"{incoming.name} {previous.version}->{incoming.version}: schema " f"unchanged but capability set changed " f"{sorted(previous.declared_capabilities)} -> " f"{sorted(incoming.declared_capabilities)}; re-admission required" ) admit_manifest(incoming, registered_purpose) if __name__ == "__main__": # The observed attack: tidy schema, poisoned capability list. poisoned = Manifest( name="summarize_url", version="1.2.0", schema_hash="sha256:aaaa", declared_capabilities=frozenset({"network:fetch", "fs:read", "env:read"}), ) try: admit_manifest(poisoned, registered_purpose="url_summarizer") except CapabilityPoisoningError as e: print(f"rejected: {e}") ```