Community Rules#

Pipelock ships with built-in DLP patterns, injection detection, and tool-poison scanners. Community rule bundles extend these defaults with additional detections that ship on a faster cadence than the core binary.

Installing a Bundle#

# Install the official community bundle (requires network access)
pipelock rules install pipelock-community

# Install from a third-party HTTPS source
pipelock rules install --source https://example.com/my-bundle/bundle.yaml my-bundle

# Install from a local path (signature verification skipped)
pipelock rules install --path /path/to/bundle/ --allow-unsigned

Bundles are stored in $XDG_DATA_HOME/pipelock/rules/ by default (typically ~/.local/share/pipelock/rules/). Override with the --rules-dir flag or the rules_dir config field.

Note: Official bundle verification works in source builds because the official rules signing public key is compiled into the source. Release binaries additionally embed the rules keyring via ldflags. Use trusted_keys for third-party bundles signed by keys outside the official keyring.

Installing a bundle through a Pipelock proxy#

A rules bundle is a list of detection patterns, so the bundle's own contents read as injection text to a response scanner. If pipelock rules install runs behind a Pipelock proxy whose response_scanning.action is block or ask — the strict, hostile-model, claude-code, and cursor presets — that proxy scans the bundle it is fetching and refuses to release it. A proxy left on the default warn logs the finding and passes the bundle through, but adaptive enforcement can upgrade a warn to a block, so the same install can start failing on a session that has escalated. When it is refused, the install fails with a 403 and the command reports which side made that decision:

HTTP GET https://pipelab.org/rules/pipelock-community/bundle.yaml: status 403: blocked by Pipelock, not by the server (reason=prompt_injection, layer=response_scan)

The fix belongs in the proxy's config, not in the rules directory on the machine running the install. Name the exact artifact under response_scanning.authenticated_artifacts:

response_scanning:
  authenticated_artifacts:
    - host: "pipelab.org"
      path: "/rules/pipelock-community/bundle.yaml"
      bundle_name: "pipelock-community"

bundle_name must equal the name field inside that bundle; the proxy refuses the artifact if they disagree, so the entry cannot be pointed at a different bundle later served from the same path.

This is not a destination exemption and it does not turn scanning off for the host. The proxy buffers that one response, fetches the .sig sidecar itself with a fresh request, verifies the signature against its embedded official keyring, and releases the body only if the signer is in the official tier and the bundle's name matches. Everything else still applies: request-side DLP, an unsigned bundle, a third-party signer, a redirect, a non-443 port, a URL carrying a query string or userinfo, any method other than GET, and any other host or path are all still refused. Only injection matching on that verified artifact is skipped.

No entry ships enabled in any preset. A standing exception to injection scanning is the operator's decision to make, and an operator who never installs a rules bundle should not be carrying one.

Updating and Removing#

# Update to the latest version
pipelock rules update pipelock-community

# List installed bundles
pipelock rules list

# Show diff between installed and available versions
pipelock rules diff pipelock-community

# Remove a bundle
pipelock rules remove pipelock-community

Status#

pipelock rules status

Reports the overall health of the rules stack: the immutable core tier, the standard-tier source and pattern counts, every installed bundle's tier/version/rule counts/signed status, and any errors or warnings from the last load. Returns non-zero when any bundle has an error (e.g., unknown required_features, signature failure) even if some bundles loaded successfully — in that case the proxy still starts, but the status command surfaces what's degraded.

Add --json for machine-readable output suitable for piping into dashboards or CI checks:

pipelock rules status --json | jq '.healthy'

Tiers#

Every bundle declares a tier. Tiers describe source and trust, not rule quality:

The core scanner runs before any bundle and cannot be replaced or disabled. Standard-tier rules load from the binary embed and cannot be replaced from disk either: there is no config field that repoints them, which is what keeps a writable path from swapping out standard detection. pipelock rules status reports the tier's origin in its standard_dlp_source and standard_response_source output fields.

Bundles cannot override or disable the core or standard tiers. They only extend detection.

RequiredFeatures#

A bundle declares the engine features its rules need. Unknown features block the bundle at load time with a clear error:

format_version: 2
name: my-company-rules
version: "2026.03.1"
tier: community
required_features:
  - dlp # built-in DLP scanner
  - checksum # post-match checksum validators (luhn, mod97, aba)
  - response # response scanning
rules:
  # ...

