Skip to content

build: add reproducible firmware container baseline - #15

Open
Zartharas wants to merge 3 commits into
Monstatek:mainfrom
Zartharas:wp1/reproducible-build-baseline
Open

Zartharas wants to merge 3 commits into
Monstatek:mainfrom
Zartharas:wp1/reproducible-build-baseline

Conversation

@Zartharas

Copy link
Copy Markdown

Summary

This change establishes the WP1 reproducible firmware-build baseline for Monstatek M1.

It:

  • adds a structured engineering-review framework
  • adds a canonical Linux/amd64 container build
  • pins the Debian base-image digest
  • pins and verifies the official Arm GNU Toolchain 14.2.Rel1 archive
  • exports only committed source for the build
  • derives SOURCE_DATE_EPOCH from the source commit
  • disables BuildKit provenance generation for stable image identity
  • disables network access during tool-version and firmware-build containers
  • records sanitized build, artifact, and repeatability evidence
  • documents current limitations and follow-up findings

Motivation

The repository previously lacked a fully documented, repeatable canonical firmware-build path.

The new container workflow provides a stable Linux/amd64 environment and records sufficient metadata to identify the source, build definition, toolchain, image, and resulting release artifacts.

Validation

The finalized build definition was validated at commit:

8c5e4f2401e37593281ffde490f657ba05b061a2

Two clean builds from that exact commit produced:

  • the same Docker image ID
  • byte-identical BIN output
  • byte-identical CRC-bearing BIN output
  • byte-identical ELF output
  • byte-identical Intel HEX output
  • identical SHA256SUMS
  • identical build metadata
  • the same firmware-warning count

Validated image identity:

sha256:127f9407e8f8bb9a2c5f811597a51dbfe9eeab558b82bd030ff1f3c086ac4bfa

Validated artifact hashes:

Artifact SHA-256
MonstaTek_M1_v0800.bin 433790ee249a574a58d60281fc5da09e72debb05bd478283bd912e1a3434d176
MonstaTek_M1_v0800_wCRC.bin 7101bb1511dd63fcc54298f0befdc991a84f25bce53208a6c3bf8ebe7ac45202
MonstaTek_M1_v0800.elf caa8c8b1882d49122fc5d4340c38b269a0fc230ef6500cb15f7f9838a0ccc64a
MonstaTek_M1_v0800.hex 22706a7ba1373a348d67fc1651bd76220c86ff4860923e3717799eed87aa57e4

Additional validation included:

  • 319 completed Ninja actions
  • ELF format elf32-littlearm
  • architecture armv8-m.main
  • text/data/BSS values of 470536 / 7032 / 169872
  • artifact manifest verification
  • documentation-link validation
  • public-evidence sanitization
  • exact commit-scope validation
  • clean working-tree validation
  • confirmation that existing tracked release artifacts were not changed

Current limitations

This PR does not claim:

  • byte identity between native macOS and Linux-container builds
  • runtime or hardware equivalence
  • elimination of the existing compiler-warning backlog
  • fully hermetic future cold builds

The Debian base-image digest and Arm GNU archive are pinned. Debian packages installed through apt-get are not yet individually version-pinned or obtained from a dated repository snapshot.

The native and container builds are valid firmware builds but are not byte-identical. The container workflow is therefore documented as the canonical reproducible-build path.

Repository hygiene

Generated build outputs and raw compiler/Docker logs are not introduced by this PR.

Raw validation logs remain local because they contain host-specific diagnostic paths. The committed evidence file contains only sanitized identities, hashes, sizes, and validation outcomes.

Record the validated native macOS GCC 14.2 build baseline.

Add sanitized findings, evidence, and disclosure documentation.

Ignore the visible local review-private workspace.
@Zartharas
Zartharas marked this pull request as ready for review August 5, 2026 01:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant