docs(security): publish Sigstore verifier command after §8 dry-run

Sigstore signing was wired in round 8 (build 629, 2026-04-29) but the
required §8 end-to-end verification dry-run was deferred to the first
public release. Ran the dry-run on 2026-05-13 against test tag
v0.0.0-sigstore-test; all 5 verification scenarios passed:

  - legit verify against production identity-regex: Verified OK
  - tamper test (appended bytes): rejected with ASN.1 signature error
  - foreign-signature identity-pin test (sigstore/cosign v2.4.3 RPM,
    which is signed via Google OIDC, not GitHub Actions): rejected
    by our identity-regex (added as a rigor extension beyond what
    RELEASE_CHECKLIST §8 required)
  - Rekor lookup with explicit --rekor-url: Verified OK
  - SBOM (.cdx.json) signature: Verified OK

docs/SBOM.md is the canonical home of the verifier command. Replaced
the "Recommended next-step hardening (not in this round)" section with
the live "Verifying a release with cosign" instructions. The command
uses <VERSION> placeholder per CLAUDE.md doc-drift rules and includes
--new-bundle-format=false (required for cosign 3.x customers because
the workflow currently signs with cosign v2.4.1's legacy .sig+.crt
pair, not the new single-.sigstore-bundle format).

README.md (Security section) and INSTALLATION.md (new Section 3.6)
point to docs/SBOM.md rather than duplicating the command — avoids
the doc-drift class of bug.

docs/RELEASE_CHECKLIST.md §8 marked DONE with an Outcome notes block
capturing the 5 verification results, three non-blocking side-findings
(Node 20 deprecation in GHA, double-base64 cert quirk, app.conf:version
vs. git-tag drift risk), and a pointer to the two prerequisite fixes
the dry-run forced (commits 691c651 + 6f8dc79).

Test release v0.0.0-sigstore-test was deleted post-verification per
the runbook; the Rekor entry remains permanently in the transparency
log (immutable by design — this is the security property, not a bug).

Author: wildleo91

INSTALLATION.md

@@ -260,6 +260,20 @@ deployment:
 
 ---
 
