Add --verify-shas and --fail-on-warnings

[TooFastTooCurious]

Summary

Closes #2.

Adds two new flags that let ABOM detect SHA-pinned action references that aren't actually reachable from their claimed upstream repo — the real class of supply-chain risk SHA pinning is supposed to protect against.

• --verify-shas (opt-in) hits api.github.com/repos/{owner}/{repo}/commits/{sha} for each unique SHA-pinned reference and emits a warning when the SHA isn't reachable from the claimed repo's refs.
• --fail-on-warnings exits 2 if any warnings were emitted. Generic on purpose so future warning categories (deprecated refs, suspicious renames, missing metadata, etc.) compose without growing the CLI surface.

Resolution behavior is unchanged. ABOM still mirrors GitHub's actual fetch path; --verify-shas only adds advisory signal on top.

What --verify-shas actually catches

                GitHub fork-network object store
                ┌──────────────────────────────┐
                │                              │
   owner/repo ──┤  commits reachable via refs  │──► :white_check_mark: resolves via raw.githubusercontent.com
                │       (main, tags, PRs)      │    :white_check_mark: reachable from owner/repo's refs
                │                              │
  owner/forkA ──┤                              │──► :white_check_mark: resolves via raw.githubusercontent.com
                │  commits only in forks       │    :x: NOT reachable from owner/repo's refs
                │   (orphaned, force-pushed,   │         ^^^^ this is what --verify-shas catches
                │    deleted from upstream)    │
                └──────────────────────────────┘

A pin like actions/checkout@<sha> succeeds even when <sha> was only ever committed to a fork. GitHub's object store doesn't care which fork originated the commit — the raw content endpoint serves it regardless. The commits API, scoped to owner/repo, is the first endpoint that distinguishes "reachable from this repo's refs" from "known to the object store."

Pipeline integration

   abom scan [target]
        │
        ▼
   ┌─────────────┐
   │ parse YAML  │
   └──────┬──────┘
          ▼
   ┌──────────────────────┐
   │ resolve transitive   │ (raw.githubusercontent.com)
   │    dependencies      │
   └──────┬───────────────┘
          ▼
   ┌──────────────────────┐
   │ advisory.CheckAll    │ (if --check)
   └──────┬───────────────┘
          ▼
   ┌──────────────────────┐
   │ abom.CollectActions  │ (dedup + summary)
   └──────┬───────────────┘
          ▼
   ┌──────────────────────┐     ┌──────────────────────┐
   │ VerifyABOMShas       │────►│ warnings.Collector   │
   │ (if --verify-shas)   │     │  - SHAUnreachable    │
   └──────┬───────────────┘     │  - RateLimit         │
          ▼                     └──────────────────────┘
   ┌──────────────────────┐              │
   │ format output        │              │
   └──────┬───────────────┘              ▼
          ▼                     ┌──────────────────────┐
   ┌──────────────────────┐     │ col.Print(stderr)    │
   │ exit code precedence │◄────┤                      │
   └──────────────────────┘     └──────────────────────┘

Verification runs as a post-pass over the deduplicated action list (not during resolution). Dedup keys on owner/repo@sha, so subdirectory variants of the same SHA collapse into a single API call.

