trustcheck 2.0.0

Package trust and provenance verification for PyPI consumers.

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.

Packages that publish no provenance are treated as needing review rather than as automatic high-risk findings, while invalid provenance, partial coverage, repository mismatches, and known vulnerabilities remain stronger negative signals.

What it checks

For a selected package version, trustcheck can:

• fetch project and release metadata from PyPI
• verify published provenance against artifact digests
• surface Trusted Publisher repository and workflow identity hints
• compare expected repository input against declared and attested signals
• flag publisher drift, missing verification, and known vulnerabilities
• scan requirements files, project TOML, and uv.lock, poetry.lock, or pdm.lock
• optionally inspect wheel and sdist contents without importing or executing package code
• emit concise text output or structured JSON for automation

Installation

pip install trustcheck

Requirements:

• Python >=3.10
• Network access to PyPI

The release pipeline also builds and validates a strict Snap package. Snap Store installation becomes available after the trustcheck name is registered and the first stable store release is published.

Machine-readable reports currently use JSON schema 1.5.0. Package and report schema versions are independent so documentation-only package releases do not force contract churn.

TrustCheck Package Scanner

Use the TrustCheck Package Scanner action to scan a checked-in dependency file before merge:

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

The action installs and runs trustcheck, uploads trustcheck-report.json as a workflow artifact, and fails the job with the CLI's exit code when policy evaluation fails. target also accepts a PyPI package name, pyproject.toml, uv.lock, poetry.lock, or pdm.lock. Each stable release publishes an immutable full version tag and updates the compatible major action tag used above.

See the CI integration guide for custom policies, OSV, dependency traversal, outputs, and report naming.

Quick start

Inspect the latest release:

trustcheck inspect requests

Inspect a specific version:

trustcheck inspect sampleproject --version 4.0.0

Show only known vulnerabilities for a release:

trustcheck inspect sampleproject --version 4.0.0 --cve

Enrich vulnerability intelligence with OSV and GitHub Advisory Database data:

trustcheck inspect jinja2 --version 2.10.0 --with-osv --cve

Inspect a package and its direct dependencies:

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

Inspect the full transitive 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 direct and transitive versions from a supported lockfile:

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

Statically inspect wheel and sdist contents:

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

Artifact inspection validates wheel RECORD hashes, lists console scripts, detects native extensions and unusual files, and compares wheel and sdist metadata. It reads archive bytes only and never imports the inspected package.

Require a release to match an expected repository:

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

Emit JSON for another tool:

trustcheck inspect sampleproject --version 4.0.0 --format json

Emit combined JSON for a requirements-style, TOML, or lockfile scan:

trustcheck scan requirements.txt --format json

Emit only vulnerability records as JSON:

trustcheck inspect sampleproject --version 4.0.0 --cve --format json

Fail CI when full verification is missing:

trustcheck inspect sampleproject --version 4.0.0 --strict

Use it from Python:

from trustcheck import inspect_package

report = inspect_package("sampleproject", version="4.0.0", include_dependencies=True)
print(report.recommendation)

Documentation

Full documentation: https://halfblood-prince.github.io/trustcheck/

• Getting started: Installation and Quickstart
• CLI usage: CLI overview, Policies, and Config and offline mode
• Integrations: JSON contract, Python API, and Compatibility
• Trust model: Verification model and repository matching
• Automation: CI integration
• Project details: Development and release process, release publishing, and Changelog

Project support:

• Bugs and feature requests: GitHub Issues
• Sensitive security reports: GitHub private vulnerability reporting
• Security policy: SECURITY.md

License

Trustcheck Personal Use License