Metadata-Version: 2.4
Name: pydependencycheck
Version: 1.5.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: networkx>=3.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: requests>=2.30.0
Requires-Dist: tomli>=1.2.0 ; python_full_version < '3.11'
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
Requires-Dist: black==25.11.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0 ; extra == 'dev'
Requires-Dist: sphinx>=6.0 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1.2.0 ; extra == 'docs'
Requires-Dist: opentelemetry-api>=1.0 ; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.0 ; extra == 'otel'
Requires-Dist: opentelemetry-exporter-jaeger>=1.0 ; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp>=0.43b0 ; extra == 'otel'
Requires-Dist: opentelemetry-exporter-prometheus>=0.43b0 ; extra == 'otel'
Requires-Dist: cryptography>=41.0 ; extra == 'sbom'
Requires-Dist: plotly>=5.0 ; extra == 'visualization'
Requires-Dist: matplotlib>=3.5 ; extra == 'visualization'
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: otel
Provides-Extra: sbom
Provides-Extra: visualization
License-File: LICENSE
Summary: Dependency intelligence and governance platform for Python projects
Author-email: Georgi Mammen Mullassery <mullassery@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/Mullassery/pydependencycheck/blob/main/README.md
Project-URL: Issues, https://github.com/Mullassery/pydependencycheck/issues
Project-URL: Repository, https://github.com/Mullassery/pydependencycheck

# PyDependencyCheck

Dependency intelligence and supply-chain security for Python projects. Scan dependencies, track provenance, detect unused packages, check licenses, generate signed SBOMs, and gate CI builds.

