# 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
- interpret SLSA v1 builder, build type, source commit, workflow, and material
  evidence
- detect mutable workflow references, unpinned build actions, and
  source-to-artifact inconsistencies
- extract Trusted Publisher identity details such as repository and workflow
- compare expected repository input against declared and attested repository signals
- compare signer, repository, workflow, builder, build type, and source commit
  evidence against the previous release
- merge PyPI, OSV, custom OSV-compatible, and Ecosyste.ms advisory intelligence
- normalize CVSS, CWE, aliases, fix versions, and withdrawn status
- enrich CVEs with optional CISA KEV and FIRST EPSS intelligence
- inspect declared runtime dependencies and summarize the worst-risk dependency in the set
- scan requirements files, project TOML, PEP 751 `pylock.toml`,
  `Pipfile.lock`, and `uv.lock`, `poetry.lock`, or `pdm.lock`
- export SARIF 2.1.0, CycloneDX 1.6 JSON/XML, SPDX 2.3 JSON,
  OpenVEX 0.2.0, Markdown, or native JSON
- statically inspect wheel and sdist contents without importing package code
- score typosquatting and package-history anomalies, and inspect Python ASTs
  plus PE, ELF, and Mach-O binaries for suspicious capabilities
- calculate, validate, dry-run, and transactionally apply minimal secure
  dependency upgrades
- batch advisory queries, bound concurrent scans, checkpoint interrupted work,
  and use SHA-256 content-addressed offline caches
- extend advisory, index, artifact, policy, and rendering behavior through
  explicitly enabled entry-point plugins
- emit a concise human-readable report or structured JSON

## Install

```bash
pip install trustcheck
```

## First command

```bash
trustcheck inspect sampleproject --version 4.0.0
```

Or add the reusable TrustCheck Package Scanner action:

```yaml
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:

```bash
trustcheck inspect requests
```

Require a specific upstream repository:

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

Emit JSON for automation:

```bash
trustcheck inspect sampleproject --version 4.0.0 --format json
```

Inspect the package and its direct dependencies:

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

Inspect the full dependency tree:

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

Scan every package listed in a requirements-style file for vulnerabilities:

```bash
trustcheck scan -f requirements.txt
```

Scan dependencies declared in a TOML project file for vulnerabilities:

```bash
trustcheck scan -f pyproject.toml
```

Inspect exact versions from a supported lockfile:

```bash
trustcheck inspect -f uv.lock --with-transitive-deps
```

Plan or validate a safe dependency repair:

```bash
trustcheck scan -f requirements.txt --with-osv --plan-fixes
trustcheck scan -f uv.lock --with-osv --fix --dry-run
```

Inspect wheel and sdist contents:

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

Fail CI when full verification is missing:

```bash
trustcheck inspect sampleproject --version 4.0.0 --strict
```

## Use from Python

`trustcheck` can also be imported directly into Python programs:

```python
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.10.0`. The package release
and report schema are versioned independently.

<script
  src="https://context7.com/widget.js"
  data-library="/halfblood-prince/trustcheck">
</script>

## Docs map

- Start with [Installation](getting-started/installation.md) and [Quickstart](getting-started/quickstart.md)
- Use [CLI Overview](cli/index.md) for command and flag reference
- Use [JSON contract](reference/json-contract.md) for integrations
- Use [Python API](reference/python-api.md) for programmatic use
- Use [Compatibility](reference/compatibility.md) for API and JSON stability guarantees
- Use [Performance and extensibility](reference/performance-extensibility.md) for batching, caching, snapshots, resume state, and plugins
- Use [Benchmarks](reference/benchmarks.md) for the reproducible `pip-audit` comparison
- Use [Trust model and repository matching](reference/trust-model.md) for verification semantics and diagnostics
- Use [CI integration](guides/ci-integration.md) to wire `trustcheck` into GitHub Actions
