README
¶
clawpatrol
The security firewall for agents.
Claw Patrol sits between your agents and prod, parses their traffic
at the wire, and gates each action against rules you write in HCL.
For example, you can block destructive SQL, or pause kubectl delete pod
until a human approves it before the request reaches Kubernetes.
For the full overview see clawpatrol.dev.
Install
curl -fsSL https://clawpatrol.dev/install.sh | sh
From source: make (requires Go and Node.js).
A rule
A real rule from our own production config:
rule "k8s-no-secrets" {
endpoint = k8s-prod
condition = "k8s.resource == 'secrets'"
verdict = "deny"
reason = "Secret values must not leave the cluster via the agent"
}
Conditions are CEL expressions over wire-level facts the gateway extracts per protocol: SQL verbs and table names for Postgres / ClickHouse, resource / verb / namespace for Kubernetes, method / path / headers / body for HTTP. The full set of facts lives in the config reference.
Run
Three deployment shapes; pick whichever fits.
clawpatrol gateway config.hcl # run the proxy itself
clawpatrol join <gateway-url> # join a gateway
clawpatrol run claude # wrap one agent's process tree
clawpatrol run opens a per-process tunnel on Linux (via netns) or
macOS (via NetworkExtension); only the wrapped command's traffic
goes through the gateway. clawpatrol join brings up a WireGuard
tunnel that routes the whole host. clawpatrol gateway is the
proxy: a single binary that loads your HCL config and accepts
clients tunneling in via WireGuard or Tailscale.
Configure
clawpatrol.dev/docs/getting-started
walks through a first config end-to-end.
clawpatrol.dev/docs/config-reference
is the auto-generated field reference. See
gateway.example.hcl for an
annotated starting template.
License
MIT. See LICENSE.md.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
clawpatrol
command
Package main implements clawpatrol main support.
|
Package main implements clawpatrol main support. |
|
clawpatrol/dnsvip
Package dnsvip handles DNS interception and virtual-IP allocation for non-HTTP endpoints that can't be disambiguated at TCP-accept time.
|
Package dnsvip handles DNS interception and virtual-IP allocation for non-HTTP endpoints that can't be disambiguated at TCP-accept time. |
|
Package dashboard ships the SPA + login page that the gateway serves.
|
Package dashboard ships the SPA + login page that the gateway serves. |
|
internal
|
|
|
config
Package config loads and validates clawpatrol's HCL gateway config.
|
Package config loads and validates clawpatrol's HCL gateway config. |
|
config/extplugin
Package extplugin spawns and proxies clawpatrol's Terraform-style external plugins.
|
Package extplugin spawns and proxies clawpatrol's Terraform-style external plugins. |
|
config/extplugin/wire
Package wire holds the small set of protocol constants shared between the gateway-side plugin manager (extplugin) and the plugin SDK (pluginsdk): the go-plugin handshake, the dispensed plugin name, the host-services broker stream id, and the per-call session metadata key.
|
Package wire holds the small set of protocol constants shared between the gateway-side plugin manager (extplugin) and the plugin SDK (pluginsdk): the go-plugin handshake, the dispensed plugin name, the host-services broker stream id, and the per-call session metadata key. |
|
config/facet
Package facet is the registry for protocol-family plugins.
|
Package facet is the registry for protocol-family plugins. |
|
config/hostmatch
Package hostmatch parses and matches the host entries that appear in an endpoint's `hosts = [...]` list.
|
Package hostmatch parses and matches the host entries that appear in an endpoint's `hosts = [...]` list. |
|
config/match
Package match holds the runtime types the request handler walks when dispatching against the compiled policy: the Matcher interface every rule's compiled predicate satisfies and the family-tagged Request snapshot the matcher reads.
|
Package match holds the runtime types the request handler walks when dispatching against the compiled policy: the Matcher interface every rule's compiled predicate satisfies and the family-tagged Request snapshot the matcher reads. |
|
config/plugins/all
Package all blank-imports every built-in plugin so a single import from main / tests pulls the entire registry into the binary.
|
Package all blank-imports every built-in plugin so a single import from main / tests pulls the entire registry into the binary. |
|
config/plugins/approvers
Package approvers registers every built-in approver kind.
|
Package approvers registers every built-in approver kind. |
|
config/plugins/credentials
Package credentials implements clawpatrol credentials support.
|
Package credentials implements clawpatrol credentials support. |
|
config/plugins/endpoints
Package endpoints registers every built-in endpoint plugin.
|
Package endpoints registers every built-in endpoint plugin. |
|
config/plugins/facets/https
Package https is the HTTPS protocol-family facet.
|
Package https is the HTTPS protocol-family facet. |
|
config/plugins/facets/k8s
Package k8s is the Kubernetes protocol-family facet.
|
Package k8s is the Kubernetes protocol-family facet. |
|
config/plugins/facets/sql
Package sql is the SQL protocol-family facet.
|
Package sql is the SQL protocol-family facet. |
|
config/plugins/facets/ssh
Package ssh is the SSH protocol-family facet.
|
Package ssh is the SSH protocol-family facet. |
|
config/plugins/rules
Package rules registers the single `rule` block kind.
|
Package rules registers the single `rule` block kind. |
|
config/plugins/sshproto
Package sshproto holds the protocol-specific contract that bridges the SSH endpoint plugin and the SSH credential plugin.
|
Package sshproto holds the protocol-specific contract that bridges the SSH endpoint plugin and the SSH credential plugin. |
|
config/plugins/tailscaleproto
Package tailscaleproto holds the protocol-specific contract that bridges the tailscale credential and the tailscale tunnel (plus the dashboard Connect modal).
|
Package tailscaleproto holds the protocol-specific contract that bridges the tailscale credential and the tailscale tunnel (plus the dashboard Connect modal). |
|
config/plugins/tunnels
Package tunnels hosts the built-in tunnel plugins.
|
Package tunnels hosts the built-in tunnel plugins. |
|
config/runtime
Package runtime hosts the request-time dispatcher and the plugin runtime interfaces.
|
Package runtime hosts the request-time dispatcher and the plugin runtime interfaces. |
|
sandbox
Package sandbox confines external plugin subprocesses.
|
Package sandbox confines external plugin subprocesses. |
|
sandbox/sandboxtest
Package sandboxtest holds test helpers for code that spawns sandboxed plugin subprocesses.
|
Package sandboxtest holds test helpers for code that spawns sandboxed plugin subprocesses. |
|
tools/docgen
command
Command docgen generates site/doc/config-reference.md from the clawpatrol HCL config plugin registry.
|
Command docgen generates site/doc/config-reference.md from the clawpatrol HCL config plugin registry. |
|
tools/docgen/internal/render
Package render builds the auto-generated HCL config reference from the live plugin registry plus Go-source comments.
|
Package render builds the auto-generated HCL config reference from the live plugin registry plus Go-source comments. |
|
Package pluginsdk is the author-facing SDK for clawpatrol's Terraform-style external plugins.
|
Package pluginsdk is the author-facing SDK for clawpatrol's Terraform-style external plugins. |
|
example
command
Standalone clawpatrol plugin demonstrating the v1 plugin protocol.
|
Standalone clawpatrol plugin demonstrating the v1 plugin protocol. |
Click to show internal directories.
Click to hide internal directories.