Skip to content

Release Verification Guide

You have a SolidSyslog release on disk and want to convince yourself, or an auditor, that it was produced by the repo it claims to come from. This guide walks through the verification a careful integrator would run, in the order they'd naturally run it.

Prerequisites:

  • cosign v3 or later on your $PATH. The signatures are produced by cosign v3, which writes the current Sigstore bundle format; v2 cannot read it and fails with bundle does not contain cert for verification, which reads as a broken signature rather than a version mismatch.
  • cyclonedx-cli v0.30.0 or later (optional, only needed to re-validate the SBOM).
  • A git checkout of the repo at the release's tag (optional, only needed to reproduce the source hash yourself).

All four Release assets should be present:

sbom.cdx.json
sbom.cdx.json.sigstore
source-tree-sha256.txt
source-tree-sha256.txt.sigstore

1. Verify the source is what we claim

source-tree-sha256.txt records the content-tree SHA-256 of the product at the release commit. The product scope is Core/ + Platform/ plus the root-level CMakeLists.txt, CMakePresets.json, LICENSE.md, and LICENSES/. The hash is deterministic across git versions, archive formats, locales, and tooling; it depends only on the bytes of each tracked file and the sorted list of paths.

Reproduce with git (authoritative)

git clone --depth 1 --branch v<version> https://github.com/cososo-ltd/solid-syslog.git
cd solid-syslog
git ls-tree -r --name-only HEAD -- \
    Core/ Platform/ CMakeLists.txt CMakePresets.json LICENSE.md LICENSES/ \
  | LC_ALL=C sort \
  | while IFS= read -r path; do
      printf "%s  %s\n" "$(git show "HEAD:$path" | sha256sum | cut -d' ' -f1)" "$path"
    done \
  | sha256sum | cut -d' ' -f1

Compare the output to the hash in source-tree-sha256.txt. The file has a few #-prefixed header lines (scope / commit / algorithm / pointer) and one blank line before the hash, so extract the value with:

grep -v '^#' source-tree-sha256.txt | grep -v '^$' | head -n 1

If that matches your computed hash, your source tree is byte-identical to the tree the SBOM describes.

Reproduce without git (fallback, working tree only)

If you don't have a git clone (e.g. you received a source archive instead) but you do have an extracted working tree with the product files present:

find Core Platform CMakeLists.txt CMakePresets.json LICENSE.md LICENSES -type f \
  | LC_ALL=C sort \
  | while IFS= read -r path; do
      printf "%s  %s\n" "$(sha256sum "$path" | cut -d' ' -f1)" "$path"
    done \
  | sha256sum | cut -d' ' -f1

Same hash expected, same comparison. Caveats:

  • Assumes the working tree is clean: any untracked or locally-modified file under the in-scope paths will change the hash.
  • Assumes line endings are LF on disk (git's .gitattributes enforces this at checkout; some extraction tools may convert on platforms that default to CRLF).

The git form is stricter because it always reads from the committed tree.

If the hashes don't match

The SBOM's metadata.properties[solidsyslog:commit-sha] property names the exact commit the hash was computed at. Verify you're on that commit:

git rev-parse HEAD

If the commit matches and the hash still doesn't, something on your side has modified a file; git status --short and git diff will show what.

2. Verify the SBOM signature

The signature commits to the GitHub Actions workflow that produced it. A valid signature proves three things:

  1. This exact SBOM came from the SolidSyslog repo's sbom.yml workflow.
  2. The workflow ran at the release tag you think it did (not on a random branch, not on a fork).
  3. The signing event was logged to the Sigstore transparency log at the time claimed.

Verification:

cosign verify-blob \
  --bundle sbom.cdx.json.sigstore \
  --certificate-identity "https://github.com/cososo-ltd/solid-syslog/.github/workflows/sbom.yml@refs/tags/v<version>" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  sbom.cdx.json

cosign outputs Verified OK and exits 0 on success. Any of these conditions fail the verification loudly:

  • The SBOM has been modified after signing.
  • The signature was produced by a different workflow file.
  • The signature was produced on a different repo (e.g. a fork).
  • The signature was produced against a different tag.
  • The Sigstore transparency log entry is missing or doesn't match.

3. Verify the source-tree-hash signature

cosign verify-blob \
  --bundle source-tree-sha256.txt.sigstore \
  --certificate-identity "https://github.com/cososo-ltd/solid-syslog/.github/workflows/sbom.yml@refs/tags/v<version>" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  source-tree-sha256.txt

Same guarantees as step 2, but for the content-tree-hash file. Combined with the hash match from step 1, you now know the source you have is the source the SBOM describes, and the SBOM is the one the workflow produced.

4. (Optional) Re-validate the SBOM against CycloneDX

cyclonedx validate \
  --input-file sbom.cdx.json \
  --input-format json \
  --input-version v1_5 \
  --fail-on-errors

This isn't strictly a provenance check (the CI already ran it), but it confirms the document on your disk is structurally and semantically a valid CycloneDX 1.5 SBOM. Useful if you're plugging it into an SBOM-consuming tool and want to rule out corruption-in-transit.

What verification does not tell you

  • It doesn't tell you whether the code behind the SBOM is bug-free, secure, or fit for purpose. The SBOM is provenance evidence, not a quality claim.
  • It doesn't tell you anything about the platform adapters you link beside the library. The SBOM's components[] is empty because SolidSyslog vendors nothing and depends on nothing; picking, versioning and verifying whatever fills the network, TLS, filesystem and OS-primitive roles is your job, and those belong in your product SBOM rather than this one.
  • It doesn't tell you whether the SolidSyslog licence is compatible with your intended use. That's a licence review, not a signature check — start from the licence.

See the threat model for the security posture, and the SBOM for a walk-through of what it actually says.