pkgwhy 1.8.0 includes safe metadata extraction, static evidence hardening, vulnerability/provenance foundations, static rule corpus/schema hardening, release/process hardening, a safe-fail experimental dynamic command skeleton, agent policy foundations, local pre-install and pip install gates, local policy files, review history, reports, CI package gates, local registry trust states, local tool validation, agent check dispatching, and local registry/runner hardening. It is not a production malware scanner and should not be treated as a definitive malware detector or full sandbox.

For non-sensitive security bugs or documentation issues, use GitHub Issues:

https://github.com/devlukeg/pkgwhy/issues

For sensitive security reports, use GitHub private vulnerability reporting if it is enabled for the public repository. If it is not enabled, contact the maintainer privately through the contact channel listed on the project or repository profile before sharing exploit details.

Sensitive details should be reported privately. Public issues are appropriate for non-sensitive coordination only.

Public issues should not include secrets, private package contents, or credentials.

pkgwhy uses static, metadata-first inspection. Package inspection reads metadata, files, text, and AST without importing or executing inspected package code.

pkgwhy metadata reads package metadata from installed distributions, metadata directories, metadata files, wheels, source archives, development checkouts, and pyproject.toml without importing packages, executing packages, running setup.py, or evaluating metadata. Archive metadata reads are bounded and path-traversal guarded. Metadata extraction is not a safety verdict.

Capability analysis reports static signals such as API references, package files, and entry points. These signals are not proof of runtime behavior, intent, or maliciousness.

Static rule evidence can include rule IDs, severity, confidence, file paths, line numbers, symbols, and false-positive notes where available. URL/domain references, native extensions, WASM files, minified JavaScript, source-map references, and credential-like names are review evidence only. They are not proof that code connects to a network, contains a real secret, or is malicious.

Credential-pattern reporting masks suspicious assignment values before output. pkgwhy is not a substitute for dedicated secret-scanning tools in repository and release gates.

Known-vulnerability analysis is source-attributed decision support. Local OSV-like files, explicit OSV.dev queries, and cached OSV responses can be incomplete, stale, unavailable, or missing ecosystem-specific details. A missing vulnerability match does not prove that a package has no vulnerabilities.

Provenance analysis is currently metadata-derived. Repository, documentation, homepage, release-activity, and source-distribution fields are reported only when available from installed metadata or optional PyPI JSON payloads. Trusted Publishing and attestation verification are not implemented and must be treated as unknown or not implemented.

pkgwhy run is a separate local private-tool execution feature. It intentionally executes local private tool code only after resolving a valid local registry entry, verifying the stored bundle hash, and applying policy checks. This execution path is separate from package inspection and does not mean package inspection imports or executes inspected package code.

The local runner blocks missing or hash-mismatched bundles, corrupt registry indexes, unsupported entrypoints, declared dependencies, and non-interactive runs that are not allowed by both judgement and manifest policy. It uses a Python virtual environment for dependency isolation only; it does not provide OS-level filesystem, network, process, or user permission sandboxing.

Local registry publishing blocks duplicate owner/name/version records and rejects symlinks in tool bundles. Registry-stored manifest and bundle paths must resolve inside the registry root.

Local registry trust states are local policy labels. New tools default to unknown. trusted and reviewed are human-maintained labels, not cryptographic verification. They do not override hash mismatch, unsigned-tool warnings, manifest approval requirements, or static capability signals. quarantined and blocked tools return blocking tool judgements and are refused by the local runner before execution.

pkgwhy tool validate <path> is a non-executing local validation command for private-tool authors. It reads local manifests and files, checks entrypoint path boundaries, reports unsupported paths such as symlinks, validates declared permission labels, and runs static capability analysis. It does not write to a registry and does not execute tool code.

