ci: test against latest stable BunkerWeb, add release workflow, bump to 1.11

Author: TheophileDiot

.github/workflows/release.yml

@@ -0,0 +1,81 @@
+name: Release
+
+# Cut a GitHub release once per plugin version bump. Mirrors the release-creation
+# step of bunkerity/bunkerweb (softprops/action-gh-release, pinned SHA, draft for
+# human review) without the heavy build matrix the plugins repo does not need.
+#
+# Fires only after the "Tests" workflow succeeds on main, and only when the
+# version in plugin.json does not already have a release — so a normal push to
+# main that does not bump the version is a no-op.
+
+on:
+  workflow_run:
+    workflows: [Tests]
+    types: [completed]
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    if: github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the tag + release
+    steps:
+      - name: Checkout the tested commit
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0 # full history so generated release notes are complete
+
+      - name: Resolve plugin version
+        id: version
+        run: |
+          # All plugin.json carry the same version (kept in lockstep by
+          # misc/update_version.sh), so any one of them is the source of truth.
+          version="$(jq -r .version clamav/plugin.json)"
+          case "$version" in
+          "" | null | *[!0-9.]*)
+            echo "::error::unexpected plugin version '$version'"
+            exit 1
+            ;;
+          esac
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "tag=v$version" >> "$GITHUB_OUTPUT"
+
+      - name: Skip if this version is already released
+        id: guard
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          # Match on tag_name across ALL releases, drafts included. A draft has
+          # no git tag until it is published, so `gh release view <tag>` would
+          # miss an unpublished draft and we'd create a duplicate on every push.
+          # The assignment aborts the step if `gh api` fails (no fail-open to
+          # "create" on an auth/network error).
+          tags="$(gh api "repos/$GITHUB_REPOSITORY/releases" --paginate --jq '.[].tag_name')"
+          if grep -Fxq "$TAG" <<<"$tags"; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "Release $TAG already exists (including drafts) — nothing to do."
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "No release for $TAG yet — creating a draft."
+          fi
+
+      - name: Create draft release
+        if: steps.guard.outputs.exists == 'false'
+        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        with:
+          tag_name: ${{ steps.version.outputs.tag }}
+          target_commitish: ${{ github.event.workflow_run.head_sha }}
+          name: ${{ steps.version.outputs.tag }}
+          draft: true # published by a maintainer after a quick review
+          generate_release_notes: true # auto-changelog from merged PRs/commits
+          body: |
+            BunkerWeb external plugins **${{ steps.version.outputs.tag }}**.
+
+            Install a plugin by mounting its directory into the scheduler's `/data/plugins`
+            (see the README). Coraza ships its WAF API as `bunkerity/bunkerweb-coraza`.

.github/workflows/tests.yml

@@ -21,17 +21,29 @@ jobs:
     outputs:
       bw_tag: ${{ steps.tag.outputs.bw_tag }}
     steps:
-      - name: Compute BW tag
+      - name: Resolve latest stable BunkerWeb tag
         id: tag
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          # NOTE: hardcoded on purpose and intentionally NOT read from
-          # COMPATIBILITY.json. If you bump the pinned BunkerWeb version, change
-          # it HERE only (single source of truth for the workflow).
-          if [ "$GITHUB_REF" = "refs/heads/main" ] ; then
-            echo "bw_tag=1.6.1" >> "$GITHUB_OUTPUT"
-          else
-            echo "bw_tag=dev" >> "$GITHUB_OUTPUT"
-          fi
+          # Always test against the latest STABLE BunkerWeb release, resolved at
+          # runtime so it never goes stale. GitHub's releases/latest endpoint
+          # excludes drafts and pre-releases (rc/beta), giving us "stable".
+          # Same tag on every branch (dev and main) — there is no pinned version.
+          # `|| true`: a 404 (no stable release yet) or rate-limit makes gh exit
+          # non-zero, which under `bash -e` would abort the step here with a raw
+          # error. Swallow it so the empty tag falls through to the case below
+          # and reports our own diagnostic.
+          tag="$(gh api repos/bunkerity/bunkerweb/releases/latest --jq .tag_name || true)"
+          tag="${tag#v}" # release tag may be "v1.6.1"; Docker tags have no "v"
+          case "$tag" in
+          "" | *-*)
+            echo "::error::could not resolve a stable BunkerWeb tag (got '${tag:-<empty>}')"
+            exit 1
+            ;;
+          esac
+          echo "Resolved latest stable BunkerWeb tag: $tag"
+          echo "bw_tag=$tag" >> "$GITHUB_OUTPUT"
 
   lint:
     runs-on: ubuntu-latest

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository purpose
 
