From 21665e16e2f9d646eae272c380c61150cd1e0b2c Mon Sep 17 00:00:00 2001 From: luckyPipewrench Date: Wed, 4 Nov 2026 20:36:01 -0500 Subject: [PATCH 1/3] docs: make contributor guidance portable and accurate --- .github/ISSUE_TEMPLATE/bug_report.md | 6 +- .github/ISSUE_TEMPLATE/new_rule.md | 2 +- .github/ISSUE_TEMPLATE/security_bypass.md | 7 +- .github/PULL_REQUEST_TEMPLATE.md | 11 +- .github/workflows/ci.yaml | 8 +- .github/workflows/pipelock.yaml | 7 +- .github/workflows/release.yaml | 6 +- .github/workflows/scorecard.yaml | 21 +-- AGENTS.md | 155 ++++++++-------------- CONTRIBUTING.md | 75 ++++++----- README.md | 12 +- SECURITY.md | 43 ++---- docs/rule-catalog.md | 4 +- scripts/compile.sh | 2 +- scripts/render_brand.py | 53 ++------ scripts/render_diagrams.py | 32 ++--- scripts/render_diagrams_test.py | 27 ++-- 17 files changed, 179 insertions(+), 292 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 93ebd58..8122f0d 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -12,8 +12,8 @@ Which rule is affected? (e.g. `dlp-perplexity-api-key`) **Problem** Is this a false positive (matches something it shouldn't) or a false negative (misses something it should catch)? -**Test string** -The string that was incorrectly matched or missed: +**Synthetic test string** +Provide a nonfunctional example that reproduces the incorrect match or miss. Use fabricated personal or health data and synthetic credentials. Report exploitable bypasses privately as described in SECURITY.md. ``` paste test string here @@ -26,4 +26,4 @@ Should this string match or not? From `pipelock --version`. **Additional context** -Relevant config, bundle version, or context about where the string appeared. +Bundle version and relevant configuration or surrounding text. Remove secrets, private addresses and identifying records before posting. diff --git a/.github/ISSUE_TEMPLATE/new_rule.md b/.github/ISSUE_TEMPLATE/new_rule.md index 5503573..d37b714 100644 --- a/.github/ISSUE_TEMPLATE/new_rule.md +++ b/.github/ISSUE_TEMPLATE/new_rule.md @@ -13,7 +13,7 @@ DLP, injection, or tool-poison? Describe the credential format, injection technique, or tool poisoning pattern. **Example match** -A realistic string that should trigger the rule: +A synthetic, nonfunctional string that should trigger the rule. Use fabricated personal or health data rather than copying a real record or credential. ``` paste example here diff --git a/.github/ISSUE_TEMPLATE/security_bypass.md b/.github/ISSUE_TEMPLATE/security_bypass.md index eb0fa2c..3635540 100644 --- a/.github/ISSUE_TEMPLATE/security_bypass.md +++ b/.github/ISSUE_TEMPLATE/security_bypass.md @@ -7,7 +7,7 @@ assignees: '' --- > **If this is exploitable in production**, please report it via -> [Pipelock Security Advisories](https://github.com/luckyPipewrench/pipelock/security/advisories) +> [Pipelock Security Advisories](https://github.com/pipelab-org/pipelock/security/advisories/new) > instead of opening a public issue. **Rule ID** @@ -16,8 +16,9 @@ Which rule is affected? (e.g. `dlp-perplexity-api-key`) **Bypass method** How does the evasion work? (encoding, splitting, structural trick, etc.) -**Test string** -A string that should be caught but isn't: +**Synthetic test string** + +A nonfunctional example that should be caught but isn't. Use synthetic credentials and fabricated personal or health data. If the example demonstrates an exploitable production bypass, submit it through Security Advisories instead of this public issue. ``` paste test string here diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 430abe1..1ac2582 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -17,14 +17,19 @@ Brief description of what this PR adds or changes. ## Testing - [ ] `BUNDLE_NAME= make compile` succeeds -- [ ] `BUNDLE_NAME= make test-fixtures` passes (all true/false positive fixtures) -- [ ] `BUNDLE_NAME= make validate` passes (pipelock accepts the bundle) -- [ ] Maintainer signing completed if this changes `published//bundle.yaml` +- [ ] `BUNDLE_NAME= make test-fixtures` passes +- [ ] `BUNDLE_NAME= make validate` passes +- [ ] Bundle version increased and `compatibility/contract.yaml` updated for each changed published bundle +- [ ] Compiled YAML passes the `yamllint` command in `CONTRIBUTING.md` +- [ ] Regenerated diagrams and `docs/rule-catalog.md` are included where affected +- [ ] `make preflight` passes, or the unavailable prerequisite is named here +- [ ] Maintainer signing completed before merge if this changes `published//bundle.yaml` ## Checklist - [ ] RE2-compatible regex (no lookahead/lookbehind) - [ ] True-positive fixture added +- [ ] Fixtures use synthetic credentials and fabricated personal or health data only - [ ] False-positive fixture added (stable rules) - [ ] Primary source citation included (stable rules) - [ ] Rule ID follows naming convention (`{type}-{provider/technique}`) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 8ce1abe..454003c 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -100,10 +100,8 @@ jobs: test "${{ needs.compatibility-floor.result }}" = "success" test "${{ needs.published-signatures.result }}" = "success" - # `Test fixtures` is a required status check. The fixture run now happens - # inside the preflight matrix, so this reports that name from the matrix - # result. Without it the requirement is unsatisfiable and every pull request - # stays blocked while appearing merely pending. + # Preserve the Test fixtures status-check name. The validate job runs fixture + # tests through make preflight; this job forwards its result. test-fixtures-required: name: Test fixtures needs: [validate] @@ -111,7 +109,7 @@ jobs: runs-on: ubuntu-latest timeout-minutes: 1 steps: - - name: Confirm matrix passed + - name: Confirm preflight passed run: test "${{ needs.validate.result }}" = "success" published-signatures: diff --git a/.github/workflows/pipelock.yaml b/.github/workflows/pipelock.yaml index f7abdd9..270f8cb 100644 --- a/.github/workflows/pipelock.yaml +++ b/.github/workflows/pipelock.yaml @@ -1,10 +1,7 @@ name: Pipelock Security Scan -# This repository publishes detection rules, so it is scanned by the product it -# writes rules for. The scan lived inside the CI workflow, where its result was -# only visible as part of a combined CI badge; a reader could not tell whether -# the scan itself passed. It runs on its own here so the README badge reports -# this scan and nothing else. +# Run the Pipelock content scan in its own workflow so the README badge reports +# this scan's result independently of the other CI checks. on: push: diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 8216527..0e1d508 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -81,10 +81,8 @@ jobs: printf 'release: FAIL - %s must contain bundle.yaml and bundle.yaml.sig\n' "$bundle_dir" >&2 exit 1 fi - # Collect every matching line and require exactly one non-empty - # value. Reading into a scalar hid a duplicate declaration whose - # empty value sorted last, because command substitution strips - # trailing newlines and the result then looked single-valued. + # Require exactly one non-empty version declaration before naming + # release assets or describing the bundle version. versions=() mapfile -t versions < <(sed -n 's/^version: "\([^"]*\)"$/\1/p' "$bundle_file") if (( ${#versions[@]} != 1 )) || [[ -z "${versions[0]}" ]]; then diff --git a/.github/workflows/scorecard.yaml b/.github/workflows/scorecard.yaml index 641a3d3..53c20d7 100644 --- a/.github/workflows/scorecard.yaml +++ b/.github/workflows/scorecard.yaml @@ -40,21 +40,6 @@ jobs: retention-days: 5 - # Scorecard results are NOT uploaded to code scanning, deliberately. - # - # Scorecard grades repository practice: pinned dependencies, branch - # protection, what share of pull requests carried an approving review. - # Code scanning is the surface for defects in this repository's code, and - # routing a grade into it files each check as a dismissible alert with a - # severity attached. - # - # Those alerts also do not stay dismissed. GitHub matches results across - # uploads by rule and fingerprint, and a Scorecard result whose identity - # shifts arrives as a NEW alert that a previous dismissal does not cover. - # The outcome was a standing queue of security-labelled items that no code - # change could close. - # - # The results remain public and retrievable: publish_results above sends - # them to the OpenSSF Scorecard API that backs the badge and the public - # viewer, and the artifact above keeps the raw SARIF. This narrows where - # the grade is displayed. It does not withhold it. + # Publish repository-practice scores through the Scorecard API and retain + # raw SARIF as an artifact. Keep code-scanning alerts for code defects; + # repeated score uploads can otherwise create alerts with changing identities. diff --git a/AGENTS.md b/AGENTS.md index d0392f2..6ee64ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,120 +1,83 @@ -# AGENTS.md: pipelock-rules Development Guide +# Pipelock Rules contributor guide -Community detection rule bundles for [Pipelock](https://github.com/pipelab-org/pipelock). +This repository publishes signed detection-rule bundles for [Pipelock](https://github.com/pipelab-org/pipelock). Rules extend its data loss prevention (DLP), prompt-injection and MCP tool-poisoning scanners. -## Quick Reference +## Repository contracts -| Item | Value | -|------|-------| -| Language | YAML (rule definitions) + Bash (build scripts) | -| CI | GitHub Actions: validate, test-fixtures, yaml-lint | -| Bundle format | `format_version: 1` YAML with Ed25519 signatures | -| Regex engine | RE2 (no lookahead/lookbehind, no backreferences) | +- Rule definitions are YAML. Build and validation tooling uses Bash, Go and Python. +- Patterns use Go's regexp package with RE2 syntax. Lookaround and backreferences aren't supported. Pipelock applies case-insensitive matching automatically. +- Published bundles use YAML with detached Ed25519 signatures. The existing pipelock-community and healthcare-phi-pii bundles use `format_version: 1`. New bundles use `format_version: 2`; existing bundles migrate only with coordinated content, signature, distribution and compatibility updates. +- `CONTRIBUTING.md` defines rule structure, naming, quality requirements and the complete change sequence. `compatibility/contract.yaml` binds the maintained bundles to their published bytes and recorded reader compatibility. -## Build, Test, Validate +## Setup and validation + +See [CONTRIBUTING.md](CONTRIBUTING.md#prerequisites) for prerequisites. The main tools are GNU Make, Bash, Go, Python 3 and a Pipelock CLI on `PATH`. YAML lint uses the pinned dependencies in `.github/requirements-yamllint.txt`. + +Preflight checks the CLI's parsed `major.minor.patch` version against `tested_through_pipelock` in `compatibility/contract.yaml`. Installing the latest Pipelock version isn't a substitute for matching that recorded version. CI builds the commit pinned in `.github/workflows/ci.yaml` and checks its reported version. ```bash -make compile # Merge default bundle files into published/pipelock-community/bundle.yaml -make validate # Compile + install into pipelock (validates schema and regexes) -make test-fixtures # Run every regex against its true/false positive fixtures -make diagrams # Re-render the README diagrams and docs/rule-catalog.md -make check-diagrams # Fail if an asset, a painted count, or a README claim has drifted -make preflight # check-diagrams, then validate and test-fixtures for every bundle -``` +# Compile the default pipelock-community bundle +make compile -Set `BUNDLE_NAME=` to work on a non-default bundle, for example `BUNDLE_NAME=healthcare-phi-pii make test-fixtures`. +# Compile and validate the selected bundle with Pipelock +make validate -`make validate` requires `pipelock` on PATH. Install with `go install github.com/luckyPipewrench/pipelock/cmd/pipelock@latest`. +# Test compiled patterns against their fixtures +make test-fixtures -Any change to rule counts, bundle versions, the Pipelock version CI installs, the pinned signing key, or a CI job name changes what the README diagrams claim. Run `make diagrams` and commit both the regenerated `assets/` and `docs/rule-catalog.md`; `make check-diagrams` fails otherwise. The generator reads only `python3` from the standard library, so it needs no extra tooling. +# Compile a non-default bundle +BUNDLE_NAME=healthcare-phi-pii make compile -## Repository Layout +# Test the non-default bundle's compiled patterns +BUNDLE_NAME=healthcare-phi-pii make test-fixtures -```text -rules/ - pipelock-community/ - dlp/ One YAML file per DLP pattern - injection/ One YAML file per injection pattern - tool-poison/ One YAML file per tool-poison pattern - healthcare-phi-pii/ - dlp/ -fixtures/ - pipelock-community/ - dlp/ True/false positive test strings per rule - injection/ - tool-poison/ - healthcare-phi-pii/ - dlp/ -published/ - pipelock-community/ - bundle.yaml Compiled bundle (all rules merged) - bundle.yaml.sig Ed25519 signature (production-signed) - healthcare-phi-pii/ - bundle.yaml -scripts/ - compile.sh Merges rule files into bundle.yaml - test-fixtures.sh Validates every regex against fixtures -``` +# Regenerate diagrams and the rule catalog from compiled bundles +make diagrams + +# Check generated diagrams and the catalog without rewriting them +make check-diagrams -## Adding a Rule - -1. Create `rules/{bundle}/{type}/{name}.yaml` following the schema in CONTRIBUTING.md -2. Add `fixtures/{bundle}/{type}/{rule-id}-true-positive.txt` (one match per line) -3. Add `fixtures/{bundle}/{type}/{rule-id}-false-positive.txt` (stable rules only) -4. Run `BUNDLE_NAME={bundle} make compile && BUNDLE_NAME={bundle} make test-fixtures` -5. Run `BUNDLE_NAME={bundle} make validate`, which installs the compiled bundle with Pipelock and checks the schema and every regex. Compilation and fixture tests alone do not cover that. -6. Submit a PR - -## Rule YAML Schema - -Every rule requires these fields: - -```yaml -- id: dlp-example-api-key # Unique, prefixed with rule type - type: dlp # dlp, injection, or tool-poison - status: stable # stable or experimental - name: "Example API Key" - description: "Detects Example.com API keys" - severity: critical # critical, high, medium, low - confidence: high # high, medium, low - references: - - "https://example.com/docs" - tags: - - "provider:example" - pattern: - regex: 'ex_[A-Za-z0-9]{32,}' # RE2-compatible +# Check diagrams, brand assets, compatibility, schemas and fixtures +make preflight ``` -`scan_field` is conditional, not required. It applies to tool-poison rules only, where it selects `name` or `description`. DLP rules omit it entirely; see `rules/pipelock-community/dlp/vercel-project.yaml` for a rule that carries every required field and no `scan_field`. +Compile changed bundles before regenerating their diagrams. Keep compatibility metadata current, regenerate assets and `docs/rule-catalog.md`, then run preflight. Generated-output checks detect stale committed files; they don't regenerate them. -```yaml - pattern: - regex: 'ex_[A-Za-z0-9]{32,}' - scan_field: description # tool-poison rules only -``` +Preflight covers every bundle listed in `PREFLIGHT_BUNDLES`. YAML lint, version-history checks, published-signature verification and separate security workflows also run in CI. A passing preflight doesn't replace those checks. + +The diagram generator needs only the Python standard library. Changes to rule counts, bundle versions, CI's Pipelock version, signing-key pins or relevant CI job names can affect generated claims. Brand assets come from `assets/mark.svg` through `scripts/render_brand.py`. `make brand` needs Inkscape and ImageMagick to regenerate vectors, rasters and provenance; `make check-brand` checks the committed output. + +## Layout -## Regex Guidelines +```text +rules/// One YAML source file per rule +fixtures/// True-positive and false-positive examples +published// Compiled bundle.yaml and detached bundle.yaml.sig +compatibility/ Byte-bound bundle and reader-format contracts +docs/rule-catalog.md Generated list of published rules +assets/ Generated diagrams and brand assets; mark.svg is the source mark +scripts/compile.sh Concatenates source rules and emits the bundle header +scripts/test-fixtures.sh Runs the Go fixture checker +``` -- RE2 syntax only (pipelock uses Go's `regexp` package) -- Prefer specific prefixes over broad character classes -- Set minimum match lengths to reduce false positives -- Case-insensitive matching (`(?i)`) is applied automatically by pipelock -- Test against real-world text, not just isolated tokens +The compiler preserves source indentation and emits dlp, injection and tool-poison directories in that order, with files sorted by filename. Use the canonical YAML layout in `CONTRIBUTING.md`. The fixture checker reads a strict single-line representation of IDs, status and regex fields; valid YAML alone doesn't establish that the fixture tooling can read a rule. -## Fixture Format +## Rules and fixtures -One test string per line. Every non-empty line is tested (no comment syntax). +Follow [CONTRIBUTING.md](CONTRIBUTING.md) for rule structure, version increases, compatibility metadata, validation and submission. It also describes the integration needed for a new bundle. -- `{rule-id}-true-positive.txt`: strings that MUST match the regex -- `{rule-id}-false-positive.txt`: strings that MUST NOT match +- Rule IDs are unique within a bundle, lowercase and hyphenated, with a type prefix followed by the provider or technique. Keep one rule per source YAML file. +- Prefer specific prefixes and suitable minimum match lengths. Keep patterns readable, such as `[A-Za-z0-9]` instead of `\w` where that expresses the intended format. Include realistic surrounding text in fixtures. +- Stable rules need primary-source references and at least one true-positive and one false-positive fixture string. Experimental rules need a true-positive fixture and an explanation; they may also carry false-positive fixtures. +- Fixture filenames use `-true-positive.txt` and `-false-positive.txt`. Each non-empty line is a test string; there's no comment syntax. +- Positive examples must match and negative examples must not match. Supplied examples establish those cases, not every possible input. +- Use synthetic credentials and fabricated personal or health data. Public fixtures, issues and pull requests mustn't contain live secrets or identifying records. +- `scan_field` is used only for tool-poison rules, selecting name or description. DLP and injection rules omit it. -## Signing +## Signing and review -Published official bundles are signed with the Pipelock official rules key. Only maintainers with keystore access can sign. CI verifies that committed `published//bundle.yaml` files are current with `rules//` and that each `bundle.yaml.sig` verifies against `.github/rules-official/pipelock-official.pub`. +Official published bundles are signed with the Pipelock official rules key. Only maintainers with signing-key access sign them. Contributors don't need that access. Maintainers add or refresh `bundle.yaml.sig` on the pull request before merge when published bundle bytes change. -## Style +CI checks that committed published bundles match their source rules and verifies their signatures against `.github/rules-official/pipelock-official.pub`. These checks remain required when a contributor can't sign locally. Maintainers review pull requests; CI and review requirements in `CONTRIBUTING.md` apply before merge. -- Rule IDs: `{type}-{provider}` or `{type}-{technique}` (lowercase, hyphens) -- One rule per YAML file -- Keep regexes readable: prefer `[A-Za-z0-9]` over `\w` for clarity -- Include primary source citations for every stable rule +Report vulnerabilities through the private advisory process in [SECURITY.md](SECURITY.md). Ordinary rule-quality reports can use public issues with synthetic reproduction data. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 471c340..de6e6d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,9 +4,14 @@ Rules are welcome via pull request. Each rule must meet the quality bar below be ## Prerequisites -- [Pipelock](https://github.com/pipelab-org/pipelock) v1.4.0+ (for `make validate`) -- Bash (for `make compile` and `make test-fixtures`) -- A regex that works with Go's RE2 engine (no lookahead/lookbehind, no backreferences) +- GNU Make and Bash for build targets and scripts, plus the standard command-line utilities used by those scripts. +- Go for the fixture checker and its tests. +- Python 3 for diagram generation and compatibility checks. +- Pipelock on `PATH` for validation and compatibility tests. Preflight requires its parsed `major.minor.patch` version to match `tested_through_pipelock` in `compatibility/contract.yaml`. A newer version core fails that check. CI builds the Pipelock commit pinned in `.github/workflows/ci.yaml` and checks the reported version. +- `yamllint` for the separate YAML lint check. Install its pinned dependencies with `pip install --require-hashes -r .github/requirements-yamllint.txt` in a Python environment you manage. +- A pattern supported by Go's regexp package (RE2 syntax, without lookaround or backreferences). + +Changing brand assets also needs Inkscape and ImageMagick (`magick` or `convert`). `make check-brand` checks committed assets without rendering them; `make brand` regenerates vectors, rasters and their provenance together. ## Contributing Rules to an Existing Bundle @@ -20,27 +25,24 @@ Rules are welcome via pull request. Each rule must meet the quality bar below be - Injection: `{technique}.yaml` - Tool-poison: `{behavior}.yaml` -3. Add fixture files in `fixtures//{type}/`: - - `{rule-id}-true-positive.txt`: one test string per line that MUST match - - `{rule-id}-false-positive.txt`: one test string per line that MUST NOT match - - Every non-empty line is tested (no comment syntax) +3. Add fixtures under `fixtures///`. Each non-empty line is test data, including lines that look like comments. Every rule needs a `-true-positive.txt` file with at least one matching example. Stable rules also need a `-false-positive.txt` file with at least one nonmatching example; experimental rules may include that file too. Use synthetic, nonfunctional credentials and fabricated personal or health data. Issues, fixtures and PR descriptions are public. + +4. Increase the selected bundle's version in `scripts/compile.sh` when its source rules change. CI also preserves the bytes associated with an already published bundle name and version; published content changes need a new version. Editing the generated header alone doesn't survive compilation. + +5. Compile the selected bundle, then update its version and `bundle_sha256` in `compatibility/contract.yaml` to match `published//bundle.yaml`. `sha256sum` prints the digest. + +6. Run the selected bundle's fixture and schema checks and CI's YAML lint command: -4. Run validation: ```bash BUNDLE_NAME= make compile BUNDLE_NAME= make test-fixtures BUNDLE_NAME= make validate + yamllint -d '{extends: default, rules: {line-length: {max: 400}, document-start: disable, truthy: disable, empty-lines: {max: 1}}}' published//bundle.yaml ``` -5. Re-render the README diagrams and the rule catalog, because both count the rules you - just changed: - ```bash - make diagrams - ``` - Commit the updated files under `assets/` **and** `docs/rule-catalog.md`. CI runs - `make check-diagrams`, which fails while either still shows the old counts. +7. Run `make diagrams` after the compiled bundles and compatibility metadata are current. Include the regenerated `assets/` files and `docs/rule-catalog.md`, then run `make preflight`. Preflight checks diagrams, brand assets, compatibility, schema validation and fixtures for the maintained bundles. YAML lint, version-history checks and signature verification are separate CI checks. -6. Submit a PR. +8. Open a pull request with the source, fixtures, compiled bundle, compatibility metadata and generated documentation. Name any validation prerequisite you couldn't run. Maintainers add or refresh the official bundle signature on the PR before merge; contributors don't need signing-key access. CI must pass before merge. `pipelock-community` is the default bundle, so existing commands such as `make compile` still target it. @@ -48,7 +50,11 @@ Rules are welcome via pull request. Each rule must meet the quality bar below be Open an issue first so naming, scope, signing-key alignment, and maintenance ownership can be confirmed before code is added. New bundles must use `format_version: 2`, which requires Pipelock v2.2.0 or later. The existing `pipelock-community` and `healthcare-phi-pii` bundles remain on `format_version: 1` until their bundle content, signatures, served copies, and compatibility checks can migrate together. -Use this header for a new bundle: +A new bundle needs compiler, validation and CI integration as well as rule files. Add a bundle-specific case and header emission in `scripts/compile.sh` that produces the complete format-2 header shown below. `make compile` overwrites the selected `published//bundle.yaml`; it doesn't preserve a hand-edited header. Add the bundle to `PREFLIGHT_BUNDLES` in `Makefile`, the compatibility-floor and YAML-lint matrices in `.github/workflows/ci.yaml`, and the installer cases in `scripts/test-compatibility-install.sh`. Add its byte-bound entry and a format-2 reader-schema identity with a pinned schema digest to `compatibility/contract.yaml`. Extend compatibility tests for that identity. Compile the bundle, run fixture and schema checks, regenerate diagrams and the catalog, and run preflight. Maintainers sign the resulting published bundle on the PR before merge. + +The existing validation target installs an unsigned copy under a temporary name. Format-2 bundles need signed validation that preserves their identity, so that path also needs integration before a new bundle can pass preflight. + +The compiled header for a new bundle has this shape: ```yaml format_version: 2 @@ -60,6 +66,7 @@ homepage: "https://example.com/security/rules" min_pipelock: "2.2.0" license: "Apache-2.0" tier: community +key_id: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" monotonic_version: 1 published_at: "2026-08-25T00:00:00Z" expires_at: "2027-08-25T00:00:00Z" @@ -70,6 +77,8 @@ rules: # Rule entries follow the format below. ``` +`key_id` is the signing public key as 64 lowercase hex characters. Replace the placeholder with the bundle's signing public key before signing. See the [bundle signing guide](https://github.com/pipelab-org/pipelock/blob/main/docs/rules.md#signing-your-bundle). + `tier` declares the bundle's trust tier. `required_features` lists the Pipelock engine features that every rule in the bundle needs. Increase `monotonic_version` for each published bundle version so Pipelock can reject rollbacks. Write `published_at` and `expires_at` as UTC RFC 3339 timestamps. New bundles should use this layout: @@ -84,23 +93,24 @@ published//bundle.yaml ## Rule YAML Format ```yaml - - id: dlp-example-api-key # unique ID, prefixed with rule type - type: dlp # dlp, injection, or tool-poison - status: stable # stable or experimental - name: "Example API Key" # human-readable name + - id: dlp-example-api-key + type: dlp + status: stable + name: "Example API Key" description: "Detects Example.com API keys" - severity: critical # critical, high, medium, low - confidence: high # high, medium, low - references: # primary sources (vendor docs, research) + severity: critical + confidence: high + references: - "https://example.com/docs/api-keys" - tags: # categorization + tags: - "provider:example" - "owasp-llm:LLM06" pattern: - regex: 'ex_[A-Za-z0-9]{32,}' # RE2-compatible regex - scan_field: description # tool-poison only: name or description + regex: 'ex_[A-Za-z0-9]{32,}' ``` +Use this indentation in source rule files: two spaces before `- id:`, four before rule fields and six before pattern fields. The compiler concatenates these files without reindenting them. The fixture checker and diagram generator read a canonical line format: keep `id` and `status` unquoted, and `regex` single-quoted on one line, with no trailing comments on those lines. Escape an apostrophe inside a single-quoted YAML value by doubling it. Rule IDs are unique within a bundle and use the rule type followed by the provider or technique, in lowercase with hyphens. `type` is `dlp`, `injection` or `tool-poison`; `status` is `stable` or `experimental`; `severity` is `critical`, `high`, `medium` or `low`; `confidence` is `high`, `medium` or `low`. `references` lists primary sources. Only tool-poison rules add `scan_field` under `pattern`, set to `name` or `description`. DLP and injection rules omit it. + ## Quality Bar ### Stable rules @@ -124,6 +134,8 @@ published//bundle.yaml - Set minimum match lengths to reduce false positives - Test against real-world text, not just isolated tokens - Case-insensitive matching is applied automatically by pipelock (`(?i)` prefix) +- Keep regexes readable: prefer `[A-Za-z0-9]` over `\w`. +- Put one rule in each YAML file. ## Rule Types @@ -138,16 +150,13 @@ published//bundle.yaml - PRs are squash-merged into `main` - CI must pass: bundle validation, fixture tests, YAML lint - Official published bundles must be current and signed before merge. Contributors - do not need signing-key access; maintainers add or refresh `bundle.yaml.sig` + don't need signing-key access; maintainers add or refresh `bundle.yaml.sig` during review when a PR changes `published//bundle.yaml`. - All review threads must be resolved before merge ## Development Workflow -1. Fork the repo and create a branch (`feat/new-rule-name` or `fix/rule-id`) -2. Add your rule and fixtures -3. Run `BUNDLE_NAME= make compile && BUNDLE_NAME= make test-fixtures && BUNDLE_NAME= make validate` -4. Push and open a PR +Fork the repository, create a branch such as `feat/new-rule-name` or `fix/rule-id`, and follow [Contributing Rules to an Existing Bundle](#contributing-rules-to-an-existing-bundle) before opening a pull request. ## Contributor License Agreement @@ -155,4 +164,4 @@ By submitting a pull request, you agree that your contributions are licensed und ## Security -If a regex could be exploited for ReDoS or other abuse, use the [security advisory process](https://github.com/pipelab-org/pipelock/security/advisories). See [SECURITY.md](SECURITY.md) for details. +Report exploitable detection bypasses, resource-exhaustion behavior and other vulnerabilities through [Pipelock Security Advisories](https://github.com/pipelab-org/pipelock/security/advisories). Use public issues for ordinary rule-quality problems that don't disclose an exploitable vulnerability. See [SECURITY.md](SECURITY.md) for reporting details and safe reproduction data. diff --git a/README.md b/README.md index 1b1e6b1..abaf61c 100644 --- a/README.md +++ b/README.md @@ -101,9 +101,9 @@ pipelock rules install --source "$base/pipelock-community-bundle.yaml" pipelock- **healthcare-phi-pii** is a healthcare DLP bundle contributed by BGASoft, Inc. It covers the regex-detectable entries from HIPAA Safe Harbor's 18 identifiers, financial PII, and clinical laboratory identifiers. -Every rule, with what it detects, its severity, and its primary source, is listed in the [rule catalog](docs/rule-catalog.md). That page is generated from the compiled bundles, so it cannot fall behind them. +The [rule catalog](docs/rule-catalog.md) lists every rule in every published bundle, with its severity and primary source where present. `make diagrams` generates it from the compiled bundles, and `make check-diagrams` detects a committed catalog that no longer matches them. -Stable rules are enabled by default. Experimental rules are not, because they carry only true-positive fixtures and may fire on traffic you consider benign. Turn them on when you want the wider net: +Stable rules are enabled by default. Experimental rules aren't: they need true-positive fixtures but may lack false-positive ones, so they can fire on traffic you consider benign. Enable them when you want to include those rules: ```yaml rules: @@ -117,7 +117,7 @@ rules: A rule moves from an authored file through compile, fixture proof, schema validation, and signing before an operator can install it -The point of the pipeline is that a rule's claims are executable. A regex that matches nothing, or that matches ordinary traffic, fails before review ever sees it. +Fixture tests require each rule to match its true-positive examples and, for stable rules, to reject its false-positive examples. Fixtures can't cover every input, so review also considers traffic they don't represent. ## Anatomy of a rule @@ -162,7 +162,7 @@ See the [full bundle authoring guide](https://github.com/pipelab-org/pipelock/bl ## Compatibility contract -The maintained bundles are tested from their declared `min_pipelock` through Pipelock `3.6.0`. A newer Pipelock release sits outside this tested range. It should warn and continue unless it can't read the bundle format. Pipelock `3.5.0` doesn't expose that warning yet, so `compatibility/contract.yaml` records the tested ceiling until a product update adds it. +CI tests each maintained bundle at its declared `min_pipelock` and at the `tested_through_pipelock` version recorded in `compatibility/contract.yaml`. The matrix doesn't individually test every version between those endpoints. A newer Pipelock version is outside this repository's recorded tested range. The compatibility contract records that range; it doesn't establish whether the running Pipelock version emits a warning about it. The contract binds each published bundle's name, CalVer, minimum version, and `format_version` to a SHA-256-pinned reader-schema identity. The two bundles named in the contract add detections. They don't carry per-rule allow or block actions, and they can't replace built-in patterns. Format 1 has no monotonic rollback counter. The installer refuses a same-version digest change. @@ -186,11 +186,11 @@ make test-fixtures # Re-render the README diagrams and the rule catalog from the live bundles make diagrams -# Everything CI runs locally, for every published bundle +# Check diagrams, brand assets, compatibility, validation and fixtures for every maintained bundle make preflight ``` -`make preflight` requires a Pipelock CLI on your PATH. It never downloads one, so a missing binary is a clear prerequisite failure rather than a silently skipped schema check. +See [CONTRIBUTING.md](CONTRIBUTING.md#prerequisites) for prerequisites and the complete rule-change sequence. Preflight needs the Pipelock version core recorded in `compatibility/contract.yaml` and doesn't download a CLI. Missing tools fail the check. YAML lint, published-signature verification and version-history checks run separately in CI. ### Repository layout diff --git a/SECURITY.md b/SECURITY.md index b3a738c..0c8f524 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,42 +1,23 @@ -# Security Policy +# Security policy -## Reporting a Vulnerability +## Reporting a vulnerability -If a community rule regex could be exploited for **ReDoS** (regular expression denial of service) or other abuse, report it through the [Pipelock Security Advisory process](https://github.com/pipelab-org/pipelock/security/advisories/new). +Report exploitable detection bypasses, resource-exhaustion behavior, signature-verification bypasses and rule-distribution supply-chain attacks through [Pipelock Security Advisories](https://github.com/pipelab-org/pipelock/security/advisories/new). Reports with security impact belong there before public disclosure, including false negatives that enable an exploitable bypass. -**Do NOT open a public GitHub issue for ReDoS or exploitable regex patterns.** +Ordinary false positives, non-exploitable detection gaps and rule-quality suggestions can use the public issue templates. If you're unsure whether a report exposes a vulnerability, start with a private advisory. -For false negatives (a rule fails to detect a real secret or injection pattern), open a regular issue using the "Rule Evasion / ReDoS" template. +Include the affected rule ID, bundle and Pipelock versions, a description of the behavior, a synthetic reproduction and a suggested fix if you have one. Public examples must use nonfunctional credentials and fabricated personal or health data. Remove secrets, private addresses and identifying records from configuration excerpts and logs. -Include: -- Rule ID affected -- Description of the bypass or exploit -- Test string demonstrating the issue -- Suggested fix (if any) +The rule checker uses Go's regexp package with RE2 syntax. Report excessive resource use with a bounded reproduction and observed results; catastrophic backtracking isn't the execution model used by this checker. -## Response Timeline +## Response timeline -- **Acknowledgment:** Within 48 hours -- **Initial assessment:** Within 1 week -- **Fix and disclosure:** Coordinated with reporter, typically within 30 days +- Acknowledgment: within 48 hours +- Initial assessment: within 1 week +- Fix and disclosure: coordinated with the reporter, typically within 30 days -## Scope - -The following are in scope for security advisories: - -- ReDoS patterns that cause catastrophic backtracking -- Regex patterns that match sensitive data they shouldn't (false positives causing information disclosure) -- Signature verification bypass in bundle signing -- Supply chain attacks via rule bundle distribution - -The following are regular issues (not security advisories): - -- False negatives (rule misses a real threat) -- False positives (rule matches benign content) -- Rule quality improvements - -## Supported Versions +## Supported versions | Version | Supported | |---------|-----------| -| 2026.x | Yes | +| 2026.x | Yes | diff --git a/docs/rule-catalog.md b/docs/rule-catalog.md index 0855271..b0df5f8 100644 --- a/docs/rule-catalog.md +++ b/docs/rule-catalog.md @@ -4,8 +4,8 @@ Every rule in every published bundle, generated from the compiled bundles by `scripts/render_diagrams.py`. Do not edit this file by hand: run `make diagrams`. Stable rules are enabled by default and carry a primary source plus fixtures in -both directions. Experimental rules carry true-positive fixtures only and stay off -until you set `rules.include_experimental: true`. +both directions. Experimental rules need true-positive fixtures, may also have +false-positive ones, and stay off until you set `rules.include_experimental: true`. ## pipelock-community diff --git a/scripts/compile.sh b/scripts/compile.sh index 2677c98..318f6f4 100755 --- a/scripts/compile.sh +++ b/scripts/compile.sh @@ -1,6 +1,6 @@ #!/bin/bash # Compile individual rule YAML files into a single bundle.yaml. -# Rules are sorted by type then ID for deterministic output. +# Rules are emitted in dlp, injection, tool-poison order, then by sorted filename. set -euo pipefail BUNDLE_NAME="${BUNDLE_NAME:-pipelock-community}" diff --git a/scripts/render_brand.py b/scripts/render_brand.py index f0d121d..b0ec363 100644 --- a/scripts/render_brand.py +++ b/scripts/render_brand.py @@ -30,8 +30,8 @@ ASSET_DIR = REPO_ROOT / "assets" MARK = ASSET_DIR / "mark.svg" -# Locked brand tokens. Source of truth is the PipeLab brand guidelines and -# pipelab.org/.brand/colors_and_type.css; these must not drift from it. +# Brand colors used by this repository. Keep these values consistent with the +# diagram palette in scripts/render_diagrams.py and the asset checks. ACCENT = "#00e5a0" BG = "#09090b" BG_ELEVATED = "#0e0e11" @@ -51,8 +51,7 @@ WORDMARK_ACCENT = "Rules" TAGLINE = "Signed, versioned detection rules for Pipelock" -# Family social-card footer. Same string, type, and position as Agent Egress -# Bench, so the two generated cards share one attribution rather than two. +# Attribution footer and its position on the repository's social preview card. CARD_FOOTER = "Apache 2.0 ยท maintained by PipeLab" CARD_FOOTER_X = 120 CARD_FOOTER_Y = 566 @@ -101,13 +100,7 @@ def _text(x, y, content, *, fill, size, family=SANS, weight=400, def particles(count, w, h, seed=7) -> list: - """Deterministic particle positions. No randomness, so the file is stable. - - Byte-identical algorithm and seed to the sibling benchmark repository, so - the two social cards carry the same field rather than two different fields - that merely look similar. The brand guidelines specify this treatment; see - section 7, Hero background. - """ + """Deterministic particle positions; a fixed seed keeps generated assets stable.""" state = seed points = [] for _ in range(count): @@ -185,12 +178,7 @@ def favicon() -> str: def lockup() -> str: - """Mark and wordmark on ONE line, for a header or a slide. - - One line rather than stacked: a two-line wordmark beside a single mark - reads off-balance however it is aligned, which is the exact defect the - sibling benchmark repository's header had. - """ + """Place the mark and a single-line wordmark together for headers and slides.""" margin, mark_size, gap, size = 20, 96, 24, 46 text_x = margin + mark_size + gap # Monospace: every glyph advances the same width, so the wordmark's extent @@ -254,10 +242,7 @@ def social_preview() -> str: """ w, h = 1280, 640 out = _open(w, h, f"{WORDMARK}: {TAGLINE}") - # The brand hero treatment, section 7 of the guidelines: teal and purple - # radials with a particle network over near-black. Same gradient stops and - # the same field as the sibling benchmark card, so the two read as one - # family rather than two projects that both happen to be dark. + # Teal and purple radial gradients sit behind a deterministic particle field. out.append( ' ' '' @@ -274,19 +259,11 @@ def social_preview() -> str: out.append(f' ') out += particle_field(w, h) - # No accent rule across the top. The sibling benchmark card has none, and on - # a card that bleeds to the edge it reads as a stray browser chrome line - # rather than as brand. + # Keep the card edge clear of a horizontal accent line. out.append(placed_mark(112, 188, 264)) - # Scale, not weight. This and the lockup have always used the same font at - # 700; the lockup simply gave its wordmark a third of the frame height while - # the card gave it a tenth, so the lockup read as the bolder of the two. At - # 86 the name carries the card the way it carries the lockup. - # - # Accent lands on the word that distinguishes THIS project, which is the - # rule the sibling repositories follow: "Agent Egress Bench", "Pipelock Rules". + # Use the lockup's font weight and emphasize Rules with the accent color. out.append(f' ' f'{WORDMARK_LEAD}' @@ -482,7 +459,7 @@ def brand_problems() -> list: if not (workflows / referenced).is_file(): problems.append(f"README: badges {referenced}, which is not in .github/workflows/") - # The family footer is a contract with the sibling card, not decoration. + # Check that the social card retains its attribution footer and position. card = social_preview() if CARD_FOOTER not in card: problems.append("social-preview: missing the family footer line") @@ -572,16 +549,10 @@ def _write_ico(pngs: list[Path], target: Path) -> None: def render_rasters() -> int: - """Export every raster from its vector and record where it came from. - - The size map lives in PNG_EXPORTS and nowhere else. It used to be repeated - as literal inkscape lines in the Makefile, which meant adding a size in one - place and silently not exporting it from the other. + """Export the sizes in PNG_EXPORTS and record each raster's source digest. - Both renderers are resolved before anything is written. Finding ImageMagick - missing only at the bundling step would leave every PNG already overwritten - and no icon bundle beside them, which is a worse state to land in than - refusing at the start. + Resolve Inkscape and ImageMagick before writing to avoid partial exports + when a required renderer is unavailable. """ _require_tool("inkscape", "export rasters") _require_tool("magick", "build the icon bundle", alternative="convert") diff --git a/scripts/render_diagrams.py b/scripts/render_diagrams.py index 9509628..a74ec4c 100755 --- a/scripts/render_diagrams.py +++ b/scripts/render_diagrams.py @@ -46,13 +46,9 @@ def discover_bundles() -> tuple: - """Every published bundle, found on disk rather than listed here. + """Discover published bundles so new bundles reach diagrams and the catalog. - A hardcoded pair is the same defect as a hardcoded rule count: it reads as - a fact and is really a snapshot, and it quietly tells a reader the - repository will only ever hold two. A third bundle now gets a catalog - section and a coverage panel with nobody remembering to edit this file, and - ``verify_against_corpus`` names the other places that must learn about it. + verify_against_corpus checks that the validation gates cover the same set. """ if not PUBLISHED_DIR.is_dir(): _fail("published/ does not exist; there is nothing to describe") @@ -74,7 +70,7 @@ def discover_bundles() -> tuple: MONO = "'JetBrains Mono', 'JetBrainsMono Nerd Font', 'Fira Code', ui-monospace, SFMono-Regular, Menlo, monospace" SANS = "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" -# Locked brand tokens (pipelab.org/.brand/colors_and_type.css). +# Diagram colors; shared colors match scripts/render_brand.py. BRAND = { "accent": "#00e5a0", "purple": "#7c3aed", @@ -920,14 +916,10 @@ def trust(p) -> str: # -------------------------------------------------------------------------- # The rule catalog. # -# The README used to list covered providers in a hand-written table, which -# answered the question a reader actually arrives with -- does this cover my -# stack -- and went stale the moment a rule landed. This regenerates the same -# answer from the compiled bundles, so it cannot drift, and check-diagrams -# fails when the committed copy falls behind. -# -# Names, severities and citations only. A rule's pattern never appears here for -# the same reason it never appears in a diagram. +# Generate the catalog from compiled bundles so names, severities and citations +# have the same source as the diagrams. check-diagrams rejects stale output. +# Patterns are omitted because the repository's content scan can detect them +# as the attacks they describe. # -------------------------------------------------------------------------- TYPE_TITLES = { @@ -958,8 +950,8 @@ def rule_catalog() -> str: "`scripts/render_diagrams.py`. Do not edit this file by hand: run `make diagrams`.", "", "Stable rules are enabled by default and carry a primary source plus fixtures in", - "both directions. Experimental rules carry true-positive fixtures only and stay off", - "until you set `rules.include_experimental: true`.", + "both directions. Experimental rules need true-positive fixtures, may also have", + "false-positive ones, and stay off until you set `rules.include_experimental: true`.", "", ] for bundle in BUNDLES: @@ -1091,10 +1083,8 @@ def verify_against_corpus() -> list: problems.append(f"pipeline diagram: stage {stage!r} credits the {gate!r} check, " "which ci.yaml no longer reports") - # The install section used to say "either official bundle", which quietly - # told a reader the repository would only ever hold two. It now lists them, - # and this checks the list both ways: a published bundle nobody can find - # instructions for, and instructions for a bundle that is not published. + # Check both directions: every published bundle needs install instructions, + # and documented install names must refer to published bundles. listed = set(re.findall(r"^pipelock rules install ([a-z0-9][a-z0-9-]*)\s*$", README.read_text(encoding="utf-8"), re.M)) for bundle in BUNDLES: diff --git a/scripts/render_diagrams_test.py b/scripts/render_diagrams_test.py index 02776b1..b67e129 100644 --- a/scripts/render_diagrams_test.py +++ b/scripts/render_diagrams_test.py @@ -154,9 +154,7 @@ def test_every_explicit_asset_color_is_a_brand_token_or_light_adaptation(self): for path, content in generator.svg_assets().items(): with self.subTest(asset=path.name): colors = set(re.findall(r"#[0-9a-f]{6}\b", content.lower())) - # Without this the regex could match nothing and the subset - # check below would pass while proving nothing, which is how - # the same gate shipped vacuous on a sibling repository. + # Require at least one color match so the subset check is meaningful. self.assertTrue(colors, f"{path.name}: the color scan matched nothing") self.assertTrue(colors <= approved, colors - approved) @@ -218,11 +216,8 @@ def test_no_generated_asset_contains_any_rule_pattern(self): self.assertNotIn(pattern, content) def test_no_asset_emits_a_long_run_of_digits(self): - # Binary floating point printed a card width of 209.6 as the coordinate - # 948.4000000000001. Sixteen digits in a row inside a path matched this - # repository's own Credit Card Number DLP rule, so the diagram failed - # the Pipelock scan on its own pull request. Coordinates are rounded at - # the source; this holds the whole asset to it. + # Long floating-point tails can resemble credential data to content scans. + # Check emitted coordinates as well as the rounding helper. seen = 0 for path, content in generator.svg_assets().items(): for token in re.findall(r"-?\d+\.\d+", content): @@ -512,10 +507,8 @@ def test_the_makefile_preflight_loop_covers_every_published_bundle(self): self.assertTrue(set(generator.BUNDLES) <= generator.makefile_preflight_bundles()) def test_a_readme_that_stops_linking_the_catalog_is_reported(self): - # Written for the purpose rather than borrowed from the repository. An - # earlier version swapped in CONTRIBUTING.md, which then gained a link - # to the catalog, and the test stopped exercising the missing-link case - # without anything failing to say so. + # Use a dedicated document with no catalog link so unrelated docs can't + # accidentally satisfy the missing-link test. with tempfile.TemporaryDirectory() as directory: readme = Path(directory) / "README.md" readme.write_text("A README that links no catalog.\n", encoding="utf-8") @@ -579,9 +572,7 @@ def test_a_bar_width_is_proportional_to_its_count(self): self.assertAlmostEqual(wide / narrow, big / small, delta=0.01) def test_the_coverage_chart_absorbs_a_third_bundle(self): - # The repository has held exactly two bundles for its whole life, which - # is how a fixed two-panel layout survives review looking correct. A - # third has to land in a new row without clipping or overlapping. + # A third bundle must occupy a new row without clipping or overlap. extra = "future-bundle" matrices = {b: generator.bundle_matrix(b) for b in generator.BUNDLES} matrices[extra] = {t: {"stable": 2, "experimental": 1} for t in generator.RULE_TYPES} @@ -642,8 +633,7 @@ def test_the_trust_chain_shows_the_real_key_digest(self): self.assertIn(generator.official_key_digest()[:16], text) def test_pipeline_body_lines_fit_inside_their_card(self): - # Mono advances at about 0.6em, so a longer line runs past the card - # edge and into the next stage's arrow. This is how that shipped once. + # Monospace glyphs advance about 0.6em; limit body lines to the card width. for _, _, _, lines in generator.pipeline_stages(): for line in lines: with self.subTest(line=line): @@ -698,8 +688,7 @@ def test_the_readme_embeds_both_themes_of_every_diagram(self): self.assertIn(f"assets/diagram-{name}-light.svg", self.readme) def test_the_readme_uses_the_brand_casing(self): - # PipeLab is the company and Pipelock is the product; the design system - # calls the casing non-negotiable and the live site follows it. + # Public names use PipeLab for the company and Pipelock for the product. self.assertNotRegex(self.readme, r"\bPipelab\b") self.assertNotRegex(self.readme, r"\bPipeLock\b") self.assertNotRegex(self.readme, r"\bpipeLock\b") From 6ae489062ac814ef01d4f99c7bf7744ea74938d8 Mon Sep 17 00:00:00 2001 From: luckyPipewrench Date: Wed, 4 Nov 2026 20:40:44 -0500 Subject: [PATCH 2/3] docs: correct contributor guide review findings Restore the information-disclosure and other-abuse advisory scope in SECURITY.md, list the README install line a new bundle needs, state the CI candidate as a build reporting the tested version, and remove remaining sibling-project and history narration from the asset generators. --- CONTRIBUTING.md | 4 ++-- README.md | 2 +- SECURITY.md | 2 +- scripts/render_brand.py | 22 ++++++++-------------- scripts/render_diagrams.py | 2 +- scripts/render_diagrams_test.py | 15 ++++++--------- 6 files changed, 19 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index de6e6d0..1ad80f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,7 +50,7 @@ Changing brand assets also needs Inkscape and ImageMagick (`magick` or `convert` Open an issue first so naming, scope, signing-key alignment, and maintenance ownership can be confirmed before code is added. New bundles must use `format_version: 2`, which requires Pipelock v2.2.0 or later. The existing `pipelock-community` and `healthcare-phi-pii` bundles remain on `format_version: 1` until their bundle content, signatures, served copies, and compatibility checks can migrate together. -A new bundle needs compiler, validation and CI integration as well as rule files. Add a bundle-specific case and header emission in `scripts/compile.sh` that produces the complete format-2 header shown below. `make compile` overwrites the selected `published//bundle.yaml`; it doesn't preserve a hand-edited header. Add the bundle to `PREFLIGHT_BUNDLES` in `Makefile`, the compatibility-floor and YAML-lint matrices in `.github/workflows/ci.yaml`, and the installer cases in `scripts/test-compatibility-install.sh`. Add its byte-bound entry and a format-2 reader-schema identity with a pinned schema digest to `compatibility/contract.yaml`. Extend compatibility tests for that identity. Compile the bundle, run fixture and schema checks, regenerate diagrams and the catalog, and run preflight. Maintainers sign the resulting published bundle on the PR before merge. +A new bundle needs compiler, validation and CI integration as well as rule files. Add a bundle-specific case and header emission in `scripts/compile.sh` that produces the complete format-2 header shown below. `make compile` overwrites the selected `published//bundle.yaml`; it doesn't preserve a hand-edited header. Add the bundle to `PREFLIGHT_BUNDLES` in `Makefile`, the compatibility-floor and YAML-lint matrices in `.github/workflows/ci.yaml`, and the installer cases in `scripts/test-compatibility-install.sh`. List its `pipelock rules install ` command in the README install section, because `make check-diagrams` rejects a published bundle with no install instructions. Add its byte-bound entry and a format-2 reader-schema identity with a pinned schema digest to `compatibility/contract.yaml`. Extend compatibility tests for that identity. Compile the bundle, run fixture and schema checks, regenerate diagrams and the catalog, and run preflight. Maintainers sign the resulting published bundle on the PR before merge. The existing validation target installs an unsigned copy under a temporary name. Format-2 bundles need signed validation that preserves their identity, so that path also needs integration before a new bundle can pass preflight. @@ -132,7 +132,7 @@ Use this indentation in source rule files: two spaces before `- id:`, four befor - Use RE2 syntax (no lookahead/lookbehind, no backreferences) - Prefer specific prefixes over broad character classes (`pplx-[A-Za-z0-9]{16,}` is better than `[a-z]{4}-[A-Za-z0-9]+`) - Set minimum match lengths to reduce false positives -- Test against real-world text, not just isolated tokens +- Test against realistic surrounding text, not just isolated tokens - Case-insensitive matching is applied automatically by pipelock (`(?i)` prefix) - Keep regexes readable: prefer `[A-Za-z0-9]` over `\w`. - Put one rule in each YAML file. diff --git a/README.md b/README.md index abaf61c..d49a284 100644 --- a/README.md +++ b/README.md @@ -162,7 +162,7 @@ See the [full bundle authoring guide](https://github.com/pipelab-org/pipelock/bl ## Compatibility contract -CI tests each maintained bundle at its declared `min_pipelock` and at the `tested_through_pipelock` version recorded in `compatibility/contract.yaml`. The matrix doesn't individually test every version between those endpoints. A newer Pipelock version is outside this repository's recorded tested range. The compatibility contract records that range; it doesn't establish whether the running Pipelock version emits a warning about it. +CI tests each maintained bundle with the declared `min_pipelock` release and with a Pipelock build that reports the `tested_through_pipelock` version recorded in `compatibility/contract.yaml`. The matrix doesn't individually test every version between those endpoints. A newer Pipelock version is outside this repository's recorded tested range. The compatibility contract records that range; it doesn't establish whether the running Pipelock version emits a warning about it. The contract binds each published bundle's name, CalVer, minimum version, and `format_version` to a SHA-256-pinned reader-schema identity. The two bundles named in the contract add detections. They don't carry per-rule allow or block actions, and they can't replace built-in patterns. Format 1 has no monotonic rollback counter. The installer refuses a same-version digest change. diff --git a/SECURITY.md b/SECURITY.md index 0c8f524..3a75d6e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,7 @@ ## Reporting a vulnerability -Report exploitable detection bypasses, resource-exhaustion behavior, signature-verification bypasses and rule-distribution supply-chain attacks through [Pipelock Security Advisories](https://github.com/pipelab-org/pipelock/security/advisories/new). Reports with security impact belong there before public disclosure, including false negatives that enable an exploitable bypass. +Report exploitable detection bypasses, resource-exhaustion behavior, signature-verification bypasses, rule-distribution supply-chain attacks, rules whose matches cause information disclosure and other abuse of a rule or bundle through [Pipelock Security Advisories](https://github.com/pipelab-org/pipelock/security/advisories/new). Reports with security impact belong there before public disclosure, including false negatives that enable an exploitable bypass. Ordinary false positives, non-exploitable detection gaps and rule-quality suggestions can use the public issue templates. If you're unsure whether a report exposes a vulnerability, start with a private advisory. diff --git a/scripts/render_brand.py b/scripts/render_brand.py index b0ec363..e0ab6a0 100644 --- a/scripts/render_brand.py +++ b/scripts/render_brand.py @@ -197,14 +197,13 @@ def lockup() -> str: out = _open(w, h, f"{WORDMARK} logo lockup") out.append(placed_mark(margin, 10, mark_size)) # Two-tone wordmark. The accent lands on the word that distinguishes - # this project from its parent, matching 'Agent Egress Bench' next door. + # this project from Pipelock itself. out.append(f' ' f'{WORDMARK_LEAD}' f'{WORDMARK_ACCENT}') # No tagline. A lockup is a mark and a wordmark; a page that uses it as a - # header states the tagline in text directly beneath, and a lockup carrying - # its own copy made the header say it twice. + # header states the tagline in text directly beneath, so the lockup omits it. out.append("") return "\n".join(out) + "\n" @@ -217,10 +216,7 @@ def lockup_stacked() -> str: cannot go -- an avatar, an app icon, a centred hero -- where a horizontal lockup has to shrink until the wordmark is unreadable. - The rule against stacking still holds where it was aimed: it forbids - breaking the WORDMARK across two lines beside a mark. Here the wordmark - stays on one line and the mark sits above it, which is the form Pipelock's - own logo already takes. + The wordmark stays on one line; only the mark moves above it. """ w, h = 420, 252 out = _open(w, h, f"{WORDMARK} stacked logo") @@ -296,11 +292,9 @@ def social_preview() -> str: # Rasters exported from the vectors above by `make brand`. # -# Every size a consumer has asked for is listed here rather than exported by -# hand into whatever tool needed it. A hand export is how a logo ends up as a -# mark stranded in the corner of a canvas: it looks fine in the exporter and -# renders as a blank square everywhere else, and nothing catches it because the -# file exists and has plausible bytes. +# Every raster size is listed here and exported from the vectors, so a size +# can't exist without a recorded source. A hand export can look correct in one +# tool and render blank elsewhere, and a file check can't tell the difference. ICON_SIZES = (16, 32, 48, 64, 128, 256, 512, 1024) ICO_SIZES = (16, 32, 48, 64, 128, 256) ICO_NAME = "icons/pipelock-rules.ico" @@ -462,10 +456,10 @@ def brand_problems() -> list: # Check that the social card retains its attribution footer and position. card = social_preview() if CARD_FOOTER not in card: - problems.append("social-preview: missing the family footer line") + problems.append("social-preview: missing the attribution footer line") if f'x="{CARD_FOOTER_X}"' not in card or f'y="{CARD_FOOTER_Y}"' not in card: problems.append( - f"social-preview: family footer is not at {CARD_FOOTER_X},{CARD_FOOTER_Y}" + f"social-preview: attribution footer is not at {CARD_FOOTER_X},{CARD_FOOTER_Y}" ) return problems diff --git a/scripts/render_diagrams.py b/scripts/render_diagrams.py index a74ec4c..8795482 100755 --- a/scripts/render_diagrams.py +++ b/scripts/render_diagrams.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Render every README asset from one source, on the PipeLab design system. +"""Render every README diagram from one source. The README embeds each diagram twice, through a ```` element that picks a variant from the reader's color scheme. Two hand-maintained copies of diff --git a/scripts/render_diagrams_test.py b/scripts/render_diagrams_test.py index b67e129..9c29d28 100644 --- a/scripts/render_diagrams_test.py +++ b/scripts/render_diagrams_test.py @@ -172,11 +172,9 @@ class PatternSecrecyTest(unittest.TestCase): def _every_regex(self) -> list: """Every rule pattern in the corpus, read by the production generator. - The previous version searched the source text for `regex: \'...\'` at a - fixed indent. That matches how every rule happens to be written today, - which is exactly why it was risky: a double-quoted or block-scalar - pattern would be skipped silently and the check would go partial without - reporting anything. Parsing sees a pattern however it is quoted. + Parsing sees a pattern however it is quoted. Searching source text at a + fixed indent would skip a double-quoted or block-scalar pattern without + reporting anything. """ return [(rule["id"], generator.regex_of(rule)) for bundle in generator.BUNDLES @@ -429,9 +427,8 @@ def test_a_readme_that_pins_two_digests_pins_neither(self): """Two digests leave a reader unable to tell which belongs to the key. The fixture writes both digests out rather than pointing at a file that - happens to contain some. An earlier version swapped in this test module - on the assumption it held two, and it holds none, so the test passed by - exercising the no-digest branch instead of the one it is named for. + happens to contain some, so the test reaches the two-digest branch + instead of the no-digest branch. """ first, second = "a" * 64, "b" * 64 with tempfile.TemporaryDirectory() as directory: @@ -450,7 +447,7 @@ def test_a_readme_that_pins_exactly_one_digest_returns_it(self): self.assertEqual(generator.readme_key_digest(), only) def test_a_readme_with_no_digest_pins_nothing(self): - """And the zero case, which is what the two-digest test used to cover.""" + """And the zero case, so the no-digest branch has its own test.""" with tempfile.TemporaryDirectory() as directory: readme = Path(directory) / "README.md" readme.write_text("no digest here\n", encoding="utf-8") From 4f1366b0e9f5118acbf6b36112dfa849986f9ad7 Mon Sep 17 00:00:00 2001 From: luckyPipewrench Date: Wed, 4 Nov 2026 20:42:40 -0500 Subject: [PATCH 3/3] docs: clarify compatibility check rationale --- Makefile | 7 +++---- scripts/render_brand.py | 4 ++-- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 9c0be77..43cc356 100644 --- a/Makefile +++ b/Makefile @@ -47,10 +47,9 @@ check-diagrams: @PYTHONDONTWRITEBYTECODE=1 python3 -m unittest scripts/render_diagrams_test.py @python3 scripts/render_diagrams.py --check -# The compatibility contract is separate from the signed v1 bundle bytes: v1 -# rejects a max_pipelock field, while current Pipelock has no runtime warning -# surface for a tested ceiling. Validate the bound format identity, then prove -# the installed reader accepts the declared shape and rejects incompatible ones. +# The compatibility contract is separate from the signed v1 bundle bytes, +# which reject a max_pipelock field. Validate the bound format identity, then +# prove the installed reader accepts the shape and rejects incompatible ones. check-compatibility: require-pipelock @PYTHONDONTWRITEBYTECODE=1 python3 -m unittest scripts/test-compatibility-contract.py @python3 scripts/check-compatibility-contract.py diff --git a/scripts/render_brand.py b/scripts/render_brand.py index e0ab6a0..f695dac 100644 --- a/scripts/render_brand.py +++ b/scripts/render_brand.py @@ -456,10 +456,10 @@ def brand_problems() -> list: # Check that the social card retains its attribution footer and position. card = social_preview() if CARD_FOOTER not in card: - problems.append("social-preview: missing the attribution footer line") + problems.append("social-preview: missing the family footer line") if f'x="{CARD_FOOTER_X}"' not in card or f'y="{CARD_FOOTER_Y}"' not in card: problems.append( - f"social-preview: attribution footer is not at {CARD_FOOTER_X},{CARD_FOOTER_Y}" + f"social-preview: family footer is not at {CARD_FOOTER_X},{CARD_FOOTER_Y}" ) return problems