sync(workflows): migrate security scans to OSV-Scanner (#189)

Author: mrz1836

.github/docs/repository-features.md

@@ -15,10 +15,10 @@ A comprehensive list of built-in features that ship with this repository.
 * **Uniform Code Style** via [gofumpt](https://github.com/mvdan/gofumpt) plus zero‑noise linting with [golangci‑lint](https://github.com/golangci/golangci-lint).
 * **Confidence‑Boosting Tests** with [testify](https://github.com/stretchr/testify), the Go [race detector](https://blog.golang.org/race-detector), crystal‑clear [HTML coverage](https://blog.golang.org/cover) snapshots, and automatic reporting via internal coverage system.
 * **Hands‑Free Releases** delivered by [GoReleaser](https://github.com/goreleaser/goreleaser) whenever you create a [new Tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging).
-* **Relentless Dependency & Vulnerability Scans** via [Dependabot](https://dependabot.com) (runs daily at 8am to ensure broadcast dependencies are always current), [Nancy](https://github.com/sonatype-nexus-community/nancy), and [govulncheck](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck).
+* **Relentless Dependency & Vulnerability Scans** via [Dependabot](https://dependabot.com) (runs daily at 8am to ensure broadcast dependencies are always current), [Nancy](https://github.com/sonatype-nexus-community/nancy), [OSV-Scanner](https://github.com/google/osv-scanner), and [govulncheck](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck).
 * **Security Posture by Default** with [CodeQL](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/about-code-scanning), [OpenSSF Scorecard](https://openssf.org), and secret‑leak detection via [gitleaks](https://github.com/gitleaks/gitleaks).
 * **Automatic Syndication** to [pkg.go.dev](https://pkg.go.dev/) on every release for instant godoc visibility.
-* **Polished Community Experience** using rich templates for [Issues & PRs](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-go-broadcastsitory).
+* **Polished Community Experience** using rich templates for Issues & PRs.
 * **All the Right Meta Files** (`LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SUPPORT.md`, `SECURITY.md`) pre‑filled and ready.
 * **Code Ownership** clarified through a [CODEOWNERS](../CODEOWNERS) file, keeping reviews fast and focused.
 * **Zero‑Noise Dev Environments** with tuned editor settings ([`.editorconfig`](../../.editorconfig)) plus curated *ignore* files for [VS Code](../../.editorconfig), [Docker](../../.dockerignore), and [Git](../../.gitignore).

.github/env/00-core.env

@@ -87,7 +87,13 @@ ENABLE_YAML_LINT=true
 # Security Scanning
 ENABLE_SECURITY_SCAN_GITLEAKS=true
 ENABLE_SECURITY_SCAN_GOVULNCHECK=true
-ENABLE_SECURITY_SCAN_NANCY=true
+# Nancy is disabled: Sonatype retired the free OSS Index tier in favor of the
+# credit-metered Sonatype Guide backend (Nancy v2). OSV-Scanner replaces it below.
+ENABLE_SECURITY_SCAN_NANCY=false
+# OSV-Scanner (google/osv-scanner) — multi-source dependency vulnerability scanning
+# backed by the OSV.dev database (GHSA, Go vuln DB, and 30+ other sources). Free,
+# no account or API key required. Complements govulncheck's reachability analysis.
+ENABLE_SECURITY_SCAN_OSV=true
 
 # Documentation & Publishing
 ENABLE_GODOCS_PUBLISHING=true

.github/env/10-mage-x.env

@@ -36,7 +36,7 @@
 # ================================================================================================
 
 # MAGE-X version
-MAGE_X_VERSION=v1.25.1
+MAGE_X_VERSION=v1.26.0
 
 # For mage-x development, set to 'true' to use local version instead of downloading from releases
 MAGE_X_USE_LOCAL=false
@@ -77,7 +77,10 @@ MAGE_X_GOVULNCHECK_VERSION=v1.1.4
 MAGE_X_GO_SECONDARY_VERSION=1.24.x
 MAGE_X_GO_VERSION=1.24.x
 MAGE_X_MOCKGEN_VERSION=v0.6.0
-MAGE_X_NANCY_VERSION=v1.2.0
+MAGE_X_NANCY_VERSION=v2.1.0
+# OSV-Scanner version for MAGE-X parity (authoritative pin is OSV_SCANNER_VERSION in
+# 10-security.env, which the CI workflow uses to `go install` the scanner).
+MAGE_X_OSV_SCANNER_VERSION=v2.5.0
 MAGE_X_STATICCHECK_VERSION=2026.1
 MAGE_X_SWAG_VERSION=v1.16.6
 MAGE_X_YAMLFMT_VERSION=v0.21.0

.github/env/10-pre-commit.env

@@ -26,7 +26,7 @@
 # 🪝 PRE-COMMIT TOOL VERSION
 # ================================================================================================
 
-GO_PRE_COMMIT_VERSION=v1.9.1
+GO_PRE_COMMIT_VERSION=v1.10.0
 GO_PRE_COMMIT_USE_LOCAL=false
 
 # ================================================================================================

.github/env/10-security.env

@@ -7,9 +7,10 @@
 #
 # This file defines configuration for security scanning tools used by go-fortress:
 # - Gitleaks: Secret and credential scanning
-# - Nancy: Dependency vulnerability scanning via OSS Index
+# - Nancy: Dependency vulnerability scanning via OSS Index (DEPRECATED — disabled)
 # - Govulncheck: Go-specific vulnerability detection
-# - CVE exclusion lists for known acceptable vulnerabilities
+# - OSV-Scanner: Multi-source dependency scanning via the OSV.dev database
+# - Shared vulnerability exclusion list (GO-*, GHSA-*, and CVE-* advisory IDs) for known acceptable vulnerabilities
 #
 # Override in: 90-project.env for project-specific security settings
 #
@@ -32,34 +33,55 @@ GITLEAKS_NOTIFY_USER_LIST=@mrz1836
 GITLEAKS_CONFIG_FILE=
 
 # ================================================================================================
-# 🛡️ NANCY CONFIGURATION
+# 🚫 SHARED VULNERABILITY EXCLUSIONS (single source of truth)
 # ================================================================================================
-
-# Nancy CVE Exclusions (known acceptable vulnerabilities)
-# Format: comma-separated CVE IDs (e.g., CVE-9999-12345,CVE-9999-43210)
-# These are example/fake CVEs - replace with real ones as needed
-NANCY_EXCLUDES=CVE-9999-12345,CVE-9999-43210
-
-# OSS Index Authentication for Nancy (optional, reduces rate limits)
-# Set OSSI_USERNAME and OSSI_TOKEN in GitHub Secrets
-# Get your API token from: https://ossindex.sonatype.org/user-token
-# OSSI_USERNAME should be your email address
+#
+# ONE list of advisory IDs to exclude across ALL dependency scanners. Maintain it here (or
+# override in 90-project.env); the CI workflow adapts it to each tool's native mechanism:
+#   - govulncheck : exported as MAGE_X_CVE_EXCLUDES for `magex deps:audit`
+#   - OSV-Scanner : rendered into an osv-scanner.toml `[[IgnoredVulns]]` config (--config)
+#   - Nancy       : passed to `nancy sleuth --exclude-vulnerability`
+#
+# Format: comma-separated advisory IDs. Use each tool's native namespace as appropriate —
+# each scanner silently ignores IDs outside its own namespace:
+#   - Go vuln DB / OSV IDs -> GO-YYYY-NNNN    (govulncheck, OSV-Scanner)
+#   - GitHub advisories    -> GHSA-xxxx-...    (OSV-Scanner)
+#   - CVE IDs              -> CVE-YYYY-NNNN    (OSV-Scanner, Nancy)
+#
+# Keep this DEFAULT EMPTY. Add real, justified exclusions in 90-project.env with a comment
+# explaining why each is acceptable (unreachable, unmaintained-but-unused, already patched…).
+SECURITY_VULN_EXCLUDES=
+#
+# Backwards compatibility: the legacy per-tool variables MAGE_X_CVE_EXCLUDES (govulncheck)
+# and NANCY_EXCLUDES (Nancy) are still honored — the workflow merges them into the effective
+# exclusion list. Projects that already set them keep working; new projects should prefer the
+# single SECURITY_VULN_EXCLUDES above. Define the legacy vars only if you need them.
 
 # ================================================================================================
-# 🔐 GOVULNCHECK CONFIGURATION
+# 🛰️ OSV-SCANNER CONFIGURATION
 # ================================================================================================
-
-# Govulncheck/Magex CVE Exclusions (known acceptable vulnerabilities)
-# Format: comma-separated CVE IDs (e.g., CVE-9999-12345,CVE-9999-43210)
-# Used by: magex deps:audit (govulncheck)
-# Can also be passed via: magex deps:audit exclude=CVE-9999-12345
-# These are example/fake CVEs - replace with real ones as needed
-MAGE_X_CVE_EXCLUDES=CVE-9999-12345,CVE-9999-43210
+#
+# OSV-Scanner (https://github.com/google/osv-scanner) scans Go dependencies against the
+# OSV.dev database (aggregates GHSA, the Go vuln DB, and 30+ other advisory sources).
+# Free, no account/API key required. Results are uploaded to GitHub Code Scanning as SARIF.
+#
+# Enforcement mode (default: enforcing):
+#   true   = fail the security job when affecting vulnerabilities are found (enforcing gate).
+#   false  = report only (findings still appear in Code Scanning + job summary, CI passes).
+# Only an *affecting* finding (OSV exit 1) can fail CI; infrastructure errors
+# (network / OSV.dev / DB) are ALWAYS inconclusive and never fail CI.
+#
+# This is ON by default for all projects. To make OSV report-only for a specific repo,
+# override in that repo's 90-project.env: OSV_SCANNER_FAIL_ON_VULNERABILITY=false
+OSV_SCANNER_FAIL_ON_VULNERABILITY=true
 
 # ================================================================================================
 # 🛠️ SECURITY TOOL VERSIONS
 # ================================================================================================
 
 GITLEAKS_VERSION=8.30.1
 GOVULNCHECK_VERSION=v1.1.4
-NANCY_VERSION=v1.2.0
+NANCY_VERSION=v2.1.0
+# OSV-Scanner: pin to a validated release (v2.5.0 released 2026-08-07; v2.4.0 is the
+# prior stable). Installed via `go install github.com/google/osv-scanner/v2/...`.
+OSV_SCANNER_VERSION=v2.5.0

.github/tech-conventions/commit-branch-conventions.md

@@ -34,8 +34,15 @@ docs(README): improve installation instructions
 To ensure consistent commit messages and code quality, we use the external **go-pre-commit** tool that checks formatting, linting, and other standards before allowing a commit. The system is configured via `.github/env/` and can be installed with:
 
 ```bash
-# Install the external tool
-go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
+# Install the latest release binary into ~/.local/bin, verified against checksums.txt
+VER=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/mrz1836/go-pre-commit/releases/latest | sed 's#.*/v##')
+OS=$(uname -s | tr '[:upper:]' '[:lower:]'); ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
+F="go-pre-commit_${VER}_${OS}_${ARCH}.tar.gz"; U="https://github.com/mrz1836/go-pre-commit/releases/download/v${VER}"
+mkdir -p ~/.local/bin && cd "$(mktemp -d)" && curl -fsSLO "$U/$F" \
+  && WANT=$(curl -fsSL "$U/go-pre-commit_${VER}_checksums.txt" | awk -v f="$F" '$2==f{print $1}') \
+  && GOT=$( { command -v sha256sum >/dev/null && sha256sum "$F" || shasum -a 256 "$F"; } | awk '{print $1}') \
+  && [ -n "$WANT" ] && [ "$WANT" = "$GOT" ] \
+  && tar -xzf "$F" -C ~/.local/bin go-pre-commit
 
 # Install hooks in your repository
 go-pre-commit install

.github/tech-conventions/pre-commit.md

@@ -29,8 +29,15 @@
 ### Installation
 
 ```bash
-# Install the go-pre-commit tool
-go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
+# Install the latest go-pre-commit release into ~/.local/bin (user-writable, no sudo), verified against checksums.txt
+VER=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/mrz1836/go-pre-commit/releases/latest | sed 's#.*/v##')
+OS=$(uname -s | tr '[:upper:]' '[:lower:]'); ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
+F="go-pre-commit_${VER}_${OS}_${ARCH}.tar.gz"; U="https://github.com/mrz1836/go-pre-commit/releases/download/v${VER}"
+mkdir -p ~/.local/bin && cd "$(mktemp -d)" && curl -fsSLO "$U/$F" \
+  && WANT=$(curl -fsSL "$U/go-pre-commit_${VER}_checksums.txt" | awk -v f="$F" '$2==f{print $1}') \
+  && GOT=$( { command -v sha256sum >/dev/null && sha256sum "$F" || shasum -a 256 "$F"; } | awk '{print $1}') \
+  && [ -n "$WANT" ] && [ "$WANT" = "$GOT" ] \
+  && tar -xzf "$F" -C ~/.local/bin go-pre-commit
 
 # Install hooks in your repository
 cd your-go-project
@@ -40,6 +47,10 @@ go-pre-commit install
 go-pre-commit --version
 ```
 
+> `~/.local/bin` must be on your `PATH` — add `export PATH="$HOME/.local/bin:$PATH"` to
+> your shell profile if `go-pre-commit` isn't found. Installing the release binary into a
+> user-writable directory also lets `go-pre-commit update` self-update it in place later.
+
 ### First Usage
 
 ```bash
@@ -241,10 +252,10 @@ The project has migrated from the embedded GoFortress pre-commit system (`.githu
 
 | Aspect           | Old (Embedded)                             | New (External)                                                         |
 |------------------|--------------------------------------------|------------------------------------------------------------------------|
-| **Location**     | `.github/pre-commit/gofortress-pre-commit` | `go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest` |
+| **Location**     | `.github/pre-commit/gofortress-pre-commit` | Release binary in `~/.local/bin` (see [Installation](#installation))    |
 | **Installation** | `cd .github/pre-commit && magex build`     | `go-pre-commit install`                                                |
 | **Maintenance**  | Part of repository                         | External tool, versioned independently                                 |
-| **Updates**      | Manual code updates                        | `go install` latest version                                            |
+| **Updates**      | Manual code updates                        | `go-pre-commit update`                                                 |
 | **Distribution** | Repository-specific                        | Reusable across Go projects                                            |
 
 ### Migration Steps
@@ -257,10 +268,7 @@ The project has migrated from the embedded GoFortress pre-commit system (`.githu
 
 2. **Install new system**:
    ```bash
-   # Install external tool
-   go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
-
-   # Install hooks
+   # Install the go-pre-commit release binary (see Installation above), then:
    go-pre-commit install
    ```
 
@@ -295,12 +303,9 @@ The project has migrated from the embedded GoFortress pre-commit system (`.githu
 
 ```bash
 # "go-pre-commit not found"
-# Fix: Ensure GOPATH/bin is in your PATH
-echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
+# Fix: Ensure the install directory (~/.local/bin) is in your PATH
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
 source ~/.bashrc
-
-# Alternative: Install to a directory in your PATH
-go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
 ```
 
 **Hook Issues:**
@@ -379,17 +384,24 @@ magex tidy      # Test mod-tidy integration
 
 **Developer Onboarding:**
 ```bash
-# Include in developer setup scripts
-go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
+# Include in developer setup scripts (installs the verified release binary into ~/.local/bin)
+VER=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/mrz1836/go-pre-commit/releases/latest | sed 's#.*/v##')
+OS=$(uname -s | tr '[:upper:]' '[:lower:]'); ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
+F="go-pre-commit_${VER}_${OS}_${ARCH}.tar.gz"; U="https://github.com/mrz1836/go-pre-commit/releases/download/v${VER}"
+mkdir -p ~/.local/bin && cd "$(mktemp -d)" && curl -fsSLO "$U/$F" \
+  && WANT=$(curl -fsSL "$U/go-pre-commit_${VER}_checksums.txt" | awk -v f="$F" '$2==f{print $1}') \
+  && GOT=$( { command -v sha256sum >/dev/null && sha256sum "$F" || shasum -a 256 "$F"; } | awk '{print $1}') \
+  && [ -n "$WANT" ] && [ "$WANT" = "$GOT" ] \
+  && tar -xzf "$F" -C ~/.local/bin go-pre-commit
 go-pre-commit install
 ```
 
 ### Maintenance
 
 **Regular Updates:**
 ```bash
-# Update go-pre-commit itself
-go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
+# Update go-pre-commit itself (self-update; alias: upgrade)
+go-pre-commit update
 
 # Update tool versions in 10-pre-commit.env
 GO_PRE_COMMIT_GOLANGCI_LINT_VERSION=v2.6.0
@@ -414,7 +426,7 @@ go-pre-commit transforms the pre-commit experience for Go projects by providing:
 The migration from the embedded GoFortress system to the external tool provides better maintainability and reusability while preserving all performance benefits.
 
 **Next Steps:**
-1. Install go-pre-commit: `go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest`
+1. Install go-pre-commit: download the release binary (see [Installation](#installation))
 2. Set up hooks: `go-pre-commit install`
 3. Verify with: `go-pre-commit run --all-files`
 4. Start enjoying faster, more reliable pre-commit checks

.github/workflows/codeql-analysis.yml

@@ -49,7 +49,7 @@ jobs:
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@f205ea1c3313d32999d8d6a48b4f6530d4437b38 # v4.37.4
+        uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -60,7 +60,7 @@ jobs:
       # Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@f205ea1c3313d32999d8d6a48b4f6530d4437b38 # v4.37.4
+        uses: github/codeql-action/autobuild@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -70,4 +70,4 @@ jobs:
       #    uses a compiled language
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@f205ea1c3313d32999d8d6a48b4f6530d4437b38 # v4.37.4
+        uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6