DOCSEARCHbyAlgolia
Submit Docs

clawpatrol Documentation

repository·main·Indexed 21 days ago

https://github.com/denoland/clawpatrol

A security firewall for AI agents that parses wire-level traffic (SQL, Kubernetes, HTTP) and gates actions against HCL-defined rules using CEL expressions. It features a typed-block HCL dialect for defining approvers, credentials, endpoints, rules, and profiles, supporting both LLM-based and human approval chains.

Tokens
74.2K
Snippets
173
Records
301
Agent score
75%

What's inside clawpatrol

  1. What is Claw Patrol

    main

    Claw Patrol is a firewall designed for AI agents. It acts as a proxy between your agents and the internet to control outbound requests, enforce security policies, and inject credentials at the wire level so that the agent process itself never handles sensitive secrets.

    Core Capabilities

    • Allow/Deny Rules: Uses Common Expression Language (CEL) to define rules against protocol-specific typed variables.
    • Protocol-Aware Inspection: Instead of just inspecting HTTP, Claw Patrol terminates and parses wire protocols to understand intent:
      • Postgres / ClickHouse: Inspects sql.verb, sql.tables, and sql.statement.
      • Kubernetes: Decomposes URLs into k8s.verb, k8s.resource, k8s.namespace, and k8s.name.
      • HTTPS: Inspects http.method, http.path, http.headers, and http.body_json (for JSON endpoints).
    • Human-in-the-loop: Can defer risky actions (like kubectl apply) to a manual approval process (e.g., via Slack).
    • Secret Injection: Replaces token-shaped placeholders in the agent's environment (e.g., GITHUB_TOKEN=ghp_clawpatrol_placeholder_do_not_use) with real credentials during transit.
    • Audit Logging: Provides a searchable dashboard of every request, verdict, and latency metric.

  2. Understand the Claw Patrol architecture and core concepts

    main

    Claw Patrol acts as a security gateway between an Agent (the requester) and upstream services. It intercepts traffic, applies policy via Rules, and injects real Credentials so the agent never handles sensitive secrets directly.

    Core Components

    • Gateway: The central daemon that loads configuration, hosts the operator UI, applies policy, and forwards authorized traffic.
    • Agent: The client program (e.g., an AI coding agent like Claude Code or a custom script) whose outbound traffic is routed through the gateway. Agents use Placeholders instead of real credentials.
    • Device: The machine originating the traffic. The gateway identifies the device to apply the correct Profile.
    • Profile: A named collection of Credentials assigned to a Device. It defines which secrets a device is authorized to wield.
    • Endpoint: A typed network target (e.g., https, sql, k8s) consisting of a name, protocol family, and host(s). Rules are attached to endpoints.
    • Credential: A handle to a secret used for one or more endpoints. The actual secret bytes are stored securely in the gateway's Secret Store.
    • Action: A single unit of work observed by the gateway (e.g., one HTTP call, one SQL query, or one SSH command) that is subject to policy.

  3. What is DERP and how does it work?

    main

    DERP is a packet relay system consisting of clients and servers. Instead of using IP addresses, peers are addressed using WireGuard public keys. It serves two primary functions:

    1. Discovery: Relays "Disco" discovery messages as a side channel during NAT traversal.
    2. Fallback: Relays encrypted WireGuard packets as a last resort when UDP is blocked or NAT traversal fails.

    The server implementation is located in ../cmd/derper.

  4. What is a Runtime and how is it used?

    main

    A Runtime is the request-time component of a plugin. While the Plugin struct handles configuration and loading, the Runtime handles actual traffic.

    In the plugin lifecycle, the Runtime is stored as any on the Plugin struct. The dispatcher then type-asserts this any value against specific interfaces based on the plugin's kind. If a plugin does not provide a runtime, it is considered "schema-only"; the loader will accept the configuration, but the dispatcher will return runtime.ErrUnsupported if any operation attempts to use it.

  5. Overview of Clawpatrol Actors

    main

    A Clawpatrol deployment consists of five primary actors:

    • Agent: The AI client (e.g., Claude, Codex) or CLI tool (e.g., kubectl, psql, ssh) being gated. It runs as an ordinary process and is unaware of Clawpatrol.
    • Device: The machine hosting the agent. It runs a Clawpatrol client (a CLI binary on Linux or a system extension on macOS) that captures outbound flows.
    • Transport: The L3 connection (WireGuard or Tailscale) between the Device and the Gateway. It carries every byte emitted by the agent.
    • Gateway: The central Clawpatrol process (Go binary) that terminates the transport, decides whether to intercept flows, runs policy plugins, and injects credentials.
    • Upstream: The target API or service (e.g., api.anthropic.com, a Postgres database, or an SSH bastion). The upstream sees the connection coming from the Gateway, not the Device.

  6. How Clawpatrol Plugins Work

    main

    The Gateway uses three families of plugins to process intercepted traffic:

    • Endpoint plugins: Define the upstream binding and the wire protocol to terminate (e.g., https, kubernetes, postgres, clickhouse_native, clickhouse_https, ssh). They handle protocol-specific decoding (e.g., parsing http.Request for HTTPS or Query/Parse messages for Postgres).
    • Credential plugins: Manage secrets (e.g., bearer tokens, OAuth, mTLS, Postgres passwords, SSH keys). They write secrets into specific slots on a matched flow (like a header or an auth replay) so the Agent never holds the real secret.
    • Approver plugins: Handle authorization verdicts. They support:
      • dashboard: Built-in approver for live pending entries.
      • human_approver: Approvals via Slack, Discord, or Telegram.
      • llm_approver: Synchronous LLM proctoring against an inline policy prompt.

  7. Current state: Device keypair lifecycle and identity

    main

    In the current implementation, every clawpatrol run invocation on a device shares a single long-lived WireGuard keypair generated during clawpatrol join.

    Lifecycle and Storage

    • Generation: runJoin() drives onboarding. Upon dashboard approval, apiOnboardApprove() calls MintKey() to generate the keypair and allocate a /32 IP.
    • Persistence: The client receives a wg-quick(5) configuration and a one-time api_token. These are stored at:
      • ~/.config/clawpatrol/wg.conf (chmod 600)
      • ~/.clawpatrol/api-token (chmod 600)

    Identity and Limitations

    • Identity: Because all concurrent clawpatrol run processes use the same static keypair, the gateway sees them as a single WireGuard peer with a single /32 IP.
    • macOS: The macOS implementation uses a NETransparentProxyProvider tunnel that loads the device's wg.conf at install time. It uses application-level IPC (/tmp/clawpatrol.sock) to inform the extension which PIDs to route, but it lacks per-session cryptographic identity.

  8. How Claw Patrol architecture works

    main

    Claw Patrol operates using a two-part architecture connected via WireGuard:

    1. Gateway: A single Go binary running on a host you control. It manages the security policy, stores credentials, maintains the audit log, and hosts the dashboard. All state is stored in a local SQLite file.
    2. Devices: Software running on your local machine, CI runners, or workstations. The device captures the agent's outbound network flows and tunnels them to the Gateway.

    Data Flow: Agent $\rightarrow$ Device $\rightarrow$ WireGuard $\rightarrow$ Gateway $\rightarrow$ Upstream

    At the Gateway, the system matches rules, injects credentials, and logs the action before the request reaches the upstream service.

  9. How Claw Patrol rules work

    main

    Rules are defined in gateway.hcl to decide the fate of a request: whether to forward it, reject it, or route it through approvers (humans via dashboard/Slack or LLMs).

    Each rule consists of:

    • endpoint: The target(s) the rule applies to.
    • condition: A CEL (Common Expression Language) expression that must evaluate to true for the rule to trigger.
    • verdict: The outcome if the condition matches ("allow" or "deny").
    • approve: A list of approvers required to allow the request.

    Rule Families: The protocol family (http, sql, k8s, or ssh) is inferred from the endpoint. A rule cannot mix different families in its endpoints list. The family determines which CEL variables are available in the condition.

    rule "example-rule" {
  endpoint  = https.console
  condition = "http.method == 'POST'"
  verdict   = "deny"
}

  10. Understand the untrusted plugin security model

    main

    Claw Patrol treats external plugins (plugin "<name>" { source = "..." }) as untrusted supply-chain attack surfaces rather than trusted gateway code. Plugins run as subprocesses within the gateway's process tree but are isolated from sensitive gateway secrets (state database, WireGuard/Tailscale keys, and CLAWPATROL_SECRET_* environment variables).

    To contain potentially malicious or compromised plugins, Claw Patrol employs two primary mechanisms:

    1. Scrubbed Environment: Plugins inherit none of the gateway's environment variables, except for PATH, HOME, TMPDIR (a private scratch directory), and the gateway socket path. This scrubbing occurs even if sandbox = "off" is configured.
    2. OS Sandboxing: By default, every plugin runs inside an OS sandbox (Linux namespaces, macOS seatbelt, or Landlock). The sandbox restricts filesystem access to the plugin's own binary, system libraries, and explicitly granted paths. It also restricts network access by default.

    If a sandbox cannot be established, the plugin fails to load unless the operator explicitly sets sandbox = "off".

  11. Understand the External Plugin Control Plane architecture

    main

    Clawpatrol uses a dual-direction gRPC architecture to facilitate communication between the gateway (host) and sandboxed external plugins. This design ensures that plugins remain untrusted and sandboxed while still being able to request actions from the gateway.

    There are two distinct communication directions:

    1. plugin → host: The plugin calls the gateway to request decisions or state. These are implemented as host-served services over a single broker stream. Examples include Evaluate (to rule on an action), Decide (for HITL prompts), and State (for persistence).
    2. host → plugin: The gateway calls the plugin to execute specific logic. These are implemented as the plugin's own gRPC services. Examples include Endpoint.HandleConn, Credential.TransformHTTP, and Approver.Approve.

    By separating these into two distinct gRPC surfaces, the system avoids complex frame multiplexing and uses standard gRPC mechanisms for correlation and metadata.

  12. How the Tailscale interactive login flow works

    main

    The Tailscale authentication flow in clawpatrol mimics the tailscale up experience. It does not use a standard OAuth client/secret exchange, but rather captures the dynamic login URL generated by tsnet.

    1. Trigger: The tunnel's Open method runs tsnet.Server.Up asynchronously without an AuthKey.
    2. URL Capture: If no prior state exists, tsnet generates a login URL (e.g., https://login.tailscale.com/a/<token>). This URL is parked in a runtime.PendingNodeAuth registry.
    3. Dashboard Interaction: The operator visits the dashboard, where a 'Connect' button (provided by the TailscaleAuthProvider) triggers a request to a BeginURL. This endpoint retrieves the live URL from the registry.
    4. Authentication: The operator follows the link to tailscale.com and approves the node.
    5. Persistence: Once approved, tsnet receives the node state. The ipn.StateStore writes these identity bytes into the gateway's SecretStore (SQLite). Subsequent restarts will find this state and skip the login step.