Move the plugin registry list to a different format

[fzipi]

Problem

The registry list lives as a markdown table in the README. It reads well, but it is hard to consume: the website, the docs, and any tool that wants to install a plugin has to parse markdown or scrape HTML.

Hand maintenance has also let the table drift. As of today: two CI badges are swapped between the nextcloud and dokuwiki rows, the false-positive-report-plugin row is missing its License cell, dokuwiki's link text has a typo, two plugins have integration tests but no badge, and there is an undocumented hole in the rule ID space at 9,515,000 - 9,515,999. See this comment for the full audit.

Goal

Make the registry a machine-readable index that tooling can resolve against to discover and install plugins from a place it can trust, and generate the README table from that index instead of maintaining it by hand.

An installer needs to answer, without parsing markdown: which plugins exist, where they live, which version to install (resolved to a release tag, not a moving branch), whether the plugin is vetted, its license, its rule ID range so collisions with already-installed plugins are detectable, and how to configure it.

Design

Two artifacts, with different owners:

• registry.yaml, in this repo — authoritative for rule ID range allocation and for the vetting signal (type, status). Changed only through reviewed PRs.
• plugin.yaml, in each plugin repo (feat: add plugin schema #37) — authoritative for the plugin's description and its configuration variables.

The index stays in this repo rather than being assembled by fetching every plugin repo, because ranges have to be allocated centrally to prevent collisions, some registered plugin repos are private and cannot be fetched at all, and a plugin repo declaring itself status: tested in its own descriptor attests nothing — the same field here, set through review, does.

What the registry attests: that a rule ID range is allocated, and that CRS maintainers reviewed the registration. It is not a code audit and not a supply-chain guarantee. Signing or checksums can attach to release tags later; out of scope for the first iteration.

Requirements

• registry.yaml holding the plugin list (name, rule ID range, repository, type, status, license), migrated from the current table with the drift above fixed
• JSON Schema for registry.yaml, validated in CI: unique names, no duplicate or overlapping ranges, ranges inside 9,500,000 - 9,999,999, GitHub repository URLs, SPDX license identifiers
• README skeleton with markers delimiting where the generated table goes
• generator that renders the table from registry.yaml, with CI badges derived from the repository field instead of typed by hand
• CI regenerates and fails on drift (git diff --exit-code) rather than committing from a GHA — same guarantee, no write access to main, no branch-protection friction
• publish a generated machine-readable index (registry.json) at a stable URL, for the website, the docs and installers
• document what the registry attests and what it does not, so downstream tooling does not over-read it

Refs #37 for the per-plugin descriptor schema.

[RedXanadu]

Do we want this?

Having it as human-readable text makes it easy to edit and update. Almost no presumed knowledge or skills are required, which is a good thing.

If the plugin registry contained info like version numbers, releases etc. then I would agree having it machine-readable would be a benefit. But we don't store that sort of information here. Unless that is part of the plan?

[fzipi]

We need to consume the registry data in other places. I don't think parsing html would do no good.

But we always could just forget about this, and in the future someone will take care of keeping things up to date across repos 🤷 .

[dune73]

We're currently doing a markdown table. I guess converting that automatically to a yaml format would be doable, but a bit brittle.

So writing the yaml and then generating the markdown would be better still human readable from my perspective. As long as it's not xml, we should be find.

@RedXanadu Is yaml really such a no-go? If yes, I can do the shell one-liner to do markdown -> yaml.

[fzipi]

Reviving this with data, plus a requirement we did not have in 2024: the point is for tooling to install plugins automatically from a place it can trust, not only to render a nicer table. That changes what the registry has to be.

The hand-maintained table has already drifted

I audited all 30 rows on main:

• CI badges swapped: the nextcloud-rule-exclusions row shows dokuwiki's badge and dokuwiki-rule-exclusions shows nextcloud's.
• false-positive-report-plugin has 6 cells instead of 7 — the License column is silently missing.
• Link text typo: dokuwiki's row renders coreruleset/dokuwki-rule-exclusions-plugin; only the href is correct.
• CI column stale in both directions: body-decompress-plugin and traffic-observation-plugin both have .github/workflows/integration.yml but no badge.
• 9,515,000 - 9,515,999 is an undocumented hole (dos-protection at 9,514, machine-learning at 9,516) — probably reclaimed from the v3 dos-protection plugin in dos-protection-modsecurity-v3 not found #12, but nothing records that.

@RedXanadu I think this is the answer to "do we want this?". Being human-readable did not keep it correct, and none of these are realistically catchable when reviewing a 200-character-wide table row. Every one of them is a generator-plus-validator catch.

What the registry has to provide if tools install from it

An installer needs to answer these without scraping markdown:

1. which plugins exist, and where they live;
2. which version to install — resolved to a release tag, not a moving branch;
3. whether it is vetted (type: official / 3rd-party, plus status);
4. the license;
5. the rule ID range, to detect collisions with what is already installed;
6. how to configure it — which is what the plugin.yaml descriptor in feat: add plugin schema #37 covers.

So: two artifacts with different owners. registry.yaml in this repo is authoritative for allocation and for the vetting signal; plugin.yaml in each plugin repo is authoritative for description and configuration variables.

Why the index stays here rather than being fetched from each plugin repo

• coreruleset/performance-plugin and coreruleset/ghost-rule-exclusions-plugin are private. A generator that fetches plugin.yaml from every plugin repo cannot see them, and they are in the table today.
• Rule ID ranges have to be allocated centrally — a plugin repo asserting its own range is how collisions happen, and preventing that is what this repo is for.
• For the trust story specifically: the vetting claim has to be made here. A plugin repo declaring itself status: tested in its own descriptor attests nothing. The same field in this repo, changed through a reviewed PR, does.

Being explicit about what "certified" means

Worth writing down in the same PR, so downstream tools do not over-read it: the registry attests that a rule ID range is allocated and that CRS maintainers reviewed the registration. It is not a code audit and not a supply-chain guarantee. Installers should resolve to a release tag and record what they installed; signing or checksums can attach to those tags later if we want that, and I am not proposing it for the first iteration.

One change to the checklist

The last box says "commit the file in the GHA". I would skip the bot commit: generate the table between <!-- BEGIN GENERATED --> markers, and have CI regenerate and git diff --exit-code so it fails on drift instead. Same guarantee, no write access to main, no branch-protection friction.

The validator is where the value is: unique names, no duplicate or overlapping ranges, ranges inside 9,500,000 - 9,999,999, GitHub repository URLs, SPDX license identifiers, and CI badges derived from the repository field rather than typed by hand — which makes the swapped-badge bug structurally impossible. It slots into the schema-validation workflow added in #37.

Beyond the README, we should publish the generated machine-readable index (a registry.json) at a stable URL, so the website, the docs and any installer consume that instead of parsing markdown. That was the original "consume from other sites" ask in the description.

Registration cost for a new plugin stays roughly what it is today: about seven YAML lines instead of one very wide table row, with no column alignment to get wrong.

@dune73 on the markdown -> yaml one-liner: I would rather hand-migrate the 30 rows once and fix the five bugs above in the same PR, since a faithful converter would carry them straight over.

If there is agreement on registry.yaml here plus plugin.yaml in the plugin repos, I will put up the migration, the generator and the validator.