Stop SBOM scan when advisory data has never been synced

Problem to Solve

The GitLab SBOM Vulnerability Scanner requires advisory data to be synced to provide results. Currently, if advisory data has never been synced on an instance (either at all or for specific purl types), the scan proceeds and returns an empty vulnerability list, giving users an impression that the project has no vulnerabilities.

This issue addresses the first critical scenario identified in the parent epic: preventing scans when sync has never succeeded for the required PURL type.

Proposal 1

Implement a pre-scan validation check that:

  1. Detects if advisory data sync checkpoints exist for the PURL types in the SBOM
  2. Fails the scan immediately (before SBOM upload) if no checkpoints exist
  3. Returns a clear, actionable error message to the user pointing to advisory sync docs and troubleshooting guidance

Implementation approach:

  • Add validation logic in the SBOM Scan API (Rails backend) to check for advisory sync checkpoint existence
  • Query PMDB tables for checkpoints matching the PURL types scan request
  • Return appropriate error response when validation fails
  • Update dependency-scanning analyzer to handle the error response and fail

Proposal 2

Implement a pre-scan validation check:

  1. Return advisory db state from the instance after upload
  2. Let analyzer stop scan if no advisory data exists

Intended Users

GitLab Self-Managed customers that may need to take extra steps to synchronize advisories on their instances.

Goal

Today: Scan runs → Returns empty results → User assumes no vulnerabilities exist ❌

With this change: Scan validation fails → Pipeline fails with clear error → User knows to configure PMDB sync ✅

Acceptance Criteria

Must have

  • SBOM Scan API Scanning validates checkpoint existence for given PURL types before processing scan
  • Scan fails immediately when no advisory data checkpoint exists for required PURL type
  • Error response includes:
    • Indicating no advisory data exists for the purl types needed to be scanned
    • Link to PMDB sync documentation/troubleshooting
  • Dependency scanning pipeline fails with the error message visible to users
  • Admin documentation updated to reflect PMDB sync requirements and this validation behavior
  • Observability data to track failed scans due to this constraint

Should have

* No SBOM upload occurs when validation fails (fail fast)

  • Metrics dashboard to track:
    • Frequency of scan failures due to missing advisory data
    • Which PURL types most commonly trigger this failure
    • Instance-level sync readiness indicators
  • Error message distinguishes between "never synced" vs other sync issues

Cannot have

No SBOM upload occurs when validation fails (fail fast) <- not until Avoid triggering a re-scan when dependencies ha... (#562694) • Igor Frenkel • 18.7 • Needs attention is delivered.

Not part of this issue

  • Sync stopped working
  • Data freshness thresholds
  • Sync-in-progress scenarios

Rollout plan

TBD

Implementation plan (proposal 2)

  • Add sbom scan api checkpoint check
  • Return checkpoint state to analyzer
  • Stop scan if outdated

/cc @nilieskou @gonzoyumo

Edited by Igor Frenkel