doc: update output formats doc + normalize json to bool

built from commit e2d110a3b5
 dated 2026-04-20 12:47:43 +0200
 by Stéphane Lesimple (speed47_github@speed47.net)

.github/workflows/autoupdate.yml

@@ -1,36 +0,0 @@
-name: autoupdate
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: '42 9 * * *'
-
-permissions:
-  pull-requests: write
-
-jobs:
-  autoupdate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Install prerequisites
-        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends iucode-tool sqlite3 unzip
-      - name: Update microcode versions
-        run: ./spectre-meltdown-checker.sh --update-builtin-fwdb
-      - name: Check git diff
-        id: diff
-        run: |
-          echo change="$(git diff spectre-meltdown-checker.sh | awk '/MCEDB/ { if(V) { print V" to "$4; exit } else { V=$4 } }')" >> "$GITHUB_OUTPUT"
-          echo nbdiff="$(git diff spectre-meltdown-checker.sh | grep -cE -- '^\+# [AI],')" >> "$GITHUB_OUTPUT"
-          git diff
-          cat "$GITHUB_OUTPUT"
-      - name: Create Pull Request if needed
-        if: steps.diff.outputs.nbdiff != '0'
-        uses: peter-evans/create-pull-request@v7
-        with:
-          branch: autoupdate-fwdb
-          commit-message: "update: fwdb from ${{ steps.diff.outputs.change }}, ${{ steps.diff.outputs.nbdiff }} microcode changes"
-          title: "[Auto] Update fwdb from ${{ steps.diff.outputs.change }}"
-          body: |
-            Automated PR to update fwdb from ${{ steps.diff.outputs.change }}
-            Detected ${{ steps.diff.outputs.nbdiff }} microcode changes

.github/workflows/build.yml

@@ -25,21 +25,81 @@ jobs:
         mv spectre-meltdown-checker.sh dist/
     - name: check direct execution
       run: |
+        set -x
         expected=$(cat .github/workflows/expected_cve_count)
         cd dist
-        nb=$(sudo ./spectre-meltdown-checker.sh --batch json | jq '.[]|.CVE' | wc -l)
+
+        json=$(sudo ./spectre-meltdown-checker.sh --batch json || true)
+
+        # Validate JSON is well-formed (and show it if not)
+        echo "$json" | jq . >/dev/null || {
+          echo "Invalid JSON produced by spectre-meltdown-checker.sh"
+          echo "$json"
+          exit 1
+        }
+
+        # Validate required keys exist
+        for key in meta system cpu cpu_microcode vulnerabilities; do
+          echo "$json" | jq -e ".$key" >/dev/null || {
+            echo "Missing top-level key: $key"
+            echo "$json" | jq .
+            exit 1
+          }
+        done
+
+        # Use -r to get raw scalars (no quotes)
+        fmtver=$(echo "$json" | jq -r '.meta.format_version // empty')
+        if [ "$fmtver" != "1" ]; then
+          echo "Unexpected format_version: $fmtver"
+          echo "$json" | jq .
+          exit 1
+        fi
+
+        run_as_root=$(echo "$json" | jq -r '.meta.run_as_root // empty')
+        if [ "$run_as_root" != "true" ]; then
+          echo "Expected run_as_root=true, got: $run_as_root"
+          echo "$json" | jq .
+          exit 1
+        fi
+
+        mocked=$(echo "$json" | jq -r '.meta.mocked // "false"')
+        if [ "$mocked" = "true" ]; then
+          echo "mocked=true must never appear in production"
+          echo "$json" | jq .
+          exit 1
+        fi
+
+        # Count CVEs robustly (as a number)
+        nb=$(echo "$json" | jq -r '[.vulnerabilities[].cve] | length')
         if [ "$nb" -ne "$expected" ]; then
           echo "Invalid number of CVEs reported: $nb instead of $expected"
+          echo "$json" | jq '.vulnerabilities[].cve'
           exit 1
         else
           echo "OK $nb CVEs reported"
         fi
