.gitea/workflows/test.yaml

@@ -0,0 +1,111 @@
+name: CI Tests
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+    - main
+  workflow_dispatch:
+
+jobs:
+  unit-test:
+    name: JS Unit Tests
+    runs-on: k8s
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Run JS Unit Tests
+      shell: bash
+      run: node --test
+
+  test:
+    name: ${{ matrix.image_set.name }} (sbom=${{ matrix.use_inbuild_sbom }})
+    needs: unit-test
+    runs-on: k8s
+    strategy:
+      fail-fast: false
+      matrix:
+        image_set:
+          # Test 1: Slim images with built-in SBOMs (2 architectures, 15-40 CVEs each)
+        - name: with-inbuild-sbom
+          head_image: debian:bookworm-slim
+          target_image: debian:bullseye-slim
+          architectures: amd64,arm64
+          expect_arch_col: true
+
+          # Test 2: Slim images without built-in SBOMs (1 architecture, 70-120 CVEs each)
+        - name: without-inbuild-sbom
+          head_image: debian:buster-slim
+          target_image: debian:stretch-slim
+          architectures: amd64
+          expect_arch_col: false
+
+          # Test 3: Cross-check (Head has built-in SBOM, Target does not, 15-70 CVEs each)
+        - name: cross-check-mixed-sbom
+          head_image: debian:bookworm-slim
+          target_image: debian:buster-slim
+          architectures: amd64
+          expect_arch_col: false
+
+        use_inbuild_sbom:
+        - 'true'
+        - 'false'
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Test CVE Differential Action
+      uses: ./
+      with:
+        head-image: ${{ matrix.image_set.head_image }}
+        target-image: ${{ matrix.image_set.target_image }}
+        target-branch: main
+        architectures: ${{ matrix.image_set.architectures }}
+        use-inbuild-sbom: ${{ matrix.use_inbuild_sbom }}
+        output-delta: cve-delta.md
+        output-summary: cve-summary.md
+
+    - name: Verify Report Generation & Content
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        test -s cve-delta.md || (echo "::error::cve-delta.md is empty or missing" && exit 1)
+        test -s cve-summary.md || (echo "::error::cve-summary.md is empty or missing" && exit 1)
+
+        # Verify that each scan produced at least 3 CVE findings
+        cve_count=$(grep -c "CVE-" cve-summary.md || echo 0)
+        echo "Total CVE entries found in summary report: $cve_count"
+        if [ "$cve_count" -lt 3 ]; then
+          echo "::error::Expected at least 3 CVEs in cve-summary.md, found only $cve_count"
+          exit 1
+        fi
+
+        echo "=== Delta Report Preview ==="
+        head -n 25 cve-delta.md
+
+        # Verify architectural column rendering behavior
+        if [ "${{ matrix.image_set.expect_arch_col }}" = "true" ]; then
+          grep -q "| Arch |" cve-delta.md || (echo "::error::Expected Arch column in multi-arch report" && exit 1)
+        else
+          if grep -q "| Arch |" cve-delta.md; then
+            echo "::error::Did not expect Arch column in single-arch report" && exit 1
+          fi
+        fi
+        echo "✅ All assertions passed (including >= 3 CVEs verification)."
+
+    - name: Archive SBOMs and CVE Reports
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: sboms-and-reports-${{ matrix.image_set.name }}-inbuild-${{ matrix.use_inbuild_sbom }}
+        path: |
+          sboms/
+          cve-reports/
+          cve-delta.md
+          cve-summary.md
+        if-no-files-found: ignore

.gitignore

@@ -13,3 +13,4 @@ cve-*.json
 cve-delta.md
 cve-summary.md
 node_modules/
