old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions
This commit is contained in:
master
334
docs/modules/scanner/signed-sbom-archive-spec.md
Normal file
334
docs/modules/scanner/signed-sbom-archive-spec.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# Signed SBOM Archive Specification
|
||||
|
||||
Version: 1.0.0
|
||||
Status: Draft
|
||||
Last Updated: 2026-01-15
|
||||
|
||||
## Overview
|
||||
|
||||
This specification defines a self-contained, cryptographically signed SBOM archive format that bundles:
|
||||
- The SBOM document (SPDX or CycloneDX)
|
||||
- DSSE signature envelope
|
||||
- Verification materials (certificates, transparency proofs)
|
||||
- Metadata (tool versions, timestamps)
|
||||
- Offline verification resources
|
||||
|
||||
## Archive Structure
|
||||
|
||||
```
|
||||
signed-sbom-{digest_short}-{timestamp}.tar.gz
|
||||
|
|
||||
+-- sbom.spdx.json # OR sbom.cdx.json (CycloneDX)
|
||||
+-- sbom.dsse.json # DSSE envelope containing signature
|
||||
+-- manifest.json # Archive inventory with hashes
|
||||
+-- metadata.json # Generation metadata
|
||||
+-- certs/
|
||||
| +-- signing-cert.pem # Signing certificate
|
||||
| +-- signing-chain.pem # Full certificate chain
|
||||
| +-- fulcio-root.pem # Fulcio root CA (for keyless)
|
||||
+-- rekor-proof/ # Optional: transparency log proof
|
||||
| +-- inclusion-proof.json
|
||||
| +-- checkpoint.sig
|
||||
| +-- rekor-public.pem
|
||||
+-- schemas/ # Bundled validation schemas
|
||||
| +-- spdx-2.3.schema.json
|
||||
| +-- spdx-3.0.1.schema.json
|
||||
| +-- cyclonedx-1.7.schema.json
|
||||
| +-- dsse.schema.json
|
||||
+-- VERIFY.md # Human-readable verification guide
|
||||
```
|
||||
|
||||
## File Specifications
|
||||
|
||||
### sbom.spdx.json / sbom.cdx.json
|
||||
|
||||
The primary SBOM document in either:
|
||||
- **SPDX**: Versions 2.3 or 3.0.1 (JSON format)
|
||||
- **CycloneDX**: Versions 1.4, 1.5, 1.6, or 1.7 (JSON format)
|
||||
|
||||
Requirements:
|
||||
- UTF-8 encoding without BOM
|
||||
- Canonical JSON formatting (RFC 8785 compliant)
|
||||
- No trailing whitespace or newlines
|
||||
|
||||
### sbom.dsse.json
|
||||
|
||||
DSSE envelope containing the SBOM signature:
|
||||
|
||||
```json
|
||||
{
|
||||
"payloadType": "application/vnd.stellaops.sbom+json",
|
||||
"payload": "<base64-encoded-sbom>",
|
||||
"signatures": [
|
||||
{
|
||||
"keyid": "SHA256:abc123...",
|
||||
"sig": "<base64-encoded-signature>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### manifest.json
|
||||
|
||||
Archive inventory with integrity hashes:
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "1.0.0",
|
||||
"archiveId": "signed-sbom-abc123-20260115T123456Z",
|
||||
"generatedAt": "2026-01-15T12:34:56Z",
|
||||
"files": [
|
||||
{
|
||||
"path": "sbom.spdx.json",
|
||||
"sha256": "abc123...",
|
||||
"size": 45678,
|
||||
"mediaType": "application/spdx+json"
|
||||
},
|
||||
{
|
||||
"path": "sbom.dsse.json",
|
||||
"sha256": "def456...",
|
||||
"size": 1234,
|
||||
"mediaType": "application/vnd.dsse+json"
|
||||
}
|
||||
],
|
||||
"merkleRoot": "sha256:789abc...",
|
||||
"totalFiles": 12,
|
||||
"totalSize": 98765
|
||||
}
|
||||
```
|
||||
|
||||
### metadata.json
|
||||
|
||||
Generation and tool metadata:
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "1.0.0",
|
||||
"stellaOps": {
|
||||
"suiteVersion": "2027.Q1",
|
||||
"scannerVersion": "1.2.3",
|
||||
"scannerDigest": "sha256:scanner-image-digest",
|
||||
"signerVersion": "1.0.0",
|
||||
"sbomServiceVersion": "1.1.0"
|
||||
},
|
||||
"generation": {
|
||||
"timestamp": "2026-01-15T12:34:56Z",
|
||||
"hlcTimestamp": "1737000000000000000",
|
||||
"operator": "build@company.com"
|
||||
},
|
||||
"input": {
|
||||
"imageRef": "registry.company.com/app:v1.0.0",
|
||||
"imageDigest": "sha256:image-digest-here",
|
||||
"platform": "linux/amd64"
|
||||
},
|
||||
"sbom": {
|
||||
"format": "spdx-2.3",
|
||||
"componentCount": 142,
|
||||
"packageCount": 89,
|
||||
"fileCount": 1247
|
||||
},
|
||||
"signature": {
|
||||
"type": "keyless",
|
||||
"issuer": "https://accounts.google.com",
|
||||
"subject": "build@company.com",
|
||||
"signedAt": "2026-01-15T12:34:57Z"
|
||||
},
|
||||
"reproducibility": {
|
||||
"deterministic": true,
|
||||
"expectedDigest": "sha256:expected-sbom-digest"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### VERIFY.md
|
||||
|
||||
Human-readable verification instructions:
|
||||
|
||||
```markdown
|
||||
# SBOM Archive Verification
|
||||
|
||||
## Quick Verification
|
||||
|
||||
```bash
|
||||
# Verify archive integrity
|
||||
sha256sum -c <<EOF
|
||||
abc123... sbom.spdx.json
|
||||
def456... sbom.dsse.json
|
||||
EOF
|
||||
|
||||
# Verify signature using cosign
|
||||
cosign verify-blob \
|
||||
--signature sbom.dsse.json \
|
||||
--certificate certs/signing-cert.pem \
|
||||
--certificate-chain certs/signing-chain.pem \
|
||||
sbom.spdx.json
|
||||
```
|
||||
|
||||
## Offline Verification
|
||||
|
||||
```bash
|
||||
# Using bundled Fulcio root
|
||||
cosign verify-blob \
|
||||
--signature sbom.dsse.json \
|
||||
--certificate certs/signing-cert.pem \
|
||||
--certificate-chain certs/signing-chain.pem \
|
||||
--certificate-oidc-issuer https://accounts.google.com \
|
||||
--offline \
|
||||
sbom.spdx.json
|
||||
```
|
||||
|
||||
## Rekor Inclusion Proof
|
||||
|
||||
```bash
|
||||
# Verify transparency log inclusion
|
||||
rekor-cli verify \
|
||||
--artifact sbom.spdx.json \
|
||||
--signature sbom.dsse.json \
|
||||
--public-key certs/signing-cert.pem \
|
||||
--rekor-server https://rekor.sigstore.dev
|
||||
```
|
||||
```
|
||||
|
||||
## Cryptographic Requirements
|
||||
|
||||
### Hash Algorithms
|
||||
|
||||
| Purpose | Algorithm | Format |
|
||||
|---------|-----------|--------|
|
||||
| File hashes | SHA-256 | Lowercase hex |
|
||||
| Merkle tree | SHA-256 | Lowercase hex with `sha256:` prefix |
|
||||
| Certificate fingerprint | SHA-256 | Uppercase hex with colons |
|
||||
|
||||
### Signature Algorithms
|
||||
|
||||
Supported signature algorithms:
|
||||
- **ECDSA-P256**: Recommended for keyless (Fulcio)
|
||||
- **ECDSA-P384**: High-security environments
|
||||
- **RSA-PSS-4096**: Legacy compatibility
|
||||
- **Ed25519**: High-performance signing
|
||||
|
||||
### DSSE Envelope
|
||||
|
||||
DSSE (Dead Simple Signing Envelope) per specification:
|
||||
- PAE (Pre-Authentication Encoding) for signing
|
||||
- Base64 encoding for payload and signatures
|
||||
- Multiple signatures supported for threshold signing
|
||||
|
||||
## Verification Process
|
||||
|
||||
### Step 1: Archive Integrity
|
||||
|
||||
```python
|
||||
# Verify tar.gz integrity
|
||||
import tarfile
|
||||
import hashlib
|
||||
|
||||
with tarfile.open("signed-sbom.tar.gz", "r:gz") as tar:
|
||||
manifest = json.load(tar.extractfile("manifest.json"))
|
||||
|
||||
for file_entry in manifest["files"]:
|
||||
content = tar.extractfile(file_entry["path"]).read()
|
||||
actual_hash = hashlib.sha256(content).hexdigest()
|
||||
assert actual_hash == file_entry["sha256"]
|
||||
```
|
||||
|
||||
### Step 2: Signature Verification
|
||||
|
||||
```python
|
||||
# Verify DSSE signature
|
||||
from sigstore.verify import Verifier
|
||||
|
||||
verifier = Verifier.production()
|
||||
result = verifier.verify(
|
||||
artifact=sbom_content,
|
||||
signature=dsse_envelope,
|
||||
certificate=signing_cert
|
||||
)
|
||||
assert result.success
|
||||
```
|
||||
|
||||
### Step 3: Certificate Chain Validation
|
||||
|
||||
```python
|
||||
# Validate certificate chain
|
||||
from cryptography import x509
|
||||
|
||||
chain = load_certificate_chain("certs/signing-chain.pem")
|
||||
root = load_certificate("certs/fulcio-root.pem")
|
||||
|
||||
validate_chain(chain, root)
|
||||
```
|
||||
|
||||
### Step 4: Transparency Log (Optional)
|
||||
|
||||
```python
|
||||
# Verify Rekor inclusion
|
||||
from rekor_client import verify_inclusion
|
||||
|
||||
result = verify_inclusion(
|
||||
artifact_hash=sbom_hash,
|
||||
proof=inclusion_proof,
|
||||
checkpoint=checkpoint
|
||||
)
|
||||
assert result.verified
|
||||
```
|
||||
|
||||
## Compatibility
|
||||
|
||||
### SBOM Formats
|
||||
|
||||
| Format | Version | Status |
|
||||
|--------|---------|--------|
|
||||
| SPDX | 2.3 | Supported |
|
||||
| SPDX | 3.0.1 | Supported |
|
||||
| CycloneDX | 1.4 | Supported |
|
||||
| CycloneDX | 1.5 | Supported |
|
||||
| CycloneDX | 1.6 | Supported |
|
||||
| CycloneDX | 1.7 | Supported |
|
||||
|
||||
### Compression
|
||||
|
||||
| Format | Extension | Status |
|
||||
|--------|-----------|--------|
|
||||
| gzip | .tar.gz | Default |
|
||||
| zstd | .tar.zst | Recommended (smaller) |
|
||||
| none | .tar | Supported |
|
||||
|
||||
## API Endpoint
|
||||
|
||||
```
|
||||
GET /scans/{scanId}/exports/signed-sbom-archive
|
||||
```
|
||||
|
||||
Query Parameters:
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| format | string | spdx-2.3 | SBOM format |
|
||||
| compression | string | gzip | Compression type |
|
||||
| includeRekor | bool | true | Include Rekor proof |
|
||||
| includeSchemas | bool | true | Bundle JSON schemas |
|
||||
|
||||
Response Headers:
|
||||
| Header | Description |
|
||||
|--------|-------------|
|
||||
| Content-Type | application/gzip or application/zstd |
|
||||
| Content-Disposition | attachment; filename="signed-sbom-{digest}.tar.gz" |
|
||||
| X-SBOM-Digest | SHA-256 of SBOM content |
|
||||
| X-Archive-Merkle-Root | Merkle root of archive |
|
||||
| X-Rekor-Log-Index | Rekor log index (if applicable) |
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Determinism**: All outputs must be reproducible given same inputs
|
||||
2. **Canonicalization**: JSON must be RFC 8785 canonical before signing
|
||||
3. **Time sources**: Use injected TimeProvider, not system clock
|
||||
4. **Key material**: Never include private keys in archives
|
||||
5. **Offline verification**: Bundle all necessary verification materials
|
||||
|
||||
## Related Specifications
|
||||
|
||||
- [DSSE Specification](https://github.com/secure-systems-lab/dsse)
|
||||
- [Sigstore Signing Specification](https://docs.sigstore.dev)
|
||||
- [SPDX Specification](https://spdx.github.io/spdx-spec/)
|
||||
- [CycloneDX Specification](https://cyclonedx.org/specification/)
|
||||
- [Rekor Transparency Log](https://docs.sigstore.dev/rekor/)
|
||||
Reference in New Issue
Block a user