+
+        # Validate json-terse backward compatibility
+        nb_terse=$(sudo ./spectre-meltdown-checker.sh --batch json-terse | jq -r 'map(.CVE) | length')
+        if [ "$nb_terse" -ne "$expected" ]; then
+          echo "json-terse backward compat broken: $nb_terse CVEs instead of $expected"
+          exit 1
+        else
+          echo "OK json-terse backward compat: $nb_terse CVEs"
+        fi
     - name: check docker compose run execution
       run: |
         expected=$(cat .github/workflows/expected_cve_count)
         cd dist
         docker compose build
-        nb=$(docker compose run --rm spectre-meltdown-checker --batch json | jq '.[]|.CVE' | wc -l)
+        json=$(docker compose run --rm spectre-meltdown-checker --batch json || true)
+        echo "$json" | jq . > /dev/null
+        fmtver=$(echo "$json" | jq '.meta.format_version')
+        if [ "$fmtver" != "1" ]; then
+          echo "Unexpected format_version: $fmtver"
+          exit 1
+        fi
+        nb=$(echo "$json" | jq '.vulnerabilities[].cve' | wc -l)
         if [ "$nb" -ne "$expected" ]; then
           echo "Invalid number of CVEs reported: $nb instead of $expected"
           exit 1
@@ -51,7 +111,14 @@ jobs:
         expected=$(cat .github/workflows/expected_cve_count)
         cd dist
         docker build -t spectre-meltdown-checker .
-        nb=$(docker run --rm --privileged -v /boot:/boot:ro -v /dev/cpu:/dev/cpu:ro -v /lib/modules:/lib/modules:ro spectre-meltdown-checker --batch json | jq '.[]|.CVE' | wc -l)
+        json=$(docker run --rm --privileged -v /boot:/boot:ro -v /dev/cpu:/dev/cpu:ro -v /lib/modules:/lib/modules:ro spectre-meltdown-checker --batch json || true)
+        echo "$json" | jq . > /dev/null
+        fmtver=$(echo "$json" | jq '.meta.format_version')
+        if [ "$fmtver" != "1" ]; then
+          echo "Unexpected format_version: $fmtver"
+          exit 1
+        fi
+        nb=$(echo "$json" | jq '.vulnerabilities[].cve' | wc -l)
         if [ "$nb" -ne "$expected" ]; then
           echo "Invalid number of CVEs reported: $nb instead of $expected"
           exit 1
@@ -92,15 +159,19 @@ jobs:
         fi
     - name: create a pull request to ${{ github.ref_name }}-build
       run: |
