From 410a21742ffeb92b17531787dc6869433fcb7cbf Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Fri, 6 Feb 2026 16:01:18 -0500 Subject: [PATCH 1/6] Python hash integrity info Signed-off-by: s-stumbo --- .../chainguard/libraries/python/overview.md | 42 ++++++++++++++++--- 1 file changed, 37 insertions(+), 5 deletions(-) diff --git a/content/chainguard/libraries/python/overview.md b/content/chainguard/libraries/python/overview.md index 47b8c68dba..e4c7008b7c 100644 --- a/content/chainguard/libraries/python/overview.md +++ b/content/chainguard/libraries/python/overview.md @@ -314,6 +314,30 @@ curl -L --user "$CHAINGUARD_PYTHON_IDENTITY_ID:$CHAINGUARD_PYTHON_TOKEN" \ The option `-L` is required to follow redirects for the actual file locations. +## Hash verification when migrating to Chainguard Libraries + +Because Chainguard rebuilds from source, there are some circumstances where you +can expect different checksums for the same package version when migrating from +upstream PyPI to Chainguard Libraries: + +- Tools such as `pip` enforce hashes when using `--require-hashes` or when hashes are pinned in requirements.txt files +- Tools such as `Poetry` and `uv` generate lock files that include SHA-256 hashes and will fail if checksums don't match +- Systems such as JFrog Artifactory or Nexus may have cached upstream PyPI wheels and continue serving them until caches are cleared + +### Resolving checksum mismatches + +>Note: Before regenerating lock files, ensure your tool is configured to use Chainguard as the package index by following the [global configuration](chainguard/libraries/python/global-configuration/) or [direct access](/chainguard/libraries/python/build-configuration/#direct-access) documentation. + +To resolve hash mismatches, re-resolve your dependencies against Chainguard Libraries: + +- For `--require-hashes`: install from Chainguard indexes then regenerate the requirements file with new hashes so they match Chainguard wheels. +- For `uv`, Poetry, or other tools that generate lockfiles: Point them at Chainguard indexes then regenerate the lockfile so stored hashes correspond to Chainguard artifacts. +- For repository managers: You may also need to clear cached PyPI artifacts to ensure future installs pull Chainguard's versions. + +>**Note:** While hash mismatches from are expected for some tooling and +configurations, you can verify the authenticity and provenance of Chainguard +packages using SBOM and SLSA attestation files as described in the next section. + ## SBOM and attestation files Chainguard Libraries for Python include files that contain software bill of @@ -321,20 +345,24 @@ material (SBOM) information. Additional files attest details about build infrastructure with the [Supply-chain Levels for Software Artifacts (SLSA)](https://slsa.dev/) provenance information. +### Embedded SBOM + The related files for Chainguard Libraries for Python are located within the Python wheel file for each package following the [PEP 770 Improving measurability of Python packages with Software Bill-of-Materials specification](https://peps.python.org/pep-0770/) for software composition analytis (SCA) using the SPDX format. -Specifically a wheel file contains two directories, the main code directory that -uses the name of the library only, and the version-specific distribution info -directory `.dist.info`. For example, the wheel archive for Flask version 2.0.0 +A wheel file contains two directories: +- The main code directory that uses the name of the library only, and +- The version-specific distribution info directory `.dist.info`. + +For example, the wheel archive for Flask version 2.0.0 includes a directory `flask-2.0.0.dist.info`. You can also find this directory in the `site-packages` directory of a Python project using a virtual environment. -Find the SBOM information in the file `sboms/sbom.spdx.json`. Any package from -Chainguard includes the reference to Chainguard in the creators section: +The SBOM information is in the file `*.dist-info/sboms/sbom.spdx.json`. Any package from +Chainguard includes a reference to Chainguard in the `creators` section: ```json { @@ -355,6 +383,8 @@ Chainguard includes the reference to Chainguard in the creators section: } ``` +### SLSA provenance + SLSA provenance is available from the Chainguard Python index following the [PEP 740 – Index support for digital attestations specification](https://peps.python.org/pep-0740/) within the integrity context @@ -392,6 +422,8 @@ Packages from Chainguard are identified by the `publisher`:`environment` set as } ``` +### Sigstore bundle + A [Sigstore bundle file](https://docs.sigstore.dev/about/bundle/) is available as `bundle.json` from the integrity context at `https://libraries.cgr.dev/python/integrity/PACKAGE/VERSION/FILE/bundle.json` From 978e5fa0a763c5c4e95f38668585e91ac44a4d18 Mon Sep 17 00:00:00 2001 From: s-stumbo <100295939+s-stumbo@users.noreply.github.com> Date: Tue, 24 Feb 2026 09:33:13 -0500 Subject: [PATCH 2/6] Update content/chainguard/libraries/python/overview.md Co-authored-by: angela-zhang <30538317+angela-zhang@users.noreply.github.com> Signed-off-by: s-stumbo <100295939+s-stumbo@users.noreply.github.com> --- content/chainguard/libraries/python/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/chainguard/libraries/python/overview.md b/content/chainguard/libraries/python/overview.md index e4c7008b7c..4401fc71db 100644 --- a/content/chainguard/libraries/python/overview.md +++ b/content/chainguard/libraries/python/overview.md @@ -330,7 +330,7 @@ upstream PyPI to Chainguard Libraries: To resolve hash mismatches, re-resolve your dependencies against Chainguard Libraries: -- For `--require-hashes`: install from Chainguard indexes then regenerate the requirements file with new hashes so they match Chainguard wheels. +- For `--require-hashes`: install from Chainguard indexes, and then regenerate the requirements file with new hashes so they match Chainguard wheels. - For `uv`, Poetry, or other tools that generate lockfiles: Point them at Chainguard indexes then regenerate the lockfile so stored hashes correspond to Chainguard artifacts. - For repository managers: You may also need to clear cached PyPI artifacts to ensure future installs pull Chainguard's versions. From 0625375948cf5f0b0d9da61a94f704b41ccb83df Mon Sep 17 00:00:00 2001 From: s-stumbo <100295939+s-stumbo@users.noreply.github.com> Date: Tue, 24 Feb 2026 09:33:31 -0500 Subject: [PATCH 3/6] Update content/chainguard/libraries/python/overview.md Co-authored-by: angela-zhang <30538317+angela-zhang@users.noreply.github.com> Signed-off-by: s-stumbo <100295939+s-stumbo@users.noreply.github.com> --- content/chainguard/libraries/python/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/chainguard/libraries/python/overview.md b/content/chainguard/libraries/python/overview.md index 4401fc71db..40ca6c2dd0 100644 --- a/content/chainguard/libraries/python/overview.md +++ b/content/chainguard/libraries/python/overview.md @@ -331,7 +331,7 @@ upstream PyPI to Chainguard Libraries: To resolve hash mismatches, re-resolve your dependencies against Chainguard Libraries: - For `--require-hashes`: install from Chainguard indexes, and then regenerate the requirements file with new hashes so they match Chainguard wheels. -- For `uv`, Poetry, or other tools that generate lockfiles: Point them at Chainguard indexes then regenerate the lockfile so stored hashes correspond to Chainguard artifacts. +- For `uv`, Poetry, or other tools that generate lockfiles: Point them at Chainguard indexes, and then regenerate the lockfile so stored hashes correspond to Chainguard artifacts. - For repository managers: You may also need to clear cached PyPI artifacts to ensure future installs pull Chainguard's versions. >**Note:** While hash mismatches from are expected for some tooling and From bdd954cedf58991b2ff427a7ebc2a8a0eddaa476 Mon Sep 17 00:00:00 2001 From: s-stumbo <100295939+s-stumbo@users.noreply.github.com> Date: Tue, 24 Feb 2026 09:33:46 -0500 Subject: [PATCH 4/6] Update content/chainguard/libraries/python/overview.md Co-authored-by: angela-zhang <30538317+angela-zhang@users.noreply.github.com> Signed-off-by: s-stumbo <100295939+s-stumbo@users.noreply.github.com> --- content/chainguard/libraries/python/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/chainguard/libraries/python/overview.md b/content/chainguard/libraries/python/overview.md index 40ca6c2dd0..992fba7d96 100644 --- a/content/chainguard/libraries/python/overview.md +++ b/content/chainguard/libraries/python/overview.md @@ -345,7 +345,7 @@ material (SBOM) information. Additional files attest details about build infrastructure with the [Supply-chain Levels for Software Artifacts (SLSA)](https://slsa.dev/) provenance information. -### Embedded SBOM +### Embedded SBOMs The related files for Chainguard Libraries for Python are located within the Python wheel file for each package following the [PEP 770 Improving From 9d93f4cf7aebcf741eed15ff26433e8de1dce90e Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Tue, 24 Feb 2026 10:01:37 -0500 Subject: [PATCH 5/6] updates Signed-off-by: s-stumbo --- content/chainguard/libraries/python/overview.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/chainguard/libraries/python/overview.md b/content/chainguard/libraries/python/overview.md index 992fba7d96..3dcbd19e04 100644 --- a/content/chainguard/libraries/python/overview.md +++ b/content/chainguard/libraries/python/overview.md @@ -424,7 +424,10 @@ Packages from Chainguard are identified by the `publisher`:`environment` set as ### Sigstore bundle +A Sigstore bundle is a self‑contained JSON file that packages everything needed to verify a signed artifact. It contains cryptographic signatures for both the SBOM and SLSA provenance files, allowing you to verify the authenticity and integrity of the supply chain metadata provided by Chainguard. + A [Sigstore bundle file](https://docs.sigstore.dev/about/bundle/) is available as `bundle.json` from the integrity context at `https://libraries.cgr.dev/python/integrity/PACKAGE/VERSION/FILE/bundle.json` specifically for each package, version, and file. + From 3122248211838b78ce981014905909c91291c397 Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Tue, 24 Feb 2026 12:21:43 -0500 Subject: [PATCH 6/6] updates Signed-off-by: s-stumbo --- content/chainguard/libraries/python/overview.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/chainguard/libraries/python/overview.md b/content/chainguard/libraries/python/overview.md index 3dcbd19e04..4d715ffc72 100644 --- a/content/chainguard/libraries/python/overview.md +++ b/content/chainguard/libraries/python/overview.md @@ -424,7 +424,8 @@ Packages from Chainguard are identified by the `publisher`:`environment` set as ### Sigstore bundle -A Sigstore bundle is a self‑contained JSON file that packages everything needed to verify a signed artifact. It contains cryptographic signatures for both the SBOM and SLSA provenance files, allowing you to verify the authenticity and integrity of the supply chain metadata provided by Chainguard. +A Sigstore bundle is a self‑contained JSON file that packages everything needed +to verify the authenticity and integrity of a signed artifact. A [Sigstore bundle file](https://docs.sigstore.dev/about/bundle/) is available as `bundle.json` from the integrity context at