CycloneDX ML-BOM Model to Inventory Receipt¶

Use this if your build already produces CycloneDX ML-BOMs and you want a small reviewable CI artifact for the model inventory/provenance boundary that existed.

Assay does not replace CycloneDX or validate the full BOM. CycloneDX carries the inventory artifact. Assay reduces one selected machine-learning-model component into an inventory receipt, bundles it, verifies the bundle, and lets CI gate the Trust Basis diff above that bundle.

Problem¶

A CycloneDX ML-BOM can carry broad model inventory, model-card references, dataset references, licenses, vulnerabilities, pedigree, and other supply-chain metadata. That is valuable, but often too broad for a small CI review artifact.

The smaller review question is:

Which selected model inventory/provenance boundary was observed, what source
artifact did it come from, and can that boundary be reviewed without importing
full BOM truth?

That is the receipt boundary. It is useful when reviewers need a portable artifact showing that a supported model component boundary was present, without pulling the whole BOM graph or treating the model as safe.

One Workflow¶

First write a CycloneDX JSON BOM that contains a selected machine-learning-model component.

Then import that selected model component into an Assay evidence bundle:

assay evidence import cyclonedx-mlbom-model \
  --input bom.cdx.json \
  --bundle-out evidence.tar.gz \
  --source-artifact-ref bom.cdx.json

Verify the bundle and compile the claim artifact:

assay evidence verify evidence.tar.gz
assay trust-basis generate evidence.tar.gz \
  --out cyclonedx-model.trust-basis.json

Compare the candidate Trust Basis against a baseline:

assay trust-basis diff \
  baseline.trust-basis.json \
  cyclonedx-model.trust-basis.json \
  --format json \
  --fail-on-regression

In CI, the baseline Trust Basis artifact usually comes from the default branch or a previously approved run.

Harness owns orchestration, exit codes, Markdown, and JUnit projection. The released recipe is here:

• CycloneDX ML-BOM model receipt pipeline

Artifact Chain¶

CycloneDX ML-BOM JSON
  -> assay evidence import cyclonedx-mlbom-model
  -> evidence.tar.gz
  -> assay trust-basis generate
  -> trust-basis.json
  -> assay trust-basis diff
  -> assay.trust-basis.diff.v1
  -> assay-harness trust-basis gate/report

Canonical Artifact¶

The supported source boundary is one CycloneDX JSON BOM with a selected components[] entry where type is machine-learning-model. Assay imports bounded model-component fields and provenance references. It does not import full BOM graphs or model-card bodies.

Tiny bounded source excerpt:

{
  "$schema": "http://cyclonedx.org/schema/bom-1.7.schema.json",
  "bomFormat": "CycloneDX",
  "specVersion": "1.7",
  "components": [
    {
      "bom-ref": "pkg:huggingface/example/checkout-risk-model@def456",
      "type": "machine-learning-model",
      "publisher": "Example Inc.",
      "name": "checkout-risk-model",
      "version": "1.1.0",
      "purl": "pkg:huggingface/example/checkout-risk-model@def456",
      "modelCard": {
        "bom-ref": "model-card-checkout-risk-model-v1-1",
        "modelParameters": {
          "datasets": [
            {
              "ref": "component-checkout-risk-training-data-v2"
            }
          ]
        }
      }
    }
  ]
}

The current receipt lane is intentionally strict. It imports the selected model component's bounded identity fields and reference fields: bom-ref, name, and, when present, version, publisher, purl, model-card refs, and dataset refs. Dataset bodies, model-card bodies, vulnerabilities, licenses, pedigree, metrics, and fairness/ethics sections stay outside the receipt boundary.

Assay does not carry the modelCard body or dataset bodies forward. It reduces only bounded identity and reference material from the selected component seam.

Proof artifacts are checked in under the Evidence Receipts in Action assets:

Inventory Receipt¶

The reduced receipt keeps the selected model boundary and source artifact digest:

{
  "schema": "assay.receipt.cyclonedx.mlbom-model-component.v1",
  "source_system": "cyclonedx",
  "source_surface": "bom.components[type=machine-learning-model]",
  "source_artifact_ref": "candidate.cdx.json",
  "source_artifact_digest": "sha256:6b0618708f49e3da21bda99a5dc82ce5409cbaa2e39d152b42fc90bc70f694ac",
  "reducer_version": "assay-cyclonedx-mlbom-model-component@0.1.0",
  "imported_at": "2026-04-28T10:01:00Z",
  "model_component": {
    "bom_ref": "pkg:huggingface/example/checkout-risk-model@def456",
    "name": "checkout-risk-model",
    "version": "1.1.0",
    "publisher": "Example Inc.",
    "purl": "pkg:huggingface/example/checkout-risk-model@def456",
    "model_card_refs": [
      "model-card-checkout-risk-model-v1-1"
    ],
    "dataset_refs": [
      "component-checkout-risk-training-data-v2"
    ]
  }
}

Boundary¶

Assay may claim that a supported external inventory receipt boundary is visible:

{
  "id": "external_inventory_receipt_boundary_visible",
  "level": "verified",
  "source": "external_inventory_receipt",
  "boundary": "supported-external-inventory-receipt-events-only"
}

That claim means one selected CycloneDX ML-BOM model component was reduced into a supported receipt shape, carried through a verifiable bundle, and compiled into a Trust Basis artifact.

When present, bounded identity fields such as version, publisher, and purl may also remain visible in the reduced receipt.

It does not mean Assay owns CycloneDX semantics.

Not Claimed¶

This path does not claim:

• the BOM is complete
• the model is safe, approved, or correct
• the model card is correct
• the referenced datasets are approved
• the licenses or vulnerabilities were evaluated
• CycloneDX officially supports Assay
• the full CycloneDX artifact is imported as Assay truth

The claim is about a reviewable inventory/provenance-reference boundary, not model safety.

Payoff Preview¶

The raw diff stays the canonical CI artifact:

{
  "schema": "assay.trust-basis.diff.v1",
  "summary": {
    "regressed_claims": 0,
    "removed_claims": 0,
    "unchanged_claim_count": 10,
    "has_regressions": false
  }
}

In the non-regression path, this shows that the inventory receipt boundary remained visible and unchanged.

The Markdown projection is intentionally smaller:

Trust Basis Gate
Status: OK
Regressed claims: 0
Removed claims: 0
Unchanged claims: 10

Markdown and JUnit are review projections only. The raw JSON diff remains the canonical CI artifact.

When to Use This¶

Use this path when:

• a CycloneDX ML-BOM already exists in your build or release process
• reviewers need a portable artifact for a model inventory/provenance boundary
• you want Trust Basis diffs and Harness gates above selected model components
• model-card bodies, dataset bodies, licenses, vulnerabilities, and full BOM graphs should stay out of the receipt boundary

For the Assay CLI import reference, see assay evidence import cyclonedx-mlbom-model. For the upstream CycloneDX seam, see the ML-BOM capability and AI Models and Model Cards use case. For the three-family static proof page, see Evidence Receipts in Action.