Python Package Provenance: What Attestations Prove—and What They Do Not

A familiar package name can make a dependency update feel routine. The useful question is more specific: which file will enter your environment, where did it come from, and what evidence supports accepting this particular release? A popular project and a legitimate publishing account do not answer all three.

The Python Package Index's April 2, 2026 incident report describes malicious releases of LiteLLM and telnyx following an exposed publishing token. The projects subsequently adopted Trusted Publishing. This is a dated incident, not an assertion that their current releases are malicious. It shows why the release path deserves attention even when the project itself is familiar.

This guide builds a small dependency acceptance record. It is intended for a student project or application team, and it uses invented files rather than downloading or executing a suspect package.

Separate four questions before choosing a tool

Suppose a release page lists a wheel and a source distribution. Both belong to the same version, but they are different artifacts. Their hashes, build paths, platform compatibility, and the work performed during installation can differ. Record the exact filename you intend to use rather than writing only the package name.

These checks can reveal different problems. A byte mismatch should stop the acceptance of that artifact. A correct digest with an unexpected publisher calls for a provenance investigation. A valid release that breaks your application is still unsuitable for deployment. Treating every failure as “the package is unsafe” loses the distinction you need to resolve it.

Understand the publishing evidence without overstating it

PyPI's attestation security model explains the relationship between an artifact and an authenticated publishing identity. That evidence can help a consumer examine whether a file came through an expected release route. It does not establish that the code is benign or that the build environment was free of compromise.

Trusted Publishing uses an identity exchange to obtain a short-lived publishing credential, reducing reliance on a manually managed long-lived PyPI token. It changes the authentication path; it does not remove the need to secure the workflow that receives publishing authority.

A practical comparison is a parcel with a verified dispatch record. The record can establish which dispatch process produced it. You still need to know whether its contents meet your requirements. Keep this analogy narrow: software artifacts are executable inputs, and their acceptance requires more than checking a shipping label.

Make a release-review record small enough to maintain

Create one row per accepted artifact. If your application uses several platform-specific wheels, a single version-level row may be insufficient. You want the record to answer what changed between the previously accepted artifact and the proposed one.

The filename above is fictional. Do not turn an example artifact into an installation command. For a real dependency, retain the source of your expectations: a link, release identifier, or signed record is more useful than “looks normal.”

The record should also name a person or team that can decide whether an exception is acceptable. A checkbox with no owner tends to become a ritual; an explicit decision makes the tradeoff visible.

Test byte integrity with a harmless local fixture

The following Python 3.12 example uses a known byte string. It creates no files, installs nothing, and makes no network requests. Its purpose is to demonstrate a digest comparison, not to implement attestation verification.

from hashlib import sha256
from hmac import compare_digest

# The expected digest is a separately chosen reference for this fixture.
expected = (
    "ba7816bf8f01cfea414140de5dae2223"
    "b00361a396177a9cb410ff61f20015ad"
)

def matches_reference(payload, expected_digest):
    actual = sha256(payload).hexdigest()
    return compare_digest(actual, expected_digest)

assert matches_reference(b"abc", expected)
assert not matches_reference(b"abcd", expected)
print("Expected fixture accepted; changed fixture rejected.")

The changed fixture fails because its bytes differ. The accepted fixture proves only that its digest matches the selected reference. If an attacker controlled both the artifact and the reference you trusted, this comparison would not reveal that problem.

For an actual file, Python's hashlib documentation describes digest calculation. A consuming tool's cryptographic attestation check is a separate operation with its own identity and verification requirements. Do not replace it with a visual inspection of a JSON document that happens to contain a signature field.

Keep version selection and installation reproducible

pip's secure-installation guidance documents hash-checking mode. With --require-hashes, the dependency requirements need appropriate pins and hashes, including transitive dependencies. A file containing only top-level package names is not the same control.

This leads to a useful workflow: select the dependency set, retain the exact artifacts or accepted references, and then install using the chosen tool's documented verification mode. Avoid silently selecting a different distribution when an artifact is unavailable. An exception should become a new decision with new evidence.

An environment listing is also different from a reviewed dependency plan. It records what was installed, which is useful for diagnosis, but the presence of a package in that listing does not explain why its release was accepted.

Handle a missing attestation as an evidence gap

A missing attestation is not automatic proof of malware. It may reflect a project's publishing process or the available artifact evidence. Conversely, an attestation that verifies is not an automatic approval decision. Define the action your team takes in each case before a hurried update arrives.

For a parser handling untrusted input or a tool holding production credentials, the consequences of a mistake differ from those of a disposable classroom environment. The evidence and approval effort should reflect that context.

Turn the record into an update habit

Start with one dependency you already use. Write its purpose, identify the exact artifact, and record what you expect of its release route. Before accepting the next version, compare those expectations with the evidence and run a small application-specific test.

Retain what changed and what remains unknown. If a check fails, decide whether the failure concerns identity, bytes, provenance, or suitability before changing controls. This gives your future self a reproducible explanation of the update rather than a vague memory that the package was popular.

Sources and scope

• PyPI: April 2026 LiteLLM/telnyx incident report — dated incident context.
• PyPI: attestation security model and consuming attestations — provenance capabilities and verification boundaries.
• PyPI: Trusted Publishers — publishing authentication.
• pip: secure installs — hash-checking requirements.
• Python 3.12: hashlib — local digest example.

Sources checked October 14, 2026. The acceptance record and fixture are original teaching examples, not a security certification or a report about the safety of current package releases.