> **Not to be confused with [PyDeepMesh](https://github.com/Mullassery/PyDeepMesh):** PyDeepMesh builds repository dependency graphs and matches advisories across ecosystems; PyDependencyCheck explains *why* each Python dependency exists, who added it, and whether it is used.

## Which project do I need?

Part of the Mullassery open-source family. These tools have similar names — here is the short version of who does what:

| If you need to… | Use |
| --- | --- |
| Build a repository's dependency graph and match it against vulnerability advisories (Python, Rust, Node, containers) | [PyDeepMesh](https://github.com/Mullassery/PyDeepMesh) |
| Understand *why* a Python dependency exists, who added it, and whether it is actually used | [PyDependencyCheck](https://github.com/Mullassery/PyDependencyCheck) |
| Statically analyze a **dbt** project (risky tests, test blast radius, cost) | [PyDBTGuard](https://github.com/Mullassery/PyDBTGuard) |
| Statically analyze **Apache Beam / Dataflow** pipelines (cost, hot keys, reliability) | [PyBeamGuard](https://github.com/Mullassery/PyBeamGuard) |
| Validate **Airflow** DAGs and dbt runs | [PyAirflowTester](https://github.com/Mullassery/PyAirflowTester) |
| Simulate cascading-failure **blast radius** across infrastructure, data pipelines, and AI systems | [PyBlastRadius](https://github.com/Mullassery/PyBlastRadius) |
| Check the **quality of the data itself** at runtime (schema, drift, anomalies) | [StatGuardian](https://github.com/Mullassery/StatGuardian) |
| Discover **devices, services, and vulnerabilities on a network** | [PyNetworkIntel](https://github.com/Mullassery/PyNetworkIntel) |
| Discover and score **API security** risk (real traffic, agent/MCP, Cedar policy) | [PyAPICheck](https://github.com/Mullassery/PyAPICheck) |
| Trace and root-cause **AI agent** failures | [PyAgentHound](https://github.com/Mullassery/PyAgentHound) |
| Diagnose **RAG retrieval** failures | [PyVectorHound](https://github.com/Mullassery/PyVectorHound) |
| Orchestrate **local, dependency-aware tasks** (DAG scheduler + content-addressed cache) | [PyTaskWireCheck](https://github.com/Mullassery/PyTaskWireCheck) |

[Browse all projects →](https://github.com/Mullassery?tab=repositories)

## What it is

PyDependencyCheck helps you understand not just *what* you depend on, but *why* it's there and whether your dependency set is healthy. It combines dependency parsing, graph analysis, OSV vulnerability scanning, Git provenance, and licensing checks into a single CLI. A Rust core powers parsing, graph algorithms, and vulnerability lookups, wrapped in Python.

## Features / Highlights

- **CI gating**: `pydependencycheck gate --min-health` exits non-zero with GitHub Actions annotations when thresholds fail.
- **Provenance**: `why` and `trace` show who added/changed a dependency and full git history.
- **Vulnerability scanning**: Checks against OSV (Open Source Vulnerabilities) in real time.
- **Unused dependency detection**: AST-based detection of unused packages in your codebase.
- **License compliance**: Check dependencies against your project's license for compatibility.
- **Signed SBOMs**: Export CycloneDX or SPDX with RSA-SHA256 signatures.
- **Health scoring**: Aggregates vulnerabilities, staleness, dead dependencies, and complexity into a single score.
- **Multi-format output**: Tables, JSON, HTML, or Markdown for integration with CI/reporting.

## Who it's for / Use cases

- **CI/CD enforcement**: Block merges when dependency health drops below acceptable thresholds.
- **Security auditing**: Identify vulnerable packages and understand their impact.
- **Dependency hygiene**: Find and remove unused dependencies to reduce attack surface.
- **Compliance reporting**: Generate signed SBOMs and license reports for audits.
- **Open-source maintenance**: Track when dependencies were added and why.

## What it is not

- **Not pip-audit**: Shares vulnerability scanning but also includes provenance, unused detection, licensing, SBOM signing, and gating. These are different tools with overlapping features.
- **Limited file discovery**: Focuses on `requirements.txt`, `pyproject.toml`, `setup.py`, `setup.cfg`. Projects that don't use these or have complex multi-project setups may need careful path handling.
- **Exact-pin remediation**: `remediate` only updates exact `==` pins to OSV fix versions; version ranges are not modified.
- **Transitive scope varies**: The `scan`/`health` view is based on parsed manifest files and detected dependencies; installed transitive resolution depends on context.

## Project status

PyDependencyCheck is in beta (v1.4.2). Core features (scanning, provenance, health scoring, vulnerability checks, licensing, SBOM export, CI gating) are implemented. See [CHANGELOG.md](CHANGELOG.md) for recent fixes and updates.

### setup.py / setup.cfg support

Static `install_requires` and `extras_require` declarations in `setup.py`
(AST, never executed) and `setup.cfg` are now included in the dependency
graph and can be patched by `pydependencycheck remediate`. Dynamic metadata
such as `install_requires=read_requirements()` cannot be resolved statically;
the scanner emits an explicit warning instead of silently treating the
project as dependency-free.

## CycloneDX VEX export

Export OSV findings as a CycloneDX 1.6 VEX document:

```bash
pydependencycheck vex . --output vex.json --state under_investigation
```

Without runtime reachability the default state is `under_investigation`, not
`not_affected` — missing evidence is never presented as a clean result.

## Installation

```bash
pip install pydependencycheck
```

Optional extras:

```bash
pip install "pydependencycheck[sbom,otel,visualization]"
```

Requires Python 3.8+. Prebuilt wheels available for Linux, macOS, and Windows.

## Quick start

```bash
# Scan current project
pydependencycheck scan

# Check health score
pydependencycheck health

# Find out why a package is installed
pydependencycheck why requests

# Trace full history of a dependency
pydependencycheck trace requests

# Check license compliance
pydependencycheck licenses --project-license MIT

# Export signed CycloneDX SBOM
pydependencycheck export --format cyclonedx --output sbom.json

# Gate CI build
pydependencycheck gate --min-health 50
```

## Commands

| Command | Purpose |
|---|---|
| `scan` | Parse manifests and show dependency overview |
| `list` | List all detected dependencies |
| `why <pkg>` | Show git blame provenance |
| `trace <pkg>` | Show current status and git history |
| `health` | Compute aggregate health score |
| `licenses` | License classification and compatibility |
| `analyze` | Deep graph analysis |
| `remediate` | Suggest/apply fixes for vulnerable exact pins |
| `export` | Export SBOM in CycloneDX/SPDX (optionally signed) |
| `gate` | CI gate with exit code and annotations |

## Known issues and deferred work

**Blocked / failed:**
- Merge with/define boundary vs PyDeepMesh; SARIF + Action.

**Rejected / deferred:**
- Duplicate multi-ecosystem scanning.

Full shipped/blocked/rejected detail: [`QUEUE_STATUS.md`](QUEUE_STATUS.md).

## Documentation

- [Installation notes](.github/INSTALL.md)
- [CI gating with GitHub Actions](docs/ci-gating.md)
- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

