git.stella-ops.org/docs/modules/binary-index/sbom-extensions.md

# 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

```json
{
  "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:

```json
{
  "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

```json
{
  "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:

```json
{
  "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

```json
{
  "@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

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

## CLI Usage

```bash
# 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
```

## Related Documents

- [Golden Set Schema](./golden-set-schema.md)
- [FixChain Predicate Schema](../attestor/fix-chain-predicate.md)
- [Binary Index Architecture](./architecture.md)