Rule pack (rule_pack) guide

1. Finish onboarding on the seller site and register a publisher key (see the plugin signing page).
2. On the seller site’s “My plugins”, create a plugin of kind rule_pack whose ID is “your namespace.name” (e.g. acme.dev.sqli-extra).
3. Write the pack source rulepack.src.json as below: pack_id must be dev/<namespace>/<name>, layer developer, and version equal to the plugin version; then produce the canonical rulepack.json with the compiler in “Local debugging”.
4. Put the SHA-256 of rulepack.json in the manifest’s spec.entrypoint.sha256, sign the manifest and upload the version.

{
  "schema": "cdnca.rule-pack/v1",
  "pack_id": "dev/acme.dev/sqli-extra",
  "version": "1.0.0",
  "layer": "developer",
  "engine": "waf_v2",
  "engine_min_version": 1,
  "name": "SQL 注入加强",
  "description": "参数 SQL 注入检测与后台路径拦截",
  "params_schema": {
    "action": {"type": "string", "enum": ["log", "block"], "bind": {"target": "waf.action", "rules": ["r010"]}}
  },
  "exports": ["r010", "r020"],
  "rules": [
    {"id": "r010", "name": "参数注入", "waf": {"match": {"inspect": [{"target": "args", "operator": "detect", "values": ["sqli"]}]}, "action": "block", "flow": "stop"}},
    {"id": "r020", "name": "后台路径", "waf": {"match": {"path": {"kind": "prefix", "value": "/wp-admin"}}, "action": "block", "flow": "stop"}}
  ],
  "defaults": {"action": "block"}
}Copy

Signing and key registration are on the plugin signing page. Signing tool and steps →

Format cdnca.rule-pack/v1 with strict fields (unknown fields, duplicate keys and trailing data are rejected), at most 1 MiB.

Budget: one pack at most 256 rules, 64 regexes and 4096 cost units (with defaults and at every parameter boundary); all mounts of one site together at most 1024 rules, 256 regexes and 16384 units. A regex is at most 512 bytes with repeats up to 256.

A rule pack can only match and then block, challenge, rate-limit or ban; it cannot rewrite requests, origins or responses or compute anything. A site administrator mounts the pack in the control plane; user-layer exceptions run before developer-layer rules.

After upload the review worker runs the validating phase (manifest, entrypoint, permissions, the kind’s own checks); any reject stops it before scanning, then the scanning phase runs. Outcome: a reject → changes requested (fix it and press “Resubmit”, at most 10 scans per version); a quarantine → human review; neither → approved directly or sent to human review under the conditions below.

• The first version (the plugin has no reviewed version yet)
• Permissions differ from the last reviewed version (added or removed)
• Privileged kinds: module, engine_module, provider
• Sellers who joined less than 90 days ago (market default, adjustable by the operator)
• Three scan attempts in a row errored

Any one of them sends the version to human review. The full rule table (rule ID, severity, reject or quarantine, evaluation mode) is on the review rules page.

• rulepack.compile_failed / rulepack.budget_exceeded: does not compile or is over budget (reject).
• rulepack.layer_invalid: pack_id is not dev/<your namespace>/<name> or layer is not developer (reject).
• rulepack.version_mismatch: the pack version differs from the plugin version (reject).
• rulepack.not_canonical: the upload is not the canonical bytes (reject).
• rulepack.gate_failed: the pack fails the publication gate on its own (reject).
• entrypoint.data_pack_permissions / entrypoint.data_pack_version / entrypoint.packages_present / entrypoint.content_mismatch: wrong permission, version, extra packages or file digest (reject).

Rules for this kind are in the review rule list: metadata.* entrypoint.* permissions.* rulepack.*

Review, the control plane and the edge use the same compiler, libs/rulepack. The canonical bytes are Compile’s Canonical output. From the repository root, compile your rulepack.src.json into the canonical rulepack.json:

mkdir -p libs/rulepack/cmd/rpc && cat > libs/rulepack/cmd/rpc/main.go <<'EOF'
package main

import (
	"fmt"
	"os"

	"github.com/cdnca/cdnca/libs/rulepack"
)

func main() {
	raw, _ := os.ReadFile(os.Args[1])
	c, err := rulepack.Compile(raw)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	os.WriteFile(os.Args[2], c.Canonical, 0o644)
	fmt.Println(c.SHA256, c.Cost.Rules, c.Cost.Regexes, c.Cost.Units)
}
EOF
GOWORK=off go -C libs/rulepack run ./cmd/rpc "$PWD/rulepack.src.json" "$PWD/rulepack.json"Copy

It prints the canonical SHA-256 (put it in spec.entrypoint.sha256) followed by rule, regex and cost-unit counts. A compile error reads the same as the rulepack.compile_failed message in the scan report.