Security: npm audit, Dependabot, Trivy, CodeQL, OSV Scanner + Node 24 + v2.5.2 (#20)

## Summary

Adds free GitHub security scanning to the pipeline and upgrades the
runtime to Node 24. Releases as **v2.5.2**.

### Security scanning (new)

- **`npm audit`** — added to `functional-tests.yml` after `npm ci`.
Blocks the `test` check on HIGH or CRITICAL CVEs using the npm advisory
database.
- **OSV Scanner** (`google/osv-scanner-action@v2.3.3`) — added to
`functional-tests.yml` after `npm audit`. Scans all `package-lock.json`
files recursively against the OSV/NIST database — the same source Trivy
uses for npm packages — so vulnerabilities are caught at the fast test
stage rather than waiting for the full Docker build and image scan.
- **Dependabot** — new `.github/dependabot.yml`. Daily checks for npm
packages across all three package roots (`/`, `/packages/core`,
`/packages/stdio`) and all GitHub Actions versions. Security alerts are
real-time regardless of schedule.
- **Trivy image scanning** — added to `docker-publish.yml` in two
places:
- Inside `pre-merge-cd-check` (PR gate): scans `:pr-{n}-amd64`;
CRITICAL+HIGH reported to Security tab via SARIF; CRITICAL with a fix
available blocks the PR.
- New `scan` job between `verify` and `merge` (post-merge gate): scans
`:latest-amd64` before manifest tags and git tag are created; CRITICAL
blocks the release.
- **CodeQL** — new `.github/workflows/codeql.yml`. Semantic TypeScript
analysis (`language: javascript`, `build-mode: none`). Runs on PRs, push
to main, and weekly.

### Bug fix: Trivy env-var pollution

`trivy-action` exports `TRIVY_FORMAT` and `TRIVY_OUTPUT` into
`$GITHUB_ENV`. When the blocking step specifies `format: table` (the
action default), the action skips overwriting those vars, so the SARIF
step values bleed in — causing the blocking step to run in SARIF mode
and fail on HIGH findings instead of CRITICAL only.

**Fix:** replaced both "Fail on CRITICAL" `trivy-action` steps with
plain `run:` steps invoking the `trivy` binary directly. CLI flags
always override environment variables.

### Node 24 upgrade

- Docker base image upgraded from `node:20-alpine` to `node:24-alpine`.
Node 20 reaches EOL April 2026; Node 24 has been Active LTS since
October 2025. Node 24 ships with npm 11 which has updated bundled
dependencies, resolving the HIGH CVEs Trivy was detecting in the Docker
image (`tar`, `glob`, `minimatch`, `cross-spawn`).
- CI `node-version` updated from `20` to `24` to match.

### Dependency fixes

- **HIGH** (npm audit fix): patched `@modelcontextprotocol/sdk`
(GHSA-345p-7cg4-v4c7) and `rollup` (GHSA-mw96-cpmx-2vgc).
- **MODERATE** (OSV Scanner / npm audit fix --force): upgraded `vitest`
`3.x` → `4.x` to resolve the `esbuild`/`vite`/`vitest` chain
(GHSA-67mh-4wv8-2f99). Build and type-check pass cleanly on vitest v4.
- `ignore-unfixed: true` on all Trivy steps — OS-level Alpine CVEs with
no patch available do not block the pipeline.

## Post-merge: GitHub Settings to enable

- **Branch protection → required checks:** Add `CodeQL` to required
status checks
- **Security → Secret scanning → Push protection:** Enable to reject
pushes containing detected secrets at the server level (free for public
repos, no workflow change needed)

## Test plan

- [x] `npm audit` passes — 0 vulnerabilities
- [x] OSV Scanner passes — 0 vulnerabilities after vitest v4 upgrade
- [x] Trivy blocking step uses `run:` to avoid env-var pollution
- [x] `pre-merge-cd-check` Trivy SARIF uploaded to Security tab
- [x] CodeQL analysis passes
- [x] Build and type-check clean on Node 24 / vitest v4
- [ ] After merge: `scan` job runs between `verify` and `merge`
- [ ] After merge: v2.5.2 Docker tags published correctly

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Paradoxbound <paradoxbound@paradoxbound.org>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

.github/dependabot.yml

@@ -0,0 +1,35 @@
+version: 2
+
+updates:
+  # Root workspace (covers shared devDependencies)
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: daily
+    labels:
+      - dependencies
+
+  # packages/core — BookStack API client
+  - package-ecosystem: npm
+    directory: /packages/core
+    schedule:
+      interval: daily
+    labels:
+      - dependencies
+
+  # packages/stdio — MCP stdio server (published package)
+  - package-ecosystem: npm
+    directory: /packages/stdio
+    schedule:
+      interval: daily
+    labels:
+      - dependencies
+
+  # GitHub Actions — keep action versions up to date
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: daily
+    labels:
+      - dependencies
+      - github-actions

.github/workflows/codeql.yml

@@ -0,0 +1,37 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Weekly scan on Sunday at midnight UTC — catches newly published CVEs
+    # against existing code between releases.
+    - cron: '0 0 * * 0'
+
+jobs:
+  analyze:
+    name: CodeQL
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # GitHub uses "javascript" as the CodeQL language identifier for both
+      # JavaScript and TypeScript.  build-mode: none means CodeQL analyses
+      # the source directly without needing a compilation step.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: javascript
+          build-mode: none
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: codeql

.github/workflows/docker-publish.yml

@@ -122,7 +122,60 @@ jobs:
           echo "arm64_digest=${ARM64_DIGEST}" >> "$GITHUB_OUTPUT"
 
   # ─────────────────────────────────────────────────────────────────────────────
-  # JOB 3 — merge
+  # JOB 3 — scan
+  # Scans the verified amd64 image for vulnerabilities before the release tags
+  # and git tag are created.  CRITICAL findings block the release.
+  # HIGH findings are reported to the Security tab but do not block.
+  # ─────────────────────────────────────────────────────────────────────────────
+  scan:
+    runs-on: ubuntu-latest
+    needs: verify
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      packages: read
+      security-events: write
+
+    steps:
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Scan image for vulnerabilities (Trivy)
+        uses: aquasecurity/trivy-action@0.30.0
+        with:
+          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest-amd64
+          format: sarif
+          output: trivy-release.sarif
+          severity: CRITICAL,HIGH
+          ignore-unfixed: true
+          exit-code: '0'
+
+      - name: Upload Trivy SARIF to Security tab
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: trivy-release.sarif
+          category: trivy-release
+
+      # Run trivy directly so CLI flags override any TRIVY_* env vars leaked
+      # from the SARIF step above (trivy-action exports env vars that persist
+      # across steps; a second trivy-action invocation cannot fully override them).
+      - name: Fail release on CRITICAL vulnerabilities
+        run: |
+          trivy image \
+            --format table \
+            --severity CRITICAL \
+            --ignore-unfixed \
+            --exit-code 1 \
+            --cache-dir .cache/trivy \
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest-amd64
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # JOB 4 — merge
   # Creates multi-arch manifest lists from the verified arch images and applies
   # all version tags.  Version is read from packages/stdio/package.json — the
   # canonical, published package — not the private root package.json.
@@ -131,7 +184,7 @@ jobs:
   # ─────────────────────────────────────────────────────────────────────────────
   merge:
     runs-on: ubuntu-latest
-    needs: verify
+    needs: scan
     if: github.event_name != 'pull_request'
     permissions:
       contents: write
@@ -283,13 +336,19 @@ jobs:
   # images that were pushed during this run so the registry is left in the same
   # state as the last successful release.
   # ─────────────────────────────────────────────────────────────────────────────
+  # ─────────────────────────────────────────────────────────────────────────────
+  # JOB 5 — cleanup
+  # Runs only when the verify, scan, or merge job fails.  Deletes any arch-
+  # suffixed images that were pushed during this run so the registry is left
+  # in the same state as the last successful release.
+  # ─────────────────────────────────────────────────────────────────────────────
   cleanup:
     runs-on: ubuntu-latest
-    needs: [verify, merge]
+    needs: [verify, scan, merge]
     if: |
       always() &&
       github.event_name != 'pull_request' &&
-      (needs.verify.result == 'failure' || needs.merge.result == 'failure')
+      (needs.verify.result == 'failure' || needs.scan.result == 'failure' || needs.merge.result == 'failure')
     permissions:
       contents: read
       packages: write
@@ -366,6 +425,7 @@ jobs:
     permissions:
       contents: read
       packages: write
+      security-events: write
 
     steps:
       - name: Checkout
@@ -424,6 +484,39 @@ jobs:
             echo "${arch} digest: ${DIGEST}"
           done
 
+      # Scan the PR amd64 image for vulnerabilities.
+      # HIGH + CRITICAL are reported to the GitHub Security tab via SARIF.
+      # CRITICAL findings fail the PR check; HIGH are informational only.
+      - name: Scan PR image for vulnerabilities (Trivy)
+        uses: aquasecurity/trivy-action@0.30.0
+        with:
+          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:pr-${{ github.event.pull_request.number }}-amd64
+          format: sarif
+          output: trivy-pr.sarif
+          severity: CRITICAL,HIGH
+          ignore-unfixed: true
+          exit-code: '0'
+
+      - name: Upload Trivy SARIF to Security tab
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: trivy-pr.sarif
+          category: trivy-pr
+
+      # Run trivy directly so CLI flags override any TRIVY_* env vars leaked
+      # from the SARIF step above (trivy-action exports env vars that persist
+      # across steps; a second trivy-action invocation cannot fully override them).
+      - name: Fail PR on CRITICAL vulnerabilities
+        run: |
+          trivy image \
+            --format table \
+            --severity CRITICAL \
+            --ignore-unfixed \
+            --exit-code 1 \
+            --cache-dir .cache/trivy \
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:pr-${{ github.event.pull_request.number }}-amd64
+
       # Create a test multi-arch manifest and confirm it is pullable.
       - name: Create and verify PR test manifest
         run: |

.github/workflows/functional-tests.yml

@@ -17,10 +17,20 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
 
       - run: npm ci
 
+      - name: Audit dependencies (npm)
+        run: npm audit --audit-level=high
+
+      - name: Scan dependencies (OSV)
+        uses: google/osv-scanner-action/osv-scanner-action@v2.3.3
+        with:
+          scan-args: |-
+            --recursive
+            ./
+
       - name: Build
         run: npm run build
 

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:20-alpine AS build
+FROM node:24-alpine AS build
 
 WORKDIR /app
 
@@ -11,7 +11,7 @@ COPY packages/core/ packages/core/
 COPY packages/stdio/ packages/stdio/
 RUN npm run build
 
-FROM node:20-alpine
+FROM node:24-alpine
 
 WORKDIR /app