pydepaudit 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. pydepaudit-1.0.0/.gitattributes +1 -0
  2. pydepaudit-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml +33 -0
  3. pydepaudit-1.0.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
  4. pydepaudit-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml +18 -0
  5. pydepaudit-1.0.0/.github/dependabot.yml +10 -0
  6. pydepaudit-1.0.0/.github/pull_request_template.md +10 -0
  7. pydepaudit-1.0.0/.github/workflows/ci.yml +35 -0
  8. pydepaudit-1.0.0/.github/workflows/release.yml +21 -0
  9. pydepaudit-1.0.0/.gitignore +25 -0
  10. pydepaudit-1.0.0/.pre-commit-config.yaml +15 -0
  11. pydepaudit-1.0.0/CHANGELOG.md +124 -0
  12. pydepaudit-1.0.0/CODE_OF_CONDUCT.md +20 -0
  13. pydepaudit-1.0.0/CONTRIBUTING.md +52 -0
  14. pydepaudit-1.0.0/LICENSE +21 -0
  15. pydepaudit-1.0.0/PKG-INFO +213 -0
  16. pydepaudit-1.0.0/README.md +155 -0
  17. pydepaudit-1.0.0/SECURITY.md +38 -0
  18. pydepaudit-1.0.0/action.yml +40 -0
  19. pydepaudit-1.0.0/pydepaudit/__init__.py +7 -0
  20. pydepaudit-1.0.0/pydepaudit/audit.py +163 -0
  21. pydepaudit-1.0.0/pydepaudit/cache.py +100 -0
  22. pydepaudit-1.0.0/pydepaudit/cli.py +196 -0
  23. pydepaudit-1.0.0/pydepaudit/config.py +167 -0
  24. pydepaudit-1.0.0/pydepaudit/cvss.py +113 -0
  25. pydepaudit-1.0.0/pydepaudit/cvss4.py +607 -0
  26. pydepaudit-1.0.0/pydepaudit/models.py +69 -0
  27. pydepaudit-1.0.0/pydepaudit/parsers/__init__.py +24 -0
  28. pydepaudit-1.0.0/pydepaudit/parsers/installed.py +21 -0
  29. pydepaudit-1.0.0/pydepaudit/parsers/markers.py +13 -0
  30. pydepaudit-1.0.0/pydepaudit/parsers/poetrylock.py +34 -0
  31. pydepaudit-1.0.0/pydepaudit/parsers/pyproject.py +77 -0
  32. pydepaudit-1.0.0/pydepaudit/parsers/requirements.py +156 -0
  33. pydepaudit-1.0.0/pydepaudit/parsers/uvlock.py +38 -0
  34. pydepaudit-1.0.0/pydepaudit/py.typed +0 -0
  35. pydepaudit-1.0.0/pydepaudit/report.py +264 -0
  36. pydepaudit-1.0.0/pydepaudit/rules.py +217 -0
  37. pydepaudit-1.0.0/pydepaudit/sources/__init__.py +1 -0
  38. pydepaudit-1.0.0/pydepaudit/sources/github.py +299 -0
  39. pydepaudit-1.0.0/pydepaudit/sources/osv.py +290 -0
  40. pydepaudit-1.0.0/pydepaudit/sources/pypi.py +232 -0
  41. pydepaudit-1.0.0/pyproject.toml +69 -0
  42. pydepaudit-1.0.0/tests/test_cache.py +184 -0
  43. pydepaudit-1.0.0/tests/test_cli.py +566 -0
  44. pydepaudit-1.0.0/tests/test_config.py +162 -0
  45. pydepaudit-1.0.0/tests/test_cvss.py +112 -0
  46. pydepaudit-1.0.0/tests/test_github.py +450 -0
  47. pydepaudit-1.0.0/tests/test_osv.py +540 -0
  48. pydepaudit-1.0.0/tests/test_parsers.py +444 -0
  49. pydepaudit-1.0.0/tests/test_pypi.py +390 -0
  50. pydepaudit-1.0.0/tests/test_report.py +215 -0
  51. pydepaudit-1.0.0/tests/test_rules.py +256 -0
