audit work, fixed StellaOps.sln warnings/errors, fixed tests, sprints work, new advisories
This commit is contained in:
master
@@ -0,0 +1,56 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "http://cyclonedx.org/schema/bom-1.7.schema.json",
|
||||
"$comment": "Placeholder schema for CycloneDX 1.7 - Download full schema from https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.7.schema.json",
|
||||
"type": "object",
|
||||
"title": "CycloneDX Software Bill of Materials Standard",
|
||||
"properties": {
|
||||
"bomFormat": {
|
||||
"type": "string",
|
||||
"enum": ["CycloneDX"]
|
||||
},
|
||||
"specVersion": {
|
||||
"type": "string"
|
||||
},
|
||||
"serialNumber": {
|
||||
"type": "string"
|
||||
},
|
||||
"version": {
|
||||
"type": "integer"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "object"
|
||||
},
|
||||
"components": {
|
||||
"type": "array"
|
||||
},
|
||||
"services": {
|
||||
"type": "array"
|
||||
},
|
||||
"externalReferences": {
|
||||
"type": "array"
|
||||
},
|
||||
"dependencies": {
|
||||
"type": "array"
|
||||
},
|
||||
"compositions": {
|
||||
"type": "array"
|
||||
},
|
||||
"vulnerabilities": {
|
||||
"type": "array"
|
||||
},
|
||||
"annotations": {
|
||||
"type": "array"
|
||||
},
|
||||
"formulation": {
|
||||
"type": "array"
|
||||
},
|
||||
"declarations": {
|
||||
"type": "object"
|
||||
},
|
||||
"definitions": {
|
||||
"type": "object"
|
||||
}
|
||||
},
|
||||
"required": ["bomFormat", "specVersion"]
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://spdx.org/schema/3.0.1/spdx-json-schema.json",
|
||||
"$comment": "Placeholder schema for SPDX 3.0.1 JSON-LD - Download full schema from https://spdx.org/schema/3.0.1/spdx-json-schema.json",
|
||||
"type": "object",
|
||||
"title": "SPDX 3.0.1 JSON-LD Schema",
|
||||
"properties": {
|
||||
"@context": {
|
||||
"oneOf": [
|
||||
{ "type": "string" },
|
||||
{ "type": "object" },
|
||||
{ "type": "array" }
|
||||
]
|
||||
},
|
||||
"@graph": {
|
||||
"type": "array"
|
||||
},
|
||||
"@type": {
|
||||
"type": "string"
|
||||
},
|
||||
"spdxId": {
|
||||
"type": "string"
|
||||
},
|
||||
"creationInfo": {
|
||||
"type": "object"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"element": {
|
||||
"type": "array"
|
||||
},
|
||||
"rootElement": {
|
||||
"type": "array"
|
||||
},
|
||||
"namespaceMap": {
|
||||
"type": "array"
|
||||
},
|
||||
"externalMap": {
|
||||
"type": "array"
|
||||
}
|
||||
}
|
||||
}
|
||||
311
docs/modules/sbom-service/spdx3-profile-support.md
Normal file
311
docs/modules/sbom-service/spdx3-profile-support.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user