-Official external plugins for [BunkerWeb](https://github.com/bunkerity/bunkerweb). Each top-level directory (`clamav/`, `coraza/`, `discord/`, `slack/`, `virustotal/`, `webhook/`) is an independently-shipped plugin. There is no monorepo build — plugins are consumed by BunkerWeb at runtime by mounting the plugin directory into `/data/plugins` of the `bunkerweb-scheduler` container.
+Official external plugins for [BunkerWeb](https://github.com/bunkerity/bunkerweb). Each top-level directory (`authentik/`, `clamav/`, `coraza/`, `discord/`, `matrix/`, `slack/`, `virustotal/`, `webhook/`) is an independently-shipped plugin. There is no monorepo build — plugins are consumed by BunkerWeb at runtime by mounting the plugin directory into `/data/plugins` of the `bunkerweb-scheduler` container.
 
 ## Plugin anatomy
 
@@ -22,26 +22,46 @@ Coraza is special: it also ships `coraza/api/` — a standalone Go HTTP service
 
 There are **two unrelated version streams**, easy to confuse:
 
-1. **Individual plugin version** in each `plugin.json` (currently `1.10`). Bump with `./misc/update_version.sh <new_version>` from the repo root — it rewrites every `plugin.json` and the README badge in place.
-2. **Plugins-collection version** in `COMPATIBILITY.json`, which maps a collection version to the BunkerWeb versions it supports (e.g. `"1.8": ["1.6.0", ...]`). This is the version shown in the README badge and controls compatibility gates.
+1. **Individual plugin version** in each `plugin.json` (currently `1.11`). Bump with `./misc/update_version.sh <new_version>` **run from the repo root** (it uses `find .` + `README.md` relative paths) — it rewrites every `plugin.json` **and the README badge** to that plugin version (see `misc/update_version.sh:17-18`).
+2. **Plugins-collection version** in `COMPATIBILITY.json`, which maps a collection version (currently `1.8`) to the BunkerWeb versions it supports (e.g. `"1.8": ["1.6.0", ...]`). Controls compatibility gates.
 
-When bumping, check both — the README badge is tied to (2), while `plugin.json` uses (1).
+These two streams are independent and `update_version.sh` only touches (1) — it now updates the README badge too (the badge's sed pattern was anchored on a leading `"` that never matched the shields.io URL, so the badge silently froze; fixed to anchor on `/badge/`, so it tracks the plugin version automatically). When bumping: run the script for (1), and edit `COMPATIBILITY.json` by hand for (2).
 
 ## Testing
 
-There is no unit-test framework. Tests are end-to-end integration tests under `.tests/`:
+Two layers: fast **unit tests** (no Docker) and **end-to-end integration tests** under `.tests/`.
+
+### Unit tests (no Docker, run locally + in CI)
+
+- **Go** — `coraza/api/main_test.go` covers the Go WAF service. Run `cd coraza/api && go test ./...`.
+- **Python (pytest)** — `tests/test_ui_actions.py` parametrizes over every plugin's `ui/actions.py`; `tests/conftest.py` provides a `FakePingUtils` mock for `bw_instances_utils`. Run `pytest tests/ -q`.
+- **Lua (busted)** — `spec/*_helpers_spec.lua` exercises the pure-logic helper modules (`authentik`, `clamav`, `discord`, `matrix`, `virustotal`) against `spec/helpers/fake_ngx.lua`. Run `busted`. This is why upstream-specific logic is factored into `<plugin>_helpers.lua` — so it's testable outside OpenResty.
+
+### Integration tests (Docker, e2e)
 
 - `./.tests/bw.sh <bw_tag>` pulls `bunkerity/bunkerweb:<tag>` + `bunkerweb-scheduler:<tag>` and retags them as `bunkerweb:tests` / `bunkerweb-scheduler:tests`. Must run first.
-- `./.tests/clamav.sh`, `./.tests/coraza.sh`, `./.tests/virustotal.sh` each: copy the plugin into `/tmp/bunkerweb-plugins/<plugin>/bw-data/plugins` (owned `101:101`), copy `.tests/<plugin>/docker-compose.yml`, `sed` the compose file to use the `:tests` tagged images, then `docker compose up --build -d` and poll with `curl`. EICAR file is downloaded for ClamAV; VirusTotal requires `VIRUSTOTAL_API_KEY` env var.
+- Per-plugin scripts: `./.tests/clamav.sh`, `coraza.sh`, `virustotal.sh`, `authentik.sh`, and `notifier.sh` (the last covers discord/slack/webhook/matrix together in one multisite stack). Each copies the plugin into `/tmp/bunkerweb-plugins/<plugin>/bw-data/plugins` (owned `101:101`), copies `.tests/<plugin>/docker-compose.yml`, `sed`s it to the `:tests` tagged images, then `docker compose up --build -d` and polls with `curl`. EICAR file is downloaded for ClamAV; VirusTotal requires `VIRUSTOTAL_API_KEY`. Several use mock upstreams instead of the real service: `.tests/virustotal/vt-mock.conf`, `.tests/authentik/mock-outpost.conf`, `.tests/notifier/ratelimit.conf`.
 - `.tests/utils.sh` provides `do_and_check_cmd` (runs a command, echoes output on failure, exits on non-zero) and `git_secure_clone` (pinned-commit clone helper). Source it with `. .tests/utils.sh`.
-- Run a single plugin's tests: `./.tests/bw.sh dev && ./.tests/clamav.sh` (or `coraza`/`virustotal`). Pass `verbose` as `$1` to dump compose logs on success.
+- Run a single plugin's e2e: `./.tests/bw.sh <bw_tag> && ./.tests/clamav.sh` (or `coraza`/`virustotal`/`authentik`/`notifier`). CI resolves `<bw_tag>` to the latest stable release; locally any pulled tag works (e.g. a stable `1.6.1`, or `dev` for the upcoming build). Pass `verbose` as `$1` to dump compose logs on success.
 - Tests need `sudo` (for chowning to BW's uid 101) and a working Docker daemon. They leave state in `/tmp/bunkerweb-plugins/` — the scripts clean it at start, but `docker compose down -v` is the safe manual reset.
 
-Discord, Slack, and Webhook have no automated tests — they're exercised by manually pointing a real BunkerWeb instance at a webhook URL.
-
 ## CI/CD (`.github/workflows/tests.yml`)
 
-Runs on push to `dev` and `main`. Picks BW tag from branch: `main` → `1.6.1`, `dev` → `dev`. Runs CodeQL, then `bw.sh` → `clamav.sh` → `coraza.sh` → `virustotal.sh` sequentially. On `main` only, `./.tests/build-push.sh 1.6.1` builds and pushes the `bunkerweb-coraza` image. **If you update the pinned BW version, update the hardcoded `1.6.1` in `tests.yml` too** — it is not read from `COMPATIBILITY.json`.
+Runs on push to `dev` and `main`. A `tag` job resolves the **latest stable BunkerWeb release** at runtime via the GitHub `releases/latest` API (`gh api repos/bunkerity/bunkerweb/releases/latest`, which excludes drafts and pre-releases; a leading `v` is stripped) and feeds that tag to every downstream job — same version on both branches, never pinned. Pipeline:
+
+1. **codeql** — `.github/workflows/codeql.yml` (also runs weekly on a cron), matrix `[python, go]`.
+2. **lint** — `pre-commit run --all-files`.
+3. **unit** — matrix `[go, python, lua]` (the unit tests above).
+4. **integration** — `needs: [tag, lint, unit]`, matrix `plugin: [clamav, coraza, virustotal, authentik, notifier]`; each runs `.tests/bw.sh <tag>` then `.tests/<plugin>.sh`.
+5. **build-push** — `main` only: `./.tests/build-push.sh <tag>` builds and pushes the `bunkerweb-coraza` image.
+
+There is **no pinned BW version** — the `tag` job always resolves the latest stable release, so the tests track upstream automatically (`COMPATIBILITY.json` is not consulted here). The resolved tag flows into `bw.sh` (pulls `bunkerity/bunkerweb[-scheduler]:<tag>`) and, on `main`, into `build-push.sh` (which also tags the pushed `bunkerweb-coraza` image with it). The job fails fast if the API returns an empty or pre-release (hyphenated) tag.
+
+Two tradeoffs of tracking upstream: (1) the `dev` branch no longer tests against BunkerWeb's `dev` build, so a plugin change that relies on an unreleased BW feature gets no CI coverage until BW ships a stable release; (2) every `main` push republishes `bunkerweb-coraza:latest` (and `:<stable>`) — harmless here because that image is a self-contained Go binary + vendored CRS, independent of the BW base tag, so only the extra tag's value moves.
+
+## Releasing (`.github/workflows/release.yml`)
+
+Releases are cut automatically from `main`. After `Tests` succeeds there, a `Release` workflow (a `workflow_run` trigger on the `Tests` workflow) reads the plugin version from `plugin.json` and, if no release `v<version>` exists yet (**drafts included** — it matches `tag_name` via `gh api`, since a draft has no git tag), opens a **draft** GitHub release with `softprops/action-gh-release` and auto-generated notes. A maintainer reviews and publishes it; a push that doesn't bump the version is a no-op. Two consequences of the `workflow_run` model: the file only fires once it is on the default branch (`main`), and it can't be tested from `dev`. So **cutting a release = `./misc/update_version.sh <ver>` → merge to `main` → publish the draft** the workflow creates.
 
 ## Linting — pre-commit is the source of truth
 
@@ -61,7 +81,17 @@ Runs on push to `dev` and `main`. Picks BW tag from branch: `main` → `1.6.1`,
 - Every hook method returns `self:ret(ok_bool, msg, [http_status])`. To deny a request, return `self:ret(true, "reason", utils.get_deny_status())`.
 - Gate expensive work at `init_worker` with `utils.has_variable("USE_<PLUGIN>", "yes")` — avoids connecting to upstream services when the plugin is globally disabled. Skip when `self.is_loading` is true.
 - Use `ngx.socket` for TCP (see `clamav.lua` INSTREAM protocol) and `resty.http` for HTTP upstreams. Prefer `resty.upload` for streaming request bodies (`clamav.lua` is the reference).
-- Cache API responses (SHA-512 of body for file scans) — `virustotal.lua` is the pattern.
+- Cache scan results keyed by the file's hash so identical uploads skip the upstream. `clamav.lua` hashes the body with **SHA-512** (`resty.sha512`); `virustotal.lua` uses **SHA-256** (`resty.sha256`, matching VT's file-id) with a 24h TTL — it's the reference for cached HTTP-API lookups.
+
+## Plugin-specific notes
+
+The "Plugin anatomy" layout and the Lua conventions above are shared by all plugins. The non-obvious, per-plugin logic lives in code — these pointers save a re-read:
+
+- **coraza** — the only plugin with an external sidecar. `coraza.lua` talks HTTP to the Go service in `coraza/api/` (`/ping` health check, `/request` for the verdict; the service returns deny/msg). CRS rules are vendored at build time by `coraza/api/crs.sh`, **pinned to a commit hash** with `.git` stripped; the two-stage `coraza/api/Dockerfile` builds the Go binary (multiphase-evaluation build tag) and bakes the rules in. Bumping CRS = bump the hash in `crs.sh`. Image: `bunkerity/bunkerweb-coraza`.
+- **clamav** — speaks ClamAV's **binary INSTREAM protocol** over `ngx.socket.tcp` (each chunk framed by a 4-byte big-endian length, terminated by a zero-length frame), not HTTP. Streams the request body via `resty.upload`, scanning only multipart parts that have a real filename (`Content-Disposition` parsing handles quoted, unquoted, and RFC 5987 `filename*`). SHA-512 cache (see above).
+- **virustotal** — HTTP to VT API v3 with `VIRUSTOTAL_API_KEY`; scans files and/or IPs. Verdict logic is in `virustotal_helpers.lua` (`evaluate()` compares VT's suspicious/malicious counts to configurable thresholds) — unit-tested in `spec/virustotal_helpers_spec.lua`. SHA-256 cache, 24h TTL. No usable ping endpoint, so `init_worker` does not pre-connect.
+- **authentik** — forward-auth: `confs/` ships the nginx snippet; the Lua access handler whitelists outpost paths and forwards/extracts auth headers (needs enlarged proxy buffers for big JWTs).
+- **discord / slack / webhook / matrix** — notifiers: build a JSON payload and POST it to an external URL from an `ngx.timer.at` async timer on the `log` hook (denials only), so request latency is unaffected. The generic case; little plugin-specific state.
 
 ## Pull requests & commits
 

README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-	<img src="https://img.shields.io/badge/bunkerweb_plugins-1.6-blue" />
+	<img src="https://img.shields.io/badge/bunkerweb_plugins-1.11-blue" />
 	<img src="https://img.shields.io/github/last-commit/bunkerity/bunkerweb-plugins" />
 	<img src="https://img.shields.io/github/actions/workflow/status/bunkerity/bunkerweb-plugins/tests.yml?branch=dev&label=CI%2FCD%20dev" />
 	<img src="https://img.shields.io/github/actions/workflow/status/bunkerity/bunkerweb-plugins/tests.yml?branch=main&label=CI%2FCD%20main" />

authentik/plugin.json

@@ -2,7 +2,7 @@
   "id": "authentik",
   "name": "Authentik",
   "description": "Protect any site (reverse proxy, served files, ...) with Authentik forward authentication (auth_request).",
-  "version": "1.10",
+  "version": "1.11",
   "stream": "no",
   "settings": {
     "USE_AUTHENTIK": {

clamav/plugin.json

@@ -2,7 +2,7 @@
   "id": "clamav",
   "name": "ClamAV",
   "description": "Automatic scan of uploaded files with ClamAV antivirus engine.",
-  "version": "1.10",
+  "version": "1.11",
   "stream": "no",
   "settings": {
     "USE_CLAMAV": {

coraza/plugin.json

@@ -2,7 +2,7 @@
   "id": "coraza",
   "name": "Coraza",
   "description": "Use Coraza as a library to inspect client request.",
-  "version": "1.10",
+  "version": "1.11",
   "stream": "no",
   "settings": {
     "USE_CORAZA": {

discord/plugin.json

@@ -2,7 +2,7 @@
   "id": "discord",
   "name": "Discord",
   "description": "Send alerts to a Discord channel (using webhooks).",
-  "version": "1.10",
+  "version": "1.11",
   "stream": "yes",
   "settings": {
     "USE_DISCORD": {

matrix/plugin.json

@@ -2,7 +2,7 @@
   "id": "matrix",
   "name": "Matrix",
   "description": "Send alerts to a Matrix room via the Matrix API.",
-  "version": "1.10",
+  "version": "1.11",
   "stream": "yes",
   "settings": {
     "USE_MATRIX": {

misc/update_version.sh

@@ -15,4 +15,7 @@ fi
 echo "Updating version of plugins to \"$1\""
 
 find . -type f -name "plugin.json" -exec sed -i 's@"version": "[0-9].*"@"version": "'"$1"'"@' {} \;
-sed -i 's@"bunkerweb_plugins\-[0-9].*\-blue"@"bunkerweb_plugins-'"$1"'-blue@' README.md
+# Anchor on the shields.io URL path (/badge/), not a leading quote — the badge
+# is inside src="…/badge/bunkerweb_plugins-<ver>-blue", so the old `"bunkerweb…`
+# pattern never matched and the badge silently went stale.
+sed -i 's@/badge/bunkerweb_plugins-[0-9][0-9.]*-blue@/badge/bunkerweb_plugins-'"$1"'-blue@' README.md