Skip to content

Security

This page covers how releases are signed and how downstream consumers verify them.

TL;DR — how do I trust this install?

The shortest path is to ask pip to verify the publisher's attestation for you:

pip install --verify-attestations intrinsic-green-learning   # pip ≥ 25.1

If you want belt-and-braces, two independent fallbacks are available: the GPG-signed SHA256SUMS on every GitHub release, and the GitHub build-provenance attestation in the GitHub attestation log. Recipes for both are in Verifying a release as a consumer below.

Supply-chain posture

Every release of this library ships with the following layers — each addresses a different attacker class, so they are intentionally redundant:

  1. OIDC Trusted Publishing to PyPI. No long-lived API token sits in the repo or in CI secrets; the GitHub Actions runner mints a short-lived OIDC token that PyPI validates against the project's Trusted Publisher configuration. Removes the "leaked PyPI token" attack surface.
  2. PEP 740 sigstore attestations. Automatically generated by pypa/gh-action-pypi-publish (default since v1.11); link the published wheel/sdist to the exact source commit and workflow run via the public Sigstore transparency log. This is what pip install --verify-attestations checks.
  3. GPG-signed SHA256SUMS. Every release asset list is signed with the Hother Bot's GPG key and uploaded as SHA256SUMS.asc alongside the wheel and sdist. Independent of PyPI — verifies even if you got the artifacts from somewhere other than pypi.org.
  4. GitHub build-provenance attestation. Emitted via gh attestation attest so the artifacts also appear in the GitHub attestation log. Lets you cross-check the PyPI claim against a second, GitHub-controlled source of truth.
  5. uv.lock audit. pip-audit runs on every PR and weekly via .github/workflows/security.yml and blocks merges on known CVEs in any transitive dependency.
  6. Workflow audit. zizmor runs on every PR, uploads SARIF to GitHub Code Scanning, and surfaces unpinned actions, excessive permissions, and credential-leak patterns before they can ship.

Verifying a release as a consumer

pip install --verify-attestations intrinsic-green-learning

Pip fetches the sigstore attestation from PyPI, verifies it against the public Sigstore transparency log, and refuses to install if verification fails. No additional tooling required.

Verify the GitHub attestation manually

# Download a wheel from a specific release
gh release download v1.2.3 --repo hotherio/intrinsic-green-learning --pattern "*.whl"

# Verify it was built from the expected source
gh attestation verify intrinsic_green_learning-1.2.3-py3-none-any.whl \
  --owner hotherio

Verify the GPG-signed checksums

# Import the Hother Bot's public key (one-time)
gpg --recv-keys <bot-key-id>

# Verify the checksum file's signature, then verify file hashes
gh release download v1.2.3 --repo hotherio/intrinsic-green-learning
gpg --verify SHA256SUMS.asc SHA256SUMS
sha256sum -c SHA256SUMS

Forgejo / self-hosted git forge

PyPI does not currently trust Forgejo OIDC tokens (immutable-ID claims are missing). If you mirror this repo to a Forgejo instance and run the release workflow there, the publish step will fall back to a PyPI API token (UV_PUBLISH_TOKEN secret). See FORGEJO.md for details.

Reporting a vulnerability

See SECURITY.md for the disclosure process.