Skip to content

trustcheck

trustcheck is a Python package and CLI for evaluating the trust posture of PyPI releases before they are installed, promoted, or approved.

It combines PyPI metadata, vulnerability records, provenance availability, cryptographic attestation verification, Trusted Publisher identity hints, and repository matching into a single operator-friendly report.

What it checks

For a selected package version, trustcheck can:

  • fetch project and release metadata from PyPI
  • inspect declared repository URLs from project metadata
  • retrieve provenance envelopes for each release artifact
  • verify attestations against the downloaded artifact digest
  • extract Trusted Publisher identity details such as repository and workflow
  • compare expected repository input against declared and attested repository signals
  • flag publisher repository and workflow drift against the previous release
  • surface PyPI vulnerability records and optional OSV/GitHub advisory intelligence
  • inspect declared runtime dependencies and summarize the worst-risk dependency in the set
  • scan requirements files, project TOML, and uv.lock, poetry.lock, or pdm.lock
  • statically inspect wheel and sdist contents without importing package code
  • emit a concise human-readable report or structured JSON

Install

pip install trustcheck

First command

trustcheck inspect sampleproject --version 4.0.0

Or add the reusable TrustCheck Package Scanner action:

steps:
  - uses: actions/checkout@v6
  - uses: Halfblood-Prince/trustcheck@v1
    with:
      target: requirements.txt
      policy: strict

The action uploads a JSON report and propagates the CLI policy exit code.

Common use cases

Check the latest release:

trustcheck inspect requests

Require a specific upstream repository:

trustcheck inspect sampleproject \
  --version 4.0.0 \
  --expected-repo https://github.com/pypa/sampleproject

Emit JSON for automation:

trustcheck inspect sampleproject --version 4.0.0 --format json

Inspect the package and its direct dependencies:

trustcheck inspect sampleproject --version 4.0.0 --with-deps

Inspect the full dependency tree:

trustcheck inspect sampleproject --version 4.0.0 --with-transitive-deps

Inspect every package listed in a requirements-style file:

trustcheck scan requirements.txt

Inspect dependencies declared in a TOML project file:

trustcheck scan pyproject.toml

Inspect exact versions from a supported lockfile:

trustcheck scan uv.lock --with-transitive-deps

Inspect wheel and sdist contents:

trustcheck inspect sampleproject --version 4.0.0 --inspect-artifacts --verbose

Fail CI when full verification is missing:

trustcheck inspect sampleproject --version 4.0.0 --strict

Use from Python

trustcheck can also be imported directly into Python programs:

from trustcheck import inspect_package

report = inspect_package("sampleproject", version="4.0.0", include_dependencies=True)
print(report.recommendation)
print(report.to_dict()["report"]["coverage"]["status"])
print(report.dependency_summary.highest_risk_recommendation)

Machine-readable reports currently use JSON schema 1.5.0. The package release and report schema are versioned independently.

Docs map