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: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.

fzipi · 2026-04-30T19:49:59Z

I agree on allowing only github repos for now.

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

fzipi · 2026-04-30T19:52:37Z

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

…itHub URLs Agent-Logs-Url: https://github.com/coreruleset/plugin-registry/sessions/f07c5958-bb5c-4998-af8b-8560d60ed8e7 Co-authored-by: fzipi <3012076+fzipi@users.noreply.github.com>

Copilot · 2026-04-30T19:55:25Z

@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.

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

azurit · 2026-06-03T11:39:58Z

+| `category`         | no       | Functional category: `rule-exclusion`, `detection`, `protection`, `utility`, `logging`, or `performance`. |
+| `status`           | yes      | Maturity level: `tested`, `being-tested`, `untested`, or `draft`. |
+| `license`          | yes      | SPDX license identifier (e.g., `Apache-2.0`, `GPL-2.0-only`). |
+| `authors`          | yes      | List of author objects with `name` (required), `email` and `url` (optional). |


Hmmm, this might be problematic if authors don't want to have a public way of contacting them, as spam might get into their inboxes, and/or other problems. Do we want to require it?

azurit · 2026-06-03T11:40:37Z

+| `authors`          | yes      | List of author objects with `name` (required), `email` and `url` (optional). |
+| `repository`       | yes      | URL of the plugin GitHub repository (only GitHub repositories are currently supported). |
+| `homepage`         | no       | URL to documentation or project site. |
+| `keywords`         | no       | Tags for discovery and categorization. |


In what format?

What do you mean? String? List?

azurit · 2026-06-03T11:44:45Z

+| Field       | Description |
+|-------------|-------------|
+| `file`      | Path to the `-config.conf` file relative to the plugin root. |
+| `variables` | List of transaction variable definitions (see below). |


In what format?

- Add `list` to variable type enum in schema and docs - Add `separator`, `prefix`, `suffix` properties to variable schema - Require `separator` when type is `list`; forbid separator/prefix/suffix for non-list types - Add `all` to engines enum (schema now matches docs) - Update docs: required column for `allowed_values` (enum) and `separator` (list) - Clarify `prefix`/`suffix` descriptions (prepended/appended per item) - Clarify `variables` field description with YAML sequence note - Fix "four types" → "five types" to include `list` Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fzipi · 2026-06-03T12:13:10Z

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

azurit · 2026-06-03T12:14:28Z

+
+#### Variable Types
+
+The four types cover all patterns found across existing CRS plugins:


I'm using another type of variables in few of 'my' plugins - it's some kind of an array, used in Lua plugins. For example:

tx.false-positive-report-plugin_smtp_cc_1=first@example.com tx.false-positive-report-plugin_smtp_cc_2=second@example.com tx.false-positive-report-plugin_smtp_cc_3=third@example.com

Can you point me to the code to take a look?

azurit · 2026-06-03T12:15:56Z

+| `allowed_values` | no       | List of valid values when type is `enum`. |
+| `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`. |


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

Comment thread docs/plugin-descriptor-schema.md Outdated

Comment thread docs/plugin-descriptor-schema.md Outdated

Comment thread docs/plugin-descriptor-schema.md Outdated

Comment thread docs/plugin-descriptor-schema.md

Apply suggestions from code review

b96f392

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

Copilot started work on behalf of fzipi April 30, 2026 19:52 View session

fix: table formatting, add engines taxonomy, restrict repository to G…

eae1216

…itHub URLs Agent-Logs-Url: https://github.com/coreruleset/plugin-registry/sessions/f07c5958-bb5c-4998-af8b-8560d60ed8e7 Co-authored-by: fzipi <3012076+fzipi@users.noreply.github.com>

Copilot finished work on behalf of fzipi April 30, 2026 19:56

theseion requested changes May 1, 2026

View reviewed changes

Comment thread docs/plugin-descriptor-schema.md Outdated

Update docs/plugin-descriptor-schema.md

7cedec4

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

fzipi requested a review from theseion May 25, 2026 11:26

azurit reviewed Jun 3, 2026

View reviewed changes

Comment thread docs/plugin-descriptor-schema.md Outdated

azurit reviewed Jun 3, 2026

View reviewed changes

Comment thread docs/plugin-descriptor-schema.md Outdated

azurit reviewed Jun 3, 2026

View reviewed changes

Comment thread docs/plugin-descriptor-schema.md Outdated

azurit reviewed Jun 3, 2026

View reviewed changes

	\| `authors` \| yes \| List of author objects with `name` (required), `email` and `url` (optional). \|
	\| `authors` \| yes \| List of author objects with `name` (required), `email` (required) and `url` (optional). \|


		#### Variable Types

		The four types cover all patterns found across existing CRS plugins:

	\| `suffix` \| no \| String marking the end of a list entry when type is `list`. \|
	\| `suffix` \| no \| String marking the end of a list entry when type is `list` (see below). \|

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

theseion commented Apr 20, 2026

Uh oh!

fzipi commented Apr 30, 2026

Uh oh!

fzipi commented Apr 30, 2026

Uh oh!

Copilot AI commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fzipi commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Copilot AI commented Apr 30, 2026 •

edited

Loading

fzipi commented Jun 3, 2026 •

edited

Loading