feat: fail closed on unverified head snapshot in dependency-vuln-check

[szpraat]

What

Adds a head-side verification guard to dependency-vuln-check, mirroring the fail-closed treatment the base side already has.

The gate diffs compare(effective_base ... head_sha). The base side is resolved to a verified snapshotted ancestor and fails closed when it can't be established. The head side had no equivalent guard — check.py trusted the compare result and failed closed only if the API call itself errored. It never verified the head SBOM was actually submitted and indexed. So:

• if the head-SBOM submission job failed, or
• if the submission hadn't finished indexing when the compare ran,

the head side read empty and a genuinely new vulnerable dependency passed silently — a false negative. Harmless while the consuming gate was observe-only; under blocking it's a false green.

Two guards

1. Submission failure — new optional input head-snapshot-succeeded. The consumer passes the result of its head-SBOM submission job (e.g. needs.pr-maven-snapshot.result == 'success'). When 'false', the gate fails closed (honoring the ci:vuln-gate-override label, same as the base-side paths). Unset → skipped, so existing consumers are unaffected.
2. Indexing lag — when the head side of the diff looks empty (0 added, deps removed), the compare is re-fetched a few times with backoff to let the dependency graph settle. A removal-only PR has the identical shape and simply re-confirms — the gate never blocks on this signal, it only waits out lag, so it cannot misfire into a false positive.

Testing

68/68 pytest pass (was 60). 8 new tests: _looks_like_missing_head helper (3), gap-1 fail-closed + override-bypass + true-proceeds (3), gap-2 retry-then-block-on-settled-diff + persistent-empty-never-blocks (2). README + action inputs + fail-closed contract documented.

Rollout

Backward compatible (new input defaults to unset/skip). After merge, the consumer (camunda/camunda ci.yml) wires head-snapshot-succeeded and Renovate bumps the pin. Companion to the vuln-gate blocking flip camunda/camunda#57561.

[Copilot]

Pull request overview

This PR strengthens dependency-vuln-check by adding head-side verification so the Dependency Review compare isn’t trusted when the PR head snapshot is missing/failed or still indexing, preventing false-negative “green” results when the gate becomes blocking.

Changes:

• Adds optional head-snapshot-succeeded action input and a fail-closed path when it is explicitly 'false'.
• Adds a head-diff “looks empty” heuristic with retry + backoff to absorb dependency-graph indexing lag before evaluating the final diff.
• Adds unit tests for the new helper and head-guard behaviors, and updates README documentation.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
dependency-vuln-check/check.py	Adds head snapshot guard, empty-head retry logic, and the _looks_like_missing_head helper.
dependency-vuln-check/action.yml	Introduces head-snapshot-succeeded input and wires it into HEAD_SNAPSHOT_SUCCEEDED.
dependency-vuln-check/README.md	Documents the new input and head-side verification/lag behavior.
dependency-vuln-check/test_check.py	Adds tests covering submission-failed fail-closed behavior and indexing-lag retry behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[liliancavalet]

❓ The allow-list fix closes the failure / cancelled path nicely. One case it doesn't cover: success is still a "proceed" value, and the consumer's pr-maven-snapshot job is continue-on-error: true. If that masks a failed snapshot to needs.pr-maven-snapshot.result == 'success', the guard gets a legit-looking success and proceeds — the exact false negative this input is meant to catch.

Do we know what .result reports for a continue-on-error job whose step failed?

[szpraat]

needs.<job>.result returns success for a continue-on-error: true job whose step failed — the failure is masked and there's no job-level outcome/conclusion to read (actions/toolkit#1739). So wiring the guard to .result == 'success' would no-op it.

This isn't fixable in check.py. The guard receives a string; a masked failure and a true pass both arrive as the literal 'success'. It's well-formed, so the allow-list — which rejects failure/cancelled/typos — can't distinguish them. No logic here can.

The fix is at the source, in the consumer wiring: expose the step outcome as a job output and pass that instead of .result:

 pr-maven-snapshot:
   continue-on-error: true
   outputs: { submitted: "${{ steps.submit.outcome }}" }
   steps:
     - id: submit
       uses: advanced-security/maven-dependency-submission-action@...
 pr-vuln-check:
   with:
     head-snapshot-succeeded: ${{ needs.pr-maven-snapshot.outputs.submitted || 'failure' }}

steps.submit.outcome is pre-continue-on-error, so a failed step reads failure; || 'failure' covers the job dying before the step runs. I opened a dedicated PR on the consumer side