Configuration Reference#

Pipelock uses a single YAML config file. Generate a starter config:

pipelock presets
pipelock generate config --list
pipelock generate config --preset balanced > pipelock.yaml
pipelock run --config pipelock.yaml

Or scan your project and get a tailored config:

pipelock audit ./my-project -o pipelock.yaml

Hot Reload#

Config changes are picked up automatically via file watcher or SIGHUP signal (100ms debounce). Most fields reload without restart. Fields that require a restart are marked below.

On reload, the scanner and session manager are atomically swapped. Runtime
kill-switch state is preserved, including the API, signal, Conductor remote,
and Conductor stale-bundle sources. Existing MCP sessions retain the old
scanner until the next request.

If a reload fails validation (invalid regex, security downgrade), the old config is retained and a warning is logged. A reload is also rejected, in any mode, when a rule-bundle resolution error (bad signature, missing lock file, version mismatch, filesystem error) would drop detection rules that are currently live: the previous config is kept so a transient bundle failure cannot silently weaken coverage. A clean bundle deletion has no loader error, so it is handled separately: strict mode rejects the reload and keeps the running config unless rules.allow_degraded: true is set, while non-strict modes allow it and emit a rule_bundle_degraded audit event naming the bundle and dropped pattern count. An unrelated bundle error that does not remove any live rule does not block the reload. At startup, strict mode refuses installed-bundle integrity failures unless rules.allow_degraded: true is set; non-strict modes and availability failures start degraded with structured audit events and degraded state on /stats and pipelock_rule_bundles_degraded.

Reload exceptions: the Sentry crash-report sanitizer captures the DLP pattern list at startup and does not update on reload. If you add DLP patterns used to scrub Sentry events, restart pipelock to propagate them. A warning is logged on any reload that changes dlp.patterns while Sentry is enabled: DLP patterns changed; Sentry scrubber uses init-time patterns until restart.

Strict parsing: Pipelock rejects unknown top-level and nested YAML fields at startup, and it only accepts a single YAML document per config file. Trailing --- documents are a hard error. This prevents typos from silently disabling controls and blocks shadow-config bypasses.

Top-Level Fields#

version: 1 # Config schema version (currently 1)
mode: balanced # "strict", "balanced", or "audit"
enforce: true # false = detect without blocking (warning-only)
explain_blocks: false # true = include fix hints in block responses

Sentry Crash Reporting#

Sentry crash reporting is disabled by default. It is enabled only when sentry.enabled: true is set and either sentry.dsn or the SENTRY_DSN environment variable is non-empty.

sentry:
  enabled: false
  dsn: ""
  environment: production
  sample_rate: 1.0

When enabled, Pipelock prints a startup disclosure. Crash payloads are rebuilt through an allowlist sanitizer before leaving the process: request bodies, headers, user identity, hostnames, breadcrumbs, module inventory, local variables, absolute paths, and source context lines are dropped. Transactions, SDK logs, metrics, and check-ins are not sent by this integration.

sample_rate: 0.0 does not disable Sentry in the Go SDK; it is treated as 1.0. To disable crash reporting, set sentry.enabled: false or leave the DSN empty. Pipelock rejects sample_rate: 0.0 when Sentry is enabled.

Block Hints (explain_blocks)#

When enabled, blocked responses include a hint explaining why the request was blocked and how to fix it. Fetch proxy responses get a hint field in the JSON body. CONNECT and WebSocket rejections get an X-Pipelock-Hint response header.

explain_blocks: true

Security note: Hints expose scanner names and config field names (e.g., "Add to api_allowlist", "Add a suppress entry"). This is useful for debugging but reveals your security policy to the agent. Default: false (opt-in). Enable when you trust your agent or need easier debugging. Leave disabled in production where untrusted agents could use hints to craft bypasses.

Modes#

API Allowlist#

Domains that are always allowed in strict mode. In balanced/audit mode, these are exempt from the domain blocklist.

api_allowlist:
  - "*.anthropic.com"
  - "*.openai.com"
  - "github.com"
  - "*.github.com"
  - "*.githubusercontent.com"
  - "registry.npmjs.org"

Supports wildcards (*.example.com matches api.example.com and the apex example.com itself). Case-insensitive.

Generated defaults and presets intentionally omit messaging/collaboration
platforms such as Slack, Discord, and Telegram because they are common
exfiltration channels. Add exact hosts only when required for your deployment.
Allowlisting controls destination reachability; it does not bypass DLP,
request-body/header scanning, response scanning, or MCP content scanning.

Fetch Proxy#

The HTTP fetch proxy listens for requests on /fetch?url=... and returns extracted text content.

fetch_proxy:
  listen: "127.0.0.1:8888"
  timeout_seconds: 30
  max_response_mb: 10
  user_agent: "Pipelock Fetch/1.0"
  monitoring:
    max_url_length: 2048
    entropy_threshold: 4.5
    max_requests_per_minute: 60
    max_data_per_minute: 0 # bytes/min per domain (0 = disabled)
    blocklist:
      - "*.pastebin.com"
      - "*.hastebin.com"
      - "*.paste.ee"
      - "*.transfer.sh"
      - "*.file.io"
      - "*.requestbin.com"
    subdomain_entropy_exclusions:
      - "files.pythonhosted.org"
      - "pypi.org"
      - "objects.githubusercontent.com"

Entropy guidance:

• English text: 3.5-4.0 bits/char
• Hex/commit hashes: ~4.0
• Base64-encoded data: 4.0-4.5
• Random/encrypted: 5.5-8.0

The default threshold (4.5) allows commit hashes and base64-encoded filenames while flagging encrypted blobs. Lower it (3.5) for strict mode. Raise it (5.0) for development environments where base64 URLs are common.

Subdomain entropy exclusions skip subdomain and path entropy checks for specific domains, but query parameter entropy is still checked. Defaults cover package/object hosts that use hash-like routing paths (files.pythonhosted.org, pypi.org, objects.githubusercontent.com). This is also useful for APIs that embed tokens in URL paths (e.g., Telegram bot API). Supports wildcard matching (*.example.com).

fetch_proxy:
  monitoring:
    subdomain_entropy_exclusions:
      - "api.telegram.org"

Query entropy parameter exclusions skip only the raw query-value entropy gate for one exact HTTPS endpoint and one exact parameter key. Subdomain entropy, path entropy, query-key entropy, adjacent parameters, DLP, SSRF, rate limits, and data budgets still apply. Use this first when a structured query language or endpoint contract creates a false positive in one parameter.

fetch_proxy:
  monitoring:
    query_entropy_param_exclusions:
      - scheme: https
        host: api.vendor.example
        path: /v1/search/recent
        param: query
        reason: structured search grammar can contain dense operators
        owner: platform-security
        expires: 2026-12-31

The endpoint-parameter matcher is intentionally strict: empty scheme defaults
to https, host is an exact DNS hostname without a port or wildcard, path
must match the URL's canonical escaped path exactly, and the raw query string
must contain exactly one key with the same unescaped spelling as param.

Query entropy exclusions skip only the query-string entropy gate for specific
hosts. They are broader than endpoint-parameter exclusions and should be reserved
for hosts whose query strings legitimately carry high-entropy opaque values
across many paths or parameters. Supports exact-host and *.example.com
wildcard matching rules.

fetch_proxy:
  monitoring:
    query_entropy_exclusions:
      - "provider.example"

Path entropy and governed API routes. Path entropy is also skipped
automatically on any path you already govern with a request_policy
route that names both a host and path constraints (path_patterns or
path_prefixes). The reasoning: if you wrote explicit path rules for a host, the
blunt entropy heuristic is redundant on those exact paths, and it otherwise
false-positives on legitimate high-entropy REST resource ids (an opaque id
segment in /v1/messages/{id} reads as a "high entropy path segment"). This is
the recommended way to run an agent against a TLS-intercepted REST API whose URLs
carry opaque ids.

This exemption is deliberately narrow:

• It is path-only. Subdomain entropy, query entropy, DLP, and SSRF stay fully
  active on the same request.
• It applies only to paths your route matches. Other paths on the same host
  still get path entropy.
• A route with no host, or with no path constraints, never exempts
  anything (a hostless route would otherwise match every host).
• Shadow rules never exempt, because they do not enforce request_policy.

Operator note: the skip covers exactly the paths your route patterns match.
If your agent calls API paths your request_policy route does not cover, widen
the route's path_patterns/path_prefixes to include them (or add the host to
subdomain_entropy_exclusions), otherwise those paths still get path entropy.

Forward Proxy#

Standard HTTP CONNECT tunneling. Agents set HTTPS_PROXY=http://127.0.0.1:8888, and HTTP clients that honor proxy settings flow through pipelock. Pair this with containment, sandboxing, or deployment policy when non-cooperative tools are in scope.

forward_proxy:
  enabled: false # Requires restart to change
  max_tunnel_seconds: 300
  idle_timeout_seconds: 120
  sni_verification: true # Verify TLS SNI matches CONNECT target
  redirect_websocket_hosts: [] # Redirect WS hosts to /ws proxy

TLS Interception#

Enables TLS MITM on CONNECT tunnels, allowing pipelock to decrypt, scan, and re-encrypt HTTPS traffic. When enabled, request bodies and headers are scanned for secret exfiltration, and responses are scanned for prompt injection, closing the CONNECT tunnel body-blindness gap.

Requires a CA certificate trusted by the agent. Generate one with pipelock tls init and install it with pipelock tls install-ca.

tls_interception:
  enabled: false
  ca_cert: "" # path to CA cert PEM (default: ~/.pipelock/ca.pem)
  ca_key: "" # path to CA key PEM (default: ~/.pipelock/ca-key.pem)
  passthrough_domains: # domains to splice (not intercept)
    - "*.googlevideo.com"
  cert_ttl: "24h"
  cert_cache_size: 10000
  max_response_bytes: 5242880 # 5MB; responses larger than this are blocked

Setup:

# Generate a CA key pair
pipelock tls init

# Install the CA into the system trust store (macOS/Linux)
pipelock tls install-ca

# Or export the CA cert for manual installation
pipelock tls show-ca

Scanning behavior: When a CONNECT tunnel is intercepted, pipelock terminates TLS with the client using a forged certificate, then opens a separate TLS connection to the upstream server. Inner HTTP requests are served via Go's http.Server, enabling:

• Request body DLP: same scanning as request_body_scanning (JSON, form, multipart extraction + DLP patterns)
• Request header DLP: same scanning as request_body_scanning.scan_headers
• Authority enforcement: the Host header must match the CONNECT target. Mismatches are blocked (prevents domain fronting inside encrypted tunnels).
• Response injection scanning: buffered responses scanned through the response_scanning pipeline before forwarding to the agent
• Compressed response blocking: responses with non-identity Content-Encoding are blocked (fail-closed, since compressed bytes evade regex DLP)

Fail-closed behaviors:

• Responses exceeding max_response_bytes are blocked
• Compressed responses (gzip, deflate, br) are blocked
• Response read errors are blocked
• Authority mismatch (Host header differs from CONNECT target) is blocked

Passthrough domains: Domains in passthrough_domains are spliced (bidirectional byte copy) without interception, preserving end-to-end TLS. Use this for domains where certificate pinning prevents interception or where you trust the destination. Supports exact match and wildcard prefix (*.example.com matches sub.example.com and the apex example.com).

Best practice -- package registries and LLM providers: Always add package registries (npm, pypi, Go proxy) and LLM API endpoints to passthrough_domains, not just exempt_domains. Using exempt_domains alone is a response-scanning decision, not a TLS-routing decision: the connection is still MITM-ed, clients that reject the generated certificate can still fail the TLS handshake, and pipelock still spends CPU generating certificates for traffic you do not intend to inspect. Passthrough skips interception entirely.

passthrough_domains:
  - "registry.npmjs.org" # npm packages
  - "pypi.org" # Python packages
  - "*.pypi.org"
  - "files.pythonhosted.org" # pip downloads
  - "proxy.golang.org" # Go modules
  - "*.anthropic.com" # LLM provider
  - "*.openai.com" # LLM provider

Request Body Scanning#

