docs: document trade-offs and differences between in-build and direct scanning

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')
@@ -488,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"