Complete batch 012 (golden set diff) and 013 (advisory chat), fix build errors
Sprints completed: - SPRINT_20260110_012_* (golden set diff layer - 10 sprints) - SPRINT_20260110_013_* (advisory chat - 4 sprints) Build fixes applied: - Fix namespace conflicts with Microsoft.Extensions.Options.Options.Create - Fix VexDecisionReachabilityIntegrationTests API drift (major rewrite) - Fix VexSchemaValidationTests FluentAssertions method name - Fix FixChainGateIntegrationTests ambiguous type references - Fix AdvisoryAI test files required properties and namespace aliases - Add stub types for CveMappingController (ICveSymbolMappingService) - Fix VerdictBuilderService static context issue Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
master
202
docs/modules/binary-index/sbom-extensions.md
Normal file
202
docs/modules/binary-index/sbom-extensions.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user