+!test/fixtures/**

README.md

@@ -7,13 +7,12 @@ A self-contained Gitea and GitHub Actions composite action that extracts multi-p
 ## ✨ Features
 
 - **Dynamic Multi-Platform Support**: Automatically discovers and scans all architectures present in container images, or iterates over an explicit list of target architectures.
-- **Fast Attestation Extraction**: Uses `docker buildx imagetools inspect` to extract platform-specific SBOMs directly from registry manifest indices in seconds without downloading layer blobs.
+- **Fast Attestation Extraction with Automatic Fallback**: Uses `docker buildx imagetools inspect` to extract platform-specific SBOMs directly from registry manifest indices. If attestations are missing or produce 0 CVE findings (common when third-party generators omit OS qualifiers in SPDX), it automatically falls back to generating SBOMs directly with Trivy per architecture.
-- **Graceful Fallbacks**: If SBOM attestations are missing for any platform, automatically falls back to generating SBOMs directly with Trivy per architecture.
 - **Set-Based Differential Analysis**: Categorizes vulnerabilities into:
   - 🔴 **Introduced Vulnerabilities** (newly added in this branch / commit)
   - 🟢 **Fixed Vulnerabilities** (present in target baseline, resolved in this branch)
   - ⚪ **Unchanged Vulnerabilities** (pre-existing in target baseline)
-- **Secure by Default**: Verified Trivy binary downloads against static SHA256 checksum lockfiles and single-step unified caching (binary + vulnerability database).
+- **Secure & Unit Tested**: Verified Trivy binary downloads against static SHA256 checksum lockfiles, single-step unified caching, and comprehensive native unit tests (`node:test`).
 
 ---
 
@@ -28,7 +27,7 @@ A self-contained Gitea and GitHub Actions composite action that extracts multi-p
 | `output-delta` | Output path for the CVE delta Markdown report | No | `cve-delta.md` |
 | `output-summary` | Output path for the full vulnerability Markdown summary | No | `cve-summary.md` |
 | `write-summary` | Whether to append the generated reports to the job summary (`$GITHUB_STEP_SUMMARY`) | No | `true` |
-| `use-inbuild-sbom` | Whether to inspect and use built-in image SBOM attestations. If false, generates SBOMs directly with Trivy | No | `false` |
+| `use-inbuild-sbom` | Whether to inspect and use built-in image SBOM attestations. If false (recommended default), generates SBOMs directly with Trivy for maximum vulnerability fidelity. If true, extracts attestations without pulling layers (faster, but findings reflect binary-package SBOMs without rootfs source-mapping; falls back to Trivy image scan if 0 CVEs detected). | No | `false` |
 
 ---
 
@@ -48,21 +47,36 @@ This action supports two modes for obtaining SBOMs:
 ### 1. Direct Image Scanning with Trivy (`use-inbuild-sbom: false` — Default & Recommended)
 By default, the action uses `trivy image --format spdx-json` to generate the SBOM directly from the container images:
 - **Full Filesystem Fidelity**: Inspects the entire flattened root filesystem, reading `/etc/os-release` and native package databases (e.g. `/var/lib/dpkg/status`, RPM databases, apk).
-- **Accurate OS & Language Package Detection**: Successfully catalogs both OS packages (Debian, Alpine, RHEL, etc.) and application dependencies (Python, Node.js, Go, etc.).
+- **Accurate OS & Language Package Detection**: Catalogs both OS packages (Debian, Alpine, RHEL, etc.) and application dependencies (Python, Node.js, Go, etc.).
 - **Symmetric, Apples-to-Apples Comparisons**: Both `head` and `target` images are analyzed using the identical Trivy engine and vulnerability database, preventing skewed diffs.
 
-### 2. Built-in Attestation Extraction (`use-inbuild-sbom: true`)
+### 2. Built-in Attestation Extraction with Resilient Fallback (`use-inbuild-sbom: true`)
 When enabled, the action extracts SBOM attestations attached to the container image using `docker buildx imagetools inspect`:
 - **Speed**: Extracts the SBOM JSON metadata directly from the registry manifest index in seconds without pulling image layer blobs.
-- **Underlying Generator (Syft)**: Docker Buildx (`sbom: true`) uses BuildKit's embedded Syft scanner (`moby/buildkit-syft-scanner`).
+- **Underlying Generator (Syft / Docker Scout)**: Docker Buildx (`sbom: true`) uses BuildKit's embedded Syft scanner (`moby/buildkit-syft-scanner`).
-- **Known Limitations with Trivy**:
+- **Distro Detection**: Automatically extracts OS distribution information from package PURLs (e.g. `debian/12`) and queries Trivy with `--distro` to accurately identify vulnerabilities on the extracted SBOM.
-  - **Testing/Rolling Distributions**: Embedded Syft versions may not recognize newer or unreleased distributions (such as Debian 13 "Trixie"), recording the OS as `family="none"` and skipping OS package vulnerability matching.
+- **Resilient Fallback**: If an extracted in-build SBOM scan produces 0 CVE findings (a common issue when third-party generators omit OS distribution qualifiers from SPDX packages) or if scanning fails, the action **automatically falls back** to running `trivy image --platform "$platform" --format spdx-json` directly on the image. This guarantees that vulnerability scans never fail silently or report false zeros.
-  - **Multi-Stage Builds**: Analyzing layer diffs rather than the flattened container rootfs can cause package database paths to be omitted or detached from the OS manifest.
+- **Audit Copies**: The action preserves copies of both the raw extracted in-build SBOM (`inbuild-sbom-*.spdx.json`) and the final scanned SBOM (`sbom-*.spdx.json`) for auditing and debugging.
-  - **Schema/PURL Discrepancies**: Syft and Trivy express certain package qualifiers and namespaces differently in SPDX. When Trivy scans a Syft SPDX file that lacks explicit distro qualifiers, Trivy will silently skip OS vulnerability checks.
+
-  - **Differential Skew**: If a `head` image uses an incomplete Syft SBOM (detecting only language packages) while `target` is scanned directly with Trivy (detecting 400+ OS packages), the differential report will erroneously show hundreds of "resolved" CVEs.
+### ⚖️ Trade-offs: Why do the results differ between strategies?
+
+The vulnerability results between Strategy 1 (`sbom: false`) and Strategy 2 (`sbom: true`) are **not identical**:
+
+| Feature / Metric | Direct Trivy Scan (`use-inbuild-sbom: false`) | Built-in Attestation (`use-inbuild-sbom: true`) |
+| :--- | :--- | :--- |
+| **Generator** | Trivy directly on container rootfs | Docker Scout / BuildKit (Syft) |
+| **Execution Speed** | Slower (pulls image layer blobs) | **Very Fast** (~5x faster, 0 layer downloads) |
+| **Debian Slim Findings Example** | **~225 CVEs** (`debian:bookworm-slim`) | **~104 CVEs** (`debian:bookworm-slim`) |
+| **Package Resolution Model** | Source & binary packages (`/var/lib/dpkg/status`) | Binary packages cataloged in SPDX PURLs |
+| **Filesystem Inspection** | Full filesystem (static binaries, libraries) | Manifest-only (packages cataloged at build time) |
+| **Primary Use Case** | **High-fidelity security audits & release gates** | **High-speed PR checks & developer feedback loops** |
+
+#### Why the vulnerability counts differ:
+1. **Debian Source vs. Binary Packages**: Debian security advisories (DSAs / DLAs) are tracked and published per **source package** (e.g., the source package `glibc` produces multiple binary packages like `libc6`, `libc-bin`, `locales`). Trivy's filesystem scanner reads `/var/lib/dpkg/status` to map installed binary packages directly to Debian source package advisories. Syft's default SPDX output catalogs installed binary packages as PURLs without source-package relations, so Trivy's SBOM scan queries only the exact binary package entries that match Debian database schemas without the source-mapping context.
+2. **Filesystem vs. Manifest Scope**: Direct image scanning unpacks and inspects the entire container image filesystem (including file hashes, crypto libraries, and static binaries). An in-build SBOM scan is strictly limited to the package inventory written by the build-time generator.
 
 > [!TIP]
-> If your builds run on stable base images where BuildKit's Syft scanner accurately captures all OS packages, you can set `use-inbuild-sbom: 'true'` to speed up CI runs. Otherwise, leave it as `false` to ensure consistent and comprehensive scans.
+> Setting `use-inbuild-sbom: 'false'` remains the recommended default for maximum accuracy and cross-platform consistency. If you choose to enable `use-inbuild-sbom: 'true'`, the built-in fallback ensures full coverage even when third-party attestations lack OS package metadata.
 
 ---
 

action.yaml

@@ -29,7 +29,7 @@ inputs:
     required: false
     default: 'true'
   use-inbuild-sbom:
-    description: Whether to inspect and use built-in image SBOM attestations. If false, generates SBOM directly from images with Trivy.
+    description: Whether to inspect and use built-in image SBOM attestations. If false (recommended default), generates SBOMs directly with Trivy for maximum vulnerability detection fidelity. If true, extracts attestations without pulling layers (faster, but findings may differ from direct scans due to binary vs source package tracking; falls back to Trivy image scan if 0 CVEs detected).
     required: false
     default: 'false'
 
@@ -158,6 +158,12 @@ runs:
       fi
 
       echo "Configured platforms: ${PLATFORMS[*]:-(single platform fallback)}"
+      if [ "$use_inbuild" = "true" ]; then
+        echo "ℹ️  Strategy: Built-in SBOM attestation extraction enabled (Docker Scout / Syft). Skips container layer downloads for maximum speed."
+        echo "ℹ️  Note: Built-in SBOM vulnerability counts may differ from direct filesystem scans ('trivy image') due to binary vs. source package tracking."
+      else
+        echo "ℹ️  Strategy: Direct Trivy image scanning enabled (default). Inspects full container rootfs and package databases for maximum fidelity."
+      fi
 
       for platform in "${PLATFORMS[@]}"; do
         arch_tag=$(echo "$platform" | sed -e 's#^[a-zA-Z0-9_-]*/##' -e 's#/#-#g')