Verifier response handling

   HEAD api.github.com/repos/{owner}/{repo}/commits/{sha}
                       │
        ┌──────────────┴──────────────┐
        │                             │
        ▼                             ▼
    status=200                    status=404 or 422
        │                             │
        ▼                             ▼
    :white_check_mark: reachable                   :warning:  SHAUnreachable warning
    (no warning)                  "SHA not reachable from
                                   owner/repo refs"

   status=403 or 429  ────►  :warning:  RateLimit (one warning only,
                                subsequent verifications skipped)

   transport / 5xx    ────►  :warning:  RateLimit (generic — never
                                SHAUnreachable, avoids false
                                positives under flaky network)

   short SHA (<40)    ────►  :warning:  SHAUnreachable ("short SHA
   [no API call]           cannot be reliably verified")

Exit code contract

                  ┌─────────────────── compromised found? ──────────────────┐
                  │                                                         │
                  ▼                                                         ▼
                 NO                                                       YES
                  │                                                         │
      ┌───── warnings? ─────┐                                         exit 1
      │                     │                                    (overrides warnings)
      ▼                     ▼
     NO                    YES
      │                     │
   exit 0        ┌─ --fail-on-warnings? ─┐
                 │                       │
                 ▼                       ▼
                NO                      YES
                 │                       │
              exit 0                  exit 2
           (warnings on                 (CI gate)
            stderr only)

Compromised action	Warnings	--fail-on-warnings	Exit
✅	✅	any	1
✅	❌	any	1
❌	✅	✅	2
❌	✅	❌	0
❌	❌	any	0

Previously the only exit signal was 1 on compromised actions — existing CI pipelines continue to work identically when neither new flag is set. Exit 2 is a new signal and only engages when --fail-on-warnings is explicitly requested.

CI usage

- name: Check Actions supply chain
  run: abom scan . --check --verify-shas --fail-on-warnings
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GITHUB_TOKEN is essentially required — anonymous API requests are capped at 60/hour; authenticated requests get 5000/hour. A startup warning fires (and is caught by --fail-on-warnings) when --verify-shas runs without a token.

Files changed

cmd/
  root.go      +48 / -8    Add persistent flags; exitError type; Execute() unwraps
  scan.go      +35 / -2    Wire verification post-pass; layered exit logic
  check.go     +51 / -15   Mirror scan wiring; replace os.Exit(1) with exitError

pkg/warnings/
  warnings.go          +65  Collector, Warning, Category
  warnings_test.go     +79  Emit/Count/All/Print round-trip

pkg/resolver/
  verify.go            +140 SHAVerifier, GitHubSHAVerifier, VerifyABOMShas
  verify_test.go       +242 mockVerifier + 9 test cases

README.md      +36 / -1    New section, flag table, exit code contract

Total: ~700 insertions, 22 deletions. No pre-existing tests modified.

Test plan

Automated (all passing locally):

• go test ./... — new pkg/warnings (4 tests) and pkg/resolver/verify_test.go (9 tests) plus all pre-existing tests
• go vet ./...
• go build ./...

Verify test matrix:

• Reachable SHA (200) → no warning
• Unreachable SHA (404) → exactly one SHAUnreachable warning
• Dedup: same owner/repo@sha across multiple action entries → one API call
• Non-SHA refs (tag/branch) → skipped, no API call
• Docker / local action types → skipped
• Short SHA (7-39 hex) → warning without API call
• Transport error → RateLimit category (not SHAUnreachable — avoids false positives)
• Mid-run 403 → single RateLimit warning, subsequent verifications suppressed
• Nil collector → no panic

Manual smoke:

• --verify-shas --offline → fails fast with "--verify-shas requires network"
• --verify-shas --no-network → fails fast
• abom --help lists both new flags plus the exit code contract

Live integration against api.github.com was not included — anonymous rate limits make it flaky in CI, and the mock-based tests exhaustively cover the response-code matrix. Happy to add a tagged integration test if desired.

Design notes for reviewers

• Why a separate pkg/warnings package instead of attaching to ABOM? Warnings are runtime diagnostics against a live API, not a property of the workflows scanned. Keeping them out of the serialized BOM preserves artifact reproducibility. If consumers ever want per-ref status in JSON output, an optional VerifiedSHA field on ActionRef is easy to add as a follow-up.
• Why HEAD instead of GET? Cheaper and we only need the status code.
• Why a post-pass instead of inline during resolve? Dedup happens naturally via CollectActions(), so the post-pass avoids redundant verification of the same SHA appearing in multiple composite actions. It also means --verify-shas works identically under abom check on a pre-generated ABOM.
• Why single-goroutine collector? The existing resolver is a sequential DFS. The Collector comment makes this assumption explicit — if concurrency is introduced later, the comment forces the decision to be revisited.

Follow-ups not included

• Existing ad-hoc fmt.Fprintf(os.Stderr, "Warning: ...") sites in pkg/resolver/remote.go and elsewhere still bypass the collector. Migrating them would give --fail-on-warnings uniform coverage. Intentionally deferred to keep this PR focused.
• Optional ActionRef.VerifiedSHA *bool field for per-ref status in JSON output. Not added to avoid changing the serialized BOM schema in this PR.
• Persistent cross-run verification cache. Probably premature — a single run has few enough unique SHAs that an in-memory map is sufficient.