Scans request bodies and headers for secret exfiltration and prompt injection before traffic leaves the protected agent path. Catches secrets and instruction-smuggling payloads in POST/PUT/PATCH bodies, JSON keys and values, form-urlencoded fields, outbound WebSocket client frames, reverse-proxy requests, intercepted CONNECT traffic, and Authorization/Cookie headers that bypass URL-level scanning.

Scope: Forward HTTP proxy (HTTPS_PROXY and HTTP_PROXY absolute-URI requests), reverse proxy, outbound WebSocket client text messages, fetch handler headers, and intercepted CONNECT tunnels (when tls_interception.enabled is true).

request_body_scanning:
  enabled: true
  action: warn # warn or block (no strip for bodies)
  pattern_actions: # optional per-DLP-pattern body/header action override
    Google API Key: warn
  disable_patterns: [] # optional exact DLP pattern names to skip on this surface
  max_body_bytes: 5242880 # 5MB; fail-closed above this
  scan_headers: true # scan request headers for DLP
  header_mode: sensitive # "sensitive" (listed headers) or "all" (everything except ignore list)
  sensitive_headers:
    - Authorization
    - Cookie
    - X-Api-Key
    - X-Token
    - Proxy-Authorization
    - X-Goog-Api-Key

Content-type dispatch: JSON bodies have string values and object keys extracted recursively. Form-urlencoded bodies are parsed as ordered key-value pairs so split instruction phrases preserve wire order. Multipart form data scans all part headers plus all part bodies regardless of declared Content-Type (max 100 parts), and decodes Content-Transfer-Encoding: base64 / quoted-printable before scanning. Text/* and XML bodies are scanned as raw text. Unknown content types get a fallback raw-text scan (never skipped, preventing Content-Type spoofing bypass).

Fail-closed behaviors (always blocked regardless of action setting):

• Bodies exceeding max_body_bytes
• Compressed bodies (Content-Encoding: gzip/deflate/br): compressed bytes evade regex DLP
• Body read errors: prevents forwarding empty/corrupt bodies
• Invalid JSON bodies
• Invalid form-urlencoded bodies: prevents parser differential attacks
• Multipart missing boundary parameter
• Multipart with more than 100 parts
• Multipart part exceeding max_body_bytes
• Multipart filename exceeding 256 bytes: prevents secret exfiltration via long filenames

Header scanning: Headers are scanned regardless of destination host. An agent can exfiltrate secrets via Authorization: Bearer <secret> to any host, including allowlisted ones. The URL allowlist controls URL-level blocking, not header DLP bypass.

Security hard-blocks: In enforce mode, immutable core DLP findings in request bodies and headers hard-block with X-Pipelock-Block-Reason: dlp_match even when request_body_scanning.action: warn; they cannot be disabled or downgraded by pattern_actions. Request-body prompt-injection findings hard-block non-provider destinations with X-Pipelock-Block-Reason: prompt_injection. Operators that need audit-only rollout for selected non-core critical body-DLP patterns can set those exact names under request_body_scanning.pattern_actions with warn, or run the deployment with enforce: false.

Adaptive enforcement interaction: A body/header DLP action of warn, including a per-pattern pattern_actions downgrade, still enters the existing adaptive enforcement path and can be upgraded to block unless the destination is adaptive-exempt. disable_patterns removes only the named DLP finding from this request-body/header surface; it does not create a destination exemption and does not affect URL, response, MCP, or file DLP scanning.

Note on security defaults: Omitting request_body_scanning.enabled or request_body_scanning.scan_headers defaults both to true. Set either field to false explicitly only when you intend to disable that protection.

Redaction#

Optional request-side redaction rewrites matched JSON scalars before a request is forwarded upstream. It runs before request-body DLP so warn-mode traffic still forwards the redacted payload instead of the original secret. The same matcher is used for HTTP request bodies, outbound WebSocket client messages, and MCP tools/call params.arguments across stdio, HTTP/SSE, and WebSocket transports.

request_body_scanning:
  enabled: true
  action: warn

redaction:
  enabled: true
  default_profile: code
  profiles:
    code:
      classes:
        - aws-access-key
        - google-api-key
        - github-token
        - slack-token
        - jwt
        - ssh-private-key
  allowlist_unparseable:
    - api.anthropic.com
    - api.openai.com
  allowlist_unparseable_routes:
    - host: login.microsoftonline.com
      methods: [POST]
      path_suffixes: [/oauth2/v2.0/token]
      content_types: [application/x-www-form-urlencoded]
  providers:
    custom_provider:
      host_patterns:
        - api.provider.example
      path_prefixes:
        - /v1/messages
      parser: json
  limits:
    max_body_bytes: 10485760
    max_redactions_per_request: 10000
    max_depth: 64

Requirements and fail-closed behavior:

• redaction.enabled: true requires request_body_scanning.enabled: true because the rewrite hook lives in the request-body scan path.
• Rewrites only operate on complete JSON payloads. Non-JSON HTTP bodies and non-JSON complete WebSocket messages are blocked unless the destination host is on allowlist_unparseable or the request matches allowlist_unparseable_routes.
• Outbound WebSocket fragments are blocked while redaction is enabled. The proxy cannot safely rewrite partial JSON messages.
• Successful rewrites add a redaction summary to the signed action receipt only when one or more values were replaced; untouched requests keep the legacy receipt bytes unchanged.

Hash redaction classes require a self-labeled prefix such as sha256:<64 hex chars> or sha-256=<64 hex chars>. Bare fixed-width hex strings are left alone so opaque OAuth client secrets and session tokens are not corrupted. AWS SigV4 pre-signed URLs also keep the access-key ID inside a structurally valid X-Amz-Credential parameter unchanged; the same access-key shape is still redacted everywhere else.

Request Policy#

Allow-by-default deny/warn safety rails on outbound HTTP API operations. A request forwards unless a rule matches; there is deliberately no section-level default_action knob, so the section can never be configured into default-deny. Request policy is not a DLP scanner and not a behavioral allowlist. It composes with both. It runs before the learn-lock contract gate so a contract allow can never suppress an operation-policy block, and it is independent of request_body_scanning (it reads a body itself only when a route-matched operation predicate or batch endpoint needs one).

Rules match on route (host, effective HTTP method, normalized path, content type) and, optionally, on an extracted GraphQL operation predicate.

request_policy:
  enabled: true
  on_parse_error: block # block (default) | warn | allow
  on_opaque_operation: block # block (default) | warn | allow
  rules:
    - name: "block-graphql-account-mutations"
      action: block
      reason: "account-state mutations require human review"
      route:
        hosts: ["api.example.com", "*.example.net"]
        methods: ["POST"]
        path_prefixes: ["/graphql"]
        content_types: ["application/json"]
      graphql:
        operation_types: ["mutation"]
        root_field_patterns: ["^delete", "^transfer"]
    - name: "warn-on-admin-deletes"
      action: warn
      shadow: true
      reason: "shadow rollout of admin DELETE guard"
      route:
        hosts: ["api.example.com"]
        methods: ["DELETE"]
        path_patterns: ['^/admin/']
  batch:
    - route:
        hosts: ["api.example.com"]
        methods: ["POST"]
        path_prefixes: ["/$batch"]
      requests_field: "requests"
      method_field: "method"
      url_field: "url"
      body_field: "body"
      max_sub_requests: 64

Rule fields:

• name: bounded, metric-label-safe rule identifier.
• action: block or warn. Per-rule only. There is no section-level default.
• shadow: when true, log the would-be action and forward anyway. A shadow match never enforces, and an enforced match always wins over a shadow match of equal strictness.
• reason: operator-facing explanation surfaced on the block. Never logged with request content.
• route: which requests the rule applies to (see below).
• graphql: optional GraphQL operation predicate (see below).

When a rule sets both route and graphql, both must match: the route selects the request, then the predicate is evaluated against the operations extracted from its body.

Route fields (route): an empty constraint matches any value for that dimension; a request matches the route only when every non-empty constraint is satisfied. Within a single dimension (multiple hosts, or path_prefixes plus path_patterns) matching is OR.

Paths are normalized before matching: bounded repeated percent-decoding (so a multi-encoded ..%252e segment cannot hide from dot-segment removal), per-segment ;parameter stripping, and dot-segment / double-slash collapsing.

Method-override handling: a request that tunnels a different method through X-HTTP-Method-Override, X-Method-Override, or X-HTTP-Method is evaluated against both the base method and the overridden method, and the stricter result wins. This stops a POST with X-HTTP-Method-Override: DELETE from dodging a DELETE-scoped rule, and equally stops a real POST from being downgraded by an override the upstream ignores.

GraphQL predicate fields (graphql): applied after the route matches. A request matches when any extracted operation satisfies the predicate. Every operation in a document or batch is evaluated, never just the first. At least one of the two fields must be set.

GraphQL operations are extracted from application/json bodies (single object or batched array) and from GraphQL-over-GET query strings (?query=...&operationName=...). A body that is not valid GraphQL-over-HTTP JSON, or that contains a query that fails to parse, fails closed via on_parse_error. A request element carrying no inline query (an APQ hash, an empty/missing query) is opaque and fails closed via on_opaque_operation. Duplicate fragment names, fragment cycles, unresolved spreads, and expansion-budget exhaustion all make the document unclassifiable and fail closed.

Scope GraphQL rules by path, not content type. A GraphQL-over-GET request carries no body and therefore no Content-Type, so a rule whose route sets content_types: ["application/json"] silently never matches the GET form, even though the engine still extracts the operation from the ?query= string. Constrain GraphQL rules with path_prefixes / path_patterns for the GraphQL endpoint, or leave content_types empty, so one rule covers both the POST-body and GET-query transports.

Discriminator predicate#

As an alternative to the GraphQL predicate, a rule can carry a discriminator predicate that matches a single top-level JSON body field against RE2 value patterns. This handles non-GraphQL JSON APIs that signal the operation through a discriminator key (an action, type, or command field).

  rules:
    - name: "block-account-close-commands"
      action: block
      reason: "account-close commands require human review"
      route:
        hosts: ["api.example.com"]
        methods: ["POST"]
        path_prefixes: ["/rpc"]
        content_types: ["application/json"]
      discriminator:
        field: "action"
        value_patterns: ["^account\\.close$", "^account\\.delete$"]

Semantics, all fail-closed:

• A string value at field is matched against value_patterns; the predicate matches when any pattern matches.
• An absent field does not match. The allow-by-default rail forwards unless another rule matches.
• A present but non-string value, a top-level body that is not a JSON object, or a duplicated target key is opaque and fails closed via on_opaque_operation.
• A body that is not valid JSON fails closed via on_parse_error.

A rule may set both graphql and discriminator; when it does, both predicates must match (in addition to the route). The discriminator predicate is evaluated on every HTTP transport and per WebSocket text frame, the same surfaces as the GraphQL predicate, and it folds into the canonical policy hash.

Batch endpoints#

A JSON batch endpoint wraps multiple sub-requests in one outer request, each carrying its own method, URL, and body. When an outer request route-matches a batch entry, request policy parses the envelope and evaluates every sub-request against the full rule set: host inherited from the outer request, plus the sub-request's effective method, normalized path, and any GraphQL operation in its body or URL query. The strictest decision across all sub-requests wins, so a dangerous operation cannot evade a rule by being wrapped in a batch.

The envelope field names default to the common OData-style JSON batch shape (requests[].{method,url,body}); override them for a differently shaped envelope. A sub-request whose method or URL field is missing or not a string fails closed (it must not silently evaluate as method="" path="/"). Nested batches are expanded up to a fixed depth; beyond that depth a sub-request that itself targets a batch endpoint fails closed regardless of configuration. An unread, oversize, or unparseable envelope fails closed via on_parse_error.

Transport coverage#

Request policy is enforced on the fetch proxy, forward proxy, CONNECT, TLS interception, reverse proxy, and redirect hops. On every HTTP transport it runs before the contract gate. WebSocket is covered on two surfaces: the upgrade handshake is matched route-only (host, GET method, path, content type), and once the socket is open each complete, UTF-8-validated client text frame is evaluated per frame as an operation body over the handshake route (the upgrade is a GET, so the effective method is GET). The per-frame body-predicate gate is checked against the live matcher on each frame rather than cached at upgrade, so a hot-reloaded rule applies to already-open sockets, and benign routes still pay no JSON-parse cost. Fragmented frames and binary frames are not evaluated as operation bodies (documented limit).

When a route-matched operation predicate or batch endpoint needs a body that cannot be inspected, the request is blocked outright, independent of the on_parse_error / on_opaque_operation settings (those apply only to a fully-read body that fails to parse). A body counts as uninspectable when it is unread, exceeds request_body_scanning.max_body_bytes (default 5 MiB), or hits a read error. The bounded read has already consumed the body stream, so the request can no longer be forwarded intact.

Enforcement, audit, and receipts#

A matched rule records a decision metric and an audit event with bounded, operator-defined labels only, never body or matched content. An enforced (non-shadow) block returns HTTP 403 with the request_policy_deny block reason and, when a receipt emitter is configured, a correlated receipt. warn and shadow matches are logged and counted, then forwarded.

WebSocket Proxy#

Bidirectional WebSocket scanning via /ws?url=ws://upstream:9090/path. Text frames are scanned through the full DLP + injection pipeline. Fragment reassembly handles split messages in scan-only mode; when redaction.enabled is on, outbound fragmented client messages fail closed because the proxy only rewrites complete JSON messages.

websocket_proxy:
  enabled: false # Requires restart to change
  max_message_bytes: 1048576 # 1MB
  max_concurrent_connections: 128
  scan_text_frames: true
  allow_binary_frames: false
  strip_compression: true # Required for scanning
  max_connection_seconds: 3600
  idle_timeout_seconds: 300
  origin_policy: rewrite # rewrite, forward, or strip
  forward_cookies: false

DLP (Data Loss Prevention)#

Scans URLs for secrets and sensitive data using regex patterns. Built-in patterns cover API keys, tokens, credentials, and prompt injection indicators. Runs before DNS resolution to prevent exfiltration via DNS queries. Matching is always case-insensitive.

dlp:
  scan_env: true
  secrets_file: "" # path to known-secrets file
  min_env_secret_length: 16
  include_defaults: true # merge user patterns with built-in patterns
  patterns:
    - name: "Custom Token"
      regex: 'myapp_[a-zA-Z0-9]{32}'
      severity: critical
    - name: "Telegram Bot Token"
      regex: '[0-9]{8,10}:[A-Za-z0-9_-]{35}'
      severity: critical
      exempt_domains: # skip this pattern for these destinations
        - "api.telegram.org"

There is no top-level dlp.action setting. DLP enforcement is transport-specific:

• URL/query scanning uses global mode plus enforce (mode: audit or enforce: false logs but does not block).
• HTTP request body/header scanning uses request_body_scanning.action.
• MCP input scanning uses mcp_input_scanning.action.
• response_scanning.action: strip is for inbound prompt-injection response rewriting, not DLP.

Validated Patterns (Financial DLP)#

Some patterns include a validator field for post-match checksum verification. When set, regex matches are passed through a checksum algorithm before being flagged. This eliminates false positives from random numbers that happen to match the pattern format.

Built-in validated patterns:

• Credit Card Number (validator: luhn) — Visa, Mastercard (including 2-series), Amex, Discover, JCB. Luhn checksum rejects ~90% of false positives.
• IBAN (validator: mod97) — International Bank Account Numbers. Validates ISO 13616 country codes and ISO 7064 mod-97 checksum. Rejects ~99% of false positives.
• Bitcoin WIF Private Key (validator: wif) — Base58Check decoding with SHA-256d checksum verification. Validates mainnet version byte (0x80) and 32/33-byte payload. Eliminates false positives from text that happens to contain 51-52 characters of the base58 alphabet.

To add ABA routing numbers (not in defaults due to higher false positive rate):

dlp:
  patterns:
    - name: "ABA Routing Number"
      regex: '\b\d{9}\b'
      severity: low
      validator: aba

Pattern Merging#

When include_defaults is true (default), your patterns are merged with the built-in set by name. If you define a pattern with the same name as a built-in, yours overrides it. New built-in patterns added in future versions are automatically included.

Set include_defaults: false to use only your patterns.

Per-Pattern Domain Exemptions#

Use exempt_domains to skip a specific DLP pattern for specific destination domains. Other patterns still fire, and response scanning remains active. Supports wildcard matching (*.example.com matches sub.example.com and example.com).

Scope: exempt_domains applies to URL-based scanning only (fetch proxy, forward proxy, WebSocket, TLS intercept). It does not apply to MCP input scanning (which has no destination domain) or environment variable leak detection (scan_env). To suppress those, use the suppress section.

This is useful for APIs that embed credentials in URL paths by design (e.g., Telegram bot API uses /bot<token>/sendMessage). The token should be allowed when talking to Telegram but blocked if it appears in requests to other domains.

To exempt a built-in pattern, override it by name and add exempt_domains:

dlp:
  patterns:
    - name: "Anthropic API Key" # same name as built-in — overrides it
      regex: 'sk-ant-[a-zA-Z0-9\-_]{20,}\b'
      severity: critical
      exempt_domains:
        - "*.anthropic.com"

For built-in provider-key patterns, the default config already exempts the provider's own API host for URL DLP and adds matching suppress entries for request-body and request-header DLP. The same key is still blocked when sent to any other destination. See Provider-Key DLP Coverage for included shapes, exclusions, and the custom provider-key path.

Built-in DLP Patterns (65)#

Environment Variable Leak Detection#

When scan_env: true, pipelock reads all environment variables at startup and flags URLs containing any env value that is:

• 16+ characters (configurable via min_env_secret_length)
• Shannon entropy > 3.0 bits/char
• Checked in raw form, base64, hex, and base32 encodings

This catches leaked API keys even without a specific DLP pattern for that provider.

Seed Phrase Detection#

Detects BIP-39 mnemonic seed phrases in URLs, request bodies, headers, MCP tool arguments, WebSocket frames, and cross-request fragment reassembly. Seed phrase compromise is permanent and irreversible, making this a critical detection layer for crypto-adjacent deployments.

seed_phrase_detection:
  enabled: true # default: true (security default)
  min_words: 12 # minimum consecutive BIP-39 words to trigger (12, 15, 18, 21, or 24)
  verify_checksum: true # default: true (validates BIP-39 SHA-256 checksum, eliminates FPs)

The detector uses a dedicated scanner (not regex). It tokenizes text, runs a sliding window over the 2048-word BIP-39 English dictionary, and validates the checksum. Detection covers varied separators (spaces, commas, newlines, dashes, tabs, pipes).

Action follows the transport-level DLP action: URL scan always blocks, MCP input uses mcp_input_scanning.action, body/header uses request_body_scanning.action.

Per-Pattern Warn Mode (DLP Rollout)#

Individual DLP patterns can carry an explicit action: warn to run in audit-only mode. Warn matches route to an informational channel and emit audit events through the runtime lifecycle, but do not trigger enforcement. Use this to roll out new detections on production traffic before flipping them to default (block).

dlp:
  patterns:
    - name: "VendorInternalToken"
      regex: "vendor_[A-Za-z0-9]{32}"
      severity: high
      action: warn # audit-only; does not block

Only action: warn and omitted (empty) are accepted on a per-pattern basis. block, strip, ask, redirect, or any other value is rejected at config load. The top-level dlp.action field is still reserved — it rejects every value including block.

Matches from warn patterns appear in scan results as InformationalMatches (distinct from Matches) and emit structured audit events with the matched pattern name, severity, transport, and request context via the DLPWarnHook. Standard emission sinks (webhook, syslog, OTLP) pick these up.

Recommended rollout flow:

1. Ship the pattern with action: warn.
2. Deploy and watch the audit sink for hits against real traffic.
3. Tune the regex + exempt_domains until false-positive rate is acceptable.
4. Remove the action line (or set it to empty string) to revert the pattern to normal DLP enforcement semantics — the actual verdict then follows the transport-level DLP action and the session's mode/enforce state rather than being unconditionally block.
5. Roll out the change through your normal config-review process.

Response Scanning#

Scans fetched content for prompt injection before returning to the agent. Uses a 6-pass normalization pipeline: zero-width stripping, word boundary reconstruction, leetspeak folding, optional-whitespace matching, vowel folding, and encoding detection.

response_scanning:
  enabled: true
  action: warn # block, strip, warn, or ask
  ask_timeout_seconds: 30 # HITL approval timeout
  include_defaults: true
  exempt_domains: # skip injection scanning for these hosts
    - "api.vendor.example"
    - "*.vendor.example"
  size_exempt_domains: # trusted large-download hosts; scan cap only
    - "downloads.example.com"
  size_exempt_scan_max_bytes: 67108864
  size_exempt_scan_max_inflight_bytes: 268435456
  unscannable_passthrough: # explicit audited stream-unscanned valve
    - host: "downloads.example.com"
      paths: ["/opaque/pkg.bin"]
      content_types: ["application/octet-stream"]
      reason: "opaque signed archive"
      added: "2026-07-04"
      expires: "2099-12-31"
  mcp_servers: # MCP response trust classes; default is untrusted/block
    - server: "analysis-server"
      trust: "reasoning" # reasoning => warn; untrusted => block
  patterns:
    - name: "Custom Injection"
      regex: 'override system prompt'

Built-in patterns (32): Prompt-injection and state/control poisoning coverage includes jailbreak phrases, system overrides, role overrides, instruction manipulation, encoded payloads, tool invocation commands, authority escalation, credential solicitation, credential path directives, auth material requirements, memory persistence directives, preference poisoning, covert-action directives, silent credential handling, and CJK-language override patterns. All patterns use DOTALL mode to match across newlines in multiline tool output.

Actions:

• block: reject the response entirely, agent gets an error
• strip: redact matched text, return cleaned content
• warn: log the match, return content unchanged
• ask: pause and prompt the operator for approval (requires TTY)

MCP required control: response_scanning.enabled: false is currently ignored in pipelock mcp proxy and pipelock mcp scan modes because MCP response scanning is the required injection-control path. Pipelock runs with default response scanning and prints a warning naming the overridden field. This compatibility fallback will become a startup/reload error in a future release; remove the disable to silence the warning.

Exempt domains: Trusted response APIs can return instruction-like text as part of normal operation, which can trigger false positives. Use exempt_domains to skip injection scanning for trusted providers. DLP scanning on the outbound request still runs — only the response injection scan is skipped. Applies to fetch proxy, forward proxy, CONNECT (TLS intercept), WebSocket, and reverse proxy. Does not affect MCP response scanning; MCP uses response_scanning.mcp_servers so a reasoning-model MCP server can warn while web-relay MCP servers keep blocking.

MCP response trust classes: MCP response scanning defaults to untrusted, which blocks response-injection findings even if the generic response_scanning.action is warn. This protects web-relay servers such as fetch/search/scraping tools. To allow a reasoning-model MCP server to answer security-analysis questions that quote canonical jailbreak strings, opt in by server name:

response_scanning:
  mcp_servers:
    - server: "analysis-server"
      trust: "reasoning"

reasoning maps to warn; untrusted maps to block. Unknown trust values fail config validation, duplicate server entries fail validation, and entries are surfaced as warnings when response_scanning.enabled is false. The trust decision applies to MCP stdio, stdio-to-HTTP, reverse Streamable HTTP/SSE, and WebSocket surfaces because they share the MCP response scan gate. Block logs and JSON-RPC errors name the server, matched pattern, and trust class so operators can see whether a server needs an explicit trust-class review.

Response trust does not make a server trusted for taint propagation. If a reasoning server is also an operator-trusted source whose clean responses should not contaminate the session, add the same --server-name value under taint.trusted_mcp_servers. Prompt-injection findings still raise hostile taint.

Launch MCP proxies with a stable server identity so the entry can match: use pipelock mcp proxy --server-name analysis-server ... for per-server wrappers, or pipelock run --mcp-listen ... --mcp-upstream ... --mcp-server-name analysis-server for the long-lived MCP listener.

For forward-proxy and TLS-intercepted traffic, an exempt host's response streams through untouched when response_scanning.enabled is true: no buffering, response scan-cap block, media metadata strip, Browser Shield rewrite, or injection scan is applied to that trusted response. Request-side DLP, redaction, SSRF, authority checks, and budget accounting still run. If a host needs full byte-preserving passthrough without MITM, prefer tls_interception.passthrough_domains.

Non-exempt responses that must be buffered for response scanning, Browser Shield, or media policy block fail-closed if they exceed the configured scan cap (fetch_proxy.max_response_mb or tls_interception.max_response_bytes). The block uses reason code response_size and names the host, observed size, scan ceiling, and the knob to raise. Data-budget truncation is separate and remains an explicit budget policy.

Use size_exempt_domains for trusted large-download hosts when the default fail-closed scan ceiling blocks legitimate artifacts such as package headers, signed binaries, or model weights. This exemption is narrower than exempt_domains: it only takes effect after the response exceeds the normal scan cap. Pipelock then buffers the full response up to size_exempt_scan_max_bytes, runs the same whole-buffer response pipeline used for under-cap bodies, and delivers bytes only after the verdict is clean or transformed by policy. Responses over that ceiling, read errors, scan errors, and exhausted size_exempt_scan_max_inflight_bytes reservations block fail-closed without delivering upstream bytes. Smaller responses from the same host still take the normal buffered scanning path. The exemption applies to forward proxy, TLS interception, and reverse proxy responses. MCP-HTTP responses and compressed (Content-Encoding) responses still fail closed when they cannot be fully scanned, regardless of this list.

Use unscannable_passthrough only for opaque-by-construction artifact downloads that cannot be meaningfully scanned and must remain byte-streamed. This is intentionally stricter than size_exempt_domains: passthrough is considered only after a response exceeds the normal scan cap, the host is also in size_exempt_domains, the path is an exact configured paths match, the response media type is a configured non-textual content_types value, Content-Length is present and positive, and Content-Disposition is attachment. Missing, malformed, expired, textual, prefix-style, inline, or chunked entries fall back to bounded scanning and then fail closed if they still cannot be inspected. Every match records the host, path, content type, and sanitized operator reason in an audit warning and receipt; keep reason audit-safe and free of secrets or private ticket details.

Generic SSE streaming (response_scanning.sse_streaming)#

Inline body scanning of text/event-stream responses for non-A2A LLM traffic (OpenAI chat completions, Anthropic messages, OpenAI-compatible gateways, generic LLM SSE). Without this, streaming responses fall back to the buffered scan path, which caps the body at the proxy's max-body limit and breaks per-event flushing — the agent waits for the whole response before seeing any tokens.

response_scanning:
  sse_streaming:
    enabled: true # generic SSE inline scanning (default true)
    action: block # block or warn
    max_event_bytes: 65536 # per-event data-payload ceiling (default 64 KB; excludes metadata)

Behavior:

• Each event's canonical SSE text (data: plus event:, id:, and retry: metadata) is fed through the same DLP + injection patterns used for buffered response scanning.
• A bounded rolling tail catches DLP and prompt-injection payloads split across sequential events.
• Clean events flush to the client immediately. In block mode, the first detected event terminates the stream; later events are not forwarded. In warn mode, findings are logged and forwarding continues.
• response_scanning.exempt_domains still pins prompt-injection findings to visibility-only for trusted hosts. DLP findings are not exempted.
• Global suppress rules apply before SSE action selection.
• Compressed SSE (gzip, br, zstd) is fail-closed-blocked on every transport. The streaming scanner is never given compressed bytes.
• Receipts use the sse_stream layer label (A2A keeps its existing a2a_stream label so dashboards stay continuous).

See docs/guides/sse-streaming.md for the full guide with transport coverage, fail-closed behavior, and adversarial test matrix.

MCP Input Scanning#

Scans JSON-RPC requests from agent to MCP server for DLP leaks and injection in tool arguments.

mcp_input_scanning:
  enabled: true
  action: warn
  on_parse_error: block # block or forward
  response_timeout_seconds: 0 # 0 = disabled (stdio MCP proxy only)

Auto-enabled when running pipelock mcp proxy. response_timeout_seconds applies independently of enabled; it governs the response read path whenever the stdio-fronted proxy is running.

If top-level redaction.enabled is also set, tools/call params.arguments are rewritten through the same matcher before input DLP runs. The behavior is identical across stdio, HTTP/SSE upstream mode, HTTP listener mode, and MCP-over-WebSocket.

MCP Tool Scanning#

Scans tools/list responses for poisoned tool definitions and detects mid-session description changes (rug pulls). Extracts text from all schema fields that an LLM might ingest: description, title, default, const, enum, examples, pattern, $comment, and vendor extensions (x-*). Recurses through composition keywords (allOf, anyOf, oneOf, $defs, if/then/else) and extracts string leaves from nested objects and arrays.

mcp_tool_scanning:
  enabled: true
  action: warn
  detect_drift: true

When detect_drift is enabled, Pipelock hashes the canonical full tool object
from tools/list, excluding only Pipelock's own provenance attestation in
_meta["com.pipelock/provenance"]. Other _meta fields are part of the drift
hash. If an MCP server publishes volatile values such as nonces, timestamps,
request IDs, or per-list counters in the tool object, that tool will drift on
every tools/list. Keep tools/list definitions stable: move changing values
to tool call arguments, tool results, or an out-of-band capability endpoint, and
leave _meta for stable metadata unless drift on that value is intentional.

MCP Tool Policy#

Pre-execution rules that block or warn before tool calls reach the MCP server. Ships with 17 built-in rules covering destructive operations, credential access, network exfiltration, persistence mechanisms, and encoded command execution.

mcp_tool_policy:
  enabled: true
  action: warn
  rules:
    - name: "Block shell execution"
      tool_pattern: "execute_command|run_terminal"
      action: block
    - name: "Warn on sensitive writes"
      tool_pattern: "write_file"
      arg_pattern: '/etc/.*|/usr/.*'
      action: warn
    - name: "Block shadow file reads"
      tool_pattern: "read_file"
      arg_pattern: '/etc/shadow'
      arg_key: '^(file_?path|target)$'
      action: block
    - name: "Block large transfers"
      tool_pattern: "^transfer$"
      arg_key: "^amount$"
      arg_type: number
      arg_number_gt: 1000000000
      action: block

Rule fields:

• name: rule identifier
• tool_pattern: regex matching tool name
• arg_pattern: regex matching argument values (optional; omit for tool-name-only rules)
• arg_key: regex scoping arg_pattern or structural validators to specific top-level argument keys (optional for arg_pattern, required for structural validators). Without arg_key, arg_pattern checks values from all argument keys. Values under matching keys are extracted recursively for regex matching.
• arg_type: required JSON type guard for the value at arg_key: string, number, integer, boolean, array, or object. Type mismatch is dangerous and matches fail-closed. When used alone, arg_type means "match if this value is not this type." If combined with numeric bounds, it must be number or integer; if combined with length bounds, it must be string or array.
• arg_number_gt: match when the numeric value at arg_key is strictly greater than this threshold.
• arg_number_lt: match when the numeric value at arg_key is strictly less than this threshold.
• arg_len_gt: match when the string rune count or array element count at arg_key is strictly greater than this non-negative threshold.
• arg_len_lt: match when the string rune count or array element count at arg_key is strictly less than this non-negative threshold.
• arg_value_in: list of dangerous canonical values; matches when the canonical value at arg_key is in the set.
• action: per-rule override (warn, block, redirect, or defer)
• redirect_profile: reference to a named redirect profile (required when action: redirect)
• resolution_policy: affirmative-clearing policy (required when action: defer; see below)

Tool policy is a default-allow denylist: a rule describes the dangerous condition, and a matched rule applies its action. arg_pattern and all configured structural validators AND together within one rule. Numeric validators parse JSON numbers losslessly, so 1e9 and 1000000000 compare as equal. If a bound/type/length validator cannot evaluate a present or required value, the rule matches fail-closed; the exception is an arg_value_in-only rule with an absent key, which does not match because the dangerous value was not sent.

Shell obfuscation detection is built-in for arg_pattern: backslash escapes, $IFS substitution, brace expansion, and octal/hex escapes are decoded before matching. See Redirect Action (v2.0) for redirect profile configuration.

Defer Action#

action: defer withholds a matched tool call instead of forwarding or blocking it, and resolves the held action to a terminal decision later. Defer is fail-closed and affirmative-clearing: the held action resolves to allow only on an explicit positive signal; timeout, cancellation, parse error, kill switch, capacity overflow, resolver error, process restart, and any non-affirmative result all resolve to block. The absence of an adverse signal is never treated as permission.

Defer is supported on MCP stdio and the stdio-to-HTTP bridge. On any other MCP transport, a defer-matched tool call is blocked (fail-closed) rather than held, because those transports cannot enforce a held-action resume.

A defer rule must declare a resolution_policy with at least one affirmative signal, or config load fails. The held-action bounds live in a top-level defer: section (sibling to mcp_tool_policy); the resolver programs and the per-rule resolution_policy live under mcp_tool_policy:

defer: # top-level section
  enabled: true
  timeout_seconds: 2 # hard per-hold timeout; resolves to block on expiry
  max_pending: 64 # total concurrent holds (overflow denies the new action)
  max_pending_per_session: 8 # per-session concurrent holds
  max_pending_bytes: 1048576 # total held-payload budget
  max_cascade_depth: 8 # max same-session pending-ancestor chain depth

mcp_tool_policy:
  enabled: true
  defer_resolver_profiles:
    approve-writes:
      exec: ["/usr/local/bin/approve-resolver"] # audited program; emits the affirmative signal
      reason: "human approval for write tools"
  rules:
    - name: "defer-risky-writes"
      tool_pattern: "^fs_write$"
      action: defer
      resolution_policy:
        resolver_profile: approve-writes # required for allow_on.approval or step_up_on.approval_requests_human
        allow_on:
          approval: true # allow only when the resolver returns an affirmative result
          tool_inventory_baseline: false # or: re-confirm against the pinned tool inventory baseline

When a new held action is admitted while another action from the same session is still pending, Pipelock records a derived linkage kind of session_pending_ancestor: the new action's parent is the newest still-held action in that session, and its cascade depth is the parent depth plus one. This is a temporal fact observed by the proxy, not a claim that the child consumed the parent's data. Linkage requires a stable session identity: actions without a session ID are never linked to each other — each is an independent depth-1 root — so unrelated session-less flows cannot inherit depth from, or be cascade-blocked by, one another.

max_cascade_depth bounds that continuous same-session defer pressure. If the next hold would exceed the limit, Pipelock denies it before creating held state, emits a resolution receipt with resolution_source: "cascade_limit", and records a terminal resolved_block row in deferred-actions.jsonl with the same cascade parent/depth metadata. If a parent later resolves to anything other than allow — including an ask/step-up outcome — still-held descendants block immediately with resolution_source: "cascade"; a non-allow parent is terminal for its whole descendant chain, and each descendant's receipt carries the parent defer ID so the triggering resolution stays traceable. A parent allow does not allow descendants; each descendant still needs its own affirmative resolution signal.

resolution_policy.allow_on.policy_permits is rejected on the supported defer transports because they do not own a live config-reload callback. Each held action emits a hash-chained defer receipt and a resolution receipt bound to the original call; pipelock verify-receipt --clean-report derives a minimal offline-verifiable report that fails closed on any incomplete, duplicate, identity-changed, or non-terminal defer pair. Defer is free-tier.

MCP Session Binding#

Pins tool inventory on the first tools/list response. Subsequent tool calls are validated against this baseline. Unknown tools trigger the configured action.

# pipelock-fragment-id: mcp-session-binding
mcp_session_binding:
  enabled: true
  unknown_tool_action: warn
  no_baseline_action: warn

Tool baseline caps at 10,000 tools per session to prevent memory exhaustion.

MCP WebSocket Listener#

Controls inbound WebSocket connections when the MCP proxy runs in listener mode with a ws:// or wss:// upstream. Loopback origins are always allowed.

mcp_ws_listener:
  allowed_origins:
    - "https://example.com"
  max_connections: 100

Session Profiling#

Per-session behavioral analysis that detects domain bursts and volume spikes.

session_profiling:
  enabled: true
  anomaly_action: warn
  domain_burst: 5
  window_minutes: 5
  volume_spike_ratio: 3.0
  max_sessions: 1000
  session_ttl_minutes: 30
  cleanup_interval_seconds: 60

Behavioral Baseline#

Profile-then-lock behavioral enforcement for a single agent. Pipelock observes completed identity sessions, learns per-session ranges, waits for operator ratification, and enforces deviations only after the profile reaches locked.

Behavioral baseline depends on session profiling because session profiling owns the session store and eviction path that records completed-session metrics. Config validation rejects behavioral_baseline.enabled: true unless session_profiling.enabled: true.

session_profiling:
  enabled: true

behavioral_baseline:
  enabled: true
  profile_dir: /var/lib/pipelock/baseline-profiles
  learning_window: 10
  deviation_action: block
  auto_ratify: false
  sensitivity_sigma: 2.0
  lock_dimensions:
    - tool_calls
    - unique_tools
    - domains
    - duration
    - requests
  poison_resistance: true
  seasonality_mode: none

Profiles persist as one JSON file per agent in profile_dir. A learned profile moves to ratify, but it does not enforce until an operator runs pipelock baseline ratify <agent> against the authenticated admin API. pipelock baseline show <agent> displays learned per-dimension ranges plus retained, observed, and trimmed session counts so the operator can approve the profile with context. pipelock baseline forget <agent> removes the persisted profile and returns the agent to observe/relearn state.

The baseline admin endpoints (list, show, ratify, forget) are only mounted on the dedicated admin API listener. Set both kill_switch.api_token and kill_switch.api_listen; the endpoints are not registered on the agent-facing main proxy port.

Adaptive Enforcement#

Per-session threat score that accumulates across scanner hits and decays on clean requests. When the score exceeds the threshold, the session escalates through levels (elevated → high → critical). At each level, the levels configuration upgrades warn and ask actions to block, or denies all traffic.

# pipelock-fragment-id: adaptive-enforcement
adaptive_enforcement:
  enabled: true
  escalation_threshold: 5.0
  decay_per_clean_request: 0.5
  level_duration_seconds: 300
  deescalation_check_seconds: 30
  clean_requests_to_deescalate: 0
  severity_weighted_signals: false
  cooperative_tool_downweight: true
  levels:
    elevated:
      upgrade_warn: block # warn→block when session is elevated
    high:
      upgrade_warn: block
      upgrade_ask: block # ask→block when session is high risk
    critical:
      upgrade_warn: block
      upgrade_ask: block
      block_all: true # deny all requests when session is critical

By default, attack containment is unchanged: a hard block contributes the same
score as before, adaptive levels recover only by time, and the 5-minute level
duration plus 30-second sweep cadence are preserved. The clean-request recovery
path is opt-in because it is intended for single interactive-agent
false-positive recovery; it never advances on mixed traffic because every
adaptive signal resets the consecutive-clean counter.

Escalation Levels#

Sessions progress through three levels as threat score accumulates past escalation_threshold multiples. Each level can independently upgrade action severity.

Level Actions#

Each level accepts the following fields. All fields use pointer semantics:

• Omit the field (or omit levels entirely) to apply the default behavior.
• Set to "block" to upgrade that action class at this level.
• Set to "" (empty string) to explicitly disable an upgrade (softening from a parent config).

Monotonic enforcement: higher levels must never be weaker than lower levels. If elevated.upgrade_warn: block, then high and critical must also have upgrade_warn: block (or omit it for the default, which is block). Pipelock validates this at config load time and rejects violations.

Default behavior when levels is omitted:

De-escalation#

Sessions at block_all recover autonomously via a background sweep that runs
every 30 seconds. If a session has been at its current escalation level for
longer than 5 minutes, it is automatically stepped down one level. Recovery
also triggers on the next incoming request, WebSocket frame, or MCP message
after the timer expires (on-entry fast path). The session must accumulate new real signals to re-escalate.

De-escalation drops one level per 5-minute period. A session at critical with no activity takes 15 minutes (3 periods) to return to normal. Each de-escalation resets the threat score to half the current threshold to prevent immediate re-escalation from stale points.

When a session is at a block_all level, blocked retries do not refresh the session's idle timer. This allows idle eviction to eventually clean up sessions that are no longer generating traffic, preventing zombie sessions from persisting indefinitely.

Domain Burst Scoring#

Session profiling detects domain bursts (many unique domains in a short window). When the burst threshold is crossed, the anomaly is signaled once per window with the configured score. Subsequent requests in the same window still trigger the configured anomaly_action (block or warn) but do not add further adaptive score, preventing burst detection from driving sessions to critical on its own. IP-wide domain bursts are tracked separately to catch agent-identity rotation from a single client IP. When cooperative_tool_downweight is enabled, burst signals from known cooperative tool user agents are reduced instead of scored at full browser-like weight.

Kill Switch#

Emergency deny-all with six independent activation sources: enabled,
sentinel_file, API, SIGUSR1, Conductor remote kill, and Conductor
stale-bundle detection. Any one active denies normal traffic (OR-composed)
except for configured exemptions (health_exempt, metrics_exempt,
api_exempt, allowlist_ips). The two Conductor-driven sources are activated
by the enterprise follower runtime. See Kill Switch
for operational details.

Heads-up on enabled: the enabled field is a source, not a subsystem switch. Setting enabled: true immediately activates the kill switch and denies all traffic from startup (all requests return HTTP 503). To configure the API/signal/sentinel sources for future activation without engaging the kill switch at startup, leave enabled: false.

kill_switch:
  enabled: false
  sentinel_file: /tmp/pipelock-kill # example path; default is "" (disabled)
  message: "Emergency deny-all active"
  health_exempt: true
  metrics_exempt: true
  api_exempt: true
  api_token: "" # Required for API source
  api_listen: "" # Requires restart. Separate port for operator API.
  allowlist_ips: [] # IPs that bypass kill switch

Port isolation: When api_listen is set, the kill switch, session, adaptive, and baseline admin APIs run on a dedicated port. The main proxy port has no API routes, preventing agents from deactivating their own kill switch, resetting their own sessions, or ratifying their own behavioral baseline.

Environment variable override: Set PIPELOCK_KILLSWITCH_API_TOKEN to override api_token from the config file. This is useful for Kubernetes deployments where the config file lives in a ConfigMap (plaintext in etcd) but the token should come from a Secret:

env:
  - name: PIPELOCK_KILLSWITCH_API_TOKEN
    valueFrom:
      secretKeyRef:
        name: pipelock-secrets
        key: killswitch-api-token

Session Admin API#

When kill_switch.api_token is configured, the session admin API is available alongside the kill switch endpoints. Uses the same bearer token authentication and port isolation.

The {key} parameter is URL-encoded. For example, my-agent|10.0.0.1 becomes my-agent%7C10.0.0.1.

Reset scope: identity-family scoped. Resetting a session clears the session's threat score, escalation level, and block_all flag. It also clears shared IP-level burst tracking for the client IP and cross-request exfiltration (CEE) state. Other sessions on the same IP will have their burst state cleared as a side effect.

Rate limiting: every mutating action (reset, airlock, task, trust, terminate, baseline ratify, baseline forget) and every detail lookup (inspect, explain) is rate-limited to 10 requests per minute per action. Each action tracks its own sliding-window counter so abuse of one endpoint cannot starve another — an operator can still hit /reset or /airlock during incident response even if /task or /trust is under load. Only GET /api/v1/sessions and GET /api/v1/baseline (the list endpoints) are unbounded; they are used as entry points for recovery tooling and have no destructive side effect. Responses that hit the limit return 429 Too Many Requests with Retry-After: 60.

Sessions are classified as identity (operator-targetable, e.g. my-agent|10.0.0.1) or invocation (internal MCP sessions, e.g. mcp-stdio-42). Only identity sessions can be reset, mutated, or terminated.

Operator CLI: the admin API is exposed through pipelock session <subcommand> for airlock recovery, pipelock adaptive <subcommand> for fleet-level adaptive state, and pipelock baseline <subcommand> for behavioral-baseline inspection and ratification. See cli/session.md, cli/adaptive.md, and cli/baseline.md for the operator references.

Token hot-reload: kill_switch.api_token is hot-reloaded on SIGHUP or fsnotify config-file changes. Rotating the token in YAML (or via the PIPELOCK_KILLSWITCH_API_TOKEN env var, which wins over YAML) takes effect on the next admin API call without restarting the proxy. The previous bearer credential is revoked atomically: requests in flight at the moment of rotation complete against the token they were issued against; subsequent requests must present the new bearer. Setting api_token to the empty string disables the endpoint (HTTP 503) without tearing down the listener, so an operator can revoke access during an incident and restore it later with a second reload.

Airlock#

Per-session graduated quarantine with timer-based recovery. When adaptive enforcement escalates a session, the airlock state machine can transition the session through soft (observe-only), hard (reads allowed, writes blocked, long-lived connections torn down), and drain (no new traffic, existing in-flight requests complete within drain_timeout_seconds). All three tiers are timed quarantines that auto-recover back down through lower tiers as soft_minutes/hard_minutes/drain_minutes expire — drain is not a terminal state and is not equivalent to POST /api/v1/sessions/{key}/terminate. Operators can override the tier at any time through the session admin API or the pipelock session CLI; explicit termination (the destructive reset) lives behind the dedicated terminate endpoint.

Airlock requires triggers: airlock.enabled: true alone is a no-op. Configure at least one trigger (triggers.on_high, triggers.on_critical) to specify which tier fires at each adaptive escalation level. All shipped presets wire on_high: soft + on_critical: hard by default. Freehand configs that set enabled: true with no triggers will reach critical escalation without ever entering airlock.

airlock:
  enabled: false
  triggers:
    on_elevated: none # no airlock on elevated
    on_high: soft # soft quarantine on high
    on_critical: hard # hard quarantine on critical
  timers:
    soft_minutes: 5 # soft tier auto-recovers after 5 minutes
    hard_minutes: 15 # hard tier auto-drops to soft after 15 minutes
    drain_minutes: 0 # drain timer disabled
    drain_timeout_seconds: 30 # drain deadline for in-flight completion

Event Emission#

Forward audit events to external systems. Three independent sinks (webhook, syslog, OTLP), each with its own severity filter. Emission is fire-and-forget and never blocks the proxy.

emit:
  instance_id: "prod-agent-1"
  webhook:
    url: "https://your-siem.example.com/webhook"
    min_severity: warn
    auth_token: ""
    timeout_seconds: 5
    queue_size: 64
    format: json # json, cef, or ocsf
  syslog:
    address: "udp://syslog.example.com:514"
    min_severity: warn
    facility: local0
    tag: pipelock
    format: json
  otlp:
    endpoint: "http://otel-collector:4318"
    min_severity: warn
    headers:
      Authorization: "Bearer <token>"
    timeout_seconds: 10
    queue_size: 256
    gzip: false

OTLP events are sent as log records over HTTP/protobuf. Each pipelock audit event maps to one OTLP LogRecord with service.name=pipelock as a resource attribute. Retries on 429, 502, 503, 504, and network errors with bounded exponential backoff (3 attempts, 1s/2s/4s). 500 and 501 are not retried. No gRPC, no batching timer.

Severity levels (hardcoded per event type, not configurable):

• critical: kill switch deny, adaptive escalation to critical level (enforcement upgraded across all transports)
• warn: blocked requests, anomalies, session events, MCP unknown tools, scan hits
• info: allowed requests, tunnel open/close, WebSocket open/close, config reload

Tool Chain Detection#

Detects attack patterns in sequences of MCP tool calls using subsequence matching with gap tolerance.

tool_chain_detection:
  enabled: true
  action: warn
  window_size: 20
  window_seconds: 60
  max_gap: 3
  tool_categories: {} # map tool names to categories
  pattern_overrides: {} # per-pattern action overrides
  sensitivity_labels: {} # override lethal-trifecta source/sink labels
  custom_patterns: []

Ships with 10 built-in patterns covering reconnaissance, credential theft, data staging, persistence, and exfiltration chains. The built-in lethal-trifecta detector watches for untrusted_source -> sensitive_source -> external_sink sequences. Use sensitivity_labels when your tool names do not carry enough semantic signal for the keyword fallback, and use pattern_overrides.lethal-trifecta to change that detector's action.

Cross-Request Exfiltration Detection#

Detects secrets split across multiple requests within a session. Two independent mechanisms (entropy budget and fragment reassembly) can run together or separately. Both feed into adaptive enforcement scoring.

cross_request_detection:
  enabled: false
  action: warn
  entropy_budget:
    enabled: false
    bits_per_window: 4096
    window_minutes: 5
    action: block
  fragment_reassembly:
    enabled: false
    max_buffer_bytes: 65536
    window_minutes: 5

Entropy Budget#

Tracks cumulative Shannon entropy of all outbound payloads (URLs, request bodies, MCP JSON-RPC payloads, WebSocket frames) per session within a sliding time window. When total entropy bits exceed the budget, the configured action fires.

Tuning: The default 4096 bits per 5-minute window allows roughly 500 characters of random data across URL query parameters and path segments. This is appropriate when scanning URL-level traffic only.

With TLS interception enabled, request bodies are also scanned for entropy. A single LLM API call body (conversation context) can contain 100,000+ bits of entropy. Set bits_per_window to 500000 or higher when using tls_interception with cross-request detection, and add your LLM provider to exempt_domains:

cross_request_detection:
  enabled: true
  entropy_budget:
    enabled: true
    bits_per_window: 500000
    exempt_domains:
      - "*.anthropic.com"
      - "*.openai.com"
      - "*.minimax.io"

Fragment Reassembly#

Buffers outbound payloads (URLs, request bodies, MCP JSON-RPC payloads, WebSocket frames) per session and re-scans the concatenated content against DLP patterns on every request (synchronous, pre-forward). Catches secrets split across multiple requests that individually look clean.

Memory: Each tracked session uses up to max_buffer_bytes. With 10,000 concurrent sessions (hard cap), the worst-case memory is max_buffer_bytes * 10000 (640 MB at defaults). Reduce max_buffer_bytes in memory-constrained environments.

Scope note: Cross-request detection scans all outbound content visible to the proxy: URLs, request bodies, MCP JSON-RPC payloads, and WebSocket frames. CONNECT tunnels without TLS interception only expose the target hostname (entropy tracking only). Enable tls_interception for full cross-request coverage on tunneled traffic.

Finding Suppression#

Suppress known false positives by rule name and path/URL pattern.

suppress:
  - rule: "Jailbreak Attempt"
    path: "*/robots.txt"
    reason: "robots.txt content triggers developer mode regex"

