feat: add plugin schema by fzipi · Pull Request #37 · coreruleset/plugin-registry

fzipi · 2026-04-13T12:30:37Z

what

add plugin schema for discovery and configuration

why

enhance plugin onboarding experience

Signed-off-by: Felipe Zipitria <felipe.zipitria@owasp.org>

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 · 2026-04-13T12:47:26Z

@copilot apply changes based on the comments in this thread

Agent-Logs-Url: https://github.com/coreruleset/plugin-registry/sessions/e5bb0215-3e42-4fc3-9912-84b7af7f99c7 Co-authored-by: fzipi <3012076+fzipi@users.noreply.github.com>

Copilot · 2026-04-13T12:51:33Z

@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

Version is derived from GitHub release tags at query time. Embedding it in plugin.yaml would inevitably drift as developers forget to update it. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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.

Co-authored-by: Max Leske <250711+theseion@users.noreply.github.com>

- Remove `files` section from schema, docs, template, and examples. File paths follow the CRS naming convention and can be derived by tooling from the plugin name. - Clarify `engines` field in docs as an enum (matching `category` wording), since the schema already restricts values. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

theseion · 2026-04-20T05:19:21Z

+| Field         | Description |
+|---------------|-------------|
+| `crs_version` | Version constraint string (e.g., `>=4.0.0`). |
+| `engines`     | List of compatible WAF engines, each one of: `modsecurity2`, `modsecurity3`, or `coraza`. |


Suggested change

| `engines` | List of compatible WAF engines, each one of: `modsecurity2`, `modsecurity3`, or `coraza`. |

| `engines` | List of compatible WAF engines, one of: `modsecurity2`, `modsecurity3`, `coraza`, `all`. |

theseion · 2026-04-20T05:21:18Z

+| `crs_version` | Version constraint string (e.g., `>=4.0.0`). |
+| `engines`     | List of compatible WAF engines, each one of: `modsecurity2`, `modsecurity3`, or `coraza`. |
+
+When omitted, no compatibility constraints are assumed. Tooling should treat missing engines as "compatible with all".


Suggested change

When omitted, no compatibility constraints are assumed. Tooling should treat missing engines as "compatible with all".

When omitted, no compatibility constraints are assumed. Tooling should treat missing `engines` field as if `engines` were set tp `all`.

theseion · 2026-04-20T05:21:49Z

+| `separator`           | no       | String used to separate multiple entries when type is `list`. |
+| `prefix`                 | no       | String marking the beginning of a list entry when type is `list`. |
+| `suffix`                 | no       | String marking the end of a list entry when type is `list`. |


Fix table formatting.

theseion · 2026-04-20T05:23:09Z

+
+The rule ID range is a registry-level concern (namespace coordination), not a plugin identity attribute. Keeping it separate makes it clear that this range is allocated by the registry and should not be changed unilaterally.
+
+### Category taxonomy


Add a similar section for engines.

theseion · 2026-04-20T05:24:54Z

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

feat: add plugin schema

25def86

Signed-off-by: Felipe Zipitria <felipe.zipitria@owasp.org>

fzipi requested a review from Copilot April 13, 2026 12:30

Copilot started reviewing on behalf of fzipi April 13, 2026 12:31 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

Copilot started work on behalf of fzipi April 13, 2026 12:47 View session

fix: address schema review comments - constraints, types, and naming

bc82781

Agent-Logs-Url: https://github.com/coreruleset/plugin-registry/sessions/e5bb0215-3e42-4fc3-9912-84b7af7f99c7 Co-authored-by: fzipi <3012076+fzipi@users.noreply.github.com>

Copilot finished work on behalf of fzipi April 13, 2026 12:54

fzipi requested a review from theseion April 13, 2026 21:44

feat: remove version field from plugin schema

e9ba83f

Version is derived from GitHub release tags at query time. Embedding it in plugin.yaml would inevitably drift as developers forget to update it. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

theseion requested changes Apr 19, 2026

View reviewed changes

fzipi and others added 2 commits April 19, 2026 20:46

Apply suggestions from code review

83f5046

Co-authored-by: Max Leske <250711+theseion@users.noreply.github.com>

theseion requested changes Apr 20, 2026

View reviewed changes

	\| `engines` \| List of compatible WAF engines, each one of: `modsecurity2`, `modsecurity3`, or `coraza`. \|
	\| `engines` \| List of compatible WAF engines, one of: `modsecurity2`, `modsecurity3`, `coraza`, `all`. \|

	When omitted, no compatibility constraints are assumed. Tooling should treat missing engines as "compatible with all".
	When omitted, no compatibility constraints are assumed. Tooling should treat missing `engines` field as if `engines` were set tp `all`.


		The rule ID range is a registry-level concern (namespace coordination), not a plugin identity attribute. Keeping it separate makes it clear that this range is allocated by the registry and should not be changed unilaterally.

		### Category taxonomy

Conversation

fzipi commented Apr 13, 2026

what

why

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fzipi commented Apr 13, 2026

Uh oh!

Copilot AI commented Apr 13, 2026

Uh oh!

theseion left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

theseion Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

theseion Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

theseion Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

theseion Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

theseion commented Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants