SBOM Sentinel

---
name: sbom-sentinel
description: >
  Turn a codebase into a prioritized supply-chain risk report. Use when the user wants
  to audit dependencies for known vulnerabilities, generate an SBOM, check a lockfile or
  container against CVEs, or gate CI on supply-chain risk. Triggers: "scan my
  dependencies", "any CVEs in this project", "generate an SBOM", "is this package
  vulnerable", "supply chain audit", "check my lockfile". SELF-BUILDING: ships no
  runnable code; on first use it directs the host agent to construct the analyzer in its
  own sandbox from the spec below and prove it against a shipped acceptance test. The
  differentiator is not "you have CVEs" but "these are the ones that actually matter
  given what you ship." Do NOT use to exploit vulnerabilities, only to find and triage them.
spec_version: 1
---

# SBOM Sentinel — self-building payload

Most vuln scanners dump a wall of CVEs and let the developer drown. This skill produces
a localized exploitability posture: it correlates each declared component with the
advisories that actually affect its version, marks what is already fixed or not
applicable, and surfaces only the actionable set. Ships markdown only — the host agent
builds the analyzer in its own sandbox and proves it green before use.

Distilled from three patterns: static-analysis dependency resolution (platformio/
platformio-core), purl-vulnerability-lookup (DependencyTrack/dependency-track), and
vulnerability-to-component linkage / VEX-VDR posture (CycloneDX/specification).

## When to use
Any request to audit a project's dependencies for known vulnerabilities, emit an SBOM,
or gate a pipeline on supply-chain risk. Works from manifests/lockfiles (package-lock.
json, poetry.lock, go.sum, Cargo.lock, requirements.txt, pom.xml) or an installed tree.

## How this skill runs (the self-build loop)
On trigger the host agent MUST: (1) check ./.sentinel_cache/v{spec_version}/ for a prior
build and reuse it if spec_version is unchanged; (2) otherwise construct sentinel.py per
the Build Brief, exposing the mandated interface; (3) write the Acceptance Harness
verbatim and run it — the build is unusable until it passes green; (4) then run the live
audit and report.

## Build Brief
Construct sentinel.py exposing two functions. The first does live work; the second is the
pure, testable correlation core the harness pins.

  resolve(project_path: str) -> list[dict]   # components: {name, version, ecosystem, purl}
  posture(components: list[dict], advisories: dict) -> list[dict]

resolve(project_path) — parse the project's manifest/lockfile(s), extract every
dependency (transitive where the lockfile provides it), and mint a Package URL per
component: pkg:{ecosystem}/{name}@{version}. This is the dependency-resolution atom
generalized beyond C/C++ #include scanning to language lockfiles.

Live advisory lookup (runtime, not in the pure core): for each PURL, query a free vuln
database — the OSV.dev batch API (POST https://api.osv.dev/v1querybatch) is recommended;
no key required. Collect advisories keyed by PURL into the advisories dict. If the sandbox
has no network, accept a caller-supplied advisories file and say so in the report.

posture(components, advisories) — the correlation core, PURE and deterministic (no I/O).
advisories is {purl: [{id, severity, introduced, fixed}]}. For each component, find
advisories for its PURL and decide status by comparing version against introduced/fixed:
version in [introduced, fixed) -> affected + actionable; version >= fixed -> fixed + not
actionable; no advisory -> clear + not actionable. Return one dict per component:
{component, purl, status, actionable, vulnerabilities:[{id, severity, fixed}]}. Sort
actionable-first, then by highest severity.

Invariants the harness checks: (1) every input component appears in output exactly once;
(2) an advisory only ever attaches to the component whose PURL it is keyed under — no
leak across components (the load-bearing correlation invariant); (3) version in
[introduced, fixed) is affected+actionable; (4) version >= fixed is fixed+not actionable;
(5) no advisory -> clear+not actionable; (6) determinism. Version compare: small
semver-ish split-on-dot numeric compare, missing bound = open; no heavy dependency.

## Acceptance Harness
Write verbatim to test_sentinel.py and run. Exercises only the pure posture core against
a fixed mock advisory DB — no network — and validates any conforming implementation.

    from sentinel import posture
    COMPONENTS = [
        {"name":"lodash","version":"4.17.19","ecosystem":"npm","purl":"pkg:npm/lodash@4.17.19"},
        {"name":"requests","version":"2.31.0","ecosystem":"pypi","purl":"pkg:pypi/requests@2.31.0"},
        {"name":"left-pad","version":"1.0.0","ecosystem":"npm","purl":"pkg:npm/left-pad@1.0.0"},
    ]
    ADVISORIES = {
        "pkg:npm/lodash@4.17.19":[{"id":"GHSA-lodash-proto","severity":"high","introduced":"4.0.0","fixed":"4.17.21"}],
        "pkg:pypi/requests@2.31.0":[{"id":"CVE-2018-requests","severity":"medium","introduced":"0","fixed":"2.20.0"}],
    }
    def run():
        out = posture(COMPONENTS, ADVISORIES); by = {r["component"]: r for r in out}
        assert len(out) == len(COMPONENTS)
        assert set(by) == {c["name"] for c in COMPONENTS}
        assert by["lodash"]["status"]=="affected" and by["lodash"]["actionable"]
        assert any(v["id"]=="GHSA-lodash-proto" for v in by["lodash"]["vulnerabilities"])
        assert by["requests"]["status"]=="fixed" and not by["requests"]["actionable"]
        assert by["left-pad"]["status"]=="clear" and not by["left-pad"]["actionable"]
        for name in ("requests","left-pad"):
            assert "GHSA-lodash-proto" not in {v["id"] for v in by[name]["vulnerabilities"]}, f"leak onto {name}"
        assert posture(COMPONENTS, ADVISORIES) == out
        assert out[0]["actionable"] is True
        print(f"PASS — {len(out)} components, {sum(1 for r in out if r['actionable'])} actionable, 0 advisory leaks")
    if __name__ == "__main__": run()

Verified offline: PASS — 3 components, 1 actionable, 0 advisory leaks. A build that
matches advisories by ecosystem prefix instead of exact PURL fails the harness (advisory
leak caught), confirming the test has teeth.

## Notes
- Reporting: emit a CycloneDX-style summary plus a human table (component, version,
  status, top CVE, fix version). Lead with the actionable set.
- Anti-staleness: bump spec_version to force a rebuild against current APIs/parsers.
- Scope: triage, not exploitation. Finds and prioritizes; does not weaponize.
- "Done" means the harness prints PASS. Nothing else counts as built.