Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/new_rule.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 4 additions & 3 deletions .github/ISSUE_TEMPLATE/security_bypass.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**
Expand All @@ -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
Expand Down
11 changes: 8 additions & 3 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,19 @@ Brief description of what this PR adds or changes.
## Testing

- [ ] `BUNDLE_NAME=<bundle-name> make compile` succeeds
- [ ] `BUNDLE_NAME=<bundle-name> make test-fixtures` passes (all true/false positive fixtures)
- [ ] `BUNDLE_NAME=<bundle-name> make validate` passes (pipelock accepts the bundle)
- [ ] Maintainer signing completed if this changes `published/<bundle>/bundle.yaml`
- [ ] `BUNDLE_NAME=<bundle-name> make test-fixtures` passes
- [ ] `BUNDLE_NAME=<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>/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}`)
8 changes: 3 additions & 5 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -100,18 +100,16 @@ 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]
if: always()
runs-on: ubuntu-latest
timeout-minutes: 1
steps:
- name: Confirm matrix passed
- name: Confirm preflight passed
run: test "${{ needs.validate.result }}" = "success"

published-signatures:
Expand Down
7 changes: 2 additions & 5 deletions .github/workflows/pipelock.yaml
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
6 changes: 2 additions & 4 deletions .github/workflows/release.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 3 additions & 18 deletions .github/workflows/scorecard.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
155 changes: 59 additions & 96 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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=<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/<bundle>/<type>/ One YAML source file per rule
fixtures/<bundle>/<type>/ True-positive and false-positive examples
published/<bundle>/ 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 `<rule-id>-true-positive.txt` and `<rule-id>-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>/bundle.yaml` files are current with `rules/<bundle>/` 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.
Loading
Loading