+        # all the files in dist/* and .github/* must be moved as is to the -build branch root, move them out for now:
         tmpdir=$(mktemp -d)
         mv ./dist/* .github $tmpdir/
         rm -rf ./dist
+
         git fetch origin ${{ github.ref_name }}-build
         git checkout -f ${{ github.ref_name }}-build
+        rm -rf doc/
         mv $tmpdir/* .
-        rm -rf src/
+        rm -rf src/ scripts/ img/
         mkdir -p .github
         rsync -vaP --delete $tmpdir/.github/ .github/
+
         git add --all
         echo =#=#= DIFF CACHED
         git diff --cached

.github/workflows/expected_cve_count

@@ -1 +1 @@
-26
+32

.github/workflows/stale.yml

@@ -1,33 +0,0 @@
-name: 'Manage stale issues and PRs'
-
-on:
-  schedule:
-    - cron: '37 7 * * *'
-  workflow_dispatch:
-    inputs:
-      action:
-        description: "dry-run"
-        required: true
-        default: "dryrun"
-        type: choice
-        options:
-          - dryrun
-          - apply
-
-permissions:
-  issues: write
-  pull-requests: write
-
-jobs:
-  stale:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/stale@v10
-        with:
-          any-of-labels: 'needs-more-info,answered'
-          labels-to-remove-when-unstale: 'needs-more-info,answered'
-          days-before-stale: 30
-          days-before-close: 7
-          stale-issue-label: stale
-          remove-stale-when-updated: true
-          debug-only: ${{ case(inputs.action == 'dryrun', true, false) }}

.github/workflows/vuln-watch.yml

@@ -1,190 +0,0 @@
-name: Online search for vulns
-
-on:
-  schedule:
-    - cron: '42 8 * * *'
-  workflow_dispatch:
-    inputs:
-      model:
-        description: 'Claude model to use (cron runs default to Sonnet)'
-        required: false
-        type: choice
-        default: claude-sonnet-4-6
-        options:
-          - claude-sonnet-4-6
-          - claude-opus-4-7
-          - claude-haiku-4-5-20251001
-      window_hours:
-        description: 'Lookback window in hours (cron runs use 25)'
-        required: false
-        type: string
-        default: '25'
-      reconsider_age_days:
-        description: 'Only reconsider backlog entries last reviewed ≥ N days ago (0 = all, default 7)'
-        required: false
-        type: string
-        default: '7'
-
-permissions:
-  contents: read
-  actions: read           # needed to list/download previous run artifacts
-  id-token: write         # needed by claude-code-action for OIDC auth
-
-concurrency:
-  group: vuln-watch
-  cancel-in-progress: true
-
-jobs:
-  watch:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-
-    steps:
-      # The scripts driving this workflow live on the `vuln-watch` branch so
-      # they don't clutter master (which is what ships to production). The
-      # workflow file itself MUST stay on the default branch, as GitHub only
-      # honors `schedule:` triggers on the default branch.
-      - name: Checkout vuln-watch branch (scripts + prompt)
-        uses: actions/checkout@v5
-        with:
-          ref: vuln-watch
-          fetch-depth: 1
-          persist-credentials: false
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-
-      - name: Install Python dependencies
-        run: python -m pip install --quiet feedparser
-
-      # ---- Load previous state ---------------------------------------------
-      # Find the most recent successful run of THIS workflow (other than the
-      # current one) and pull its `vuln-watch-state` artifact. On the very
-      # first run there will be none — that's fine, we start empty.
-      - name: Find previous successful run id
-        id: prev
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -e
-          run_id=$(gh run list \
-            --workflow="${{ github.workflow }}" \
-            --status=success \
-            --limit 1 \
-            --json databaseId \
-            --jq '.[0].databaseId // empty')
-          echo "run_id=${run_id}" >> "$GITHUB_OUTPUT"
-          if [ -n "$run_id" ]; then
-            echo "Found previous successful run: $run_id"
-          else
-            echo "No previous successful run — starting from empty state."
-          fi
-
-      - name: Download previous state artifact
-        if: steps.prev.outputs.run_id != ''
-        uses: actions/download-artifact@v5
-        continue-on-error: true   # tolerate retention expiry
-        with:
-          name: vuln-watch-state
-          path: state/
-          run-id: ${{ steps.prev.outputs.run_id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-
-      # ---- Fetch + diff (token-free; runs every time) ---------------------
-      # Performs conditional GETs (ETag / If-Modified-Since) against every
-      # source, parses RSS/Atom/HTML, dedups against state.seen + state.aliases,
-      # applies the time-window filter, and emits new_items.json.
-      # Updates state.sources (HTTP cache metadata + per-source high-water
-      # marks) in place so the cache survives even when Claude doesn't run.
-      - name: Fetch + diff all sources
-        id: diff
-        env:
-          SCAN_DATE: ${{ github.run_started_at }}
-          # Cron runs have no `inputs` context, so the fallback kicks in.
-          WINDOW_HOURS:         ${{ inputs.window_hours || '25' }}
-          RECONSIDER_AGE_DAYS:  ${{ inputs.reconsider_age_days || '7' }}
-        run: python -m scripts.vuln_watch.fetch_and_diff
-
-      # ---- Fetch checker code so Claude can grep it for coverage ---------
-      # The orphan vuln-watch branch has none of the actual checker code,
-      # so we pull the `test` branch (the dev branch where coded-but-
-      # unreleased CVE checks live) into ./checker/. The prompt tells
-      # Claude this is the canonical source of truth for "is CVE-X already
-      # implemented?". Only fetched on days with something to classify.
-      - name: Checkout checker code (test branch) for coverage grep
-        if: steps.diff.outputs.new_count != '0' || steps.diff.outputs.reconsider_count != '0'
-        uses: actions/checkout@v5
-        with:
-          ref: test
-          path: checker
-          fetch-depth: 1
-          persist-credentials: false
-
-      # ---- Classify new items with Claude (skipped when nothing is new) ---
-      # Model selection: a manual workflow_dispatch run picks from a dropdown
-      # (defaulting to Sonnet). Scheduled cron runs have no `inputs` context,
-      # so the `|| 'claude-sonnet-4-6'` fallback kicks in — cron always uses
-      # Sonnet to keep the daily cost floor low.
-      - name: Run classifier with Claude
-        id: classify
-        if: steps.diff.outputs.new_count != '0' || steps.diff.outputs.reconsider_count != '0'
-        uses: anthropics/claude-code-action@v1
-        env:
-          SCAN_DATE: ${{ github.run_started_at }}
-        with:
-          prompt: |
-            Read the full task instructions from scripts/daily_vuln_watch_prompt.md
-            and execute them end-to-end. Your input is new_items.json (already
-            deduped, windowed, and pre-filtered — do NOT re-fetch sources).
-            Write the three watch_${TODAY}_*.md files and classifications.json.
-            Use $SCAN_DATE as the canonical timestamp.
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          # model + tool allowlist pass through claude_args (v1 dropped the
-          # dedicated `model:` and `allowed_tools:` inputs). Job-level
-          # `timeout-minutes: 20` above bounds total runtime.
-          claude_args: |
-            --model ${{ inputs.model || 'claude-sonnet-4-6' }}
-            --allowedTools "Read,Write,Edit,Bash,Grep,Glob,WebFetch"
-
-      - name: Upload Claude execution log
-        if: ${{ always() && steps.classify.outputs.execution_file != '' }}
-        uses: actions/upload-artifact@v5
-        with:
-          name: claude-execution-log-${{ github.run_id }}
-          path: ${{ steps.classify.outputs.execution_file }}
-          retention-days: 30
-          if-no-files-found: warn
-
-      # ---- Merge classifications back into state --------------------------
-      # Also writes stub watch_*.md files if the classify step was skipped, so
-      # the report artifact is consistent across runs.
-      - name: Merge classifications into state
-        if: always()
-        env:
-          SCAN_DATE: ${{ github.run_started_at }}
-        run: python -m scripts.vuln_watch.merge_state
-
-      - name: Upload new state artifact
-        if: always()
-        uses: actions/upload-artifact@v5
-        with:
-          name: vuln-watch-state
-          path: state/seen.json
-          retention-days: 90
-          if-no-files-found: error
-
-      - name: Upload daily report
-        if: always()
-        uses: actions/upload-artifact@v5
-        with:
-          name: vuln-watch-report-${{ github.run_id }}
-          path: |
-            watch_*.md
-            current_toimplement.md
-            current_tocheck.md
-            new_items.json
-            classifications.json
-          retention-days: 90
-          if-no-files-found: warn

README.md

@@ -272,23 +272,23 @@ In **Hardware-only** mode, the script only reports CPU information and per-CVE h
 
 - Get the latest version of the script using `curl` *or* `wget`
 
-    ```bash
+```bash
-    curl -L https://meltdown.ovh -o spectre-meltdown-checker.sh
+curl -L https://meltdown.ovh -o spectre-meltdown-checker.sh
-    wget https://meltdown.ovh -O spectre-meltdown-checker.sh
+wget https://meltdown.ovh -O spectre-meltdown-checker.sh
-    ```
+```
 
 - Inspect the script. You never blindly run scripts you downloaded from the Internet, do you?
 
-    ```bash
+```bash
-    vim spectre-meltdown-checker.sh
+vim spectre-meltdown-checker.sh
-    ```
+```
 
 - When you're ready, run the script as root
 
-    ```bash
+```bash
-    chmod +x spectre-meltdown-checker.sh
+chmod +x spectre-meltdown-checker.sh
-    sudo ./spectre-meltdown-checker.sh
+sudo ./spectre-meltdown-checker.sh
-    ```
+```
 
 ### Using a docker container
 

spectre-meltdown-checker.sh

@@ -13,7 +13,7 @@
 #
 # Stephane Lesimple
 #
-VERSION='26.33.0420460'
+VERSION='26.33.0420455'
 
 # --- Common paths and basedirs ---
 readonly VULN_SYSFS_BASE="/sys/devices/system/cpu/vulnerabilities"