package-doctor 0.1.0__tar.gz

package_doctor-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: The tool reported something wrong, or crashed
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: |
+        If a finding looks wrong, paste the row and what you expected instead.
+
+        Two kinds are especially worth reporting:
+          - a package reported as fine that isn't (a false negative — the worst
+            failure this tool has)
+          - wording that reads as a judgement on a maintainer rather than a
+            description of risk
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Output
+      description: "`package-doctor explain <name>` is usually the most useful thing to paste."
+      render: text
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      placeholder: "package-doctor --version, and your Python version"

package_doctor-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security issue
+    url: https://github.com/binuka200/package-doctor/security/advisories/new
+    about: Please report privately rather than opening a public issue.

package_doctor-0.1.0/.github/ISSUE_TEMPLATE/exposure-map.yml

@@ -0,0 +1,56 @@
+name: Exposure map correction
+description: A package is in the wrong list, or missing from it
+title: "[map] "
+labels: ["exposure-map"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The map is ~710 judgement calls made by one person, so corrections are
+        the most useful thing this project receives.
+
+        Wrong entries matter more than missing ones: a bad entry makes the tool
+        lie, a gap only makes it quieter.
+  - type: input
+    id: package
+    attributes:
+      label: Package name
+      placeholder: e.g. diskcache
+    validations:
+      required: true
+  - type: dropdown
+    id: change
+    attributes:
+      label: What should change?
+      options:
+        - Add it — an attacker can reach this
+        - Remove it — it is not at a trust boundary
+        - Move it — it is in the wrong category
+        - Mark it mature — at a boundary, but finished by design
+    validations:
+      required: true
+  - type: textarea
+    id: reasoning
+    attributes:
+      label: What convinced you?
+      description: |
+        The part that actually matters. Ideally an advisory, a function, or an
+        API that shows the package handling data from outside the trust
+        boundary — or shows that it doesn't.
+
+        Please don't answer "it's popular" or "it sounds security-related".
+        `bandit` is a security scanner, not a target. `xxhash` is not
+        cryptographic. `num2words` has three unfixed advisories that turn out
+        to be a maintainer account compromise rather than anything it does
+        with input.
+      placeholder: |
+        diskcache stores values by pickling them to disk, and
+        GHSA-... says "DiskCache has unsafe pickle deserialization".
+        Anything that can write the cache directory gets code execution.
+    validations:
+      required: true
+  - type: input
+    id: evidence
+    attributes:
+      label: Link to evidence
+      placeholder: https://osv.dev/vulnerability/GHSA-... or a link to the source

package_doctor-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## What this changes
+
+<!-- One or two lines. -->
+
+## Why
+
+<!--
+For exposure map changes, this is the part that gets reviewed. Quote the
+advisory, function or API that convinced you — "adds foo, its load() unpickles
+whatever you hand it, see GHSA-xxxx" takes ten seconds to check.
+
+"It's popular" and "it sounds security-related" are not reasons. See
+CONTRIBUTING.md.
+-->
+
+## Checklist
+
+- [ ] `pytest` passes
+- [ ] Behaviour changes have a test
+- [ ] If this touches the exposure map, the reasoning is above

package_doctor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests research
+      # The suite is offline by design: HTTP is served by httpx.MockTransport,
+      # so a flaky upstream API can never turn into a red build.
+      #
+      # The coverage floor sits just under where the suite is today, to catch a
+      # drop rather than to chase a number. The decision logic - risk, exposure,
+      # sourcescan, osv - is well above it; the gap is mostly presentation.
+      - run: pytest -q --cov=package_doctor --cov-fail-under=85
+
+  # Installs the built wheel, not the editable checkout, and loads the exposure
+  # map from outside the repository. An editable install hides a wheel that is
+  # missing its data file - which is exactly what an over-broad .gitignore once
+  # produced - and this is the only step that would have caught it.
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build --wheel
+      - run: pip install dist/*.whl
+      - run: package-doctor --version
+      - run: cd / && python -c "from package_doctor.exposure import load_exposure_map; load_exposure_map(); print('exposure map loads from the installed wheel')"

package_doctor-0.1.0/.github/workflows/live-contracts.yml

@@ -0,0 +1,28 @@
+name: Live API contracts
+
+# These hit real PyPI, OSV, ecosyste.ms, CISA and FIRST endpoints to catch
+# upstream drift - a renamed field, a changed envelope, a new pagination cap -
+# which unit tests with stubbed transport cannot see.
+#
+# Deliberately NOT part of pull-request CI: four third-party services have no
+# business deciding whether somebody's PR is red. A failure here means the tool
+# is now misreading real data and needs a fix, not that a contributor did
+# anything wrong.
+
+on:
+  schedule:
+    - cron: "17 6 * * 1"   # Mondays, early UTC
+  workflow_dispatch:
+
+jobs:
+  contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      # -rs reports skips, so an outage is visible in the log rather than
+      # looking like a clean pass.
+      - run: pytest -m live -q -rs

package_doctor-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.DS_Store
+# Research output only. Anchored so it cannot match src/package_doctor/data/,
+# which hatchling would otherwise drop from the wheel.
+/data/

package_doctor-0.1.0/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-12
+
+### Added
+
+- Two-axis risk model: a dependency is only escalated when it sits at a trust
+  boundary **and** shows evidence that nobody is left to fix it.
+- Exposure map of ~710 packages across 14 trust-boundary categories, plus
+  reviewed-and-cleared and mature-by-design lists.
+- Advisory history from OSV, read as never-fixed / fixed-late / fixed-timely
+  rather than a naive time-to-fix.
+- Exploitability ranking via CISA KEV and FIRST EPSS, scoped to the pinned
+  version — turns "affected by 35 advisories" into which one to read first.
+- Reachability: AST-parses your own source and reports where each dependency is
+  imported.
+- `scan`, `explain` and `cache` commands, JSON output, `--version`, and
+  `--fail-on` exit codes for CI.
+- Research harness (`research/`) for bulk-scanning PyPI and for deciding what
+  the exposure map should cover next.
+- `requirements/*.txt` is discovered, and `-r` includes are followed within
+  the project, so the pip-tools and Django layouts scan without flags.
+- `explain` says when no pinned version was known and advisory matching was
+  therefore skipped; the version to match is given with `--pin`.
+
+### Fixed
+
+- Advisory ranges are read with OSV's semantics: `last_affected` closes a
+  range inclusively and an `introduced` with no closing event runs to
+  infinity. Only `fixed` was recognised before, so an advisory closed by
+  `last_affected` read as "no published fix" and an open-ended one never
+  matched the pinned version. Across eight real projects that produced 36 of
+  64 *act on these* verdicts, all wrong - Django 6 escalated for a CSRF bug
+  closed at 1.2.7 - and one missed advisory. "Never fixed" now means the
+  latest release is still affected; a range that ends before the latest
+  release with no fix named is reported as closed, not counted either way.
+- GHSA and PYSEC records of the same CVE are merged before counting.
+  cryptography 46.0.7 read as "affected by 7 advisories"; it is four.
+- Import sites are named relative to the project directory rather than to
+  the package directory being walked, so zulip's `analytics/models.py` and
+  `zerver/models.py` no longer both report as `models.py`.
+- The project's own package, uv workspace members, and anything a lockfile
+  records with a local source are skipped and listed as such, instead of
+  being assessed as dependencies. mlflow's report led with mlflow.
+- A wildcard such as `click==8.*` is read as a range, not stored as the
+  version "8.*", which OSV matched against nothing.
+- `requirements/<env>/*.txt` is discovered, one level deep.
+- The scan header and the JSON say how many packages had no pinned version
+  and so had no advisory matching, instead of implying "no advisories".
+- An archived repository with a release inside the stale window is one weak
+  signal, worded "the code may have moved", rather than proof of abandonment.
+  google-cloud-bigquery's archived repo is a monorepo migration.
+
+### Security
+
+- Terminal output strips control and formatting characters, including whole
+  CSI and OSC sequences, from every string that originates outside the
+  process: lockfile versions, scanned file names, API-supplied URLs and
+  advisory ids. `rich` neutralises markup but passes a raw ESC through, so a
+  hostile lockfile could previously wrap a row in a hyperlink to somewhere
+  else or clear the screen.
+- The source scanner and the dependency-file parsers read only regular files,
+  with a bounded read rather than a size check. A FIFO named `evil.py` or a
+  symlink to `/dev/zero` in a scanned checkout previously hung the scan.
+- Dependency files are capped at 32 MB, and a refused file is reported rather
+  than silently treated as empty.
+- Pathologically nested TOML and JSON is treated as malformed. `tomllib`
+  raises `RecursionError`, not `TOMLDecodeError`, on a lockfile a few thousand
+  brackets deep, which previously ended the scan with a traceback.
+- CVE identifiers from OSV aliases are validated against their exact form
+  before being spliced into the EPSS query string.
+- The response cache file is created `0600` before SQLite opens it, rather
+  than tightened afterwards.
+
+### Changed
+
+- PyPI responses are reduced to the fields the tool reads before they are
+  cached: the release timeline collapses to one upload time and one yanked
+  flag per release. The full body was over a megabyte per package on average,
+  which put any lockfile past about 230 packages over the cache's size limit
+  and into a cycle of pruning fresh entries and refetching them. Reduced
+  entries live under a new cache key; old ones expire on their own.
+
+- A response over the size cap is now its own outcome. It was reported as
+  "not found on PyPI", which was untrue, and never cached, so every run
+  re-downloaded the body just to abandon it. It is now reported as too large
+  to read, remembered for the cache lifetime, and the package's advisories
+  are still counted from OSV. PyPI's cap is 64 MB, above the 32 MB default,
+  because its body is reduced the moment it is parsed; the largest today is
+  12.6 MB.
+
+### Measured
+
+On sixty open source repositories (`research/eval-repos.txt`, harness in
+`research/evaluate_repos.py`), 12,973 packages:
+
+- Advisory version matching agrees with OSV's own version-scoped query on
+  6,727 of 6,728 distinct pinned pairs; the one disagreement is a
+  SEMVER-typed range OSV ignores for PyPI and this tool reads.
+- Against `pip-audit` on the same pins: 1,672 vulnerabilities found by both,
+  **zero missed**, one found additionally (the same range).
+- Of 108,193 reported import sites, 108,162 verified against the source line;
+  the rest are pytest's `_pytest` and `py` modules, attributed correctly.
+- Every act verdict resting on a maintenance signal was read; none was found
+  wrong on the tool's stated criteria.
+- Exposure map tested for predictive validity across 3,000 packages: packages it
+  marks exposed carry advisories at ~2.6x the rate of packages it reviewed and
+  cleared.
+
+[Unreleased]: https://github.com/binuka200/package-doctor/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/binuka200/package-doctor/releases/tag/v0.1.0

package_doctor-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,52 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for
+everyone, regardless of age, body size, visible or invisible disability,
+ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behaviour that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility for our mistakes, and learning from them
+- Focusing on what is best for the community
+
+Examples of unacceptable behaviour:
+
+- Sexualised language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## A note specific to this project
+
+This tool makes public statements about whether open source packages are
+maintained. Much of that work is unpaid, and many of the packages it names are
+the work of volunteers who gave what they could.
+
+Discuss packages, not the people who wrote them. "No releases since 2021,
+repository archived" is a fact that helps a user. "This project is dead and the
+maintainer abandoned it" is a judgement about a person, and it is not welcome
+here — in issues, in pull requests, or in the tool's own output.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be
+reported to the maintainer at **contact@binukajayaweera.dev**.
+
+All complaints will be reviewed and investigated promptly and fairly. The
+maintainer is obligated to respect the privacy and security of the reporter.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

package_doctor-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing
+
+Thanks for looking. Most of what this project needs is not code.
+
+## The most useful thing you can do
+
+**Argue with [`exposure.toml`](src/package_doctor/data/exposure.toml).**
+
+That file is ~710 judgement calls about which Python packages sit somewhere an
+attacker can reach. Every one of them was made by one person. Some are wrong,
+and the wrong ones are worse than the missing ones — a bad entry makes the tool
+lie, while a gap only makes it quieter.
+
+If you know a corner of Python well — Django, ML, crypto, async, packaging —
+twenty minutes reading the relevant category is worth more than a month of new
+entries.
+
+### What belongs in the map
+
+A package belongs in a `[category.*]` list when it:
+
+1. parses, decodes, renders, verifies or transports data that commonly comes
+   from outside your trust boundary, **or**
+2. makes an authentication or authorisation decision, **or**
+3. builds queries or commands from caller-supplied values.
+
+### What does not
+
+- **"It's popular."** Not a criterion. `six` is everywhere and belongs nowhere
+  near the map.
+- **"It sounds security-related."** `bandit`, `semgrep` and `pip-audit` are
+  security *tools*, not trust boundaries. `xxhash` and `mmh3` are not
+  cryptographic despite the names.
+- **"It has lots of CVEs."** A reason to look, never the answer. `num2words`
+  has three advisories with no fix — and reading them shows a maintainer
+  account compromise, not anything the library does with input. It is in
+  `[reviewed] not_exposed` for exactly that reason.
+
+**Read the advisories before deciding.** Several entries look harmless from
+their one-line description and turn out to be textbook: `diskcache` is "a disk
+cache" whose advisories say *unsafe pickle deserialization*; `apscheduler` is
+"a task scheduler" whose serializers had remote code execution.
+
+### The three lists
+
+| list | meaning |
+| --- | --- |
+| `[category.*]` | an attacker can reach this |
+| `[reviewed] not_exposed` | checked, and they can't — with a note saying why the obvious guess is wrong |
+| `[stable] mature` | they can, but the library is finished, so ignore its age |
+
+The second list matters as much as the first. It is how "we checked and it's
+fine" stays distinguishable from "nobody has looked", which is a distinction the
+rest of the tool is built on.
+
+### Finding something worth deciding
+
+```bash
+package-doctor scan . --json -o scan.json
+python research/suggest_map.py --scan scan.json
+```
+
+That ranks the packages the map has no opinion about by how much the silence
+costs, and prints what each one is for. Working the top of that list beats
+reading down a popularity ranking.
+
+### Opening the PR
+
+One category change per PR where you can, and say **why** in the description —
+ideally quoting the advisory or the API that convinced you. "Adds `foo`" is hard
+to review; "adds `foo`, its `load()` unpickles whatever you hand it, see
+GHSA-xxxx" takes ten seconds.
+
+## Code
+
+```bash
+git clone https://github.com/binuka200/package-doctor
+cd package-doctor
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                 # offline, ~1s
+pytest -m live         # hits the real APIs; opt-in, not run in PR CI
+ruff check src tests research
+```
+
+The suite is offline by design — HTTP is served by `httpx.MockTransport`, so no
+upstream outage can redden a build. CI enforces 85% coverage and a clean
+`ruff check`; the rule set is in `pyproject.toml` and is deliberately small.
+
+### Principles worth knowing before you change behaviour
+
+These are load-bearing, and there are tests asserting each of them:
+
+- **Missing data is never a bad score.** No advisory history means *unknown*,
+  not *healthy*. No repository declared means *unknown*, not *abandoned*. If you
+  find code that turns a null into a zero, that's a bug.
+- **Release age alone never produces a finding.** It cannot tell an abandoned
+  library from a finished one. Two weak signals must agree, or one
+  authoritative signal must fire.
+- **A guess can never demand action.** An inferred category can raise something
+  to *watch*; only a curated one can reach *act on this*.
+- **There is no aggregate health score, and there should not be.** A single
+  number is the thing users can't act on and maintainers can't argue with.
+
+### Research scripts
+
+`research/` holds the instruments used to study the ecosystem, not the product.
+They write to `data/`, which is gitignored. Run `bulk_scan.py` before
+`analyse.py` or `suggest_map.py --dataset`.
+
+## Reporting a problem
+
+A finding that reads as a judgement on a maintainer rather than a description of
+risk **is a bug** — please report it. Most unmaintained packages are the work of
+volunteers who gave what they could, and the tool's wording should reflect that.
+
+For anything security-sensitive, see [SECURITY.md](SECURITY.md).

package_doctor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Binuka Jayaweera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.