Valid feature names are 1-64 lowercase alphanumeric characters with underscores. When an older pipelock binary encounters a bundle that requires a feature it doesn't support, the bundle fails to load rather than silently dropping the feature-dependent rules. This prevents detection drift between the bundle author's expectations and the running binary.

Core SSRF Literal#

The immutable core scanner includes private-IP literal enforcement — it blocks literal RFC 1918 ranges, loopback, link-local, and cloud metadata addresses regardless of bundle tier or scanner configuration. This is a separate layer from the standard SSRF scanner and cannot be disabled wholesale. It honors ssrf.ip_allowlist for ordinary private and loopback addresses, but cloud-metadata, link-local, and multicast addresses are a non-overridable deny: no allowlist entry exempts them, and an entry that overlaps one is rejected at config load.

If you need to reach a private IP for legitimate internal use, do not disable pipelock — add the narrowest possible range (ideally a single /32) to ssrf.ip_allowlist, use trusted_domains for hostname-based internal services whose DNS you control, or scope pipelock to a narrower set of agents. There is no supported way to allow access to a cloud-metadata endpoint.

How Rules Are Loaded#

At startup, pipelock scans the rules directory for installed bundles. Each bundle's rules are merged with the built-in patterns:

• DLP rules are added to the DLP pattern list alongside built-in patterns
• Injection rules are added to the response scanning pattern list
• Tool-poison rules are added to the tool description scanner

Bundle rules cannot override or disable built-in patterns. They are additive only.

Version-gate outcomes#

During a rolling upgrade, set allow_unversioned_bundle_load explicitly on every instance. A binary from before this behavior treats an omitted value as refuse, so an omitted setting reads differently across a mixed fleet and the effective policy hash differs with it.

Configuration#

# pipelock.yaml
rules:
  rules_dir: ~/.local/share/pipelock/rules # default ($XDG_DATA_HOME/pipelock/rules)
  min_confidence: medium # skip experimental rules (low confidence)
  include_experimental: false # default: only stable rules are active
  allow_degraded: false # strict mode refuses installed-bundle integrity failures
  trust_embedded_keys: true # default: trust the compiled official rules keyring
  # trusted_keys: # additional trusted public keys (beyond embedded keyring)
  # - name: "vendor-security"
  # public_key: "64-char-hex-encoded-ed25519-public-key"

Degraded Bundle State#

Pipelock separates rule-bundle load failures into two operator classes:

• Integrity failures: bad signatures, missing or mismatched bundle.lock, bundle hash mismatch, malformed installed bundle content, expired bundles, signer/tier mismatch, and freshness rollback state tampering.
• Availability failures: missing optional rules directory, bundle file read/stat failures, freshness lock failures, or a bundle that requires a newer engine feature.

In mode: strict, an integrity failure for an installed bundle refuses startup unless rules.allow_degraded: true is explicitly set. The error names the bundle and class so the operator can verify or reinstall the bundle before retrying. Availability failures keep the process available but mark the bundle state degraded.

In non-strict modes, Pipelock starts with the remaining rules but emits a structured rule_bundle_degraded audit event and a startup warning. /stats reports degraded bundle count and names under rule_bundles; /metrics exposes pipelock_rule_bundles_degraded.

On hot reload, a clean deletion of a previously live bundle is treated as a coverage drop. Strict mode rejects that reload and keeps the running config unless rules.allow_degraded: true is set on the candidate config. Non-strict modes allow the reload but emit a warning and audit event naming the bundle and pattern count dropped.

rules.allow_degraded is an emergency override, not a normal operating mode. Use it only after confirming the bundle store is intentionally unavailable or after choosing to continue while restoring bundle integrity.

Trust Model#

Bundles are Ed25519-signed YAML files. Pipelock verifies signatures against a keyring before loading rules.

Official bundles#

Official bundles (like pipelock-community) are signed with the production key compiled into the source and also embedded in release binaries at build time. No additional configuration is needed.

The first successful install is trust on first use for freshness. The signature proves who published the bundle and that its bytes are intact, but a machine with no saved history can't prove that the first valid bundle it sees is the newest one. Pipelock records that accepted bundle's monotonic version and format. Later installs and updates can't move either value backward. Removing or explicitly resetting the freshness state also removes that local rollback history, so verify the installed bundles before running pipelock rules reset-freshness.

Private-root-only operators can set rules.trust_embedded_keys: false to remove the compiled official keyring from bundle verification. In that mode, bundles must be signed by rules.trusted_keys; unsigned local bundles are rejected, and strict mode treats non-matching installed bundles as integrity failures unless the operator explicitly enables rules.allow_degraded.

