SBOM Extension Fields for FixChain Attestation

Sprint: SPRINT_20260110_012_005_ATTESTOR Last Updated: 10-Jan-2026

This document describes the extension fields used to link FixChain attestations to SBOM components.

Overview

When a FixChain attestation verifies that a patch eliminates a vulnerability, the results can be embedded in the SBOM as extension properties. This enables consumers to verify fix status directly from the SBOM without separate attestation lookup.

CycloneDX Properties

CycloneDX 1.4+ supports custom properties on components. StellaOps uses the stellaops: namespace for FixChain-related properties.

Component-Level Properties

{
  "components": [
    {
      "type": "library",
      "name": "openssl",
      "version": "3.1.0",
      "purl": "pkg:deb/debian/openssl@3.1.0",
      "properties": [
        {
          "name": "stellaops:fixChainRef",
          "value": "sha256:abc123def456789..."
        },
        {
          "name": "stellaops:fixChainVerdict",
          "value": "fixed"
        },
        {
          "name": "stellaops:fixChainConfidence",
          "value": "0.97"
        },
        {
          "name": "stellaops:goldenSetRef",
          "value": "sha256:def456abc789012..."
        },
        {
          "name": "stellaops:fixChainCve",
          "value": "CVE-2024-0727"
        },
        {
          "name": "stellaops:fixChainAnalyzedAt",
          "value": "2026-01-15T12:00:00Z"
        }
      ]
    }
  ]
}

Property Definitions

Property	Description	Example
`stellaops:fixChainRef`	Content digest of the FixChain attestation	`sha256:abc123...`
`stellaops:fixChainVerdict`	Verdict status: `fixed`, `partial`, `not_fixed`, `inconclusive`	`fixed`
`stellaops:fixChainConfidence`	Confidence score (0.0 - 1.0)	`0.97`
`stellaops:goldenSetRef`	Content digest of the golden set definition	`sha256:def456...`
`stellaops:fixChainCve`	CVE identifier being verified	`CVE-2024-0727`
`stellaops:fixChainAnalyzedAt`	ISO 8601 timestamp of analysis	`2026-01-15T12:00:00Z`

Multiple CVE Verification

When multiple CVEs are verified for the same component, use indexed properties:

{
  "properties": [
    {
      "name": "stellaops:fixChainRef:0",
      "value": "sha256:abc123..."
    },
    {
      "name": "stellaops:fixChainCve:0",
      "value": "CVE-2024-0727"
    },
    {
      "name": "stellaops:fixChainVerdict:0",
      "value": "fixed"
    },
    {
      "name": "stellaops:fixChainRef:1",
      "value": "sha256:def456..."
    },
    {
      "name": "stellaops:fixChainCve:1",
      "value": "CVE-2024-0728"
    },
    {
      "name": "stellaops:fixChainVerdict:1",
      "value": "partial"
    }
  ]
}

SPDX Annotations

SPDX 2.3 supports annotations for attaching additional information to packages.

Package Annotation

{
  "packages": [
    {
      "SPDXID": "SPDXRef-Package-openssl",
      "name": "openssl",
      "versionInfo": "3.1.0"
    }
  ],
  "annotations": [
    {
      "annotationDate": "2026-01-15T12:00:00Z",
      "annotationType": "OTHER",
      "annotator": "Tool: StellaOps FixChain Analyzer v1.0.0",
      "comment": "Fix verified: CVE-2024-0727 (97% confidence). FixChain: sha256:abc123..., GoldenSet: sha256:def456..."
    }
  ]
}

Structured Annotation Format

For machine-readable annotations, use JSON within the comment field:

{
  "annotations": [
    {
      "annotationDate": "2026-01-15T12:00:00Z",
      "annotationType": "OTHER",
      "annotator": "Tool: StellaOps FixChain Analyzer v1.0.0",
      "comment": "{\"type\":\"stellaops:fixchain\",\"cveId\":\"CVE-2024-0727\",\"verdict\":\"fixed\",\"confidence\":0.97,\"fixChainRef\":\"sha256:abc123...\",\"goldenSetRef\":\"sha256:def456...\"}"
    }
  ]
}

SPDX 3.0 Extensions

SPDX 3.0 introduces external references which provide better support for attestations.

Security External Reference

{
  "@type": "software_Package",
  "@id": "urn:spdx:Package-openssl",
  "name": "openssl",
  "packageVersion": "3.1.0",
  "externalRef": [
    {
      "@type": "ExternalRef",
      "externalRefType": "securityOther",
      "locator": "sha256:abc123def456789...",
      "comment": "FixChain attestation for CVE-2024-0727"
    }
  ]
}

Verification Workflow

Extract Properties: Parse SBOM and extract stellaops:fixChainRef properties
Fetch Attestation: Retrieve attestation by content digest
Verify Signature: Validate DSSE envelope signature
Verify Predicate: Parse and validate FixChainPredicate
Match Component: Verify SBOM component matches attestation subject
Check Verdict: Confirm verdict meets policy requirements

CLI Usage

# Annotate SBOM with FixChain attestation
stella sbom annotate \
  --sbom sbom.cdx.json \
  --fixchain attestation.dsse.json \
  --output sbom-annotated.cdx.json

# Verify SBOM annotations
stella sbom verify-fixchain \
  --sbom sbom-annotated.cdx.json \
  --attestation-store /path/to/store

# Export fix status report
stella sbom fixchain-report \
  --sbom sbom-annotated.cdx.json \
  --format markdown