312 lines
7.9 KiB
Markdown
312 lines
7.9 KiB
Markdown
# SPDX 3.0.1 Profile Support
|
|
|
|
> **Version:** Draft
|
|
> **Status:** Planned
|
|
> **Sprint:** [SPRINT_20260107_004](../../implplan/SPRINT_20260107_004_000_INDEX_spdx3_profile_support.md)
|
|
|
|
This document describes StellaOps support for SPDX 3.0.1 and its profile-based model.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
SPDX 3.0.1 introduces a **profile-based model** that extends the Core specification with domain-specific metadata. StellaOps implements the following profiles:
|
|
|
|
| Profile | Status | Description | Integration |
|
|
|---------|--------|-------------|-------------|
|
|
| Core | Planned | Foundation for all elements | Required |
|
|
| Software | Planned | Packages, files, snippets | Scanner |
|
|
| Lite | Planned | Minimal CI/CD SBOMs | Scanner |
|
|
| Build | Planned | Build provenance | Attestor |
|
|
| Security | Planned | Vulnerability assessments | VexLens |
|
|
| Licensing | Future | License expressions | Policy |
|
|
| AI | Future | AI model artifacts | AdvisoryAI |
|
|
| Dataset | Future | Dataset metadata | Future |
|
|
|
|
---
|
|
|
|
## Current Support
|
|
|
|
### SPDX 2.x (Current)
|
|
|
|
StellaOps currently supports SPDX 2.2 and 2.3:
|
|
|
|
- **Parsing:** Full support via `SpdxParser`
|
|
- **Generation:** SPDX 2.3 JSON format
|
|
- **Integration:** AirGap importer, Scanner output
|
|
|
|
### SPDX 3.0.1 (Planned)
|
|
|
|
Full SPDX 3.0.1 support is planned with:
|
|
|
|
- **Parsing:** JSON-LD format with profile detection
|
|
- **Generation:** Profile-conformant output
|
|
- **Integration:** Attestor (Build), VexLens (Security)
|
|
|
|
---
|
|
|
|
## Profile Details
|
|
|
|
### Core Profile
|
|
|
|
The Core profile is the foundation for all SPDX 3.0.1 documents.
|
|
|
|
**Key Elements:**
|
|
- `Element` - Base for all typed elements
|
|
- `Relationship` - Links between elements
|
|
- `CreationInfo` - Document metadata
|
|
- `ExternalRef` - References to external resources
|
|
- `ExternalIdentifier` - PURL, CPE, SWID identifiers
|
|
- `IntegrityMethod` - Hash verification
|
|
|
|
**Required Fields:**
|
|
- `spdxId` - Unique IRI identifier
|
|
- `creationInfo` - With `specVersion: "3.0.1"`
|
|
|
|
### Software Profile
|
|
|
|
The Software profile describes software components.
|
|
|
|
**Key Elements:**
|
|
- `Package` - Software package
|
|
- `File` - Individual file
|
|
- `Snippet` - Code snippet
|
|
- `SpdxDocument` - Document root
|
|
|
|
**Common Properties:**
|
|
- `packageVersion` - Version string
|
|
- `packageUrl` - PURL (via ExternalIdentifier)
|
|
- `downloadLocation` - Source URL
|
|
- `homePage` - Project homepage
|
|
|
|
**Example:**
|
|
```json
|
|
{
|
|
"@type": "software_Package",
|
|
"spdxId": "urn:stellaops:spdx:sha256-abc:Package:xyz",
|
|
"name": "example-package",
|
|
"software_packageVersion": "1.0.0",
|
|
"externalIdentifier": [
|
|
{
|
|
"@type": "ExternalIdentifier",
|
|
"externalIdentifierType": "packageUrl",
|
|
"identifier": "pkg:npm/example-package@1.0.0"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Lite Profile
|
|
|
|
The Lite profile provides minimal SBOMs for CI/CD pipelines.
|
|
|
|
**Minimal Required Fields:**
|
|
- `spdxId`
|
|
- `creationInfo` (created, createdBy, specVersion)
|
|
- `name`
|
|
- `packageVersion` (for packages)
|
|
- `downloadLocation` OR `packageUrl`
|
|
|
|
**Use Cases:**
|
|
- CI/CD pipeline artifacts
|
|
- Quick compliance checks
|
|
- Lightweight transmission
|
|
|
|
### Build Profile
|
|
|
|
The Build profile captures build provenance.
|
|
|
|
**Key Element:**
|
|
- `Build` - Build process information
|
|
|
|
**Properties:**
|
|
- `buildType` - Build system URI
|
|
- `buildId` - Unique build identifier
|
|
- `buildStartTime` / `buildEndTime` - Timing
|
|
- `configSourceUri` - Build configuration sources
|
|
- `environment` - Build environment
|
|
- `parameter` - Build parameters
|
|
|
|
**Integration with Attestor:**
|
|
```
|
|
in-toto/SLSA SPDX 3.0.1 Build
|
|
----------- ----------------
|
|
buildType --> build_buildType
|
|
builder.id --> createdBy (Agent)
|
|
invocation.config --> build_configSourceUri
|
|
materials --> Relationships (GENERATED_FROM)
|
|
```
|
|
|
|
### Security Profile
|
|
|
|
The Security profile describes vulnerability assessments.
|
|
|
|
**Key Elements:**
|
|
- `Vulnerability` - CVE/vulnerability reference
|
|
- `VexAffectedVulnAssessmentRelationship`
|
|
- `VexNotAffectedVulnAssessmentRelationship`
|
|
- `VexFixedVulnAssessmentRelationship`
|
|
- `VexUnderInvestigationVulnAssessmentRelationship`
|
|
- `CvssV3VulnAssessmentRelationship`
|
|
- `EpssVulnAssessmentRelationship`
|
|
|
|
**Integration with VexLens:**
|
|
```
|
|
OpenVEX SPDX 3.0.1 Security
|
|
------- -------------------
|
|
status: affected --> VexAffectedVulnAssessmentRelationship
|
|
status: not_affected --> VexNotAffectedVulnAssessmentRelationship
|
|
status: fixed --> VexFixedVulnAssessmentRelationship
|
|
justification --> statusNotes
|
|
action_statement --> actionStatement
|
|
```
|
|
|
|
---
|
|
|
|
## JSON-LD Structure
|
|
|
|
SPDX 3.0.1 uses JSON-LD format:
|
|
|
|
```json
|
|
{
|
|
"@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
|
|
"@graph": [
|
|
{
|
|
"@type": "SpdxDocument",
|
|
"spdxId": "urn:example:doc",
|
|
"creationInfo": {
|
|
"@type": "CreationInfo",
|
|
"specVersion": "3.0.1",
|
|
"created": "2026-01-07T12:00:00Z",
|
|
"createdBy": ["urn:example:tool:stellaops"],
|
|
"profile": [
|
|
"https://spdx.org/rdf/3.0.1/terms/Core/ProfileIdentifierType/core",
|
|
"https://spdx.org/rdf/3.0.1/terms/Software/ProfileIdentifierType/software"
|
|
]
|
|
},
|
|
"rootElement": ["urn:example:pkg:root"],
|
|
"element": [
|
|
"urn:example:pkg:root",
|
|
"urn:example:pkg:dep1"
|
|
]
|
|
},
|
|
{
|
|
"@type": "software_Package",
|
|
"spdxId": "urn:example:pkg:root",
|
|
"name": "my-application",
|
|
"software_packageVersion": "2.0.0"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## API Usage
|
|
|
|
### Scanner SBOM Generation
|
|
|
|
```http
|
|
GET /api/v1/scan/{id}/sbom?format=spdx3&profile=software
|
|
```
|
|
|
|
**Parameters:**
|
|
| Parameter | Values | Default |
|
|
|-----------|--------|---------|
|
|
| `format` | `spdx3`, `spdx2`, `cyclonedx` | `spdx2` |
|
|
| `profile` | `software`, `lite` | `software` |
|
|
|
|
### Attestor Build Profile
|
|
|
|
```http
|
|
GET /api/v1/attestation/{id}?format=spdx3
|
|
```
|
|
|
|
### VexLens Security Profile
|
|
|
|
```http
|
|
GET /api/v1/vex/consensus/{artifact}?format=spdx3
|
|
```
|
|
|
|
---
|
|
|
|
## Profile Conformance
|
|
|
|
Documents declare profile conformance in `CreationInfo.profile`:
|
|
|
|
```json
|
|
{
|
|
"profile": [
|
|
"https://spdx.org/rdf/3.0.1/terms/Core/ProfileIdentifierType/core",
|
|
"https://spdx.org/rdf/3.0.1/terms/Software/ProfileIdentifierType/software",
|
|
"https://spdx.org/rdf/3.0.1/terms/Security/ProfileIdentifierType/security"
|
|
]
|
|
}
|
|
```
|
|
|
|
StellaOps validates documents against declared profiles when:
|
|
- Parsing external documents (opt-in validation)
|
|
- Generating documents (automatic conformance)
|
|
|
|
---
|
|
|
|
## Migration from SPDX 2.x
|
|
|
|
### Parallel Support
|
|
|
|
During transition, StellaOps supports both formats:
|
|
|
|
1. **SPDX 2.x** - Default for backward compatibility
|
|
2. **SPDX 3.0.1** - Opt-in via `format=spdx3`
|
|
|
|
### Key Differences
|
|
|
|
| Aspect | SPDX 2.x | SPDX 3.0.1 |
|
|
|--------|----------|------------|
|
|
| Format | Flat JSON | JSON-LD |
|
|
| Version field | `spdxVersion` | `specVersion` in CreationInfo |
|
|
| Packages | `packages[]` array | `@graph` with `@type` |
|
|
| Relationships | `relationships[]` | Relationship elements in `@graph` |
|
|
| Checksums | `checksums[]` | `verifiedUsing` IntegrityMethod |
|
|
| PURL | `externalRefs` | `externalIdentifier` |
|
|
|
|
### Version Detection
|
|
|
|
StellaOps auto-detects SPDX version:
|
|
|
|
```csharp
|
|
// 2.x: Has spdxVersion property
|
|
if (root.TryGetProperty("spdxVersion", out _))
|
|
return SpdxVersion.V2;
|
|
|
|
// 3.x: Has @context property
|
|
if (root.TryGetProperty("@context", out _))
|
|
return SpdxVersion.V3;
|
|
```
|
|
|
|
---
|
|
|
|
## Air-Gap Considerations
|
|
|
|
For air-gapped deployments:
|
|
|
|
1. **Bundle contexts locally** - SPDX JSON-LD contexts must be available offline
|
|
2. **Configure local context URIs** - Point to local context files
|
|
3. **Validate offline** - Use bundled schemas for validation
|
|
|
|
```yaml
|
|
# etc/spdx3.yaml
|
|
Spdx3:
|
|
ContextResolution:
|
|
Mode: Local # or Remote, Cached
|
|
LocalContextPath: /etc/stellaops/spdx3-contexts/
|
|
```
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- [SPDX 3.0.1 Specification](https://spdx.github.io/spdx-spec/v3.0.1/)
|
|
- [SPDX 3.0.1 Model Repository](https://github.com/spdx/spdx-3-model)
|
|
- [Sprint: SPDX 3.0.1 Profile Support](../../implplan/SPRINT_20260107_004_000_INDEX_spdx3_profile_support.md)
|