@@ -168,6 +174,7 @@ runs:
           docker buildx imagetools inspect "${{ inputs.head-image }}" \
             --format "{{ json (index .SBOM \"${platform}\").SPDX }}" > "sboms/head/sbom-${arch_tag}.spdx.json" 2>/dev/null || true
           cleanup_file "sboms/head/sbom-${arch_tag}.spdx.json"
+          [ -f "sboms/head/sbom-${arch_tag}.spdx.json" ] && cp "sboms/head/sbom-${arch_tag}.spdx.json" "sboms/head/inbuild-sbom-${arch_tag}.spdx.json" 2>/dev/null || true
         fi
 
         if [ ! -f "sboms/head/sbom-${arch_tag}.spdx.json" ]; then
@@ -184,6 +191,7 @@ runs:
           docker buildx imagetools inspect "${{ inputs.target-image }}" \
             --format "{{ json (index .SBOM \"${platform}\").SPDX }}" > "sboms/target/sbom-${arch_tag}.spdx.json" 2>/dev/null || true
           cleanup_file "sboms/target/sbom-${arch_tag}.spdx.json"
+          [ -f "sboms/target/sbom-${arch_tag}.spdx.json" ] && cp "sboms/target/sbom-${arch_tag}.spdx.json" "sboms/target/inbuild-sbom-${arch_tag}.spdx.json" 2>/dev/null || true
         fi
 
         if [ ! -f "sboms/target/sbom-${arch_tag}.spdx.json" ]; then
@@ -201,6 +209,7 @@ runs:
           docker buildx imagetools inspect "${{ inputs.head-image }}" \
             --format '{{ json .SBOM.SPDX }}' > sboms/head/sbom-default.spdx.json 2>/dev/null || true
           cleanup_file sboms/head/sbom-default.spdx.json
+          [ -f sboms/head/sbom-default.spdx.json ] && cp sboms/head/sbom-default.spdx.json sboms/head/inbuild-sbom-default.spdx.json 2>/dev/null || true
         fi
 
         if [ ! -f sboms/head/sbom-default.spdx.json ]; then
@@ -217,6 +226,7 @@ runs:
           docker buildx imagetools inspect "${{ inputs.target-image }}" \
             --format '{{ json .SBOM.SPDX }}' > sboms/target/sbom-default.spdx.json 2>/dev/null || true
           cleanup_file sboms/target/sbom-default.spdx.json
+          [ -f sboms/target/sbom-default.spdx.json ] && cp sboms/target/sbom-default.spdx.json sboms/target/inbuild-sbom-default.spdx.json 2>/dev/null || true
         fi
 
         if [ ! -f sboms/target/sbom-default.spdx.json ]; then
@@ -304,6 +314,32 @@ runs:
 
       head_summary=()
       target_summary=()
