Inspect an agent extension before it gets authority

An agent extension can be a page of instructions, an executable plugin, or a bundle that installs hooks and dependencies. Those are different trust decisions. Review the artifact you have—not its label, popularity, or promised productivity—before it inherits repository access.

This guide includes an original offline lab with synthetic manifests. No extension code is included or executed, no network or secret access occurs, and no third-party package is installed.

Understand the underlying boundary: an instruction is not a capability.

Start by classifying the artifact

A document-only extension contains readable instructions or reference material. It can still influence an agent's choices, so inspect its instructions and data-handling expectations, but it has no executable entry point in this model.

An executable plugin has a runtime entry point or hook. Its review must include what launches it, what it can read or change, which processes it can start, where it can connect, which credentials it can reach, and which dependencies run with it. A design pack may be document-only, executable, or mixed; the name does not decide the risk.

Use four separate questions:

1. What is it? Bind the review to a canonical source, exact revision, artifact digest, maintainer, and license.
2. What runs? Inventory entry points, install scripts, hooks, dependencies, and update behavior.
3. What authority is requested? Compare filesystem, process, network, secret, browser, and external-account access with a local allowlist.
4. How does it leave? Record removal, configuration restoration, retained outputs, and the evidence needed to confirm rollback.

Declarations are inputs to policy, not proof

A manifest makes requested capabilities reviewable. It cannot prove that executable code is honest, complete, or confined. Static inspection may find suspicious behavior, and a sandbox may constrain behavior, but this lab does neither.

The example validator checks only declared JSON fields. It rejects a requested capability when that capability is absent from declaredCapabilities or absent from the policy allowlist. Its small schema fails closed on unknown fields, blank required values, wrong field types, and unsafe entry-point paths. It also checks structural rules: document-only entries must be Markdown or text with no hooks, executable updates must be pinned, dependencies are denied by this lab policy, and provenance-shaped fields must be present.

It does not:

• inspect source code or transitive package contents;
• verify a signature, repository ownership, license text, revision, or digest against an upstream artifact;
• enforce an operating-system sandbox or prevent filesystem, process, network, or secret access;
• detect hidden runtime behavior, dynamic downloads, obfuscation, or a compromised update channel; or
• establish that an extension is safe to install.

Treat an allow result as “the declaration satisfies this small policy,” never “the plugin is safe.”

The two synthetic cases

The document-only fixture declares one GUIDE.md entry, no hooks, no dependencies, and no capabilities. It passes the lab policy.

The executable-plugin fixture declares repository-read access but requests repository-read, outbound-network, and secret-read capabilities. The last two are undeclared and all but repository-read are outside the policy allowlist. The validator rejects it without loading an entry point or making a connection.

Expected result summary:

synthetic-writing-guide       allow
synthetic-repository-helper   reject
  requested capability is undeclared: network:outbound
  requested capability is denied by policy: network:outbound
  requested capability is undeclared: secrets:read
  requested capability is denied by policy: secrets:read

This is a deterministic policy demonstration, not a malware scan and not evidence about any real product.

Reproduce the offline check

Prerequisite: Node.js 24 or newer. The validator uses Node.js built-ins only and makes no network request.

• Validator source, served as plain text
• Document-only synthetic manifest
• Executable-plugin synthetic manifest with undeclared requests
• Synthetic policy
• Pre-install review rubric

Download all five files into one directory, rename agent-extension-validator.mjs.txt to agent-extension-validator.mjs, then run:

node agent-extension-validator.mjs agent-extension-policy.synthetic.json agent-extension-document-only.synthetic.json agent-extension-plugin-undeclared.synthetic.json

The process exits with code 2 because at least one manifest is rejected. That rejection is the expected successful test outcome. Review the JSON result rather than treating every nonzero exit as a validator failure.

A practical pre-install gate

Use the downloadable rubric to retain a compact decision record. A useful gate should stop when identity is ambiguous, the artifact cannot be inspected before execution, required authority exceeds the task, executable updates float, dependencies are unexplained, the license is missing, or rollback is not credible.

For executable candidates that survive manifest review, continue in a disposable environment with denied-by-default credentials and network access. Observe actual file, process, and network behavior; compare it with declarations; test removal; and retain exact inputs and outputs. That is a separate evaluation, not something this offline lab claims to have performed.

Why provenance and expectations matter

NIST SSDF 1.1 recommends making release-integrity information available and retaining provenance for releases. SLSA 1.2 defines provenance as verifiable information about where, when, and how an artifact was produced; its artifact-verification guidance says verification must compare provenance with expectations and reject unexpected external parameters. OWASP SCVS organizes component verification around inventory, bills of materials, build environment, package management, component analysis, and provenance.

These are general supply-chain references, not endorsements of this fixture schema or proof that a manifest alone supplies those controls.

Keep the decision narrow

“Document-only” is not “trusted,” and “open source” is not “reviewed.” Conversely, executable code is not automatically forbidden; it simply requires evidence proportional to its authority and failure modes. The useful outcome is an explicit, reversible decision tied to exact bytes and a local policy—not a permanent reputation score.