+## Section 3.6 — Verifying the release signature (recommended before install)
+
+The `.spl` is Sigstore-signed by GitHub Actions. Verifying before install
+confirms the artifact came from this repo's release pipeline and was not
+swapped on the GitHub Releases page. See
+[docs/SBOM.md](docs/SBOM.md#verifying-a-release-with-cosign) for the
+canonical `cosign verify-blob` command and identity-regex.
+
+Skipping this check leaves you exposed to a release-channel takeover
+(an attacker who compromises the Releases page can swap both the `.spl`
+and the `.sha256` sidecar). Sigstore signing closes that gap.
+
+---
+
 ## Section 4 — Post-install verification checklist
 
 Run these checks after the first install:

README.md

@@ -71,6 +71,7 @@ Built for SOC teams who need to manage detection rule exceptions without touchin
 - Server-side RBAC enforcement on every request
 - Path traversal protection, input sanitization, rate limiting
 - Control Panel restricted to admin roles
+- Release artifacts are Sigstore-signed; see [docs/SBOM.md](docs/SBOM.md#verifying-a-release-with-cosign) for the cosign verification command
 
 ### Row Expiration
 

docs/RELEASE_CHECKLIST.md

@@ -119,7 +119,7 @@ or new filters here.
 
 ---
 
-## 8. Sigstore Signing — End-to-End Verification (REQUIRED on first signed release)
+## 8. Sigstore Signing — End-to-End Verification [x] DONE — verified 2026-05-13 on tag v0.0.0-sigstore-test
 
 **Background.** Round 8 (build 629, 2026-04-29) wired Sigstore keyless
 signing into `.github/workflows/release.yml`. The workflow uses GitHub
@@ -252,3 +252,41 @@ After this section is completed once, mark this section as
 leave it in place. Future releases verify automatically via the
 quarterly pip-audit cadence + per-release workflow run; this one-shot
 just proves the wiring.
+
+### Outcome notes (2026-05-13 dry-run on tag v0.0.0-sigstore-test)
+
+5/5 verification scenarios passed:
+
+- Step 2 (legit verify against production identity-regex) — `Verified OK`
+- Step 3 (tamper test, appended bytes to .spl) — failed with "invalid
+  signature when validating ASN.1 encoded signature"
+- Step 3b (foreign-signature identity-pin test, added as a rigor
+  extension to this runbook) — verified that a known-good Sigstore
+  signature from a different repo (`sigstore/cosign` v2.4.3 RPM, which
+  is signed via Google OIDC, not GitHub Actions) is rejected by the
+  production identity-regex. Confirms the identity pin is the actual
+  security boundary, not just signature-integrity. Recommend adding
+  Step 3b to this checklist permanently.
+- Step 4 (Rekor lookup with explicit `--rekor-url`) — `Verified OK`
+- Bonus: SBOM (`.cdx.json`) signature verifies the same way
+
+Verifier command published in `docs/SBOM.md` (canonical) with pointers
+from `README.md` (Security section) and `INSTALLATION.md` (Section 3.6).
+
+Three side-findings worth follow-up but not blocking:
+
+- The release workflow runs `actions/checkout@v4` + `actions/setup-python@v5`
+  which both deprecate Node 20; GitHub forces Node 24 by 2026-09-16.
+- `cosign-release: 'v2.4.1'` outputs `.crt` as base64-wrapped PEM
+  (cosign-internal format). cosign verify-blob handles it transparently;
+  only matters for openssl inspection.
+- `scripts/package.sh` derives `<VERSION>` for the .spl filename from
+  `default/app.conf:version`, not from the git tag. Pre-tag-cut step
+  must bump `app.conf:version` to match the tag, otherwise the .spl
+  filename mismatches the tag and Sigstore identity still verifies but
+  the customer-facing artifact name looks wrong. Add to "Tag cut"
+  pre-checklist on next round.
+
+The two prerequisite fixes that the dry-run forced (commits 691c651 +
+6f8dc79) are not Sigstore-related — they were pre-existing validate.sh
+issues that had never been exercised by a passing release run.

docs/SBOM.md

@@ -88,36 +88,65 @@ sha256sum -c wl_manager-<version>.spl.sha256
 
 ### Limitations of the current model
 
-1. The .spl and the .sha256 are distributed via the same channel
-   (GitHub Releases). An attacker who compromises GitHub Releases
-   for this repository can replace BOTH files. The hash file is
-   only an integrity check against in-flight tampering / CDN
-   corruption / archive rot — NOT against a release-channel
-   takeover.
-2. There is no signature on the .sha256 file. A `gpg --verify`
-   step would tie the release to a key whose public half is
-   distributed out-of-band (e.g., `KEYS` file in this repo,
-   PGP keyserver, maintainer's web bio).
-
-### Recommended next-step hardening (not in this round)
-
-- **Sigstore / cosign keyless signing** — sign the .spl during
-  the GitHub Actions release run using the OIDC token from the
-  workflow itself. Verifiers can confirm the .spl was produced by
-  `RelativisticJet/wl_manager`'s release workflow without us
-  managing any long-lived signing key. Single best ROI.
-- **`KEYS` file at repo root** with a maintainer GPG public key,
-  and `release.yml` signing the .sha256 with the matching private
-  key (stored as a GitHub Actions secret). Heavier than Sigstore
-  but matches what most established Splunk apps ship.
-- **Per-release SBOM artifact** (CycloneDX or SPDX) attached
-  alongside the .spl. The current SBOM is small enough to live in
-  this document, but customers running automated SCA tools expect
-  a machine-readable file per release.
-
-These are all C-tier follow-ups for a future round; the current
-.sha256 model is adequate for the threat the repo currently faces
-(opportunistic CDN tampering, unintentional corruption).
+1. (resolved as of 2026-05-13) — The .spl is now Sigstore-signed in
+   addition to having a SHA-256 sidecar. Customers who run only the
+   `sha256sum -c` check have the same exposure to a release-channel
+   takeover as before, but customers who run the cosign verification
+   below cannot be deceived by a Releases-page swap.
+2. There is still no GPG signature on the .sha256 file. A `gpg --verify`
+   step would tie the release to a maintainer key whose public half is
+   distributed out-of-band. Not in this round; see "Future hardening"
+   below.
+
+### Verifying a release with cosign
+
+Each release ships `.sig` (signature) and `.crt` (Fulcio short-lived
+certificate) sidecar files for both the `.spl` and the `.cdx.json`
+SBOM. The signing identity is the GitHub Actions workflow
+(`.github/workflows/release.yml`) that produced the artifact, recorded
+in the Rekor transparency log.
+
+Install cosign (>= v2.4):
+
+- macOS: `brew install cosign`
+- Linux: see <https://docs.sigstore.dev/cosign/system_config/installation/>
+- Windows: `winget install sigstore.cosign`
+
+Verify (replace `<VERSION>` with the release you're installing):
+
+```bash
+cosign verify-blob \
+  --new-bundle-format=false \
+  --certificate wl_manager-<VERSION>.spl.crt \
+  --signature wl_manager-<VERSION>.spl.sig \
+  --certificate-identity-regexp '^https://github.com/RelativisticJet/wl_manager/\.github/workflows/release\.yml@refs/tags/.*$' \
+  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
+  wl_manager-<VERSION>.spl
+```
+
+A passing verifier prints `Verified OK`. A tampered .spl or a signature
+from any other repo's workflow fails closed.
+
+`--new-bundle-format=false` is required for cosign 3.x because the
+release workflow currently signs with cosign v2.4.1 (producing the
+legacy `.sig` + `.crt` pair, not the new single-`.sigstore`-bundle
+format that cosign 3.x defaults to). cosign 2.x users can drop the
+flag — the command works either way.
+
+You can also verify the SBOM the same way by substituting
+`wl_manager-<VERSION>.spl.cdx.json` and its `.sig` / `.crt` pair.
+
+### Future hardening (not in this round)
+
+- **GPG sidecar on .sha256**: a maintainer key distributed via a `KEYS`
+  file at repo root, with `release.yml` GPG-signing the .sha256. Heavier
+  than Sigstore but matches what most established Splunk apps ship.
+  Defense-in-depth against the day Fulcio's CA cert chain rotates faster
+  than customers can update their cosign install.
+- **Upgrade signing to cosign v3.x new-bundle format**: removes the
+  `--new-bundle-format=false` flag from the customer command. Wait until
+  the customer base demonstrates they're on cosign 3.x; today most
+  package managers still ship cosign 2.x.
 
 ## Subresource Integrity (SRI) — N/A by architecture