@@ -0,0 +1 @@
1
+ * text=auto eol=lf
@@ -0,0 +1,33 @@
1
+ name: Bug report
2
+ description: Something pydepaudit reports or does is wrong
3
+ labels: [bug]
4
+ body:
5
+ - type: textarea
6
+ id: what-happened
7
+ attributes:
8
+ label: What happened?
9
+ description: Expected vs actual behavior.
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: repro
14
+ attributes:
15
+ label: Reproduction
16
+ description: Command run and the dependency file contents (or a minimal one).
17
+ render: text
18
+ validations:
19
+ required: true
20
+ - type: input
21
+ id: version
22
+ attributes:
23
+ label: pydepaudit version
24
+ description: Output of `pydepaudit --version`.
25
+ validations:
26
+ required: true
27
+ - type: input
28
+ id: python
29
+ attributes:
30
+ label: Python version and OS
31
+ placeholder: e.g. 3.13 on Windows 11
32
+ validations:
33
+ required: true
@@ -0,0 +1,5 @@
1
+ blank_issues_enabled: false
2
+ contact_links:
3
+ - name: Security issue
4
+ url: https://github.com/MathiasPaulenko/pydepaudit/security/advisories/new
5
+ about: Do not open public issues for vulnerabilities — report privately.
@@ -0,0 +1,18 @@
1
+ name: Feature request
2
+ description: Suggest an improvement or new capability
3
+ labels: [enhancement]
4
+ body:
5
+ - type: textarea
6
+ id: problem
7
+ attributes:
8
+ label: What problem does it solve?
9
+ description: The use case, not the implementation.
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: proposal
14
+ attributes:
15
+ label: Proposed behavior
16
+ description: How should it look from the CLI/JSON side?
17
+ validations:
18
+ required: false
@@ -0,0 +1,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: weekly
7
+ - package-ecosystem: pip
8
+ directory: /
9
+ schedule:
10
+ interval: weekly
@@ -0,0 +1,10 @@
1
+ ## Summary
2
+
3
+ <!-- What does this change and why? Link the issue if there is one. -->
4
+
5
+ ## Checklist
6
+
7
+ - [ ] `ruff check .` and `ruff format --check .` pass
8
+ - [ ] `mypy pydepaudit` passes
9
+ - [ ] `pytest` passes, new behavior has tests
10
+ - [ ] Docs/CHANGELOG updated if user-facing
@@ -0,0 +1,35 @@
1
+ name: ci
2
+
3
+ on:
4
+ push:
5
+ branches: [main, master]
6
+ pull_request:
7
+
8
+ jobs:
9
+ lint:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+ - uses: actions/setup-python@v5
14
+ with:
15
+ python-version: "3.13"
16
+ cache: pip
17
+ - run: pip install -e .[dev]
18
+ - run: ruff check . && ruff format --check .
19
+ - run: mypy pydepaudit
20
+
21
+ test:
22
+ runs-on: ${{ matrix.os }}
23
+ strategy:
24
+ fail-fast: false
25
+ matrix:
26
+ os: [ubuntu-latest, windows-latest]
27
+ python-version: ["3.11", "3.12", "3.13", "3.14"]
28
+ steps:
29
+ - uses: actions/checkout@v4
30
+ - uses: actions/setup-python@v5
31
+ with:
32
+ python-version: ${{ matrix.python-version }}
33
+ cache: pip
34
+ - run: pip install -e .[dev]
35
+ - run: pytest
@@ -0,0 +1,21 @@
1
+ name: release
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ permissions:
8
+ id-token: write
9
+ contents: read
10
+
11
+ jobs:
12
+ pypi:
13
+ runs-on: ubuntu-latest
14
+ environment: pypi
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ - uses: actions/setup-python@v5
18
+ with:
19
+ python-version: "3.13"
20
+ - run: pip install build && python -m build
21
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,25 @@
1
+ # Private development docs — never publish
2
+ ref/
3
+
4
+ # Python
5
+ __pycache__/
6
+ *.py[cod]
7
+ *.egg-info/
8
+ dist/
9
+ build/
10
+ .venv/
11
+ venv/
12
+ .env
13
+ .env.*
14
+
15
+ # Cache/test artifacts
16
+ .pydepaudit-cache/
17
+ .pytest_cache/
18
+ .mypy_cache/
19
+ .ruff_cache/
20
+ .coverage
21
+ htmlcov/
22
+
23
+ # IDE
24
+ .idea/
25
+ .vscode/
@@ -0,0 +1,15 @@
1
+ repos:
2
+ - repo: https://github.com/pre-commit/pre-commit-hooks
3
+ rev: v5.0.0
4
+ hooks:
5
+ - id: trailing-whitespace
6
+ - id: end-of-file-fixer
7
+ - id: check-yaml
8
+ - id: check-toml
9
+ - id: check-added-large-files
10
+ - repo: https://github.com/astral-sh/ruff-pre-commit
11
+ rev: v0.8.1
12
+ hooks:
13
+ - id: ruff
14
+ args: [--fix]
15
+ - id: ruff-format
@@ -0,0 +1,124 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [1.0.0] - 2026-10-15
11
+
12
+ ### Added
13
+
14
+ - Project scaffold: package layout, CLI skeleton (`check`, `show`), lint/type-check/test tooling and CI.
15
+ - Dependency parsing for uv.lock, requirements.txt and pyproject.toml.
16
+ - PyPI metadata per dependency: latest version, license and last release date.
17
+ - CVE audit via the OSV API with GHSA/CVSS severity mapping.
18
+ - Maintainer health via the GitHub API: archived flag, last push, contributor count.
19
+ - Findings engine with severities, `.pydepaudit.toml` config, `--fail-on` and `--license` options.
20
+ - Local HTTP cache (1h TTL, `--no-cache` to bypass) and parallel source fetching.
21
+ - poetry.lock parsing, PEP 735 dependency-groups and pip-compile-style
22
+ requirements (inline `--hash`, line continuations); dual-license (SPDX `OR`)
23
+ handling; project license autodetection from pyproject.toml/LICENSE.
24
+ - Graceful handling of malformed API payloads, dependency files, network errors
25
+ and non-UTF-8 consoles.
26
+
27
+ - Vulnerability records are deduplicated by shared CVE/GHSA/PYSEC aliases and
28
+ now carry `fixed` — the earliest version resolving the vuln — shown in the
29
+ table and JSON output.
30
+ - Yanked-version detection: an exact pin to a release yanked from PyPI
31
+ (PEP 592) produces a medium finding.
32
+ - CVSS v4.0 scoring (macrovector + interpolation, ported from the official
33
+ FIRST reference implementation) — v4 vectors now resolve to severities
34
+ instead of `unknown`.
35
+ - requirements.txt `-r`/`--requirement` includes are followed recursively
36
+ (cycle-safe); `-c`/`--constraint` files narrow declared pins, pip-style.
37
+ - Environment markers (`; sys_platform == ...`) are evaluated against the
38
+ current platform — inapplicable requirements are not audited.
39
+ - `check --installed` audits the live environment via `importlib.metadata`
40
+ instead of declared dependency files.
41
+ - `--format sarif` emits SARIF 2.1.0 for GitHub code scanning upload.
42
+ - OpenSSF Scorecard as an extra maintainer-health signal: repos scoring below
43
+ `scorecard_min` (default 5.0, configurable in `.pydepaudit.toml`) produce a
44
+ low-severity finding; `show` prints the score.
45
+ - Composite GitHub Action (`action.yml`): `uses: MathiasPaulenko/pydepaudit@v*`.
46
+
47
+ ### Fixed
48
+
49
+ - OSV `querybatch` returns trimmed records (id + modified only); vulnerability
50
+ details are now hydrated from `/v1/vulns/{id}` in parallel and cached, so
51
+ severities, aliases and summaries are complete.
52
+ - CVSS v4: strict vector validation (invalid metric values no longer crash the
53
+ scorer), `MSI/MSA` correctly default to base `SI/SA`, and the final rounding
54
+ now matches the reference implementation's half-up epsilon rule.
55
+ - A malformed pin in a lock file no longer aborts the whole audit — the
56
+ dependency falls back to its latest released version.
57
+ - requirements.txt: UTF-8 BOM files are parsed, `-r` inside a `-c` file stays
58
+ a constraint (no phantom dependencies), `-cfile` attached form is supported,
59
+ and include targets that can't be resolved are skipped instead of crashing.
60
+ - Malformed API payloads harden end to end: non-dict PyPI/GitHub bodies, bad
61
+ upload timestamps, non-string license fields, corrupt cache files and OSV
62
+ hydration failures degrade cleanly instead of crashing.
63
+ - GitHub 403 responses (rate limiting) are treated as transient and are no
64
+ longer cached as "repository not found".
65
+ - Auxiliary endpoints (contributors, Scorecard) failing no longer kills the
66
+ audit; the signals degrade to `None`.
67
+ - OSV queries now use the canonical PyPI package name, and yanked-version
68
+ detection compares PEP 440 versions (`==1.0.0` matches yanked `1.0`).
69
+ - Terminal output sanitizes control/bidi characters in untrusted upstream text
70
+ (package names, license strings, vuln summaries) — no more ANSI injection or
71
+ `UnicodeEncodeError` crashes on legacy consoles.
72
+ - GitHub repo URLs with `www.github.com` are detected; invalid or hostile repo
73
+ strings are rejected before request construction.
74
+ - Config validation rejects wrong types for `denied_licenses`, `ignore` and
75
+ numeric fields with clear errors instead of `TypeError` tracebacks.
76
+ - Cache writes are atomic (write-then-rename) so concurrent readers never see
77
+ a torn JSON file.
78
+ - SARIF output omits the `locations` block when the dependency has no source
79
+ file instead of emitting an empty `uri`.
80
+ - Composite GitHub Action passes inputs via environment variables, closing the
81
+ shell-injection path on `path`/`format`/`fail-on` inputs.
82
+ - `GITHUB_TOKEN` was set as a client-level header and therefore sent to
83
+ api.securityscorecards.dev. Auth is now applied per request to GitHub
84
+ endpoints only; third-party calls send an empty `Authorization` header.
85
+ - Cache filenames now include a digest (avoiding sanitized-key collisions),
86
+ and each atomic write uses a unique temporary file for concurrent writers.
87
+ Invalid UTF-8 entries are treated as cache misses.
88
+ - Distinct version declarations for the same normalized package are no longer
89
+ discarded; contradictory exact pins are not misreported as installable.
90
+ - PEP 735 dependency-group includes are flattened with cycle protection, and
91
+ requirements includes support quoted paths containing spaces.
92
+ - CVSS v3 vectors now reject malformed headers, duplicate/unknown metrics and
93
+ invalid optional values instead of calculating a score from partial input.
94
+ - PyPI timestamps without time zones are normalized to UTC; malformed package
95
+ versions/names and unknown-license sentinels no longer produce unsafe or
96
+ misleading metadata.
97
+ - Rich markup in untrusted dependency/license text is rendered literally, and
98
+ terminal sanitization also strips Arabic letter marks and deprecated bidi
99
+ controls without mutating the library caller's stdout configuration.
100
+ - `show` reports malformed upstream JSON as a clean CLI error; blank declared
101
+ project-license metadata falls back to LICENSE-file detection.
102
+ - Cache records are checked against their package/repository/vulnerability key,
103
+ so a malformed entry cannot substitute metadata for a different object.
104
+ - The default HTTP cache is now per-user and outside the audited project;
105
+ checked-in `.pydepaudit-cache` files can no longer poison audit results.
106
+ - GitHub API redirects are followed only to HTTPS repository endpoints on
107
+ `api.github.com`; other source clients do not follow redirects. External
108
+ redirects cannot trigger SSRF or receive tokens.
109
+ - Excessively nested JSON/TOML and requirement markers now degrade to clean
110
+ parse errors or skipped malformed records instead of leaking recursion
111
+ tracebacks from cache, API, and project-file parsing.
112
+ - Cache writes reject non-standard JSON numbers, and long requirements
113
+ continuations are assembled in linear time.
114
+ - Requirements includes now parse quoted paths and distinguish constraint and
115
+ requirement visits to the same file; redundant constraints are not repeated.
116
+ - Repeated declarations for one package retain distinct version pins, while
117
+ PEP 735 group includes and cycles are handled without dropping dependencies.
118
+ - CVSS v3 rejects malformed vectors; non-finite/out-of-range Scorecard values
119
+ and malformed license sentinels no longer distort findings or JSON output.
120
+ - SARIF source paths are URI-escaped, and installed-environment results no
121
+ longer claim a fictitious file location.
122
+
123
+ [Unreleased]: https://github.com/MathiasPaulenko/pydepaudit/compare/v1.0.0...HEAD
124
+ [1.0.0]: https://github.com/MathiasPaulenko/pydepaudit/releases/tag/v1.0.0
@@ -0,0 +1,20 @@
1
+ # Code of Conduct
2
+
3
+ This project follows the
4
+ [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/),
5
+ version 2.1.
6
+
7
+ In short: be respectful, constructive and welcoming. Harassment, personal
8
+ attacks and publishing others' private information are not tolerated.
9
+
10
+ ## Enforcement
11
+
12
+ Report unacceptable behavior through GitHub's abuse reporting or by opening a
13
+ private vulnerability report on the repository's Security tab. All reports are
14
+ reviewed and handled confidentially.
15
+
16
+ ## Attribution
17
+
18
+ This policy is based on the
19
+ [Contributor Covenant](https://www.contributor-covenant.org), which is used by
20
+ thousands of open source projects.
@@ -0,0 +1,52 @@
1
+ # Contributing
2
+
3
+ Thanks for your interest in pydepaudit. Contributions of all kinds are welcome:
4
+ bug reports, feature requests, documentation and code.
5
+
6
+ ## Development setup
7
+
8
+ ```bash
9
+ git clone https://github.com/MathiasPaulenko/pydepaudit.git
10
+ cd pydepaudit
11
+ python -m venv .venv
12
+ # Windows PowerShell
13
+ .\.venv\Scripts\Activate.ps1
14
+ # Linux/macOS
15
+ source .venv/bin/activate
16
+ python -m pip install -e ".[dev]"
17
+ pre-commit install
18
+ ```
19
+
20
+ ## Workflow
21
+
22
+ 1. Open an issue first for anything non-trivial.
23
+ 2. Create a branch, make your change, add tests.
24
+ 3. Keep commits small and use [Conventional Commits](https://www.conventionalcommits.org)
25
+ (`feat:`, `fix:`, `docs:`…).
26
+ 4. Open a pull request — CI runs lint, type-check and tests on Linux/Windows.
27
+
28
+ ## Checks
29
+
30
+ Everything must pass before merging:
31
+
32
+ ```bash
33
+ ruff check . && ruff format --check .
34
+ mypy pydepaudit
35
+ pytest --cov=pydepaudit
36
+ ```
37
+
38
+ - Tests use `pytest` + `respx` for HTTP mocking — no live network calls in tests.
39
+ - `mypy --strict` on the package; public APIs need type hints and docstrings.
40
+ - New parsers/sources get unit tests; CLI changes get `CliRunner` tests.
41
+
42
+ ## Bug reports
43
+
44
+ Use the bug report issue template and include:
45
+
46
+ - `pydepaudit --version` and Python version
47
+ - the dependency file being audited (or a minimal reproducer)
48
+ - expected vs actual output
49
+
50
+ ## Security issues
51
+
52
+ Do not open a public issue — see [SECURITY.md](SECURITY.md).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mathias Paulenko
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,213 @@
1
+ Metadata-Version: 2.5
2
+ Name: pydepaudit
3
+ Version: 1.0.0
4
+ Summary: Audit Python dependencies for CVEs, licenses, staleness and maintainer health in one command.
5
+ Project-URL: Homepage, https://github.com/MathiasPaulenko/pydepaudit
6
+ Project-URL: Repository, https://github.com/MathiasPaulenko/pydepaudit
7
+ Project-URL: Issues, https://github.com/MathiasPaulenko/pydepaudit/issues
8
+ Project-URL: Changelog, https://github.com/MathiasPaulenko/pydepaudit/blob/main/CHANGELOG.md
9
+ Author: Mathias Paulenko
10
+ License: MIT License
11
+
12
+ Copyright (c) 2026 Mathias Paulenko
13
+
14
+ Permission is hereby granted, free of charge, to any person obtaining a copy
15
+ of this software and associated documentation files (the "Software"), to deal
16
+ in the Software without restriction, including without limitation the rights
17
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18
+ copies of the Software, and to permit persons to whom the Software is
19
+ furnished to do so, subject to the following conditions:
20
+
21
+ The above copyright notice and this permission notice shall be included in all
22
+ copies or substantial portions of the Software.
23
+
24
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30
+ SOFTWARE.
31
+ License-File: LICENSE
32
+ Keywords: audit,ci,cve,dependencies,license,security,supply-chain
33
+ Classifier: Development Status :: 5 - Production/Stable
34
+ Classifier: Environment :: Console
35
+ Classifier: Intended Audience :: Developers
36
+ Classifier: License :: OSI Approved :: MIT License
37
+ Classifier: Operating System :: OS Independent
38
+ Classifier: Programming Language :: Python :: 3
39
+ Classifier: Programming Language :: Python :: 3.11
40
+ Classifier: Programming Language :: Python :: 3.12
41
+ Classifier: Programming Language :: Python :: 3.13
42
+ Classifier: Programming Language :: Python :: 3.14
43
+ Classifier: Topic :: Security
44
+ Classifier: Topic :: Software Development :: Quality Assurance
45
+ Requires-Python: >=3.11
46
+ Requires-Dist: httpx>=0.27
47
+ Requires-Dist: packaging>=24.0
48
+ Requires-Dist: rich>=13.7
49
+ Requires-Dist: typer>=0.12
50
+ Provides-Extra: dev
51
+ Requires-Dist: mypy>=1.10; extra == 'dev'
52
+ Requires-Dist: pre-commit>=3.7; extra == 'dev'
53
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
54
+ Requires-Dist: pytest>=8.0; extra == 'dev'
55
+ Requires-Dist: respx>=0.21; extra == 'dev'
56
+ Requires-Dist: ruff>=0.6; extra == 'dev'
57
+ Description-Content-Type: text/markdown
58
+
59
+ # pydepaudit
60
+
61
+ [![PyPI](https://img.shields.io/pypi/v/pydepaudit)](https://pypi.org/project/pydepaudit/)
62
+ [![CI](https://github.com/MathiasPaulenko/pydepaudit/actions/workflows/ci.yml/badge.svg)](https://github.com/MathiasPaulenko/pydepaudit/actions/workflows/ci.yml)
63
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
64
+
65
+ Audit Python dependencies for **known vulnerabilities, license-policy signals,
66
+ release staleness, yanked releases and repository health** in one command.
67
+
68
+ `pydepaudit` complements vulnerability scanners with metadata-driven license and
69
+ maintenance signals. It does not determine whether a package is legally
70
+ compliant or safe to use.
71
+
72
+ ```text
73
+ $ pydepaudit check
74
+
75
+ Package Declared Status Details
76
+ requests 2.31.0 ✅ no CVEs · Apache-2.0 · 8d ago · 157 contributors
77
+ urllib3 1.26.5 ⚠️ GHSA-34jh-... (CVE-2023-43804) | stale 14mo
78
+ some-lib 0.4.1 🔴 copyleft license: GPL-3.0 | single contributor, inactive 24mo
79
+
80
+ 3 findings: 1 high, 2 medium
81
+ ```
82
+
83
+ ## Install
84
+
85
+ ```bash
86
+ pip install pydepaudit
87
+ # or
88
+ pipx install pydepaudit
89
+ ```
90
+
91
+ Requires Python 3.11+.
92
+
93
+ ## Usage
94
+
95
+ ```bash
96
+ pydepaudit check # audit pyproject.toml / requirements.txt / uv.lock
97
+ pydepaudit check --format json # machine-readable output for CI
98
+ pydepaudit check --format sarif # SARIF for GitHub code scanning
99
+ pydepaudit check --fail-on high # exit 1 on findings >= severity
100
+ pydepaudit check --license MIT # declare your project license for compat checks
101
+ pydepaudit check --no-cache # bypass the local HTTP cache
102
+ pydepaudit check --installed # audit the live environment instead
103
+ pydepaudit show requests # details for one dependency
104
+ ```
105
+
106
+ `--fail-on` accepts `low`, `medium`, `high` or `critical`. Ignored dependencies
107
+ do not count toward the threshold.
108
+
109
+ Dependency files are discovered in this order — the first one found wins:
110
+
111
+ 1. `uv.lock` (exact pinned versions)
112
+ 2. `poetry.lock`
113
+ 3. `requirements.txt`
114
+ 4. `pyproject.toml` (PEP 621 dependencies, optional-dependencies and PEP 735 dependency-groups)
115
+
116
+ ## Reports
117
+
118
+ JSON output has a top-level `dependencies` array. Each entry includes the
119
+ declared dependency, status, PyPI metadata, optional `repo_health`, vulnerability
120
+ records (including `fixed` when OSV provides a fixing version), and findings.
121
+ SARIF output follows version 2.1.0 and can be uploaded to GitHub code scanning.
122
+
123
+ ## What it checks
124
+
125
+ | Dimension | Source | Severity logic |
126
+ |---|---|---|
127
+ | Vulnerabilities | [OSV API](https://osv.dev) (`querybatch`) | OSV severity or supported CVSS score |
128
+ | License policy | PyPI metadata | denied alternatives only → high; weak-copyleft without a permissive option → medium; unknown metadata → low |
129
+ | Release age | PyPI release metadata | at least 18 months → medium; at least 12 months → low |
130
+ | Yanked pin | PyPI release metadata | exact pin to a fully yanked release → medium |
131
+ | Repository | GitHub and OpenSSF Scorecard | archived → high; one inactive contributor → medium; inactivity or low Scorecard → low |
132
+
133
+ All data sources are public. GitHub works unauthenticated (60 requests/hour);
134
+ set `GITHUB_TOKEN` for a higher rate limit. The token is sent only to
135
+ `api.github.com`.
136
+
137
+ License checks are heuristic: they compare PyPI license metadata with configured
138
+ substring patterns and recognize simple `OR` alternatives. They are not a full
139
+ SPDX evaluator or legal advice. Review the actual license terms before making a
140
+ compliance decision.
141
+
142
+ ## CI
143
+
144
+ One line in your pipeline:
145
+
146
+ ```yaml
147
+ - run: pydepaudit check --fail-on high
148
+ ```
149
+
150
+ Or use the GitHub Action:
151
+
152
+ ```yaml
153
+ - uses: MathiasPaulenko/pydepaudit@v1.0.0
154
+ with:
155
+ fail-on: high
156
+ ```
157
+
158
+ Or upload findings to GitHub code scanning:
159
+
160
+ ```yaml
161
+ - run: pydepaudit check --format sarif > results.sarif
162
+ - uses: github/codeql-action/upload-sarif@v4
163
+ with: {sarif_file: results.sarif}
164
+ ```
165
+
166
+ Without `--fail-on`, findings alone do not change the exit code. Exit codes:
167
+ `0` unless a finding reaches the selected `--fail-on` threshold;
168
+ `1` when that threshold is reached, no dependency files are found, or the audit
169
+ fails; `2` for invalid arguments or configuration.
170
+
171
+ ## Configuration
172
+
173
+ The project license is autodetected from `pyproject.toml` or `LICENSE`; declare it
174
+ explicitly with `--license` or `project_license` when detection misses.
175
+
176
+ Optional `.pydepaudit.toml` in the project root:
177
+
178
+ ```toml
179
+ stale_months = 12 # low finding past this age
180
+ stale_medium_months = 18 # medium finding past this age
181
+ inactive_months = 12 # repo inactivity threshold
182
+ scorecard_min = 5.0 # low finding below this Scorecard score (0–10)
183
+ project_license = "MIT" # copyleft deps are allowed if this is copyleft
184
+ denied_licenses = ["GPL", "AGPL", "SSPL"]
185
+
186
+ [ignore]
187
+ legacy-lib = "vendored fork, upstream abandoned on purpose"
188
+ ```
189
+
190
+ Month thresholds must be non-negative integers, and
191
+ `stale_medium_months` must be greater than or equal to `stale_months`.
192
+ `scorecard_min` must be between 0 and 10. `[ignore]` suppresses all findings for
193
+ each listed package; keep a reason so the exception is reviewable.
194
+
195
+ ## Cache
196
+
197
+ HTTP responses are cached for one hour in the per-user cache directory, outside
198
+ the audited project. This avoids trusting cache files supplied by a repository.
199
+ Use `--no-cache` to bypass the cache.
200
+
201
+ ## Contributing
202
+
203
+ See [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, test workflow and commit
204
+ conventions. Security issues go to [SECURITY.md](SECURITY.md), never to public
205
+ issues.
206
+
207
+ ## Status
208
+
209
+ Stable 1.0.0 release. See [CHANGELOG.md](CHANGELOG.md) for release notes.
210
+
211
+ ## License
212
+
213
+ MIT