stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 12 Releases Wiki Activity
Files
5970f0d9bd10d45056fb80ccf4aba7c82090be25
git.stella-ops.org/docs/modules/scanner/deterministic-sbom-compose.md
master cef4cb2c5a Add support for ГОСТ Р 34.10 digital signatures 
- Implemented the GostKeyValue class for handling public key parameters in ГОСТ Р 34.10 digital signatures.
- Created the GostSignedXml class to manage XML signatures using ГОСТ 34.10, including methods for computing and checking signatures.
- Developed the GostSignedXmlImpl class to encapsulate the signature computation logic and public key retrieval.
- Added specific key value classes for ГОСТ Р 34.10-2001, ГОСТ Р 34.10-2012/256, and ГОСТ Р 34.10-2012/512 to support different signature algorithms.
- Ensured compatibility with existing XML signature standards while integrating ГОСТ cryptography.
2025-11-09 21:59:57 +02:00

4.2 KiB
Raw Blame History

Deterministic SBOM Composition (Spec Draft)

Status: Draft v0.1 (Sprint 136 / 203 / 209 linkage)
Owners: Scanner Guild · DevEx/CLI Guild · UI Guild · Docs Guild · Security Guild
Related Tasks: SCANNER-SURFACE-04, SURFACE-FS-07, SCANNER-EMIT-15-001, SCANNER-SORT-02, CLI-SBOM-60-001, CLI-SBOM-60-002, UI-SBOM-DET-01, UI-POLICY-DET-01, DOCS-SCANNER-DET-01, DOCS-POLICY-DET-01, DOCS-CLI-DET-01, SCANNER-CRYPTO-90-002, SCANNER-CRYPTO-90-003

1. Purpose

Guarantee that every container scan yields provably deterministic SBOM artifacts that can be verified offline. Each layer fragment is DSSE-signed before merge, _composition.json captures the canonical merge recipe, and the final CycloneDX inventory/usage SBOMs expose Merkle roots and stella.contentHash properties. CLI/UI/policy layers consume those signals to block non-deterministic releases and provide human-friendly diagnostics.

2. Scope

2.1 Fragment attestation

  • Scanner Worker emits layer.fragments payloads as canonical JSON (lexicographic keys, compact whitespace, normalized timestamps, ordered component arrays).
  • Each fragment is signed via DSSE (default Ed25519; PQ/Dilithium toggle routed through ICryptoProviderRegistry).
  • _composition.json records {layerDigest, fragmentSha256, dsseEnvelopeSha256} per fragment alongside the overall Merkle root.
  • Surface manifests append links to fragment DSSE envelopes so offline kits can fetch them without re-scan.

2.2 Canonical merge

  • Merge order strictly follows layerDigest (ascending hex) and then component.identity.purl (fallback to identity.key).
  • CycloneDX metadata gains:
    • properties["stellaops:stella.contentHash"] for each fragment and composition root.
    • properties["stellaops:composition.manifest"] referencing _composition.json CAS URI.
    • properties["stellaops:merkle.root"] for the composed BOM.
  • ScannerTimestamps.Normalize continues to zero fractional microseconds; SBOM timestamps should default to "0001-01-01T00:00:00Z" when no semantic timestamp is required.

2.3 Surface manifest extensions

  • SurfaceManifestArtifact gains optional attestations[] with {kind, mediaType, digest, uri} for DSSE envelopes.
  • _composition.json is published as an additional artifact kind composition.recipe.
  • Surface reader/writer validate Merkle roots before caching manifest entries.

2.4 Tooling impacts

  • CLI (stella sbomer ...): adds layer and compose verbs, deterministic diff reporting, and offline verification per _composition.json.
  • UI/Policy: determinism badge, drift diffs, and a policy gate that blocks releases when fragment DSSE/verifications fail.
  • Docs: new guides under docs/scanner & docs/cli plus policy references detailing how to interpret determinism metadata.
  • Crypto: PQ-friendly DSSE toggle delivered via SCANNER-CRYPTO-90-002/003 so sovereign bundles can select Dilithium/Falcon.

3. Verification Flow (offline kit)

  1. Verify DSSE on each fragment (using verifiers.json).
  2. Recompute sha256(c14n(fragment)) and compare with _composition.json.
  3. Re-run composition locally (using canonical ordering) and compare sha256(c14n(composed)) against manifest.properties["stellaops:merkle.root"].
  4. Optionally validate provided Merkle proofs (leaf → root) and attest that the UI/Policy gate marked the scan as deterministic.

4. Deliverables Checklist

Area Deliverable
Scanner Worker DSSE per fragment, _composition.json, canonical fragment serializer, Surface manifest updates
Emit pipeline Layer-sorted composition, stella.contentHash, Merkle metadata, PQ-aware signing hooks
CLI stella sbomer layer/compose/drift, verification commands, documentation
UI Determinism badge, drift diagnostics, policy gate wiring
Docs Updated scanner/cli/policy guides, offline kit instructions
Tests Regression suites covering canonicalization, DSSE verification, PQ keypaths, Merkle roots

5. References

  • docs/modules/scanner/architecture.md
  • docs/modules/scanner/design/surface-fs.md
  • docs/replay/DETERMINISTIC_REPLAY.md
  • docs/modules/cli/architecture.md
  • docs/modules/policy/architecture.md