Document hand-off recipes for SBOM and vulnerability-management servers

[richardmhope]

--output already emits the canonical formats. What is missing is any guidance on what to do with them beyond storing the file — the ## SBOM artefacts section of references/ci-integration.md stops at actions/upload-artifact, which on its own produces no security property at all, and nothing covers handing output to the systems people actually run.

That is glue, and glue belongs in documentation rather than in flags. See "Out of scope" below.

Recipes to add

Each a few lines of shell or YAML, and honest about being glue rather than a supported integration:

• Dependency-Track — the most common OSS destination, and the least obvious payload to get right by hand.
• DefectDojo — import-scan, from either the CycloneDX or the SARIF output.
• cosign attest, binding the SBOM to an artefact digest. This already appears as a scope item in Deterministic output, so an SBOM can be attested by digest #20 — whichever issue is picked up first should take it and the other should drop it, rather than both landing a copy.

#21 is a prerequisite

Dependency-Track identifies projects by name and version; DefectDojo by product and engagement. metadata.component is currently the scanned directory's basename with no version at all (src/icebergsca/report/cyclonedx.py:88-92), so a scheduled upload lands every run as the same unversioned project — and the server loses exactly the drift tracking it exists to provide.

Recipes written before #21 would be documenting a broken workflow. Land that first.

A design note worth recording

Where a team runs one of these servers, the server owns triage — that is what it is for. They do not also want .icebergsca.toml, and two triage stores that can disagree is worse than either alone: "suppressed here, open there" is a bad failure mode.

The recipes should say so plainly, and it is a boundary for the ignore file too. It earns its place for the majority of users who have CI and no vulnerability-management server; it should not grow toward competing with one.

Out of scope: a --send-to flag

Recorded here so it does not need re-deriving:

• Unbounded surface. Dependency-Track, DefectDojo, GUAC, Xray, Harbor and Sonatype IQ each have their own auth model, payload shape, project-identification scheme and async-job semantics. Every one added is a permanent maintenance tail that cannot be exercised honestly without standing up that server, and the suite's current guarantee is that it never touches the network.
• Credentials. The only environment variable read anywhere in the package today is NO_COLOR, and the tool holds no secrets. A write-scoped API token means secret handling, redaction in logs and errors, and a new class of leaked-token bug. Same posture as declining to sign: do not take on privileges the job does not need.
• Exit codes. 0/1/2/3 now mean scan-completed, scan-broke, usage, gate-tripped. A successful scan whose upload failed is none of them, and would either need a fourth code or conflate a third-party outage with a scan failure — the precise distinction that design exists to preserve.

Note the dependency argument does not apply: httpx is already present, with retry, backoff and concurrency. The cost here is surface area and secrets, not the dependency tree.

If an exception is ever made, Dependency-Track is the strongest candidate — a single clearly-scoped integration with its own opinion, never a generic --send-to <url> pretending all servers are alike.

Constraint for whoever picks this up

tests/test_skill.py:60-62 asserts the references directory is exactly {json-report.md, ci-integration.md}. These recipes extend ci-integration.md; they cannot become a third reference file without changing that test — and the test is right, since an agent-facing skill with a sprawling reference set is worse than a tight one. website/docs/output.md carries overlapping CI content and should link rather than duplicate.