trustcheck

trustcheck is a powerful Python package designed to enhance Python supply chain security by evaluating the trust posture of PyPI releases prior to installation, promotion, or approval. This tool combines multiple sources of information into a comprehensive, operator-friendly report that includes:

• PyPI metadata
• Vulnerability records
• Provenance availability
• Cryptographic attestation verification
• Trusted Publisher identity hints
• Repository matching results

Key Features

For any selected package version, trustcheck can perform the following checks:

• Fetch project and release metadata directly from PyPI
• Inspect declared repository URLs from project metadata
• Retrieve provenance envelopes for each release artifact
• Verify attestations against downloaded artifact digests
• Extract Trusted Publisher identity details like repository and workflow
• Compare expected repository input against declared and attested repository signals
• Flag repository and workflow discrepancies against previous releases
• Surface any PyPI vulnerability records relevant to the selected version
• Emit both a concise human-readable report and a structured JSON output

Quick Start Guide

Inspect the latest release of a package:

trustcheck inspect requests

Inspect a specific version:

trustcheck inspect sampleproject --version 4.0.0

Require the release to match an expected source repository:

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

Show detailed per-file evidence:

trustcheck inspect sampleproject --version 4.0.0 --verbose

Emit JSON output for integration with other tools:

trustcheck inspect sampleproject --version 4.0.0 --format json

Fail CI if full verification is not achieved:

trustcheck inspect sampleproject --version 4.0.0 --strict

API Usage

The trustcheck package also exposes a small API for programmatic use, allowing for integration into existing workflows with functions including:

• trustcheck.inspect_package
• trustcheck.TrustReport

Example:

from trustcheck import inspect_package

report = inspect_package("sampleproject", version="4.0.0")

CLI Reference

A range of supported flags allows customization of the inspection process, including version specifications, repository requirements, output formats, and strict policies to enforce verification rigorously.

Output Model

The default text output is optimized for operators, providing a summary followed by detailed evidence and risk information. It categorizes results into recommendation tiers such as verified, metadata-only, review-required, and high-risk, facilitating swift decision-making.

Compatibility and Limitations

trustcheck is ideal for continuous integration and policy automation, with a strong commitment to backward compatibility in its JSON output and Python API. However, it is essential to note that metadata quality can vary, and certain projects may not publish sufficient provenance information.

Development and Quality Practices

The repository employs rigorous CI processes, including linting, type checks, cross-platform testing, and dependency audits, to ensure high-quality code. trustcheck also enables live integration tests against real PyPI packages, further reinforcing its reliability.