Scanner Artifact Association Graph

Sprint: SPRINT_20260507_002_Scanner_artifact_association_graph

Purpose

Scanner emits evidence for many related objects: source snapshots, build runs, container images, SBOMs, scan jobs, detector reports, findings, and evidence bundles. Those objects must not remain isolated records. The artifact association graph makes them first-class subjects that can be resolved from CLI, Console, and SBOM service APIs.

Subject Model

The SBOM service owns durable graph persistence. Scanner and related tooling emit enough metadata to create these subject kinds:

Kind	Required identity	Notes
`source-snapshot`	`repoUrl` plus `commitSha`	`treeHash`, `sourcePath`, and `dockerfilePath` are optional evidence enrichments.
`build-run`	`buildId` or `primaryLocator`	Use for CI build, pipeline, or BuildKit execution records.
`oci-image`	immutable `sha256:` digest	Tags are hints only and never verify identity by themselves.
`sbom`	SBOM document `sha256:` digest	Represents the SBOM document, not the scanned image.
`scan-job`	`scanJobId` or `primaryLocator`	Used as the root for scan-detail UI resolution.
`detector-report`	subject key or report locator	Used for language, native, OS, and secrets analyzer reports.
`finding`	finding subject key	Findings may link back to detector reports and evidence bundles.
`evidence-bundle`	bundle locator or digest	Usually a DSSE, proof, or offline evidence bundle reference.

Scanner Metadata Emission

BuildX descriptor generation now accepts and emits source/build/scan association fields:

--repository
--commit-sha or --commit
--tree-hash
--build-id
--pipeline-id
--scan-job-id or --scan-job
--source-path
--dockerfile or --dockerfile-path

The descriptor annotations include org.stellaops.artifact.association.version=v1 plus OCI/source/build/scan fields. This lets CI import the resulting descriptor into the artifact graph without a separate out-of-band mapping file.

Scanner source config models expose an optional association object:

{
  "association": {
    "emitArtifactLinks": true,
    "requireImageDigest": true,
    "linkCandidatesOnly": false,
    "sourceSnapshotMode": "commit-and-tree-hash"
  }
}

requireImageDigest=false is accepted only with a validation warning because mutable tags can create candidates but cannot verify links.

Secrets Evidence

Secrets reports now carry association metadata:

sourceSnapshotId
artifactDigest
detectorReportId
evidenceBundleId

Secret leak evidence exposes a normalized evidenceLocator and redactedFingerprint. The fingerprint is derived from rule, locator, and masked value. Plaintext secrets are not persisted into artifact-link metadata.

Operator Flows

CLI:

stella artifact link export `
  --tenant tenant-a `
  --source-repo https://git.example/acme/app.git `
  --commit abcdef123456 `
  --build-id build-42 `
  --image-digest sha256:<64-hex> `
  --scan-job scan-123 `
  --detector-report lang-node-report `
  --output artifact-links.json

stella artifact link --server http://sbom.local import --file artifact-links.json
stella artifact link --server http://sbom.local resolve --tenant tenant-a --scan-job scan-123 --json
stella artifact link --server http://sbom.local candidates --tenant tenant-a
stella artifact link --server http://sbom.local confirm <link-id> --tenant tenant-a --operator alice --reason matched-source

Online commands set the SBOM service tenant auth header from the bundle tenantId, the --tenant option, STELLAOPS_TENANT_ID, or STELLAOPS_TENANT.

Console:

Scan detail resolves /api/sbomservice/api/v1/artifact-links/resolve?tenant=<tenant>&scanJobId=<scanId>.
The page shows connected subjects, relationships, confidence, and missing-link states.
Candidate confirmation/rejection uses the same SBOM service status APIs as the CLI.

Verification Evidence

BuildX descriptor tests cover deterministic association annotations and metadata.
Source config validator tests cover association parsing and invalid option handling.
Secrets analyzer tests cover association metadata and redacted evidence fingerprints.
CLI tests cover deterministic bundle export and online API routing.
Web tests cover artifact-link API calls and scan-detail rendering.