build(gateway): generate deterministic SPDX SBOM

2026-07-30 22:47:55 +07:00
parent 786c96b110
commit 08eb6dc36c
10 changed files with 570 additions and 3 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-30
@@ -0,0 +1,28 @@
+## Context
+
+The repository already produces reproducible pure-Go Linux binaries and can read exact Go module/build metadata. A standard deterministic document is missing; adding an external SBOM tool is unnecessary for this bounded artifact.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Generate byte-stable SPDX 2.3 JSON with Go standard library encoding.
+- Describe the repository, Protocol dependency, all resolved modules, both Linux binaries, relationships, hashes, architectures, notices, and truthful licenses.
+
+**Non-Goals:**
+
+- Vulnerability scanning, signing, image remediation, public release, or inferred license conclusions.
+
+## Decisions
+
+- Use a small repository command that reads each binary with
+  `debug/buildinfo`, verifies Linux architecture and cgo settings, and compares
+  embedded module inventories before sorting every package and relationship.
+- Use fixed SPDX identifiers and a source-date timestamp supplied by the caller; reject dirty/ambiguous inputs rather than embedding current time.
+- Use `NOASSERTION` for unavailable concluded/declared license evidence and record no vulnerability result.
+
+## Risks / Trade-offs
+
+- [Go module metadata lacks complete license conclusions] → retain notices and use `NOASSERTION`.
+- [Artifact paths make output host-dependent] → encode architecture, filename, size, and digest only.
+- [A hand-built serializer could drift] → validate required SPDX fields and require byte-identical double generation.
@@ -0,0 +1,24 @@
+## Why
+
+The gateway has reproducible Linux binaries and a dependency inventory but no deterministic standard SBOM, while OPS-009 and the Phase 3C gateway plan require one for engineering exit.
+
+## What Changes
+
+- Generate byte-stable SPDX 2.3 JSON using repository, Go module, and artifact metadata.
+- Record exact source revision, immutable Protocol version/checksum, module relationships, Linux artifact hashes and architectures, and truthful license fields.
+- Retain notices/provenance and use `NOASSERTION` where license evidence is unavailable.
+- Keep vulnerability scanning, signing, and Phase 3C-C image remediation explicitly separate.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `gateway-deployment-artifact`: Require an inspected deterministic standard SBOM for shipped gateway binaries.
+
+## Impact
+
+Data Plane packaging tooling, deterministic tests, Makefile targets, canonical deployment-artifact OpenSpec, and evidence records. Uses Go standard library only; no new dependency. Requirements: SYS-019, P3C-002, P3C-035, OPS-009, VER-015, VER-017.
@@ -0,0 +1,12 @@
+## MODIFIED Requirements
+
+### Requirement: Artifact evidence is inspected and truthful
+Candidate evidence SHALL record exact source and immutable Protocol revisions/checksums, artifact hashes, architecture, embedded dependency inventory, container configuration when built, and the actual scanner/signing status. It SHALL include one byte-stable SPDX 2.3 JSON SBOM for the shipped Linux gateway artifacts containing the source package, resolved Go modules, dependency and generated-from relationships, artifact hashes and architectures, retained notices/provenance, and truthful license fields using `NOASSERTION` where evidence is unavailable. It MUST NOT claim a vulnerability result, signature, image architecture, deployment, or license conclusion that was not produced and inspected.
+
+#### Scenario: Deterministic gateway SBOM
+- **WHEN** the canonical SBOM command runs twice with the same clean source revision, Protocol module/checksum, module graph, source date, and Linux artifacts
+- **THEN** both SPDX JSON outputs are byte-identical and every declared artifact/module relationship and hash matches the inspected inputs
+
+#### Scenario: Supplemental scanner is unavailable
+- **WHEN** no qualifying vulnerability scanner is available in the frozen environment
+- **THEN** the artifact remains explicitly unscanned and unsigned, the deterministic SBOM/compiler/dependency/boundary evidence is retained, and no zero-finding security claim is emitted
@@ -0,0 +1,14 @@
+## 1. Red deterministic contract
+
+- [x] 1.1 Add a focused test requiring SPDX 2.3 fields, source/Protocol/module relationships, two architectures, and exact artifact hashes
+- [x] 1.2 Prove current packaging cannot produce the required standard SBOM
+
+## 2. Standard-library generator
+
+- [x] 2.1 Implement bounded deterministic SPDX JSON generation from explicit build and Go module metadata
+- [x] 2.2 Record truthful license fields, notices/provenance, unscanned status, and no signing claim
+
+## 3. Verification
+
+- [ ] 3.1 Prove byte-stable regeneration and rejection of dirty, missing, mismatched, or ambiguous inputs
+- [x] 3.2 Reconcile the deployment-artifact canonical spec and run strict validation
@@ -12,8 +12,26 @@ The candidate SHALL build the gateway with the normal immutable Protocol module
 - **THEN** both amd64 and arm64 outputs are byte-identical pure-Go ELF executables with matching embedded GOOS, GOARCH, and cgo settings

 ### Requirement: Artifact evidence is inspected and truthful
-Candidate evidence SHALL record exact source and Protocol revisions, artifact hashes, architecture, embedded dependency inventory, container configuration when built, and the actual scanner/signing status. It MUST NOT claim an SBOM, vulnerability result, signature, image architecture, or deployment that was not produced and inspected.
+Candidate evidence SHALL record exact source and immutable Protocol
+revisions/checksums, artifact hashes, architecture, embedded dependency
+inventory, container configuration when built, and the actual scanner/signing
+status. It SHALL include one byte-stable SPDX 2.3 JSON SBOM for the shipped Linux
+gateway artifacts containing the source package, resolved Go modules, dependency
+and generated-from relationships, artifact hashes and architectures, retained
+notices/provenance, and truthful license fields using `NOASSERTION` where
+evidence is unavailable. It MUST NOT claim a vulnerability result, signature,
+image architecture, deployment, or license conclusion that was not produced and
+inspected.
+
+#### Scenario: Deterministic gateway SBOM
+- **WHEN** the canonical SBOM command runs twice with the same clean source
+  revision, Protocol module/checksum, module graph, source date, and Linux
+  artifacts
+- **THEN** both SPDX JSON outputs are byte-identical and every declared
+  artifact/module relationship and hash matches the inspected inputs

 #### Scenario: Supplemental scanner is unavailable
 - **WHEN** no qualifying vulnerability scanner is available in the frozen environment
- **THEN** the artifact remains explicitly unscanned, deterministic compiler/dependency/boundary evidence is retained, and no zero-finding security claim is emitted
+- **THEN** the artifact remains explicitly unscanned and unsigned, the
+  deterministic SBOM/compiler/dependency/boundary evidence is retained, and no
+  zero-finding security claim is emitted