Plugins — Claw Patrol Docs

Most of the protocols Claw Patrol gates — HTTPS, Postgres, ClickHouse, SSH, Kubernetes — ship as built-in plugins compiled into the gateway binary. When you need to gate something the binary doesn’t know about, you can ship an external plugin: a separate Go program the gateway spawns as a subprocess and talks to over gRPC, modeled on Terraform’s provider design.
External plugins extend exactly the same registry the built-ins use. They can declare:
Add a plugin block to the gateway HCL and reference its types the same way you reference built-ins:
The name label ("example") is informational — it’s the local identifier you’d use to refer to this plugin’s source in tooling. The names that actually matter are the type names and facet names the plugin declares in its manifest. Both are flat strings living in one global registry per kind (one for endpoint types, one for credential types, one for tunnel types, one for facets, each shared with the built-ins). The gateway does not auto-namespace anything.
Plugin authors prefix their own names by convention — the way Terraform providers do (aws_iam_role, kubernetes_deployment): the SMTP endpoint in the example plugin is example_smtp, its credential is example_magic_token, its custom facet is also example_smtp (endpoint types and facets live in different registries, so reusing one name for the matched pair is fine and often clearer). A plugin that ships a name colliding within a registry — with a built-in (e.g. https endpoint type, http facet) or another plugin — fails at validate time with a clear diagnostic.
source can be a local path (above) or a GitHub repository. With a repository, clawpatrol resolves a semver constraint against the repo's release tags, downloads the build for this host's OS/arch, verifies it, caches it, and pins the resolved version in the lockfile — the same model Terraform uses for providers:
version is a hashicorp/go-version constraint (>= 1.2.0, ~> 1.2, ~> 1.2.0, >= 1.0, < 2.0, an exact 1.2.3). ~> 1.2 allows 1.x ≥ 1.2; ~> 1.2.0 allows 1.2.x. Pre-release tags are excluded unless you pin one exactly. version is only valid on a GitHub source.
The download is an explicit, reviewable step — the running gateway only ever loads the locked version, and never upgrades on its own:
plugins info reads each GitHub plugin's signed static manifest for the newest release satisfying its constraint and prints the metadata and the privileges it requires — without downloading the binary — so you can review what an install or upgrade would grant before it happens.
The gateway checks GitHub for newer matching releases in the background and surfaces "update available" on the dashboard's Plugins page, but never downloads or upgrades automatically — you run update.
Commit clawpatrol.lock.hcl. On a fresh host the gateway downloads exactly the locked version (verifying it) on first load; if the locked version no longer satisfies the constraint, or the source changed, it fails closed and tells you to run install / update.
So clawpatrol can find and verify the right binary, a plugin's GitHub release must contain, per platform, an archive named with the Go GOOS/GOARCH tokens, plus a checksums file:
Only the trailing _<os>_<arch>.tar.gz is load-bearing — clawpatrol selects the archive by that suffix and reads its checksum from SHA256SUMS — so the prefix is convention, not a hard requirement.
The optional static manifest is the plugin's own manifest emitted by its --print-manifest mode (the SDK's pluginsdk.Run handles the flag). Publishing it as a release asset — listed in SHA256SUMS and covered by the attestation — lets clawpatrol plugins info show a plugin's metadata and required privileges before downloading the binary.
Add a build-provenance attestation with one workflow step so clawpatrol can verify the binary (and the manifest) was built by your repo (see the trust model below):
Three layers gate a downloaded binary, from least to most powerful:
Checksum. The archive's sha256 must match the release's SHA256SUMS.
Trust on first use. The extracted binary's hash is recorded in clawpatrol.lock.hcl; every later load re-hashes the cached binary and fails closed on any mismatch — and a version bump re-runs the permission-escalation check (a new release that newly wants network is blocked until you re-approve it).
Build provenance. If the release carries a GitHub build-provenance attestation, clawpatrol verifies (via Sigstore) that the binary was built by that repo's GitHub Actions workflow — the github.com/owner/repo you already named is the trust anchor, so there is no key to manage. This closes the first-download gap that checksums alone leave open. The attestation also names the source commit the binary was built from; clawpatrol records it in the lockfile (commit = "...") — an immutable reference, since tags are mutable — and on a later re-download of the pinned version rejects an attestation that names a different commit (a re-pointed tag).
How a missing attestation is treated is set per plugin by provenance:
A present-but-invalid attestation always fails closed (every mode but "off").
Provenance is also tracked trust-on-first-use, like the network grant: the lockfile records whether the pinned version was attested, and a later binary that loses provenance — attested before, not now — is blocked (a re-pointed tag, or an upgrade that drops its attestation, looks exactly like a supply-chain attack) until you accept it with clawpatrol plugins approve <name>. A plugin that was never attested keeps installing with a warning; only a downgrade is blocked.
Plugins are untrusted. A plugin runs in the gateway process tree and the gateway holds secrets (the state DB with the CA key and credential material, WireGuard / Tailscale keys, CLAWPATROL_SECRET_* environment variables). To contain a malicious or compromised plugin, every plugin subprocess runs inside an OS sandbox by default and with a scrubbed environment — it inherits none of the gateway's environment,