ghostpkg 0.1.0__tar.gz

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

@@ -0,0 +1,24 @@
+name: Bug
+description: Something crashed or behaved incorrectly
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Command you ran
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: ghostpkg version and OS
+      placeholder: "0.1.0, Windows 11, Python 3.12"
+    validations:
+      required: true

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

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/M1rwana12/ghostpkg/security/advisories/new
+    about: Please report security issues privately, not as a public issue.

ghostpkg-0.1.0/.github/ISSUE_TEMPLATE/false-positive.yml

@@ -0,0 +1,40 @@
+name: False positive
+description: ghostpkg flagged a package that is actually fine
+labels: ["false-positive", "bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This is the most valuable report you can file. A tool that cries wolf on
+        real packages gets turned off, and then it protects nothing.
+  - type: input
+    id: package
+    attributes:
+      label: Package name
+      placeholder: some-real-package
+    validations:
+      required: true
+  - type: dropdown
+    id: ecosystem
+    attributes:
+      label: Ecosystem
+      options: [pypi, npm]
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Output
+      description: Paste the full output, ideally from `ghostpkg check <name> --json`.
+      render: shell
+    validations:
+      required: true
+  - type: checkboxes
+    id: strict
+    attributes:
+      label: Were you using --strict?
+      description: >
+        --strict promotes warnings to blocks and is documented as flagging
+        legitimate new packages. That behaviour is expected.
+      options:
+        - label: I was NOT using --strict

ghostpkg-0.1.0/.github/ISSUE_TEMPLATE/missed-package.yml

@@ -0,0 +1,30 @@
+name: Missed detection
+description: ghostpkg passed a package it should have caught
+labels: ["missed-detection"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Note the known limitation first: a hallucinated name that an attacker has
+        **already registered** passes the existence check by design. That case is
+        tracked as the project's main open problem — but concrete examples are
+        still very useful, so please file it.
+  - type: input
+    id: package
+    attributes:
+      label: Package name
+    validations:
+      required: true
+  - type: dropdown
+    id: ecosystem
+    attributes:
+      label: Ecosystem
+      options: [pypi, npm]
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: Why should it have been caught?
+    validations:
+      required: true

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

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.9", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+      - name: CLI smoke test
+        run: |
+          ghostpkg --version
+          ghostpkg check requests

ghostpkg-0.1.0/.gitignore

@@ -0,0 +1,69 @@
+# --- Secrets: never commit credentials ---
+# Token/credential files
+*.token
+*.secret
+*.key
+*.pem
+*.pfx
+*.p12
+.env
+.env.*
+!.env.example
+secrets.*
+credentials.*
+auth.json
+hosts.yml
+.netrc
+_netrc
+
+# gh / git credential stores (should never be here, blocked defensively)
+.config/gh/
+.gh/
+.git-credentials
+
+# --- Windows ---
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+*.lnk
+
+# --- Editors / IDE ---
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# --- Build / temp ---
+dist/
+build/
+out/
+tmp/
+temp/
+*.log
+*.tmp
+*.bak
+
+# --- Language ecosystems ---
+node_modules/
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+target/
+
+# --- Local scratch (never published) ---
+scratch/
+.local/
+
+# Internal planning document -- deliberately not published.
+# It is the portfolio strategy doc, not part of this tool.
+PLAN.md
+
+# Playwright MCP scratch output
+.playwright-mcp/
+
+# Banner art-direction options (working files, not shipped)
+banner-options/

ghostpkg-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-01
+
+First release.
+
+### Added
+- `ghostpkg check` — check one or more package names against PyPI or npm.
+- `ghostpkg scan` — check every dependency in `requirements.txt` or `package.json`.
+- Verdicts: `BLOCK` for names absent from the registry, `WARN` for weak signals
+  (recent publication, single release, missing repository link, small edit
+  distance to a popular name), `OK` otherwise.
+- `--strict` to promote warnings to blocks, `--json` for machine-readable output,
+  `-q/--quiet` to hide passing packages.
+- Exit codes: `0` nothing blocked, `1` something blocked, `2` usage or registry
+  error.
+- Bundled list of the 2,000 most-downloaded PyPI projects, used only for typo
+  distance.
+
+### Notes on the design
+- The default profile blocks on **non-existence only**. An earlier version scored
+  packages and blocked anything suspicious; measured against the live feed of
+  newly published PyPI packages, it flagged 100% of legitimate same-day
+  publications. Age cannot separate a malicious registration from an honest new
+  release, so softer signals are warnings.
+- The typo-distance budget scales with name length. A flat budget flagged `flask`,
+  `click` and `black` as typos of one another.
+- Zero runtime dependencies, by policy.
+- No corpus of hallucinated package names is shipped, following the decision of
+  the USENIX'25 authors not to publish theirs.
+
+[Unreleased]: https://github.com/M1rwana12/ghostpkg/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/M1rwana12/ghostpkg/releases/tag/v0.1.0

ghostpkg-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to ghostpkg
+
+Thanks for looking. This is a small, deliberately narrow tool, and the bar for
+changes is mostly about keeping it that way.
+
+## Getting set up
+
+```bash
+git clone https://github.com/M1rwana12/ghostpkg
+cd ghostpkg
+pip install -e ".[dev]"
+pytest
+```
+
+The test suite constructs `PackageFacts` directly and never touches the network,
+so it runs offline and cannot break because a real package changed.
+
+## The two rules that shape this project
+
+**1. No runtime dependencies.** A supply-chain security tool that installs a
+dependency tree of its own undermines its own argument. Standard library only.
+A pull request that adds a runtime dependency will be declined regardless of how
+useful the dependency is.
+
+**2. A false positive is worse than a miss.** People run this in front of every
+install. If it cries wolf on a legitimate package, they turn it off, and then it
+protects nothing.
+
+That second rule is not a preference, it's a measurement. The first version of
+this tool scored packages on age, release count and missing repository links,
+then blocked anything suspicious. Tested against the live feed of newly published
+PyPI packages, it flagged **100% of them**. A malicious slopsquat registered
+three days ago and an honest new library published three days ago are the same
+package from the outside.
+
+So: the default profile blocks on non-existence only. If you want to propose a
+new blocking signal, bring evidence that it does not fire on legitimate packages.
+
+## Especially welcome
+
+- **False positive reports.** If `ghostpkg` flagged something real, that's a bug
+  and it's the most valuable report you can file.
+- **The open problem:** detecting a hallucinated name that an attacker has
+  *already registered*. The existence check cannot see it. If you have an idea
+  that does not collapse into "block everything new", open an issue.
+- npm coverage. The popular-name list used for typo distance is PyPI-derived, so
+  npm typosquat detection is weaker than it should be.
+- More ecosystems: crates.io, RubyGems, Go modules.
+
+## Please don't
+
+- **Do not add a corpus of hallucinated package names to this repository.** The
+  authors of the USENIX'25 study withheld theirs deliberately, because such a
+  list is a ready-made target list for attackers pre-registering those names.
+  That reasoning applies here. This project checks names live and ships no corpus.
+- Don't broaden the scope into code scanning or malware detection. Other tools do
+  that well.
+
+## Style
+
+Match the surrounding code. Type hints on public functions, `from __future__
+import annotations` at the top of each module (the package supports Python 3.9).
+Comments explain *why*, not *what* — several comments in `assess.py` record the
+measurement behind a decision, and that is the kind worth writing.
+
+## Pull requests
+
+Keep them focused. Add a test. CI runs on Linux, macOS and Windows across Python
+3.9, 3.12 and 3.13, and it needs to be green.

ghostpkg-0.1.0/LICENSE

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