feat: add plugin schema

[fzipi]

what

• add plugin schema for discovery and configuration

why

• enhance plugin onboarding experience

[Copilot]

Pull request overview

Adds a JSON Schema and accompanying documentation/examples to standardize CRS plugin discovery and configuration via a plugin.yaml descriptor.

Changes:

• Introduce plugin-schema.json (JSON Schema draft 2020-12) for validating plugin descriptors.
• Add documentation describing the schema fields and intended usage (docs/plugin-descriptor-schema.md).
• Provide example plugin descriptors under examples/ for reference and onboarding.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
plugin-schema.json	Defines the structure/constraints for plugin.yaml plugin descriptors.
docs/plugin-descriptor-schema.md	Documents the schema fields, intent, and rollout plan.
examples/wordpress-rule-exclusions-plugin.yaml	Example descriptor for a rule-exclusion plugin.
examples/fake-bot-plugin.yaml	Example descriptor for a detection plugin with multiple variables.
examples/body-decompress-plugin.yaml	Example descriptor for a utility plugin with numeric bounds.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fzipi]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Applied all changes from the review in commit bc82781:

• configuration.variables: added minItems: 1 to prevent empty variable lists
• default/example type validation: added if/then conditionals for all four types — boolean values must be integer 0 or 1; integer values must be integers; string and enum values must be strings
• allowed_values: added items: {type: string} and a conditional requiring it when type is "enum", and forbidding it for non-enum types
• min/max: changed from type: number to type: integer and added a conditional that forbids them on non-integer variable types
• Example fix: renamed tx.body-decompress-plugin_enable → tx.body-decompress-plugin_enabled to match the documented convention
• Docs: updated the boolean type description to clarify values are integers (0/1) following the ModSecurity convention

[theseion]

The registry will also need to have a new way to register plugins, i.e., a YAML file that contains an entry for each GitHub repository. That means that at least the repository URL in the schema is an unnecessary duplicate.

We should make it clear that we currently only support GitHub repositories.

[theseion]

Do you agree with what I wrote here? Is I wrote there, we should also make it clear that we only support GitHub atm.

[fzipi]

I agree on allowing only github repos for now.

[fzipi]

@copilot fix all table formatting and add a similar section for the engines category taxonomy.

[Copilot]

@copilot fix all table formatting and add a similar section for the engines category taxonomy.

Done in commit eae1216:

• Fixed table alignment for separator, prefix, and suffix rows in the variable definition table
• Added an "Engine taxonomy" section under Design Decisions (parallel to the existing "Category taxonomy" section) listing all four supported values (modsecurity2, modsecurity3, coraza, all) with descriptions

Do you agree with what I wrote here? Is I wrote there, we should also make it clear that we only support GitHub a...

Agreed — the repository URL in plugin.yaml can be used as the lookup key until a separate registry YAML exists. For now, in commit eae1216 the repository field in the schema has been restricted to a GitHub owner/repo URL pattern (^https://github\.com/[^/]+/[^/]+/?$), and the docs field description has been updated to note that only GitHub repositories are currently supported.

[fzipi]

Addressed the open review comments in the latest commit:

Schema changes (plugin-schema.json):

• Added list to the variable type enum
• Added separator, prefix, suffix properties to the variable schema
• separator is now required when type is list; separator/prefix/suffix are forbidden for non-list types
• Added all to the engines enum so the schema matches the documented behavior

Docs changes (docs/plugin-descriptor-schema.md):

• Updated allowed_values required column to yes (for "enum") — matches schema conditional
• Updated separator required column to yes (for "list") — matches schema conditional
• Clarified prefix/suffix descriptions: "prepended/appended to each list item"
• Clarified variables field description: "YAML sequence of transaction variable definitions"
• Fixed "four types" → "five types" to account for list

Still open (active discussion, no consensus yet):

• Whether email should be required for authors
• Format/meaning of keywords

[fzipi]

Pushed f654fcb, which closes out the remaining review items.

New indexed variable type (@azurit's open thread) — for the numbered sibling variables that Lua plugins read until one is unset, e.g. tx.false-positive-report-plugin_smtp_cc_1 through _5. name carries the base name, max_index the bound. Details and the open question about whether the bound is always fixed are in the thread.

all is now exclusive in compatibility.engines — the enum kept all as @theseion suggested, but ["all", "coraza"] used to validate and contradict itself. It is now constrained to be the only entry when present.

Schema validation in CI — the repo had no workflows, so nothing checked the schema, the examples, or the template. .github/workflows/validate-descriptors.yml runs check-jsonschema over examples/*.yaml, plugin.yaml.template, and tests/valid/, then asserts every fixture in tests/invalid/ is rejected. The three invalid fixtures cover the new rules and I confirmed each fails for its intended reason, not incidentally. Authors can run the same check locally with uvx check-jsonschema --schemafile plugin-schema.json plugin.yaml.

Docs — the descriptor must be named plugin.yaml at the repository root, since tooling locates it by appending that path to the repository URL; keywords is spelled out as a YAML list of lowercase tags (@azurit asked about the format and the answer never made it into the file); the template gained commented list and indexed examples.

@theseion @azurit ready for another look.