Updating a dependency¶

The SBOM for CPython’s bundled dependencies is kept atMisc/sbom.spdx.json. When updating a dependency to a new versionyou’ll need to edit the version and other metadata about this dependency inthe SBOM.

The recommended workflow is:

1. Download the new dependency as an archive. Take note of the new version, downloadURL, and checksum of the downloaded archive.

2. Update the vendored code in the CPython source tree.

3. EditMisc/sbom.spdx.json to add the newversionInfo,downloadLocation,checksums, andexternalReferences for thecorrespondingpackage. For most of these updates all that’s needed is toupdate the embedded version within URLs and project identifiers.Don’t update any information infiles andrelationships as this willbe generated automatically by the SBOM tool.

4. Runmakeregen-sbom orpythonTools/build/generate_sbom.py.Ensure that this doesn’t fail with validation errors.

5. RungitdiffMisc/sbom.spdx.json and check the diff matches theexpected changes.

6. Commit the changes toMisc/sbom.spdx.json along with theupdate to the dependency code.

Adding a new dependency¶

When adding a dependency it’s important to have the following information:

• Name, version, and download URL of the project

• License of the project as anSPDX License Expression

• Software identifiers that match values in vulnerability databases(CPE andPackage URLsor “PURLs”)

• Paths to include and exclude in the CPython source tree corresponding to this dependency

After gathering this information:

1. Add the information into a new entry inpackages in the fileMisc/sbom.spdx.json. Don’t worry about formatting, the tool willauto-format your manually written JSON. The fields to fill out include:

   • name for the project name.

   • SPDXID which will be"SPDXRef-PACKAGE-{name}".

   • licenseConcluded for the SPDX license identifier of the project license.

   • versionInfo for the version of the project.

   • downloadLocation should be an HTTPS URL for the project download as an archive.

   • checksums[0].checksumValue and.algorithm will be the SHA-256checksum of the downloaded archive.

   • originator for the original author information, prefix with either anOrganization: orPerson: depending on the author/maintenance situation.

   • primaryPackagePurpose will likely be"SOURCE".

   • externalReferences is a list of one or more project identifiers,either CPE or Package URL. The value forreferenceLocator must includethe value inversionInfo to ensure the identifiercorresponds to the correct release of the software. You can read more aboutexternal references in theSPDX SBOM specification.

2. If a new license ID is to be used, add the license expression toALLOWED_LICENSE_EXPRESSIONS in theTools/build/generate_sbom.py.

3. Add the paths to include and exclude into aPackageFiles instancewith a key corresponding to the SBOM ID for the package (SPDXID without theSPDXRef-PACKAGE-* prefix) inTools/build/generate_sbom.py.

4. Run the tool withmakeregen-sbom orpythonTools/build/generate_sbom.py.Ensure that the tool doesn’t fail with any validation errors.

5. Compare the changes toMisc/sbom.spdx.json withgitdiff, checkthat all information appears correct.

6. Commit the changes toMisc/sbom.spdx.json andTools/build/generate_sbom.py.

Removing a dependency¶

When removing a dependency:

1. Remove the entry from theMisc/sbom.spdx.jsonunder thepackages field.

2. Remove the correspondingPackageFiles entry inTools/build/generate_sbom.py

3. Run the tool withmakeregen-sbom orpythonTools/build/generate_sbom.py.Ensure that the tool doesn’t fail with any validation errors.

4. Compare the changes toMisc/sbom.spdx.json withgitdiff, checkthat correct package is removed from the SBOM.

5. Commit the changes toMisc/sbom.spdx.json andTools/build/generate_sbom.py.