Skip to content

RELEASES.md

Latest commit

 

History

History
220 lines (152 loc) · 5.19 KB

RELEASES.md

File metadata and controls

220 lines (152 loc) · 5.19 KB

SecureFabric Release Process & Verification

This document describes the release process, artifact signing, and verification procedures for SecureFabric node binaries.

Release Artifacts

Each release includes:

  • Multi-arch binaries: Linux (amd64, arm64), macOS (amd64, arm64), Windows (amd64)
  • SHA256SUMS: Checksums for all artifacts
  • SHA256SUMS.sig: Cosign signature of checksums
  • SHA256SUMS.pem: Cosign certificate for verification
  • SBOM.json: Software Bill of Materials (SPDX format)

Automated Release Process

Releases are created automatically via GitHub Actions when a version tag is pushed:

git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

The release workflow:

  1. Builds multi-arch binaries using matrix strategy
  2. Generates SHA256 checksums for all artifacts
  3. Creates SBOM using Syft
  4. Signs checksums with Cosign (keyless signing via Sigstore)
  5. Publishes to GitHub Releases

Manual Release Process

For local builds and testing:

1. Build Release Binaries

# Build for current platform
./scripts/build-release.sh

# Clean build
./scripts/build-release.sh --clean

2. Sign Artifacts

# Sign with cosign (keyless)
./scripts/sign-release.sh cosign

# Sign with GPG
./scripts/sign-release.sh gpg

# Sign with both
./scripts/sign-release.sh both

3. Verify Signatures

./scripts/sign-release.sh verify

Verification for Users

Download Release

VERSION=v0.1.0
PLATFORM=linux-amd64

curl -LO "https://github.com/NodeCube/securefabric-core/releases/download/${VERSION}/securefabric-node-${PLATFORM}.tar.gz"
curl -LO "https://github.com/NodeCube/securefabric-core/releases/download/${VERSION}/SHA256SUMS"
curl -LO "https://github.com/NodeCube/securefabric-core/releases/download/${VERSION}/SHA256SUMS.sig"
curl -LO "https://github.com/NodeCube/securefabric-core/releases/download/${VERSION}/SHA256SUMS.pem"

Verify Checksum

# Verify the downloaded binary matches the checksum
sha256sum -c SHA256SUMS --ignore-missing

Expected output:

securefabric-node-linux-amd64.tar.gz: OK

Verify Signature (Cosign)

Install cosign: https://docs.sigstore.dev/cosign/installation

# Verify the checksums file was signed by our CI
cosign verify-blob \
  --certificate SHA256SUMS.pem \
  --signature SHA256SUMS.sig \
  --certificate-identity-regexp "https://github.com/NodeCube/securefabric-core/*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  SHA256SUMS

Expected output:

Verified OK

Extract and Run

# Extract
tar xzf securefabric-node-linux-amd64.tar.gz

# Verify it runs
./securefabric-node --version

Keyless Signing with Cosign

We use Sigstore's keyless signing:

  • No long-lived private keys - reduces key management burden
  • OIDC-based identity - GitHub Actions identity is verified
  • Transparency log - All signatures recorded in Rekor
  • Certificate pinning - Verify signatures came from our CI

How It Works

  1. GitHub Actions authenticates with Sigstore using OIDC token
  2. Sigstore issues short-lived certificate with GitHub identity
  3. Cosign signs artifacts and records in transparency log
  4. Users verify using the certificate and identity checks

SBOM (Software Bill of Materials)

Each release includes an SBOM in SPDX format:

# Download SBOM
curl -LO "https://github.com/NodeCube/securefabric-core/releases/download/${VERSION}/SBOM.json"

# View dependencies
jq '.packages[] | {name, version}' SBOM.json

The SBOM includes:

  • All Rust dependencies (direct and transitive)
  • Versions and license information
  • Vulnerability tracking metadata

Security

For security issues, please refer to SECURITY.md for responsible disclosure procedures.

Release Checklist (Maintainers)

Before creating a release:

  • All tests passing on main branch
  • CHANGELOG.md updated with release notes
  • Version bumped in Cargo.toml
  • Security audit completed (cargo audit)
  • Documentation updated
  • Review pending PRs

Create release:

# Create and push tag
git checkout main
git pull origin main
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

Post-release:

  • Verify CI completed successfully
  • Test download and verification
  • Announce release
  • Update documentation
  • Close milestone

Versioning

We follow Semantic Versioning:

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

Pre-release suffixes:

  • -alpha.N: Early testing
  • -beta.N: Feature complete, testing
  • -rc.N: Release candidate

Binary Distribution

Binaries are distributed through GitHub Releases. Always download from the official repository:

Never download binaries from unofficial sources.

Reproducible Builds (Future)

We plan to support reproducible builds:

  • Deterministic build environment
  • Fixed Rust toolchain version
  • Documented build process
  • Independent verification

Questions?

For questions about the release process, please open an issue on GitHub.