Pre-install package gate commands are decision support. pkgwhy precheck <package> --json checks package requirements before installation and can optionally query PyPI/OSV or download artifacts only when explicit flags request that work. Artifact precheck downloads to a temporary review directory, verifies SHA-256 when PyPI metadata provides it, statically inspects files, and deletes temporary files by default. It does not install, import, or execute inspected package code.

Pip install gate commands are also decision support. pkgwhy pip install <package> and pkgwhy pip install -r requirements.txt run precheck before invoking pip. Pip is invoked only when policy allows or when a human uses an explicit override flag. The gate logs compact local decision summaries when possible, but those logs are not tamper-proof audit records. The pip gate does not sandbox pip, installed package code, build backends, or install-time behavior.

CI templates are local workflow scaffolding. They install and run the local pkgwhy CLI, write reports, and optionally fail jobs based on configured mode. They do not contact a hosted pkgwhy service, provide a cloud review, or require secrets for basic use.

Local policy, review history, reports, and pkgwhy ci are filesystem-backed features. They may be useful for local audit trails and team workflows, but they are not tamper-proof audit logs and they do not imply hosted review, cloud sync, account management, or remote policy enforcement.

Commercial and agent platform documentation is roadmap-only. The current release does not configure hosted review, billing, payment providers, API keys, cloud services, remote policy enforcement, or shared accounts.

Agent policy commands are decision support. pkgwhy agent precheck <package> --json applies conservative policy to package judgement JSON and defaults to blocking unknown or high-risk package use in non-interactive mode until a human reviews the evidence. pkgwhy agent check <target> --json dispatches package specs, requirements files, pyproject-style TOML files, and local tool folders/scripts to existing local checks and returns one normalized decision envelope. Agent decision logs are local compact summaries, best-effort when the config directory is writable, and intentionally omit full package evidence. They are not a tamper-proof audit system.

Runner warning:

This run uses a Python virtual environment for dependency isolation. It does not fully sandbox operating-system permissions.

Dynamic analysis is a separate experimental roadmap area and is not part of the stable security decision surface in this release. Dynamic analysis intentionally executes code, so unknown package code is not run on the host. The current pkgwhy dynamic inspect command is a safe-fail skeleton: it reports that no sandbox backend is available or that execution is blocked, and refuses to execute the target. Future dynamic analysis is expected to be opt-in, use a disposable sandbox boundary, disable network access by default, use temporary scratch filesystem access by default, avoid host secrets, and fail safely if the requested sandbox backend is unavailable. Empty process, filesystem, or network event lists should not be treated as proof that no behavior occurred.

• No complete vulnerability database coverage, guaranteed advisory freshness, or transitive vulnerability analysis yet.
• OSV.dev lookup is optional and must be explicitly requested. Cached OSV responses are stale fallback data, not freshness guarantees.
• Trusted Publishing and attestation verification are not implemented yet.
• Full source distribution versus wheel comparison is not implemented yet.
• No runner dependency installation yet.
• No tool bundle signing or signature verification yet.
• No tool lock/verify commands or registry export/import yet.
• No tamper-proof audit log, remote attestation, or signed decision record yet.
• No sandboxed pip execution; pkgwhy pip install is a policy gate before pip, not an installer sandbox.
• No full tool-specific agent judgement beyond local tool validation and registry tool judgement yet.
• No cloud registry, remote pull, hosted review API, or account-based registry auth yet.
• Typosquatting detection is heuristic and conservative. It can miss risky names and can surface false positives.
• Static URL/domain and credential-pattern extraction is heuristic. It can miss references and can surface documentation, examples, tests, or placeholders.
• JavaScript minification and native/WASM files are not automatically malicious, and static analysis cannot fully explain compiled or generated artifacts.
• No OS-level sandboxing or production dynamic sandbox in this release.
• No cloud review or remote evidence lookup in the current release.
• No guarantee that every risky behavior can be detected statically.

This repository should not contain PyPI tokens, cloud credentials, registry signing keys, or payment-provider secrets.

See also Threat Model, Release Checklist, and Production Readiness Blockers.