robintra/perf-sentinel v0.7.0

on GitHub

What's new in v0.7.0

v0.7.0 introduces the public periodic disclosure pipeline. A new perf-sentinel disclose subcommand aggregates an archived NDJSON window stream into a single period-level JSON report with deterministic content hashing and an in-toto v1 attestation sidecar. A new perf-sentinel verify-hash subcommand chains content hash recompute, Sigstore signature verification and SLSA L2 binary provenance check in one third-party-runnable command. Carbon accounting moves from aggregate to per-service attribution when runtime calibration is available, and an official disclosure requires 75% per-service coverage to be accepted.

Public periodic disclosure

• perf-sentinel disclose subcommand aggregates an NDJSON stream of per-window reports into one period-level public document. The stream is produced by the daemon's new [daemon.archive] writer (size-rotated, count-pruned). Two granularity levels via --confidentiality: internal (G1, full per-pattern detail per service) or public (G2, anti-pattern counts only). --strict-attribution refuses windows with non-attributed spans, useful when asserting that 100% of measured operations were correctly attributed.
• In-toto v1 attestation sidecar via --emit-attestation, complete statement (_type, predicateType, subject, predicate) ready to sign with cosign sign-blob --bundle bundle.sig --new-bundle-format. The predicate carries pattern counts for audit visibility.
• integrity.content_hash is deterministic and invariant under post-disclose signature insertion. The hasher blanks integrity.content_hash, integrity.signature, integrity.binary_attestation and report_metadata.integrity_level before computing, so an operator can patch the signature locators into report.json without breaking the hash.
• integrity.core_patterns_required and core_patterns_hash declare which canonical anti-pattern set produced the report. verify-hash cross-checks the hash against the local binary's canonical set, catching a substitution attempt where a hostile report claims patterns the running binary cannot detect.

verify-hash subcommand and exit codes

• perf-sentinel verify-hash chains three checks: deterministic content hash recompute (pure Rust, always run), Sigstore signature verification via cosign verify-blob --new-bundle-format, and SLSA L2 binary provenance summary with a slsa-verifier command pointing at the binary in integrity.binary_verification_url.
• Five distinct exit codes: 0 TRUSTED, 1 UNTRUSTED (hash mismatch, signature invalid, identity mismatch), 2 PARTIAL (cosign or slsa-verifier absent, sidecars missing), 3 INPUT_ERROR, 4 NETWORK_ERROR. A scripted verify-hash && deploy gate still blocks on non-zero, but a wrapper distinguishing 2 vs 1 can tell tooling absence from a tamper attempt.
• Remote mode with --url <report.json> fetches the report, attestation.intoto.jsonl and bundle.sig from the same URL prefix, allowing a third-party auditor to verify a publicly-hosted disclosure without cloning the producer's infrastructure.

Breaking change: identity binding required

verify-hash now refuses to invoke cosign without operator-supplied identity flags. Three modes:

• --expected-identity <ID> --expected-issuer <URL>: cosign verifies the bundle was issued by exactly this OIDC identity. Safe default for a third-party audit.
• --no-identity-check: cryptographic integrity only, explicitly logged as PARTIAL. Reserved for internal self-check before publication.
• Neither flag passed: Status::Fail on the signature slot.

Passing the report-supplied signer_identity and signer_issuer to cosign as constraints was autosigning. Any GitHub or Google account holder could forge a bundle and have verify-hash return TRUSTED. The new contract forces the consumer to declare the expected signer.

Sigstore signature, SLSA L2 binary provenance

• In-toto v1 statement signed with cosign sign-blob instead of attest-blob, which would wrap the statement in a second statement and create a permanent malformed entry in the Rekor public log. The migration covers both signing and verifying paths. Requires cosign 2.4+ in the signing pipeline.
• Configurable Rekor URL via [reporting.sigstore] rekor_url, defaults to the public Rekor.
• SLSA L2 binary provenance for every release binary via slsa-framework/slsa-github-generator. The release publishes multiple.intoto.jsonl alongside the platform binaries and Docker image, with subject hashes gated on the build step succeeding.

Per-service carbon attribution

GreenSummary now carries energy and carbon at per-service granularity when the scoring pipeline observed runtime calibration:

• per_service.{energy_kwh, carbon_kg, energy_source_model, measured_ratio} fields populated by the scoring stage when a window's per-endpoint energy attribution is present.
• calibration_inputs.energy_source_models lists the distinct energy models observed in the period, surfaced in disclosures so an auditor sees which scope (measured, proxy_io, ...) the totals lean on.
• runtime_windows_count and fallback_windows_count in the aggregate distinguish per-service-attributed windows from those that fell back to the I/O proxy.
• period_coverage field exposes the runtime-calibration coverage ratio as a first-class metric in the disclosure.

75% runtime coverage gate

An intent = "official" disclosure requires that runtime_windows_count / (runtime_windows_count + fallback_windows_count) >= 0.75. Below 75%, the I/O proxy dominates the totals and per-service attribution loses meaningful coverage. The gate is enforced at disclose --intent official time and at daemon startup when [reporting] intent = "official" is configured.

Helm chart

charts/perf-sentinel 0.2.34 to 0.2.35, appVersion 0.6.2 to 0.7.0. The artifacthub.io/changes annotation surfaces the disclosure pipeline and the autosigning fix on Artifact Hub.

Documentation

• docs/REPORTING.md and docs/FR/REPORTING-FR.md document the disclosure pipeline end-to-end: --period-type, glob --input behavior, G1 vs G2 granularity, the integrity.signature schema with per-field provenance, an interim jq helper to patch locator fields between sign and publish, the URL convention for --url sidecars, identity verification modes, and build provenance for local builds.
• docs/SCHEMA.md plus docs/schemas/perf-sentinel-report-v1.json publish the formal JSON schema for the disclosure document. The example reports in docs/schemas/examples/ track the v0.7.0 baseline.
• docs/design/08-PERIODIC-DISCLOSURE.md, 09-CARBON-ATTRIBUTION.md, 10-SIGSTORE-ATTESTATION.md record the methodology and the constraints that shaped the implementation.

Internal quality

• cognitive_complexity clippy gate enforced workspace-wide at threshold 60, with a pre-commit hook running clippy on staged Rust files.
• process_window, validate_methodology and score_green refactored into per-axis helpers, all below the new threshold.
• Daemon advisory warnings for [reporting] disclose_output_path (reserved for 0.8.0) emit exactly once at startup, including when the daemon CLI overrides the listen address.

Full Changelog: v0.6.2...v0.7.0