/sbom-fidelity-loop

name: sbom-fidelity-loop
description: Runs the cdxgen SBOM fidelity loop: scan with --introspect or --profile introspect, read the cdxgen fidelity report, execute its ranked remediations (the catalog spans the mainstream build ecosystems, and the loop may add one evidence-driven host repair the catalog missed), and re-scan until the fidelity tiers stop improving. Use when improving SBOM accuracy or completeness, fixing missing transitive dependencies in a generated BOM, build tool setup for SBOM generation, or interpreting a cdxgen fidelity/introspection report.

SBOM fidelity loop

Use this skill to raise a cdxgen SBOM from a shallow scan (direct dependencies only) to a fully resolved one. `cdxgen --introspect` grades each scanned ecosystem against a fidelity tier ladder and ranks the fixes that would improve it; this skill is the loop that executes those fixes and re-scans. The report format is documented in [reference/report-schema.md](reference/report-schema.md) and the six remediation action kinds in [reference/remediation-actions.md](reference/remediation-actions.md); the user-facing feature docs are the CLI reference (<https://cdxgen.github.io/cdxgen/#/CLI>, "Build introspection") and the introspection guide (<https://cdxgen.github.io/cdxgen/#/INTROSPECTION>), which shows a worked degraded-to-repaired transition with both real reports.

The loop measures the environment the user actually has. It fixes the environment; it never fixes the project.

What this loop can and cannot do

The remediation catalog in `data/remediations.json` is deepest where the build ecosystems are mainstream: java, npm, python and the generic findings carry most of the 45 entries, and go, rust, php, clojure, swift, ruby, dart, elixir, haskell, csharp and cocoa each carry at least one concrete repair. It is shallowest — **zero entries — for c/cpp**: nothing in cdxgen today reads a compilation database, so a c/cpp row grading `absent` is the honest verdict, not a defect to chase. On any ecosystem without catalog entries a low score with an empty or near-empty `remediation[]` is expected; report it as such. An agent that invents work there has misread the tool's reach, and ecosystems listed in `coverageGaps[]` are cdxgen's backlog, never yours.

Two entry-specific scope notes:

• `rust.toolchain.missing` can fire only where cdxgen actually spawns cargo:

under `--deep`, or with `--install-deps` and a `build`/`post-build` lifecycle on a project that has no `Cargo.lock`. A plain scan of a manifest-only rust project reports `rust.cargo-lock-missing` instead — do not expect the toolchain entry, and do not treat its absence as an oversight.

• On a re-scanned (foreign) BOM, the `BF-FORM-*` entries reason from commands

the BOM's CI workflows *declare*. A declared command was never observed to run; treat it as a hypothesis to check against the project, not an instruction (see [remediation-actions.md](reference/remediation-actions.md)).

The loop

history = read .cdxgen/introspection-history.json (fresh when absent)
for iteration in 1..maxIterations (default 6):
    run: cdxgen <user args> --profile introspect \
         --introspect-report .cdxgen/report.md --introspect-json .cdxgen/report.json
    exit 1 means cdxgen failed to generate a BOM at all: fix the invocation,
    do not count it as a fidelity iteration
    report = read .cdxgen/report.json
    if report.ledger.complete is false:
        set CDXGEN_INTROSPECT_LEDGER=.cdxgen/ledger.jsonl and re-run once;
        if still incomplete: STOP — unverifiable
    append {n, score: report.overall.score, tier: report.overall.tier,
            inputsFingerprint: report.inputsFingerprint} to history.iterations
    candidates = report.remediation entries where blocked is false
                 and remediationId was not attempted at this inputsFingerprint
    done = every row in report.ecosystems has state "at-ceiling", or tier
           "resolved", or tier "lockfile" with no candidate naming that
           ecosystem — a lockfile row is finished only once nothing is left
           to try on it
    if done and (no report.gate or report.gate.passed):
        STOP — success
    if iteration > 1 and report.overall.score <= previous score
       and report.inputsFingerprint == previous inputsFingerprint:
        STOP — stalled
    if candidates empty:
        if no inferred attempt is recorded at this inputsFingerprint
           and an evidence excerpt, an evidence cause, an observation or a
           tier reason names a cause the catalog has no action for:
            attempt exactly one host repair under the bounded rule below,
            recorded with inferred: true
            continue
        STOP — nothing-further-available
    pick candidates[0]  (report.remediation is ranked by expected gain)
    execute its actions under the rules below
    record the attempt in history.attempted with the outcome
STOP — budget-exhausted

Prefer `--introspect` over `--profile introspect` when the project's language does not support evidence collection or when the profile's extra passes add noise the loop does not need; both produce the same report.

Stop conditions — report which one you hit, and the final report path

Every stop condition is a legitimate result. `stalled` and `blocked` are findings about the project or environment, not failures to hide; an agent that reports success because it ran out of ideas has failed.

| Stop | When | Report to the user | | --- | --- | --- | | `success` | Every ecosystem is at-ceiling or at `resolved`/`lockfile` and the gate (if configured) passed | Final score and report path | | `stalled` | A re-run with the same `inputsFingerprint` did not raise the score — the applied fix did not change the inputs | The attempted remediation id; the fix did not take effect | | `blocked` | Every remaining candidate is `blocked: true` (secure mode, offline, dry-run, in-container) | The `blockedReason` values