Path matching: exact (foo.txt), glob (*.txt, vendor/**), directory prefix (vendor/), basename glob (*.txt matches dir/foo.txt).

See Finding Suppression Guide for the full reference.

Git Protection#

Git-aware scanning for pre-push secret detection and branch restrictions.

git_protection:
  enabled: false
  allowed_branches: ["feature/*", "fix/*", "main"]
  allowed_push_repos: ["git.vendor.example/team/private-*", "forge.vendor.example/*"]
  pre_push_scan: true

pipelock git scan-diff is a fail-closed gate. Empty input and valid metadata-only diffs (mode-only changes, rename-only changes, and --no-prefix diffs with no added secret content) pass. Non-empty input that is not recognizable unified diff output exits non-zero as unverifiable. Added + lines that cannot be attributed to a valid file header and hunk are still scanned as orphan added-content candidates, so partial or malformed diffs cannot hide a secret before or between valid file sections. Unsupported binary patches fail closed because the line scanner cannot inspect their payload. Generated pre-push hooks invoke git diff --no-ext-diff --no-textconv before pipelock git scan-diff so repository-local diff drivers and textconv filters cannot substitute untrusted patch text.

The gate scans added text lines, not unchanged context lines. That avoids re-blocking every push because of a pre-existing secret already present in the repository. Future hardening should scan changed blob contents by object ID and add per-hunk window scanning for split-token cases.

Logging#

Structured audit logging to stdout and/or file.

logging:
  format: json
  output: stdout
  file: ""
  include_allowed: true
  include_blocked: true

Internal Networks (SSRF Protection)#

Private/reserved IP ranges blocked from agent access. Post-DNS check prevents SSRF via DNS rebinding.

internal:
  - "0.0.0.0/8"
  - "127.0.0.0/8"
  - "10.0.0.0/8"
  - "100.64.0.0/10"
  - "172.16.0.0/12"
  - "192.168.0.0/16"
  - "169.254.0.0/16"
  - "::1/128"
  - "fc00::/7"
  - "fe80::/10"
  - "224.0.0.0/4"
  - "ff00::/8"

All RFC 1918, RFC 4193, link-local, loopback, CGN (Tailscale/Carrier-Grade NAT), multicast, and cloud metadata ranges are blocked by default. IPv6 zone IDs (e.g. ::1%eth0) are stripped before IP parsing to prevent bypass.

Trusted Domains#

Domains exempt from SSRF internal-IP checks. Use this when a domain legitimately resolves to a private IP (e.g., an internal API behind a VPN) and you want pipelock to allow the connection.

trusted_domains:
  - "internal-api.example.com"
  - "*.corp.example.com"

Important: This is a top-level config field, not nested under forward_proxy. Placing it under forward_proxy will silently do nothing. DLP and other content scanning still runs on trusted domains -- only the SSRF IP check is bypassed.

Strict mode: trusted_domains does not override api_allowlist. In strict mode, a domain must be in both api_allowlist (to be reachable) and trusted_domains (to resolve to internal IPs). If a domain is only in api_allowlist and resolves internally, pipelock blocks it with a hint to add it to trusted_domains.

Per-agent trusted_domains overrides are available in agent profiles (Pro license).

DNS Host Overrides#

Static hostname-to-IP overrides used by SSRF DNS checks and the proxy dial path. Use this for reproducible local fixtures or controlled internal names when you cannot or do not want to modify system DNS.

dns:
  host_overrides:
    fixture.example.test:
      - "127.0.0.1"
trusted_domains:
  - "fixture.example.test"

Host overrides do not exempt a destination from SSRF blocking by themselves. If an override resolves to an internal IP, the hostname must also be present in trusted_domains or the target IP must be covered by ssrf.ip_allowlist. Raw IP targets never use dns.host_overrides.

SSRF IP Allowlist#

Exempt specific IP ranges from SSRF blocking. Use this when your internal services resolve to known IP ranges and you want to allow connections by IP rather than by hostname.

ssrf:
  ip_allowlist:
    - "192.168.1.0/24"
    - "10.0.0.5/32"

Use the narrowest CIDR that covers the trusted service. A single-host /32
carve-out allows that IP only; a neighboring address in the same private range
still blocks:

ssrf:
  ip_allowlist:
    - "10.0.0.42/32" # api.vendor.example

With that config, https://api.vendor.example/ resolving to 10.0.0.42
is allowed by the SSRF IP check, while https://api.vendor.example/
resolving to 10.0.0.43 is still blocked. If the trust boundary is the
hostname rather than a fixed address, use top-level trusted_domains instead;
that is narrower by name but broader across whatever IPs DNS returns for that
trusted hostname — so only use it for hostnames whose DNS you control, since a
compromised or rebinding record could otherwise point a trusted name at an
arbitrary internal IP.

Cloud-metadata, link-local, and multicast addresses cannot be allowlisted.
ssrf.ip_allowlist only exempts ordinary private and loopback addresses.
Entries that overlap cloud instance-metadata endpoints (for example
169.254.169.254), link-local ranges (169.254.0.0/16, fe80::/10),
multicast, or the unspecified address are rejected at config load, and the
scanner refuses to exempt them at runtime even if configured. These addresses
are a credential-theft and infrastructure boundary; there is no knob to open
them.

Complementary to trusted_domains: trusted_domains is hostname-based trust (the domain resolves to a private IP, but you trust the domain). ssrf.ip_allowlist is IP-based trust (you trust the IP range regardless of which domain resolves to it). Either one exempts from SSRF blocking.

Validation: Entries must be canonical CIDRs (network address, not host address). 10.0.0.5/24 is rejected because the host bits are set (use 10.0.0.0/24 instead). Catch-all prefixes (0.0.0.0/0, ::/0) are rejected because they would disable SSRF protection entirely.

Presets#

Seven starter configs are selectable with pipelock generate config --preset <name>.
Run pipelock presets or pipelock generate config --list to list the current built-in names with mode, default action, and reachability posture:

Key differences between presets:

Hostile-Model Preset#

The hostile-model preset is for agents running uncensored, abliterated, or jailbroken models where the model itself has zero safety guardrails. It assumes the model will comply with any instruction, including exfiltrating secrets or executing injected prompts.

Use this preset for:

• Red-team testing: exercising agent attack paths against the network layer
• Self-hosted uncensored models: weight-ablated models (e.g. OBLITERATUS variants) with safety refusals removed
• Jailbroken agents: any model that can be trivially steered past its own guardrails

What it enables beyond strict:

• Every defense layer active: forward proxy, request body scanning, WebSocket scanning, MCP input/tool/policy scanning, session binding, session profiling, adaptive enforcement, tool chain detection
• Aggressive entropy threshold (3.0): catches more encoded secrets at the cost of higher false-positive rates
• Lower rate limit (15/min): constrains exfiltration bandwidth
• Shorter URL limit (300 chars): reduces data budget per request
• All MCP tool policy rules enabled: blocks shell obfuscation, file writes outside allowed paths, and network access patterns
• TLS interception pre-configured (disabled by default; enable and generate a CA to activate)

The core principle: the model won't protect you, so the network layer must.

Default Agent Identity#

When pipelock runs behind a workload-local proxy configuration, incoming requests typically lack the X-Pipelock-Agent header because the upstream container sends traffic through HTTPS_PROXY without identity headers. Set default_agent_identity so that traffic is attributed to the workload rather than showing as anonymous in logs, receipts, and metrics.

default_agent_identity: "deployment/my-agent"

If you also set bind_default_agent_identity: true, pipelock ignores caller-supplied X-Pipelock-Agent headers and ?agent= query params and binds all traffic on that listener to the configured default identity. This is the recommended mode for the generated pipelock init sidecar companion topology.

These precedences apply to default-identity resolution after listener-level and source-CIDR resolution have been evaluated. They do not override an agent profile that matched on listener address or source CIDR.

Resolution precedence with binding disabled: context override > X-Pipelock-Agent header > default_agent_identity > ?agent= query param > anonymous.

Resolution precedence with binding enabled: context override > default_agent_identity > anonymous.

pipelock init sidecar sets both fields automatically from the workload kind and name (e.g., deployment/my-agent). Override the identity with --agent-identity.

Agent Profiles#

Per-agent policy overrides. When multiple agents share one pipelock instance, each agent can have its own mode, allowlist, DLP patterns, rate limits, and request budgets. Scalar fields (mode, enforce) inherit from the base config when unset. mcp_tool_policy replaces the base section entirely when set on an agent profile (no deep merge). session_profiling replaces the per-agent fields (domain_burst, anomaly_action, volume_spike_ratio) unconditionally while preserving global-only fields (max_sessions, session_ttl_minutes, cleanup_interval_seconds). rate_limit overrides individual rate limit fields (non-zero values win). DLP merging follows separate rules (see below).

agents:
  claude-code:
    listeners: [":8889"]
    source_cidrs: ["10.42.3.0/24"]
    mode: strict
    api_allowlist: ["github.com", "*.githubusercontent.com"]
    dlp:
      include_defaults: true
      patterns:
        - name: "Internal Token"
          regex: 'internal_[a-zA-Z0-9]{32}'
          severity: critical
    rate_limit:
      max_requests_per_minute: 30
    session_profiling:
      domain_burst: 3
      anomaly_action: block
    mcp_tool_policy:
      enabled: true
      action: block
      rules:
        - name: "Block shell"
          tool_pattern: "bash|shell"
          action: block
    budget:
      max_requests_per_session: 500
      max_bytes_per_session: 52428800
      max_unique_domains_per_session: 50
      window_minutes: 60

  research-agent:
    listeners: [":8890"]
    mode: balanced
    enforce: false
    budget:
      max_unique_domains_per_session: 200

  _default:
    mode: balanced

Agent Resolution#

Pipelock resolves the agent name for each request using this priority order:

1. Listener binding: matched by the port the request arrived on (injected as a context override, spoof-proof)
2. Source CIDRs: matched by client IP against source_cidrs ranges defined on each agent profile
3. Header (X-Pipelock-Agent): set by the calling agent or orchestrator
4. Query parameter (?agent=name): appended to fetch/WebSocket URLs
5. Fallback: _default profile if defined, otherwise base config

Listener-based resolution is the only method that cannot be spoofed by the agent. It injects a context override that takes priority over header and query param. Header and query param methods are convenient but trust the caller. Use listeners when isolation matters.

For MCP proxy mode, the --agent flag resolves the profile directly at startup (not through the HTTP resolution chain).

Override Fields#

Each agent profile can override these fields:

DLP Merge Behavior#

Agent DLP overrides follow the same include_defaults pattern as the global DLP section:

• include_defaults: true (or omitted): agent patterns are appended to the base config patterns. If an agent pattern shares a name with a base pattern, the agent version wins.
• include_defaults: false: agent patterns replace the base patterns entirely.

Budget Config#

Budgets cap what an agent can do within a rolling time window. All fields default to 0 (unlimited).

When a budget limit is reached:

• Request count and domain limits are checked before the outbound request. Exceeding either returns 429 Too Many Requests.
• Byte limit (fetch proxy): the response body read is capped at the remaining byte budget. If the response exceeds the limit, it is discarded and a 429 is returned.
• Byte limit (CONNECT/WebSocket): streaming connections track bytes after close. The byte budget is enforced on the next admission check, not mid-stream, because tunnel data cannot be recalled after transmission.
• DoW limits (MCP proxy): tool call budgets are checked before each tools/call dispatch. When dow_action is "block", the call is rejected with a JSON-RPC error. When "warn", the call is logged and allowed through. Currently enforced: total tool call count, same-tool retry storms, loop/cycle detection, and wall-clock duration. Endpoint retry, fan-out, and concurrent-call limits are not enforced.

Listener Binding#

Each agent can bind to one or more dedicated ports via the listeners field. Pipelock opens these ports at startup alongside the main proxy port. Requests arriving on an agent's listener are automatically resolved to that agent without relying on headers or query params.

This is the only spoof-proof resolution method. The agent process connects to its assigned port, and pipelock knows which profile to apply based on the port alone.

agents:
  trusted-agent:
    listeners: [":8889"]
    mode: balanced
  untrusted-agent:
    listeners: [":8890"]
    mode: strict
    budget:
      max_requests_per_session: 100

Note: Listener bindings are set at startup. Changing listeners requires a process restart (not hot-reloadable).

Source CIDR Matching#

Each agent can define one or more source_cidrs entries. Pipelock matches the client IP of every incoming request against these CIDRs. This works for all traffic types including CONNECT tunnels, where header-based identification is not possible.

In Kubernetes, each pod has a unique IP. In Docker Compose, each container has its own. Source CIDR matching maps those IPs to agent profiles with zero agent-side configuration.

agents:
  claude-code:
    source_cidrs: ["10.42.3.0/24"]
    mode: strict
  cursor:
    source_cidrs: ["10.42.5.0/24", "10.42.6.0/24"]
    mode: balanced

Resolution priority: listener binding > source CIDR > header > query param > _default.

CIDRs must not overlap between different agents (containment and exact matches are both rejected). Overlapping CIDRs within the same agent are allowed.

The _default Profile#

If defined, _default applies to any request that does not match a named agent. Without _default, unmatched requests use the base config directly.

License Key#

Multi-agent profiles (the agents: section) require a signed license token. The token is an Ed25519-signed JWT-like string issued by pipelock license issue. At startup, pipelock verifies the signature, checks expiration, and confirms the token includes the agents feature. If any check fails, agent profiles are disabled with a warning. All single-agent protection remains active.

New deployments may receive a root-signed intermediate certificate alongside the token. When license_intermediate_file is configured, Pipelock verifies the token through token -> intermediate -> embedded root public key and fails closed if the intermediate is malformed, expired, signed by the wrong root, or revoked by the CRL. Omitting license_intermediate_file preserves legacy direct-root token verification.

Loading Sources#

Pipelock checks three sources for the license token, in priority order:

The first non-empty source wins. Later sources are not checked. PIPELOCK_LICENSE_KEY values containing only whitespace are treated as empty and fall through to lower-priority sources. If license_file is configured but the file is empty or contains only whitespace, pipelock fails with an error rather than falling back to inline license_key. This is fail-closed by design: a misconfigured Secret mount should not silently downgrade to an inline fallback.

Env var (recommended for containers):

export PIPELOCK_LICENSE_KEY="pipelock_lic_v1_eyJ..."
pipelock run --config pipelock.yaml

File path:

# pipelock-fragment-id: license-path-precedence
license_file: /etc/pipelock/license.token # absolute path
license_file: license.token # relative to config file directory

The file should contain only the license token string. Leading and trailing whitespace is trimmed. The file must have owner-only permissions (0600); group- or world-readable files are rejected. The file is read at startup. Adding or changing a license requires a restart to take effect; a config-triggered reload will detect the change but will not apply it until restart. Removing the currently active license source takes effect immediately on reload (for example, unsetting PIPELOCK_LICENSE_KEY or removing the active license_file/license_key entry).

Inline (simplest):

license_key: "pipelock_lic_v1_eyJ..."

Full example with all license fields:

# pipelock-fragment-id: license-complete-reference
license_key: "pipelock_lic_v1_eyJ..." # inline token (lowest priority)
license_file: "/etc/pipelock/license.token" # file path (medium priority)
license_crl_file: "/etc/pipelock/license.crl" # signed revocation list
license_intermediate_file: "/etc/pipelock/license-intermediate.json" # root-signed intermediate cert
license_require_intermediate: false # require the token to chain through an intermediate
license_crl_max_age: 25h # CRL freshness window under require mode (default 25h)
license_public_key: "a1b2c3d4..." # hex-encoded Ed25519 public key (dev builds only)

Kubernetes Secret Example#

Mount a license key from a Kubernetes Secret as an env var:

env:
  - name: PIPELOCK_LICENSE_KEY
    valueFrom:
      secretKeyRef:
        name: pipelock-license
        key: token

Or mount the Secret as a file and reference it in config:

# pipelock-fragment-id: license-container-layout
license_file: /etc/pipelock/license/token
license_intermediate_file: /etc/pipelock/license/intermediate.json

Key Verification#

Official release builds embed the signing public key at compile time via ldflags. The embedded key takes priority over license_public_key and cannot be overridden by config, preventing self-signing bypasses. The license_public_key config field is only used in development builds where no key is embedded.

license_crl_file points at a signed license revocation list. It is read and verified at startup and on config reload; a revoked active license is disabled immediately. The CRL file should be mounted from trusted operator-controlled storage, not written by the agent.

license_intermediate_file points at the root-signed intermediate license-signing certificate. It is public cert material, not a secret, but it controls the active signing chain and should still come from trusted operator-controlled storage. Relative paths resolve against the config file directory. A configured intermediate certificate is checked at startup: a missing, unreadable, malformed, expired, or wrong-root cert emits a startup warning and disables licensed features such as multi-agent profiles and Assess signing, rather than silently downgrading to direct-root verification. It never blocks startup or single-agent protection — a licensing-tier misconfiguration must not take the proxy down, and a short-lived intermediate's expiry must not crash-loop it. Changing this field requires a restart for the new license chain to take effect.

license_require_intermediate (default false; env PIPELOCK_LICENSE_REQUIRE_INTERMEDIATE) turns the intermediate tier from optional into mandatory. When true, Pipelock refuses any token that is not validated through a root-certified intermediate: a legacy direct-root token (or one forged with a stolen root key) is rejected with no fall-back, a missing or stale CRL fails closed (the CRL is the revocation floor), and signature/expiry/revocation failures fail closed. The default false preserves today's behaviour exactly — existing root-signed licenses keep verifying — so this is an explicit operator decision made AFTER an intermediate and a fresh CRL are distributed. A malformed boolean env value resolves to true (fail closed to the strictest interpretation, never silently to false) and surfaces a startup warning — a typo in the enable-toggle must never re-open the direct-root fallback. A require-on-but-misconfigured consumer (no intermediate, or a bad env value) surfaces that warning and disables paid features while detection/enforcement stays up. A reload that flips require on/off re-verifies and tears down a paid surface that no longer satisfies the required chain.

When require mode is on, the CRL is also subject to a freshness check: a CRL whose signed issue time is older than the freshness window is rejected as stale and fails closed, even if its own expiry has not passed. The window is configurable via license_crl_max_age (env PIPELOCK_LICENSE_CRL_MAX_AGE), a duration string; the default is 25h. An unset value falls back to the 25h default silently (omitting the field is normal). A malformed or non-positive value also falls back to the 25h default but surfaces a startup warning — a misconfigured window can never disable the freshness check (a bad value fails safe to the default, never to "no check"). Publish CRLs on at least a cadence shorter than the window while require mode is active, independent of the CRL's longer signed validity window — otherwise require-mode consumers will block once the last published CRL ages past license_crl_max_age. Full migration sequence: the intermediate-signing migration runbook.

CLI Commands#

pipelock license keygen # generates ~/.config/pipelock/license.key + license.pub
pipelock license issue --email customer@company.com --expires 2027-03-07
pipelock license inspect TOKEN # decode without verifying

A _default profile without any named agents does not require a license key.

Installing a License#

Use pipelock license install to write a license token to a file:

pipelock license install <TOKEN> # writes to ~/.config/pipelock/license.token
pipelock license install --path /etc/pipelock/license.token <TOKEN> # custom path

The command validates the token format, writes it atomically (temp file + rename), and prints setup instructions. Point your config at the file:

# pipelock-fragment-id: license-activation
license_file: /etc/pipelock/license.token

Then restart pipelock to activate Pro features.

Renewal#

License tokens have a fixed expiry (typically 45 days). When your subscription renews, you receive a new token by email. To update:

1. Run pipelock license install <NEW_TOKEN> (overwrites the existing file)
2. Restart pipelock

The new token activates on restart. Your current token continues working until its expiry date, so there is no rush to update immediately. A config reload detects the changed license inputs but does not apply them until restart (activation requires restart; revocation is immediate).

Scan API#

Evaluation-plane HTTP listener for programmatic scanning. Disabled by default. When enabled, serves POST /api/v1/scan on a dedicated port with independent auth, rate limiting, and timeouts.

scan_api:
  listen: "127.0.0.1:9090"
  auth:
    bearer_tokens:
      - "your-secret-token"
  rate_limit:
    requests_per_minute: 600 # per token
    burst: 50
  max_body_bytes: 1048576 # 1MB
  field_limits:
    url: 8192
    text: 524288 # 512KB
    content: 524288
    arguments: 524288
  timeouts:
    read: "2s"
    write: "2s"
    scan: "5s"
  connection_limit: 100
  kinds:
    url: true
    dlp: true
    prompt_injection: true
    tool_call: true

All kinds are enabled by default. Set any to false to disable. tool_call DLP and prompt-injection scanning run on demand through this API regardless of the inline MCP proxy's mcp_input_scanning.enabled setting; that toggle controls live MCP proxy traffic, not explicit Scan API requests. Full API reference: docs/scan-api.md.

Address Protection#

Detects blockchain address poisoning attacks. Compares outbound addresses against a user-supplied allowlist of known-good destinations and flags similar-looking addresses using prefix/suffix fingerprinting. This is destination verification, not secret detection — separate from DLP.

Disabled by default. Users opt in explicitly.

address_protection:
  enabled: true
  action: block
  unknown_action: warn
  allowed_addresses:
    - "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
    - "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  chains:
    eth: true
    btc: true
    sol: false
    bnb: true
  similarity:
    prefix_length: 4
    suffix_length: 4

At least one chain must be enabled when address_protection.enabled is true. All-chains-disabled with the feature enabled is rejected at validation (silent no-op prevention).

Hot reload: disabling address protection triggers a reload warning. Re-enabling takes effect immediately.

File Sentry#

Real-time filesystem monitoring for agent subprocesses. Detects secrets written to disk that bypass the MCP tool call path. Applies to subprocess MCP mode only (pipelock mcp proxy -- COMMAND).

file_sentry:
  enabled: false
  watch_paths:
    - "." # required:false; degraded if unavailable
    - path: "/var/agent-secrets" # required:true; startup fails if unavailable
      required: true
  scan_content: true
  max_file_bytes: 0 # 0 = built-in 10 MiB default
  ignore_patterns:
    - "node_modules/**"
    - ".git/**"
    - "*.o"
    - "*.so"

When a watch_paths entry is required: false, startup records a degraded path and continues if that watch cannot be installed. Set required: true on paths that are part of the security boundary; startup fails closed if those watches cannot be installed. Unknown fields in mapping entries are rejected so typos such as require: true do not silently disable the hard-fail opt-in.

Findings are reported as stderr warnings and Prometheus metrics (pipelock_file_sentry_findings_total). Structured audit log emission (file_sentry_dlp event type) is defined but not yet wired to the webhook/syslog pipeline. On Linux, process lineage tracking attributes file writes to the agent's process tree via PR_SET_CHILD_SUBREAPER and /proc walking.

action: block is the fail-closed enforcement boundary. The cancel fires from the consumer goroutine after the log line and metric emission, which means there is unavoidable latency between the kernel write and the proxy teardown: the file has already been written to disk by the time the scan completes. Block prevents the agent from continuing to act on the leak, it does not prevent the write itself. For write-time interception the operator must layer Landlock or a sandbox at the deployment level.

Files larger than max_file_bytes are skipped to bound memory use, but the skip is surfaced through the watcher's error path instead of being silently dropped. Stat/read failures are surfaced the same way. Write events are debounced (50ms quiet window) to avoid scanning partial writes.

Community Rules#

Optional signed rule bundles that extend built-in detection patterns. See docs/rules.md for the full user guide.

# pipelock-fragment-id: trusted-rule-key
rules:
  rules_dir: ~/.local/share/pipelock/rules # default ($XDG_DATA_HOME/pipelock/rules)
  min_confidence: medium # skip low-confidence (experimental) rules
  include_experimental: false # only load stable rules by default
  allow_degraded: false # emergency strict-mode degraded startup/reload override
  trusted_keys: # additional signing keys (beyond embedded keyring)
    - name: "vendor-security"
      public_key: "64-char-hex-encoded-ed25519-public-key"

Hot reload: rule directory changes are re-resolved when config reload runs. A clean uninstall that removes live bundle patterns is rejected in strict mode unless allow_degraded is set; non-strict modes allow it and emit degraded-state telemetry. Installing or updating bundles still normally uses the pipelock rules commands and a config reload or restart to re-resolve the runtime policy.

Sandbox#

Process containment for agent commands using Linux kernel primitives. The agent runs in a restricted environment with controlled filesystem access, no direct network, and a filtered syscall set.

sandbox:
  enabled: true
  best_effort: false # degrade gracefully when namespace isolation unavailable
  strict: false # error if any layer unavailable (mutually exclusive with best_effort)
  workspace: /home/user/project # agent working directory (default: CWD)
  filesystem: # optional Landlock overrides (default policy works for most agents)
    allow_read:
      - /usr/share/data
      - /app/ # application code in containers
    allow_write:
      - /tmp/agent-work

If filesystem is omitted, the default Landlock policy is used (safe for Python/Node/Go agents without config). Read access grants execute (Landlock bundling). Write paths are also executable.

Containment layers:

• Landlock LSM: Restricts filesystem access to declared paths. Allowlist model. Protected directories (~/.ssh, ~/.aws, ~/.kube, etc.) are denied. Only dirs that exist on the system are checked.
• Network namespaces: Agent runs in an isolated network namespace. All HTTP/HTTPS traffic is kernel-confined to the namespace and routed through pipelock's bridge proxy. Raw socket direct egress is impossible. MCP stdio servers that act as HTTP bridges receive HTTP_PROXY/HTTPS_PROXY pointing at the in-namespace bridge, so upstream calls still traverse Pipelock's forward-proxy scanner.
• Seccomp BPF: Syscall allowlist (~130 safe syscalls for Go/Python/Node.js). Blocks ptrace, mount, module loading, kexec (KILL). io_uring returns EPERM (allows runtimes like Node.js 22 to fall back to epoll). Clone flags filtered to prevent namespace escape.

For sandboxed MCP stdio servers on Linux, the bridge enables forward-proxy handling internally even when forward_proxy.enabled is false in YAML. This is scoped to the sandbox bridge only and does not expose the normal forward proxy listener.

In --best-effort mode (for containers without user-namespace support), the bridge still scans traffic but network enforcement is cooperative: a child process that clears HTTP_PROXY / HTTPS_PROXY can bypass Pipelock.

Usage:

# Sandbox an MCP server
pipelock mcp proxy --sandbox --config pipelock.yaml -- npx server

# Sandbox a bridge-style MCP server; its outbound HTTP(S) goes through Pipelock
pipelock mcp proxy --sandbox --config pipelock.yaml -- npx -y @upstash/context7-mcp

# Sandbox a standalone command
pipelock sandbox --config pipelock.yaml -- python agent.py

# Pass environment variables to sandboxed process
pipelock sandbox --env API_KEY --env HOME=/app -- node server.js

# Best-effort mode for containers (Landlock + seccomp, no namespace)
pipelock sandbox --best-effort -- python agent.py

# Check sandbox capabilities without launching
pipelock sandbox --dry-run --json -- python agent.py

Environments:

Requirements: Linux 5.13+ (Landlock ABI v1). Unprivileged on bare metal. macOS 13+ for sandbox-exec. Containers may need --best-effort if default seccomp blocks CLONE_NEWUSER.

--best-effort is a degraded mode with a known bypass vector. When user namespaces are unavailable — either the container runtime's seccomp profile blocks CLONE_NEWUSER or the host has kernel.unprivileged_userns_clone=0 (default on some Debian-derivative kernels) — pipelock cannot create a network namespace for the child, so outbound traffic is enforced only by HTTP_PROXY / HTTPS_PROXY environment variables. A process inside the sandbox that explicitly unsets those vars, or makes a raw socket call without consulting the proxy env, will connect directly to the network and bypass pipelock's scanning pipeline. Pipelock emits a loud startup WARNING line alongside the DEGRADED status whenever this path is taken, on both pipelock sandbox and pipelock mcp proxy --sandbox-best-effort. For deployments that need kernel-level enforcement, either (1) make CLONE_NEWUSER available (adjust the runtime's seccomp profile or set kernel.unprivileged_userns_clone=1) so pipelock can run full 3/3 containment, or (2) use the companion-proxy topology from pipelock init sidecar — putting pipelock in a separate pod with a NetworkPolicy that restricts the agent pod's egress to the pipelock Service IP is the kernel-enforced equivalent of a network namespace.

Config Audit Scoring (v2.6)#

Score a pipelock configuration for security posture. Evaluates 23 categories with a 170-point budget and produces a normalized 0-100 percentage, letter grade, and actionable recommendations.

pipelock audit score --config pipelock.yaml
pipelock audit score --config pipelock.yaml --json

Categories scored: DLP (pattern count, env scanning, entropy), response scanning (enabled, action, pattern count), MCP tool scanning, MCP tool policy (rule count, blocking rules, overpermission), MCP input scanning, MCP session binding, kill switch (source count), enforcement mode, domain blocklist, adaptive enforcement, tool chain detection, sandbox, live-lock contracts, redaction, browser shield, mediation envelope, flight recorder, request body scanning, cross-request detection, address protection, seed-phrase detection, git protection, and file sentry.

Tool policy overpermission audit: flags wildcard arg_pattern values, high-risk tool patterns with non-blocking actions, and policies with no effective blocking rules. Respects section-level default action inheritance.

Redirect Action (v2.0)#

A policy action that rewrites dangerous tool execution to a safer target instead of blocking outright.

mcp_tool_policy:
  enabled: true
  action: warn
  redirect_profiles:
    fetch_proxy:
      exec: ["/proc/self/exe", "internal-redirect", "fetch-proxy"]
      preserve_argv: true
      reason: "Route outbound fetches through audited proxy"
  rules:
    - name: shell-egress
      tool_pattern: '(?i)^(bash|shell|exec)$'
      arg_pattern: '(?i)\b(curl|wget)\b'
      action: redirect
      redirect_profile: fetch_proxy

Redirect failure falls through to block (fail-closed). Every redirect emits a structured audit event with the original command, redirect target, policy rule, and reason.

Canary Tokens (v2.1)#

Synthetic secrets injected into the agent's environment. If pipelock detects a canary in any outbound request, it's irrefutable proof of compromise -- not a heuristic, but a known-fake value that should never appear in traffic.

canary_tokens:
  enabled: true
  tokens:
    - name: "aws_canary"
      value: "canary-aws-trap-value-0x42a7"
      env_var: "AWS_ACCESS_KEY_ID" # optional: inject as env var
    - name: "db_canary"
      value: "postgres://canary:trap@honeypot.internal/fake"
    - name: "api_canary"
      value: "sk_test_CANARY_4eC39HqLyjWDarjtT1zdp7dc"

Canary checks run after DLP as a safety net (exact string match, O(1) per token). If a DLP pattern already matched, the canary check is skipped. Detection emits a high-severity event with full request context. Use pipelock canary generate to create sample configurations.

Flight Recorder (v2.1)#

Hash-chained, tamper-evident evidence log. Every scanner verdict, tool call, and session event is recorded to JSONL with SHA-256 hash chains and optional Ed25519 signed checkpoints.

flight_recorder:
  enabled: true
  dir: /var/lib/pipelock/evidence
  checkpoint_interval: 1000
  retention_days: 90
  redact: true
  require_receipts: false
  sign_checkpoints: true
  signing_key_path: "/path/to/signing-key"
  max_entries_per_file: 10000
  raw_escrow: false
  escrow_public_key: ""
  completeness:
    heartbeat_interval: 60s
  evidence_health:
    enabled: true
    self_audit_interval: 30s
    max_anchor_lag: 24h
  # Setting exactly one anchor point activates runtime auto-anchoring.
  # There is no public Rekor URL default.
  anchor:
    rekor_url: https://rekor.internal.example
    rekor_key_path: /etc/pipelock/keys/rekor-entry.key
    # local_log: /var/lib/pipelock/anchor-log.jsonl # alternative to Rekor
    # log_id: local-fake-log
    interval: 1h
    receipt_threshold: 1000

dashboard_snapshot:
  enabled: true
  path: /var/lib/pipelock/evidence/dashboard/runtime-snapshot.json
  interval: 10s

Configuring an anchor point is the complete opt-in. Without anchor.rekor_url
or anchor.local_log, the section is inert. Auto-anchor failures degrade
evidence health and retry later; they never block or delay proxy traffic or
receipt emission. Rekor uses v1 hashedrekord, and only the checkpoint's
SHA-512 digest and signature leave the box, never receipt content. A self-hosted
log provides durability and tamper evidence but not operator independence; a
public log can provide an independent witness but publishes checkpoint metadata
and may rate-limit submissions.

Dashboard Runtime Snapshot#

dashboard_snapshot controls the proxy-produced, counts-only runtime snapshot
used by pipelock dashboard serve for the Budgets view. It is operational
state, excluded from the canonical policy hash, and restart-only on reload.

Evidence files are named evidence-<session>-<seq>.jsonl. Each entry contains a SHA-256 hash of its predecessor, forming a tamper-evident chain. Action receipts form a second chain within the evidence log (each receipt links to the previous receipt via chain_prev_hash). Breaking the receipt chain is detectable by pipelock verify-receipt --chain /var/lib/pipelock/evidence --key /etc/pipelock/keys/receipt.pub; file-manifest drift is checked separately with pipelock integrity check /path/to/workspace.

Learn and Lock#

Per-agent behavioral-contract workflow. The learn block controls where observation evidence is written, how privacy salt is resolved, and which inference floors the compiler uses.

learn:
  enabled: false
  capture_dir: /var/lib/pipelock/learn
  privacy:
    salt_source: "${PIPELOCK_LEARN_SALT}"
    public_allowlist_default: true
  inference:
    floors:
      min_sessions: 5
      min_events: 20
      min_windows: 3
    normalization:
      algorithm: frequency_weighted_entropy_v1
      min_events: 10
      min_distinct_values: 5
      entropy_threshold_bits: 3.0
      reserved_segments_extra: []
      cardinality_cap_per_host: 1000
      tail_promotion_block_pct: 5.0