From d636a3fb6f0e0ef913442ac06d1bc3391f102baa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hans-J=C3=BCrgen=20Sch=C3=B6nig?= Date: Thu, 16 Jul 2026 17:28:06 +0200 Subject: [PATCH] docs: eliminate false-capability claims + release 1.0.12 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up audit for the "documents a capability that doesn't work" class (prompted by the managed-DBaaS claims). Beyond the DBaaS fixes already on main, corrected: - internal/audit/transparency.go: the TransparencyLog comment claimed a rekor.Log implementation ships; only self-hosted StorageBackedLog exists — external Rekor is post-v1.0 roadmap. Reworded to "planned". - docs/compliance/pci-dss.md: the QSA evidence-bundle runbook told auditors to verify an image-level SLSA attestation that isn't produced (image unpublished; image SLSA is roadmap). Added the caveat + a working blob/tarball slsa-verifier alternative. - docs/reference/build-flavours.md: dropped the "official pg-hardstorage-fips distribution artifact ... out of the box" framing (no such artifact ships) → build-from-source + planned note. - SPEC.md: Scoop and -fips/-pg-ext container image variants were listed as shipped; marked planned/gated. Audit confirmed the managed-DBaaS class is fully eliminated (every RDS/Aurora/Cloud SQL/Azure/Neon/Supabase mention is now a negation; self-hosted/self-managed remains the only supported target). Release prep: CHANGELOG 1.0.12 and doc version examples bumped. --- CHANGELOG.md | 32 +++++++++++++++++++ SPEC.md | 6 ++-- docs/compliance/pci-dss.md | 15 ++++++++- docs/compliance/slsa-l3-provenance.md | 6 ++-- docs/reference/build-flavours.md | 13 ++++---- .../reference/runbooks/control-plane-setup.md | 2 +- docs/tutorials/getting-started.md | 8 ++--- internal/audit/transparency.go | 9 ++++-- 8 files changed, 70 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 66f5334..f3718e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,38 @@ keeps reading that version for at least 24 months after a successor lands. ## [Unreleased] +## [1.0.12] — 2026-07-16 + +### Docs: remove false-capability claims (managed DBaaS + unshipped features) + +An audit for the "documents a capability that doesn't actually work" +class of bug, prompted by finding that several places claimed support +for fully-managed DBaaS. + +- **Managed DBaaS**: the LLM-embedded README, SPEC, and the Kubernetes + sidecar chart (Chart.yaml + README) stated or implied pg_hardstorage + works against Amazon RDS/Aurora, GCP Cloud SQL, Azure Database, and + similar — while the rest of the docs correctly explain it cannot: + managed services do not expose `BASE_BACKUP` / physical replication + to customers. All corrected to the accurate "self-managed PostgreSQL + only" framing. The replication-protocol data plane removes the + *host-access* barrier — not the `BASE_BACKUP` barrier. +- **Rekor**: a `TransparencyLog` code comment claimed a `rekor.Log` + implementation ships; only the self-hosted `StorageBackedLog` exists. + External Rekor is post-v1.0 roadmap (now stated as such). +- **PCI-DSS evidence bundle**: the QSA runbook instructed verifying an + image-level SLSA attestation that isn't produced (container image + unpublished; image SLSA is roadmap). Added the caveat and a working + blob/tarball `slsa-verifier` alternative. +- **FIPS artifact**: build-flavours described an "official + pg-hardstorage-fips distribution artifact… out of the box"; no such + artifact ships (it's roadmap). Reworded to build-from-source + a + planned-artifact note. +- **SPEC packaging**: Scoop and the `-fips`/`-pg-ext` container image + variants were listed as shipped; marked planned/gated. + +No behaviour change. + ## [1.0.11] — 2026-07-16 Twelve operator-inconvenience fixes found by exercising the CLI surface, diff --git a/SPEC.md b/SPEC.md index f0400fe..776af27 100644 --- a/SPEC.md +++ b/SPEC.md @@ -94,7 +94,7 @@ PG 15+. WAL transport prefers the **PostgreSQL replication protocol over a datab Same binary, same UX, same config file from a 10 GB single-host PG to a 100+ TB Patroni cluster on Kubernetes. Big-database features (parallel chunk pipeline, snapshot base backups, multiple WAL streams from replicas) are *automatic upgrades* the system picks based on database size and topology — the operator does not have to opt into them manually. 5. **WAL via the replication protocol, not URLs.** - Default WAL transport is `START_REPLICATION` over libpq. It works on managed PostgreSQL where you can't install an archive library. It survives network blips because of the persistent slot. The C archive-library extension is an *optional* secondary path for environments where pulling can't keep up. + Default WAL transport is `START_REPLICATION` over libpq. It works against any self-managed PostgreSQL that exposes physical replication — including locked-down hosts where you can't (or won't) install an archive library, since it needs no OS access. (Fully-managed DBaaS like RDS still withhold physical replication from customers, so they remain unsupported — the libpq transport removes the host-access barrier, not the `BASE_BACKUP`/replication barrier.) It survives network blips because of the persistent slot. The C archive-library extension is an *optional* secondary path for environments where pulling can't keep up. 6. **No magic strings, no jargon.** We say *deployment* and *backup* and *restore*. Not "stanza", not "repo node", not "diff backup". The command tree reads like English. @@ -1302,8 +1302,8 @@ pg_hardstorage/ - Static `pg_hardstorage` for `linux/{amd64,arm64}`, `darwin/arm64`, `windows/amd64` (CLI-only on Windows). - Default `CGO_ENABLED=0`. FIPS variant `pg-hardstorage-fips` (`GOEXPERIMENT=boringcrypto CGO_ENABLED=1`). - Reproducible builds (`-trimpath -buildvcs=false`, pinned toolchain). -- goreleaser: tarballs + `.deb` + `.rpm` + Homebrew tap + Scoop. -- Container images (distroless): `ghcr.io/cybertec-postgresql/pg_hardstorage:`, `-fips:`, `-pg-ext:-`. +- goreleaser: tarballs + `.deb` + `.rpm` + Homebrew tap (Scoop: planned). +- Container images (distroless): `ghcr.io/cybertec-postgresql/pg_hardstorage:` (publishing gated on GHCR enablement); `-fips:` and `-pg-ext:-` variants: planned. - All artifacts cosign-signed; SBOM via syft; attestations via `cosign attest`. - Apache 2.0; CLA via DCO sign-off; public plugin registry post-v1.0. diff --git a/docs/compliance/pci-dss.md b/docs/compliance/pci-dss.md index cf01128..fbf17a7 100644 --- a/docs/compliance/pci-dss.md +++ b/docs/compliance/pci-dss.md @@ -143,7 +143,7 @@ audit period plus the cosign signatures on the running binary: ```sh -VERSION=1.0.11 # the release / image tag you're attesting +VERSION=1.0.12 # the release / image tag you're attesting # 1. Audit chain bundle pg_hardstorage audit export-bundle \ @@ -161,6 +161,19 @@ pg_hardstorage compliance report \ > ./qsa-q1-2026-controls.md # 3. Build provenance attestation +# +# NOTE: image-level SLSA provenance attestation is roadmap and gated on +# GHCR container publishing being enabled (the container image is not +# published by default). Only blob/tarball SLSA provenance ships today — +# for a QSA evidence bundle, verify the RELEASE TARBALL instead: +# +# slsa-verifier verify-artifact \ +# pg_hardstorage_${VERSION}_linux_amd64.tar.gz \ +# --provenance-path multiple.intoto.jsonl \ +# --source-uri github.com/cybertec-postgresql/pg_hardstorage +# +# The image-based command below applies ONLY once container images and +# their SLSA attestations are published (see slsa-l3-provenance.md): cosign verify-attestation \ --type slsaprovenance \ "ghcr.io/cybertec-postgresql/pg_hardstorage:v${VERSION}" \ diff --git a/docs/compliance/slsa-l3-provenance.md b/docs/compliance/slsa-l3-provenance.md index 283c3c2..a10fd04 100644 --- a/docs/compliance/slsa-l3-provenance.md +++ b/docs/compliance/slsa-l3-provenance.md @@ -74,7 +74,7 @@ Verify a downloaded artifact against its provenance with the `slsa-verifier`: ```sh -VERSION=1.0.11 # the release you're verifying +VERSION=1.0.12 # the release you're verifying slsa-verifier verify-artifact \ --provenance-path pg_hardstorage.intoto.jsonl \ --source-uri github.com/cybertec-postgresql/pg_hardstorage \ @@ -109,7 +109,7 @@ When images ship, they are intended to carry a cosign signature plus an image-level SLSA provenance attestation: ```sh -VERSION=1.0.11 # the image tag you're verifying +VERSION=1.0.12 # the image tag you're verifying # Verify the image signature cosign verify "ghcr.io/cybertec-postgresql/pg_hardstorage:v${VERSION}" \ @@ -139,7 +139,7 @@ JSON format, generated by `syft` (configured via the and attached to the GitHub Release: ```sh -VERSION=1.0.11 # the release you're inspecting +VERSION=1.0.12 # the release you're inspecting # The SBOM is a plain file on the Release; inspect it directly jq -r '.packages[].name' \ "pg_hardstorage_${VERSION}_linux_amd64.tar.gz.spdx.sbom.json" diff --git a/docs/reference/build-flavours.md b/docs/reference/build-flavours.md index dfddbcf..f68d5d0 100644 --- a/docs/reference/build-flavours.md +++ b/docs/reference/build-flavours.md @@ -87,11 +87,12 @@ The `fips` build tag flips the constant in the audit log stamps every backup taken by this binary with `fips: true` for compliance auditors. -The official `pg-hardstorage-fips` distribution artifact -also bakes in `-tags pkcs11` so HSM-backed envelopes — -the canonical FIPS posture — are available out of the -box. Operators rolling their own FIPS build add the tag -explicitly: `go build -tags 'fips pkcs11' …`. +There is no official `pg-hardstorage-fips` distribution +artifact today — the FIPS `.deb`/`.rpm` (which will bake in +`-tags pkcs11` so HSM-backed envelopes, the canonical FIPS +posture, work out of the box) is roadmap; see the FIPS +variant how-to. Until it ships, build FIPS yourself and add +the tag explicitly: `go build -tags 'fips pkcs11' …`. --- @@ -154,7 +155,7 @@ default file; operators vendor it into their fork once. ``` default → no FIPS, no HSM, Docker sandbox fips → FIPS, no HSM, Docker sandbox (linux/amd64) -fips+pkcs11→ FIPS, HSM, Docker sandbox (linux/amd64; the official FIPS artifact) +fips+pkcs11→ FIPS, HSM, Docker sandbox (linux/amd64; the planned official FIPS artifact) firecracker→ no FIPS, no HSM, microVM sandbox (linux + KVM) ``` diff --git a/docs/reference/runbooks/control-plane-setup.md b/docs/reference/runbooks/control-plane-setup.md index d484e55..dadedd2 100644 --- a/docs/reference/runbooks/control-plane-setup.md +++ b/docs/reference/runbooks/control-plane-setup.md @@ -249,7 +249,7 @@ curl --cacert /etc/pg_hardstorage/server/cert.pem \ # { # "id": "db1.example.com", # "host": "db1.example.com", -# "version": "v1.0.11", +# "version": "v1.0.12", # "deployments": ["db1", "db2"], # "registered_at": "...", # "last_heartbeat": "..." diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index 08ace95..1af5cef 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -35,7 +35,7 @@ tarballs (Windows is CLI-only). Grab the matching one from verify the cosign signature, and drop the binary on your `$PATH`: ```sh -VERSION=1.0.11 # latest release: https://github.com/cybertec-postgresql/pg_hardstorage/releases/latest +VERSION=1.0.12 # latest release: https://github.com/cybertec-postgresql/pg_hardstorage/releases/latest curl -LO "https://github.com/cybertec-postgresql/pg_hardstorage/releases/download/v${VERSION}/pg_hardstorage_${VERSION}_linux_amd64.tar.gz" tar xzf "pg_hardstorage_${VERSION}_linux_amd64.tar.gz" sudo install -m 0755 pg_hardstorage /usr/local/bin/ @@ -45,7 +45,7 @@ pg_hardstorage version ### `.deb` (Debian / Ubuntu) ```sh -VERSION=1.0.11 # the release you downloaded +VERSION=1.0.12 # the release you downloaded sudo dpkg -i "pg-hardstorage_${VERSION}_amd64.deb" ``` @@ -57,7 +57,7 @@ creates `/etc/pg_hardstorage/`, `/var/lib/pg_hardstorage/`, ### `.rpm` (Fedora / RHEL / Rocky / Alma) ```sh -VERSION=1.0.11 # the release you downloaded +VERSION=1.0.12 # the release you downloaded sudo rpm -i "pg-hardstorage-${VERSION}-1.x86_64.rpm" ``` @@ -259,7 +259,7 @@ you are doing — exit 9 means the verifier said no. ```sh $ pg_hardstorage version -pg_hardstorage v1.0.11 (abc1234, built 2026-04-29T12:00:00Z) +pg_hardstorage v1.0.12 (abc1234, built 2026-04-29T12:00:00Z) ``` `doctor` is the single-command "is anything wrong" check. It prints a diff --git a/internal/audit/transparency.go b/internal/audit/transparency.go index f1c6b04..08f59a2 100644 --- a/internal/audit/transparency.go +++ b/internal/audit/transparency.go @@ -30,9 +30,12 @@ import ( // who can't reach a public log a tamper-evident-but-self-hosted // trust story. // -// - rekor.Log: real Rekor + cosign attestation, behind the -// same interface so the chain anchor flow doesn't change shape -// as the trust model grows. +// - A future rekor.Log (real Rekor + cosign attestation) is the +// PLANNED second implementation behind the same interface, so the +// chain-anchor flow won't change shape as the trust model grows. +// It does not exist yet — external Rekor anchoring is post-v1.0 +// roadmap (see docs/explanation/audit-chain.md); only the +// self-hosted StorageBackedLog ships today. // // This is deliberately a small interface — Put / Get / Latest. The // Sigstore-Rekor public API is much larger; we cover only what the