pkgwhy 1.0.0__tar.gz

pkgwhy-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+pip-wheel-metadata/

pkgwhy-1.0.0/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+## 1.0.0 - 2026-06-30
+
+- Promote the `1.0.0rc1` release-candidate surface to the final 1.0.0 tracked codebase after local release-prep review.
+- Freeze the 1.0.0 feature surface for package intelligence, static rule evidence, vulnerability/provenance decision support, agent policy JSON, local registry/runner safety, and release-process documentation.
+- Keep dynamic analysis explicitly experimental and outside the stable security decision surface for this release.
+- Align README, SECURITY, package metadata, and version metadata for final local `1.0.0` validation.
+- Harden release validation with artifact trace scanning, cache metadata validation, Markdown audit warnings, hermetic JSON snapshots, and exact rule catalog membership tests.
+- Align final release wording and package classifier for local 1.0.0 hardening.
+- Harden final review checks for offline-first documentation, trace path matching, dynamic boundary wording, Markdown escaping, static corpus import traps, and rule-category ordering.
+
+## 0.9.5a0 - Unreleased pre-alpha
+
+- Add release checklist, versioning policy, threat model, and production-readiness blocker documentation.
+- Improve public responsible disclosure guidance without configuring external services or secrets.
+- Link release/process documentation from README, SECURITY, and CONTRIBUTING.
+- Add CI CLI smoke checks and public trace hygiene scanning without publishing secrets or deployment steps.
+- Align local package metadata for the `0.9.5a0` release/process hardening candidate.
+
+## 0.9.0a0 - Unreleased pre-alpha
+
+- Keep dynamic analysis experimental for this release, with no production sandboxing claim.
+- Keep `pkgwhy dynamic inspect` as a safe-fail CLI skeleton that refuses host execution of unknown package code and does not invoke Docker or run containers.
+- Add tests that assert the dynamic result warnings and limitations carry the explicit experimental boundary.
+- Align README, SECURITY, CLI help, and local package metadata for the `0.9.0a0` dynamic-analysis boundary.
+
+## 0.8.0a0 - Unreleased pre-alpha
+
+- Start static rule corpus/schema hardening with a versioned static rule catalog snapshot.
+- Add stable rule ID ordering helpers and tests to catch accidental rule renames, removals, or reordering.
+- Add static rule corpus documentation covering rule categories, rule families, fixture strategy, and compatibility expectations.
+- Add controlled Python static-signal corpus fixtures for dynamic execution, dynamic imports, deserialisation, encoded payloads, subprocess/package-manager use, environment access, URL/domain extraction, and credential masking.
+- Add controlled JavaScript, native, WASM, shell, and build-file corpus fixtures with false-positive coverage for JavaScript call-like substrings.
+- Add normalized golden JSON snapshot tests and schema compatibility policy documentation for agent-facing package, audit, precheck, and tool judgement output.
+- Document static rule ID lifecycle, evidence location expectations, corpus fixture coverage, and false-positive/false-negative limitations.
+- Harden OSV response decoding, audited-version PyPI provenance status, rule catalog snapshots, and JSON/static corpus regression tests.
+
+## 0.7.0a0 - Unreleased pre-alpha
+
+- Harden explicit OSV.dev audit lookups with a local response cache, stale-cache fallback, cache status warnings, and continued offline-by-default behavior.
+- Keep vulnerability matching conservative by treating OSV `limit` events as upper bounds, not fixed-version recommendations.
+- Add advisory source URL evidence to known-vulnerability matches and audit-level vulnerability/provenance source summaries.
+- Bump audit JSON output to `pkgwhy.audit.v2` for the expanded source summary fields.
+- Add optional `pkgwhy audit --pypi` provenance lookup from PyPI JSON without inferring Trusted Publishing or attestation status.
+- Report PyPI source distribution presence only when PyPI file metadata actually lists a source archive.
+- Add tests for OSV parsing, matching, caching, source attribution, PyPI provenance, and audit integration.
+- Document that cached advisory data can be stale and that missing vulnerability matches are not proof of safety.
+
+## 0.6.0a0 - Unreleased pre-alpha
+
+- Add schema-versioned agent policy defaults with conservative non-interactive decisions for package use.
+- Add `pkgwhy agent policy`, `pkgwhy agent precheck <package> --json`, and package-focused `pkgwhy agent judge <package> --json`.
+- Add schema-versioned agent package precheck output that embeds the package judgement and records policy reasons.
+- Add compact local agent decision logs that omit full package evidence.
+- Harden local registry publish and judgement paths by failing closed on corrupt registry indexes.
+- Block duplicate owner/name/version publishes instead of silently replacing existing registry entries.
+- Reject symlinked tool bundle members during local publish and keep stored registry paths bounded to the registry root during tool judgement.
+- Add `pkgwhy run --non-interactive` to apply stricter tool execution policy from the CLI.
+- Include successful pre-run policy decision, reasons, and warnings in local tool execution logs.
+- Continue to treat signatures as `not_implemented` and virtual environments as dependency isolation only, not OS sandboxing.
+
+## 0.5.0a0 - Unreleased pre-alpha
+
+- Start the experimental dynamic sandbox design phase without enabling arbitrary dynamic package execution.
+- Add a dynamic sandbox threat model covering static-vs-dynamic boundaries, no-host-execution defaults, network-off defaults, scratch filesystem expectations, no-secrets constraints, event model goals, and current limitations.
+- Add a safe-fail `pkgwhy dynamic inspect` command skeleton that refuses host execution until a sandbox backend exists.
+- Add schema-versioned dynamic analysis result models with empty event lists unless a backend actually observes events.
+- Add controlled fixture-only dynamic execution test support that runs only local test fixtures under a fixture root with a scratch working directory and minimal environment.
+- Add a Docker executable detection boundary for the future container backend without invoking Docker or running containers.
+- Document that missing sandbox backends must fail safely rather than falling back to host execution.
+
+## 0.4.0a0 - Unreleased pre-alpha
+
+- Add stronger static-analysis rule evidence while keeping `pkgwhy` in pre-alpha decision-support positioning.
+- Add structured file/line/symbol evidence for Python dynamic execution, dynamic imports, deserialisation-risk APIs, unsafe YAML load, encoded-payload handling, subprocess/shell execution, environment/secret-like references, and package-manager manipulation.
+- Add static setup/build-file analysis for `setup.py`, `setup.cfg`, and `pyproject.toml` build-backend metadata without running build scripts.
+- Add source URL/domain extraction as evidence only, with explicit false-positive notes.
+- Add conservative credential-like assignment detection with suspicious values masked in output.
+- Add JavaScript rule evidence for minification/density, dynamic execution, encoded-payload handling, source-map references, and obfuscation-like patterns.
+- Add native extension, executable, and WASM binary rule evidence while documenting that these artifacts are not automatically malicious.
+- Surface compact rule-evidence summaries in human `inspect`, `risk`, and `judge` output while preserving schema-versioned JSON judgement output.
+
+## 0.3.0a0 - Unreleased pre-alpha
+
+- Add a vulnerability/provenance/risk-model foundation while keeping `pkgwhy` in pre-alpha decision-support positioning.
+- Add OSV-like vulnerability record models, parser, explicit OSV.dev client boundary, and conservative version-range matching.
+- Add optional `pkgwhy audit --vulnerability-file` support for controlled local advisory data and explicit `pkgwhy audit --osv` support for live OSV.dev lookup.
+- Add metadata-derived provenance/source-trust summaries to package judgement JSON, with Trusted Publishing, attestation verification, and sdist/wheel comparison marked as unknown or not implemented.
+- Add `pkgwhy.risk_model.v1`, rule IDs, rule severity, confidence, and evidence fields to package judgement JSON.
+- Document that vulnerability databases can be incomplete and that missing vulnerability matches are not proof of safety.
+
+## 0.2.0a0 - Unreleased pre-alpha
+
+- Prepare the first PyPI/TestPyPI developer-preview candidate with the local registry and runner MVP included.
+- Add GitHub repository, homepage, issue, and changelog metadata for `https://github.com/devlukeg/pkgwhy`.
+- Start local package intelligence foundation with `scan`, `explain`, `why`, `inspect`, and `judge --json`.
+- Add metadata-first inspection, package-size scanning, AST-only Python capability signals, dependency classification, and conservative judgement models.
+- Add local registry, local publish, local tool inspect/judge, and local `pkgwhy run` MVP with hash verification, per-tool virtual environments, execution logs, and explicit non-sandboxing warning.
+- Add initial local tool execution policy checks for hash verification, non-interactive defaults, unsupported execution modes, unsigned-tool warnings, and deferred dependency installation.
+- Document that results are static evidence and decision support, not proof of package safety or malware certainty.