Third-party bundles#

Organizations can create and sign their own bundles. Add their public key to trusted_keys in your config. Pipelock verifies third-party signatures the same way it verifies official ones.

Unsigned bundles#

The --allow-unsigned flag skips signature verification during install. Use this only for local testing. Unsigned bundles log a warning at startup.

Bundle keyring separated from the license key#

As of v2.5.0 the bundle-signing keyring is stored and loaded independently from the license key. Rotating one does not force rotating the other. The migration is automatic on first load; bundles signed under the prior layout verify unchanged. Operators running a custom trusted_keys list are unaffected.

Multi-bundle layout#

The pipelock-rules repo ships a multi-bundle directory layout so each bundle is signed and versioned independently. A bundle is identified by name and tier, not by file location, so operators can install only the bundles they need. Install several bundles side by side; each one runs in addition to the core and standard tiers:

pipelock rules install pipelock-community
pipelock rules install --source https://example.com/finance-pii/bundle.yaml finance-pii

pipelock rules list shows every installed bundle with its tier, version, and rule counts. Bundles are additive — they cannot override or disable the core or standard tiers, and they cannot override each other; identical rules across bundles dedupe at load time.

The official registry also publishes the independently versioned
healthcare-phi-pii community bundle for regex-detectable healthcare and
financial identifiers.

Verifying Signatures#

# Re-verify all installed bundles against the embedded keyring
pipelock rules verify

Creating Your Own Bundle#

A bundle is a single YAML file with a header and a list of rules:

format_version: 2
name: my-company-rules
version: "2026.04.1"
author: vendor-security
description: "Internal detection patterns for Vendor Corp"
min_pipelock: "2.2.0"
tier: community
monotonic_version: 1
published_at: "2026-04-16T00:00:00Z"
expires_at: "2027-04-16T00:00:00Z"
required_features:
  - dlp

rules:
  - id: dlp-internal-api-key
    type: dlp
    status: stable
    name: "Vendor Internal API Key"
    description: "Detects Vendor Corp internal API keys"
    severity: critical
    confidence: high
    pattern:
      regex: 'vendor_[a-zA-Z0-9]{32}'

DLP rules may set pattern.validator to luhn, mod97, aba, or wif when
the identifier carries that checksum. Pipelock applies the validator after a
regex match, so malformed lookalikes do not become DLP findings. Bundle
authors should declare required_features: ["checksum"] and set
min_pipelock to the oldest Pipelock release whose rule-bundle loader supports
the pattern.validator field.

format_version: 1 bundles still load for backwards compatibility, but new bundles should use format_version: 2 so they can declare tier, required_features, and freshness metadata. The v2 validation also requires monotonic_version, published_at, and expires_at.

Rule types#

Tool-poison rules with scan_field: description scan the tool's description and description fields nested in its input schema. Built-in scanning still covers every other agent-visible tool field, but those fields do not trigger description-scoped bundle rules.

Bundle rules are deny-only. A pattern.exempt_domains field is accepted for compatibility but ignored, and the loader reports a warning naming the rule when it sees one. Configure exemptions in the local Pipelock config instead.

Machine-readable reader contract#

A release-stamped Pipelock binary can export the rule-bundle contract it enforces:

pipelock rules schema > pipelock-rule-schema.json

The JSON records the exact Pipelock version and source revision, accepted bundle formats, YAML fields,
enum values, rule types, type-specific pattern fields, merge targets, and bundle action semantics. The
command refuses to produce an unversioned contract when the build can't report its source revision.
Consumers should pin output from an exact Pipelock artifact by digest instead of fetching a moving
release during ordinary pull-request checks.

Signing your bundle#

# Generate a keypair for your organization
pipelock keygen my-org

# Sign the bundle (uses the keystore at ~/.pipelock/)
pipelock sign bundle.yaml --agent my-org

# Distribute: bundle.yaml + bundle.yaml.sig + your public key hex

Users add your public key to their trusted_keys config to verify your bundles.

Hosting#

The official community bundle is hosted at pipelab.org/rules/. The pipelock rules install command fetches from this URL by default. Self-hosted bundles can be served from any HTTPS endpoint using the --source flag.

Version Format#

Bundles use CalVer: YYYY.MM.patch (e.g., 2026.03.1). The min_pipelock field ensures compatibility with the installed binary version.