+      use_inbuild="${{ inputs.use-inbuild-sbom }}"
+
+      detect_distro() {
+        node -e '
+          const fs = require("fs");
+          try {
+            const data = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+            let name, ver;
+            for (const pkg of (data.packages || [])) {
+              for (const ref of (pkg.externalRefs || [])) {
+                if (ref.referenceType === "purl" && ref.referenceLocator) {
+                  const mName = ref.referenceLocator.match(/[?&]os_name=([^&]+)/);
+                  const mVer = ref.referenceLocator.match(/[?&]os_version=([^&]+)/);
+                  if (mName && mVer) {
+                    name = mName[1];
+                    ver = mVer[1];
+                    break;
+                  }
+                }
+              }
+              if (name && ver) break;
+            }
+            if (name && ver) console.log(name + "/" + ver);
+          } catch (e) {}
+        ' "$1" 2>/dev/null || true
+      }
 
       # 1. Scan Head SBOMs
       if [ ${#head_sboms[@]} -eq 0 ]; then
@@ -316,9 +352,49 @@ runs:
           err_log="cve-reports/head/cve-${arch}.err"
 
           echo "Scanning head SBOM for architecture: $arch"
+          distro_arg=""
+          if [ "$use_inbuild" = "true" ]; then
+            detected_distro=$(detect_distro "$f")
+            if [ -n "$detected_distro" ]; then
+              echo "Detected distribution '${detected_distro}' from in-build SBOM PURLs. Scanning with --distro."
+              distro_arg="--distro ${detected_distro}"
+            fi
+          fi
+
+          scan_success=false
+          if trivy sbom $distro_arg --skip-version-check --format json --output "$out_json" "$f" 2>"$err_log"; then
+            scan_success=true
+          fi
+
+          vuln_cnt=0
+          if [ -s "$out_json" ]; then
+            cnt=$(grep -c '"VulnerabilityID"' "$out_json" 2>/dev/null || true)
+            cnt=$(echo "$cnt" | tr -d '[:space:]')
+            [ -n "$cnt" ] && vuln_cnt="$cnt"
+          fi
+
+          # Fallback if in-build SBOM scan produced 0 CVEs (e.g. incompatible third-party format) or scan failed
+          if [ "$use_inbuild" = "true" ] && { [ "$scan_success" != "true" ] || [ "$vuln_cnt" -eq 0 ]; }; then
+            echo "::warning::In-build SBOM for head image (${arch}) yielded ${vuln_cnt} CVE findings. Falling back to direct Trivy image scan..."
+            t_plat="linux/${arch}"
+            [ "$arch" = "default" ] && t_plat=""
+            plat_arg=""
+            [ -n "$t_plat" ] && plat_arg="--platform $t_plat"
+            if trivy image --skip-version-check $plat_arg --format spdx-json --output "$f" "${{ inputs.head-image }}"; then
+              echo "Re-scanning head SBOM generated directly by Trivy..."
               if trivy sbom --skip-version-check --format json --output "$out_json" "$f" 2>"$err_log"; then
+                scan_success=true
+                if [ -s "$out_json" ]; then
+                  cnt=$(grep -c '"VulnerabilityID"' "$out_json" 2>/dev/null || true)
+                  cnt=$(echo "$cnt" | tr -d '[:space:]')
+                  [ -n "$cnt" ] && vuln_cnt="$cnt"
+                fi
+              fi
+            fi
+          fi
+
+          if [ "$scan_success" = "true" ]; then
             if [ -s "$out_json" ]; then
-              vuln_cnt=$(grep -o '"VulnerabilityID"' "$out_json" 2>/dev/null | wc -l || echo 0)
               if [ "$vuln_cnt" -eq 0 ]; then
                 echo "::warning::Head image architecture '${arch}' has 0 CVE findings. Verify that OS/packages were recognized."
                 head_summary+=("  - ${arch}: ⚠️ WARNING (0 vulnerability findings detected)")
@@ -350,9 +426,49 @@ runs:
           err_log="cve-reports/target/cve-${arch}.err"
 
           echo "Scanning target SBOM for architecture: $arch"
+          distro_arg=""
+          if [ "$use_inbuild" = "true" ]; then
+            detected_distro=$(detect_distro "$f")
+            if [ -n "$detected_distro" ]; then
+              echo "Detected distribution '${detected_distro}' from in-build SBOM PURLs. Scanning with --distro."
+              distro_arg="--distro ${detected_distro}"
+            fi
+          fi
+
+          scan_success=false
+          if trivy sbom $distro_arg --skip-version-check --format json --output "$out_json" "$f" 2>"$err_log"; then
+            scan_success=true
+          fi
+
+          vuln_cnt=0
+          if [ -s "$out_json" ]; then
+            cnt=$(grep -c '"VulnerabilityID"' "$out_json" 2>/dev/null || true)
+            cnt=$(echo "$cnt" | tr -d '[:space:]')
+            [ -n "$cnt" ] && vuln_cnt="$cnt"
+          fi
+
+          # Fallback if in-build SBOM scan produced 0 CVEs (e.g. incompatible third-party format) or scan failed
+          if [ "$use_inbuild" = "true" ] && { [ "$scan_success" != "true" ] || [ "$vuln_cnt" -eq 0 ]; }; then
+            echo "::warning::In-build SBOM for target image (${arch}) yielded ${vuln_cnt} CVE findings. Falling back to direct Trivy image scan..."
+            t_plat="linux/${arch}"
+            [ "$arch" = "default" ] && t_plat=""
+            plat_arg=""
+            [ -n "$t_plat" ] && plat_arg="--platform $t_plat"
+            if trivy image --skip-version-check $plat_arg --format spdx-json --output "$f" "${{ inputs.target-image }}"; then
+              echo "Re-scanning target SBOM generated directly by Trivy..."
               if trivy sbom --skip-version-check --format json --output "$out_json" "$f" 2>"$err_log"; then
+                scan_success=true
+                if [ -s "$out_json" ]; then
+                  cnt=$(grep -c '"VulnerabilityID"' "$out_json" 2>/dev/null || true)
+                  cnt=$(echo "$cnt" | tr -d '[:space:]')
+                  [ -n "$cnt" ] && vuln_cnt="$cnt"
+                fi
+              fi
+            fi
+          fi
+
+          if [ "$scan_success" = "true" ]; then
             if [ -s "$out_json" ]; then
-              vuln_cnt=$(grep -o '"VulnerabilityID"' "$out_json" 2>/dev/null | wc -l || echo 0)
               if [ "$vuln_cnt" -eq 0 ]; then
                 echo "::warning::Target baseline image architecture '${arch}' has 0 CVE findings. Verify that OS/packages were recognized."
                 target_summary+=("  - ${arch}: ⚠️ WARNING (0 vulnerability findings detected)")
@@ -378,6 +494,12 @@ runs:
       echo "================================================================================"
       echo "                   CVE VULNERABILITY SCAN DIAGNOSTIC OVERVIEW                  "
       echo "================================================================================"
+      if [ "$use_inbuild" = "true" ]; then
+        echo "Scan Strategy: Built-in OCI Attestation (Syft/Docker Scout) with distro detection"
+      else
+        echo "Scan Strategy: Direct Trivy Image Scan (Full rootfs & source package mapping)"
+      fi
+      echo "--------------------------------------------------------------------------------"
       echo "HEAD Image: ${{ inputs.head-image }}"
       for line in "${head_summary[@]}"; do
         echo "$line"

cve-diff.js

@@ -84,14 +84,15 @@ function loadReportsForArg(arg) {
       process.exit(1);
     }
 
-    if (!data || typeof data !== 'object' || !Array.isArray(data.Results)) {
+    if (!data || typeof data !== 'object') {
-      console.error(`::error::Malformed Trivy report structure (missing Results array) in: ${filePath}`);
+      console.error(`::error::Malformed Trivy report structure in: ${filePath}`);
       process.exit(1);
     }
 
+    const results = Array.isArray(data.Results) ? data.Results : [];
     loadedFiles++;
 
-    for (const result of data.Results) {
+    for (const result of results) {
       const target = result.Target || result.Type || 'App';
       const vulns = Array.isArray(result.Vulnerabilities) ? result.Vulnerabilities : [];
       for (const v of vulns) {
@@ -135,7 +136,7 @@ function formatVulnRow(v, allScannedArchs = new Set(), showArch = true) {
 
   const installed = v.InstalledVersion || '-';
   const fixed = v.FixedVersion || '-';
-  let title = (v.Title || v.Description || '').replace(/\n/g, ' ').trim();
+  let title = (v.Title || v.Description || '').replace(/\n/g, ' ').replace(/\|/g, '\\|').trim();
   if (title.length > 80) {
     title = title.slice(0, 77) + '...';
   }

test/cve-diff.test.js

@@ -0,0 +1,111 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const {
+  loadReportsForArg,
+  formatVulnRow,
+  renderMarkdownDiff,
+  renderFullSummary,
+} = require('../cve-diff.js');
+
+const FIXTURES_DIR = path.join(__dirname, 'fixtures');
+
+test('loadReportsForArg loads valid reports and extracts multi-arch metadata', () => {
+  const targetDir = path.join(FIXTURES_DIR, 'target');
+  const cves = loadReportsForArg(targetDir);
+
+  assert.equal(cves.size, 2);
+  assert.ok(cves.has('CVE-2023-0001:::glibc'));
+  assert.ok(cves.has('CVE-2023-0002:::openssl'));
+
+  const glibc = cves.get('CVE-2023-0001:::glibc');
+  assert.equal(glibc.Severity, 'CRITICAL');
+  assert.deepEqual(Array.from(glibc._archs).sort(), ['amd64', 'arm64']);
+  assert.deepEqual(Array.from(cves.scannedArchs).sort(), ['amd64', 'arm64']);
+
+  const openssl = cves.get('CVE-2023-0002:::openssl');
+  assert.equal(openssl.Severity, 'HIGH');
+  assert.deepEqual(Array.from(openssl._archs), ['amd64']);
+});
+
+test('loadReportsForArg handles reports with missing or null Results array without crashing', () => {
+  const emptyDir = path.join(FIXTURES_DIR, 'empty');
+  const cves = loadReportsForArg(emptyDir);
+
+  assert.equal(cves.size, 0);
+});
+
+test('renderMarkdownDiff produces correct introduced, resolved, and unchanged sets', () => {
+  const targetDir = path.join(FIXTURES_DIR, 'target');
+  const headDir = path.join(FIXTURES_DIR, 'head');
+
+  const baseCves = loadReportsForArg(targetDir);
+  const branchCves = loadReportsForArg(headDir);
+
+  const diff = renderMarkdownDiff(baseCves, branchCves, 'main');
+
+  // Introduced: CVE-2023-0003 (curl)
+  assert.ok(diff.includes('New Vulnerabilities Introduced (1)'));
+  assert.ok(diff.includes('CVE-2023-0003'));
+  assert.ok(diff.includes('`curl`'));
+
+  // Resolved: CVE-2023-0001 (glibc)
+  assert.ok(diff.includes('Resolved / Removed Vulnerabilities (1)'));
+  assert.ok(diff.includes('CVE-2023-0001'));
+  assert.ok(diff.includes('`glibc`'));
+
+  // Unchanged count
+  assert.ok(diff.includes('| ⚪ **Unchanged Vulnerabilities** | 1 |'));
+
+  // Multi-arch is present in fixtures (amd64, arm64), so Arch column should be shown
+  assert.ok(diff.includes('| Arch |'));
+});
+
+test('renderMarkdownDiff hides Arch column when single architecture is scanned', () => {
+  const targetSingle = path.join(FIXTURES_DIR, 'target', 'cve-amd64.json');
+  const headSingle = path.join(FIXTURES_DIR, 'head', 'cve-amd64.json');
+
+  const baseCves = loadReportsForArg(targetSingle);
+  const branchCves = loadReportsForArg(headSingle);
+
+  const diff = renderMarkdownDiff(baseCves, branchCves, 'main');
+
+  assert.ok(!diff.includes('| Arch |'));
+  assert.ok(diff.includes('New Vulnerabilities Introduced (1)'));
+  assert.ok(diff.includes('Resolved / Removed Vulnerabilities (1)'));
+});
+
+test('renderFullSummary outputs summary table and lists all vulnerabilities', () => {
+  const headDir = path.join(FIXTURES_DIR, 'head');
+  const headCves = loadReportsForArg(headDir);
+
+  const summary = renderFullSummary(headCves);
+
+  assert.ok(summary.includes('### 🛡️ Security Scan Report'));
+  assert.ok(summary.includes('| Total Vulnerabilities | **2** |'));
+  assert.ok(summary.includes('CVE-2023-0002'));
+  assert.ok(summary.includes('CVE-2023-0003'));
+});
+
+test('formatVulnRow properly formats badge, architecture tag, and escape pipes', () => {
+  const vuln = {
+    Severity: 'CRITICAL',
+    VulnerabilityID: 'CVE-2023-0001',
+    PrimaryURL: 'https://avd.aquasec.com/nvd/cve-2023-0001',
+    PkgName: 'glibc',
+    InstalledVersion: '2.31',
+    FixedVersion: '2.32',
+    Title: 'A vulnerability with | pipe symbol',
+    _archs: new Set(['amd64']),
+  };
+
+  const allArchs = new Set(['amd64', 'arm64']);
+  const rowWithArch = formatVulnRow(vuln, allArchs, true);
+
+  assert.ok(rowWithArch.includes('🔴 CRITICAL'));
+  assert.ok(rowWithArch.includes('`amd64`'));
+  assert.ok(rowWithArch.includes('\\|')); // Pipe escaped
+
+  const rowWithoutArch = formatVulnRow(vuln, allArchs, false);
+  assert.ok(!rowWithoutArch.includes('`amd64`'));
+});

test/fixtures/empty/cve-amd64.json

@@ -0,0 +1,8 @@
+{
+  "SchemaVersion": 2,
+  "ArtifactName": "debian:bullseye-slim",
+  "ArtifactType": "spdx",
+  "Metadata": {
+    "OS": null
+  }
+}

test/fixtures/head/cve-amd64.json

@@ -0,0 +1,30 @@
+{
+  "SchemaVersion": 2,
+  "ArtifactName": "debian:bookworm-slim",
+  "ArtifactType": "container_image",
+  "Results": [
+    {
+      "Target": "debian:bookworm-slim (debian 12)",
+      "Class": "os-pkgs",
+      "Type": "debian",
+      "Vulnerabilities": [
+        {
+          "VulnerabilityID": "CVE-2023-0002",
+          "PkgName": "openssl",
+          "InstalledVersion": "1.1.1n-0+deb11u4",
+          "FixedVersion": "1.1.1n-0+deb11u5",
+          "Severity": "HIGH",
+          "Title": "Timing attack in OpenSSL"
+        },
+        {
+          "VulnerabilityID": "CVE-2023-0003",
+          "PkgName": "curl",
+          "InstalledVersion": "7.88.1-10",
+          "FixedVersion": "7.88.1-10+deb12u1",
+          "Severity": "MEDIUM",
+          "Title": "Buffer overflow in curl"
+        }
+      ]
+    }
+  ]
+}

test/fixtures/head/cve-arm64.json

@@ -0,0 +1,22 @@
+{
+  "SchemaVersion": 2,
+  "ArtifactName": "debian:bookworm-slim",
+  "ArtifactType": "container_image",
+  "Results": [
+    {
+      "Target": "debian:bookworm-slim (debian 12)",
+      "Class": "os-pkgs",
+      "Type": "debian",
+      "Vulnerabilities": [
+        {
+          "VulnerabilityID": "CVE-2023-0003",
+          "PkgName": "curl",
+          "InstalledVersion": "7.88.1-10",
+          "FixedVersion": "7.88.1-10+deb12u1",
+          "Severity": "MEDIUM",
+          "Title": "Buffer overflow in curl"
+        }
+      ]
+    }
+  ]
+}

test/fixtures/target/cve-amd64.json

@@ -0,0 +1,36 @@
+{
+  "SchemaVersion": 2,
+  "ArtifactName": "debian:bullseye-slim",
+  "ArtifactType": "container_image",
+  "Metadata": {
+    "OS": {
+      "Family": "debian",
+      "Name": "11"
+    }
+  },
+  "Results": [
+    {
+      "Target": "debian:bullseye-slim (debian 11)",
+      "Class": "os-pkgs",
+      "Type": "debian",
+      "Vulnerabilities": [
+        {
+          "VulnerabilityID": "CVE-2023-0001",
+          "PkgName": "glibc",
+          "InstalledVersion": "2.31-13+deb11u5",
+          "FixedVersion": "2.31-13+deb11u6",
+          "Severity": "CRITICAL",
+          "Title": "Memory corruption in glibc"
+        },
+        {
+          "VulnerabilityID": "CVE-2023-0002",
+          "PkgName": "openssl",
+          "InstalledVersion": "1.1.1n-0+deb11u4",
+          "FixedVersion": "1.1.1n-0+deb11u5",
+          "Severity": "HIGH",
+          "Title": "Timing attack in OpenSSL"
+        }
+      ]
+    }
+  ]
+}

test/fixtures/target/cve-arm64.json

@@ -0,0 +1,22 @@
+{
+  "SchemaVersion": 2,
+  "ArtifactName": "debian:bullseye-slim",
+  "ArtifactType": "container_image",
+  "Results": [
+    {
+      "Target": "debian:bullseye-slim (debian 11)",
+      "Class": "os-pkgs",
+      "Type": "debian",
+      "Vulnerabilities": [
+        {
+          "VulnerabilityID": "CVE-2023-0001",
+          "PkgName": "glibc",
+          "InstalledVersion": "2.31-13+deb11u5",
+          "FixedVersion": "2.31-13+deb11u6",
+          "Severity": "CRITICAL",
+          "Title": "Memory corruption in glibc"
+        }
+      ]
+    }
+  ]
+}