pkgwhy-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+`pkgwhy` is in the 1.0.0 release line. Small, focused issues and pull requests are easiest to review.
+
+## Development Setup
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+## Engineering Expectations
+
+- Inspection code should read metadata, package files, text, and AST without importing or executing inspected package code.
+- Keep inspection paths separate from the explicit `pkgwhy run` execution path for local private tools.
+- Keep agent policy decisions separate from package inspection and local tool execution.
+- Prefer static metadata, file, text, and AST analysis.
+- Use conservative security language.
+- Malware, source availability, vulnerability, risk, signature, hash, and review claims should be backed by evidence from the implementation or the cited source.
+- Full sandboxing should be described only for isolation that is actually implemented and tested.
+- Keep JSON output stable for agent workflows.
+- Keep release, publishing, repository visibility, and distribution changes out of ordinary feature pull requests.
+
+## Before Submitting Changes
+
+Run:
+
+```bash
+.venv/bin/python -m pytest
+git diff --check
+.venv/bin/python -m pkgwhy --help
+.venv/bin/python -m pkgwhy agent policy --help
+.venv/bin/python -m pkgwhy registry --help
+.venv/bin/python -m pkgwhy run --help
+.venv/bin/python -m build
+.venv/bin/python -m twine check dist/*
+```
+
+For release work, also follow [docs/release-checklist.md](docs/release-checklist.md), [docs/versioning-policy.md](docs/versioning-policy.md), and [docs/production-readiness.md](docs/production-readiness.md).
+
+Publishing automation, external services, payment processing, secrets, and cloud backends are not included in this release line.
+
+Repository: <https://github.com/devlukeg/pkgwhy>
+
+Issues: <https://github.com/devlukeg/pkgwhy/issues>

pkgwhy-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Luke Gerakiteys
+
+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.
+