slopsentry 0.1.0__py3-none-any.whl

slopsentry/__init__.py

@@ -0,0 +1,3 @@
+"""SlopSentry: check packages for slopsquatting before installing them."""
+
+__version__ = "0.1.0"

slopsentry/checks/__init__.py

@@ -0,0 +1,3 @@
+"""Checks: each returns (status, detail, points)."""
+
+CheckResult = tuple[str, str, int]

slopsentry/checks/age.py

@@ -0,0 +1,74 @@
+"""Flag packages that look freshly registered: young, few releases, no project links."""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from slopsentry.checks import CheckResult
+from slopsentry.registry import PyPIClient, RegistryError
+
+NEW_PACKAGE_DAYS = 90
+FEW_RELEASES = 2
+
+NEW_POINTS = 40
+FEW_RELEASES_POINTS = 20
+NO_LINKS_POINTS = 20
+
+
+def _parse_time(value: str) -> datetime:
+    # Python 3.10's fromisoformat doesn't accept the "Z" suffix PyPI uses.
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    return datetime.fromisoformat(value)
+
+
+def _upload_times(project: dict[str, Any]) -> list[datetime]:
+    return [
+        _parse_time(f["upload_time_iso_8601"])
+        for files in (project.get("releases") or {}).values()
+        for f in files
+        if f.get("upload_time_iso_8601")
+    ]
+
+
+def _has_links(info: dict[str, Any]) -> bool:
+    return bool(info.get("home_page")) or any((info.get("project_urls") or {}).values())
+
+
+async def check_age(name: str, client: PyPIClient, now: datetime | None = None) -> CheckResult:
+    try:
+        project = await client.get_project(name)
+    except RegistryError as exc:
+        return ("error", str(exc), 0)
+    if project is None:
+        return ("skip", "not found on PyPI", 0)
+    # PyPI has deprecated `releases` in this endpoint. Absent means unknown, not new.
+    if "releases" not in project:
+        return ("skip", "release history unavailable", 0)
+
+    now = now or datetime.now(timezone.utc)
+    findings: list[str] = []
+    points = 0
+
+    uploads = _upload_times(project)
+    if not uploads:
+        findings.append("no released files")
+        points += NEW_POINTS
+    else:
+        age_days = (now - min(uploads)).days
+        if age_days < NEW_PACKAGE_DAYS:
+            findings.append(f"first release {age_days} days ago")
+            points += NEW_POINTS
+
+    releases = sum(1 for files in (project.get("releases") or {}).values() if files)
+    if releases <= FEW_RELEASES:
+        findings.append(f"only {releases} release{'s' if releases != 1 else ''}")
+        points += FEW_RELEASES_POINTS
+
+    if not _has_links(project.get("info") or {}):
+        findings.append("no homepage or repository link")
+        points += NO_LINKS_POINTS
+
+    if findings:
+        return ("warn", "; ".join(findings), points)
+    first = min(uploads).date().isoformat()
+    return ("pass", f"first released {first}, {releases} releases, has project links", 0)

slopsentry/checks/exists.py

@@ -0,0 +1,17 @@
+"""Check that a package exists on PyPI."""
+
+from slopsentry.checks import CheckResult
+from slopsentry.registry import PyPIClient, RegistryError
+
+MISSING_POINTS = 100
+
+
+async def check_exists(name: str, client: PyPIClient) -> CheckResult:
+    try:
+        project = await client.get_project(name)
+    except RegistryError as exc:
+        return ("error", str(exc), 0)
+
+    if project is None:
+        return ("fail", "not found on PyPI", MISSING_POINTS)
+    return ("pass", "found on PyPI", 0)

slopsentry/checks/lookalike.py

@@ -0,0 +1,126 @@
+"""Flag names that look like a popular PyPI package: typos, separators and affixes."""
+
+import json
+from dataclasses import dataclass, field
+from functools import cache
+from importlib.resources import files
+
+from slopsentry.checks import CheckResult
+from slopsentry.checks.age import check_age
+from slopsentry.registry import PyPIClient, normalize_name
+
+LOOKALIKE_POINTS = 50
+# An established package (age check passes cleanly) that resembles a popular one is most
+# likely a legitimate neighbour, e.g. simpy/sympy: shown, but not enough to warn alone.
+ESTABLISHED_LOOKALIKE_POINTS = 15
+
+# Edit distance allowed: 1, or 2 for names longer than LONG_NAME characters.
+LONG_NAME = 10
+# Guard 1: names shorter than this get no edit-distance matching (od/id, sax/six).
+MIN_EDIT_LENGTH = 5
+
+PREFIXES = ("py-", "python-")
+SUFFIXES = ("-py", "-python", "-lib")
+
+
+@dataclass(frozen=True)
+class PopularIndex:
+    names: tuple[str, ...]  # normalised, most downloaded first
+    rank: dict[str, int] = field(init=False)
+    squashed: dict[str, list[str]] = field(init=False)
+
+    def __post_init__(self) -> None:
+        rank = {name: i for i, name in enumerate(self.names)}
+        squashed: dict[str, list[str]] = {}
+        for name in self.names:
+            squashed.setdefault(name.replace("-", ""), []).append(name)
+        object.__setattr__(self, "rank", rank)
+        object.__setattr__(self, "squashed", squashed)
+
+
+def popular_index(names: list[str]) -> PopularIndex:
+    return PopularIndex(tuple(normalize_name(n) for n in names))
+
+
+@cache
+def bundled_index() -> PopularIndex:
+    data = files("slopsentry.data").joinpath("top_pypi.json").read_text(encoding="utf-8")
+    return PopularIndex(tuple(json.loads(data)["packages"]))
+
+
+def edit_distance(a: str, b: str, limit: int) -> int:
+    """Damerau-Levenshtein (optimal string alignment) distance, or limit + 1 if over limit."""
+    if abs(len(a) - len(b)) > limit:
+        return limit + 1
+    before: list[int] = []
+    prev = list(range(len(b) + 1))
+    for i in range(1, len(a) + 1):
+        cur = [i] + [0] * len(b)
+        for j in range(1, len(b) + 1):
+            cur[j] = min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] != b[j - 1]))
+            if i > 1 and j > 1 and a[i - 1] == b[j - 2] and a[i - 2] == b[j - 1]:
+                cur[j] = min(cur[j], before[j - 2] + 1)
+        if min(cur) > limit:
+            return limit + 1
+        before, prev = prev, cur
+    return prev[-1]
+
+
+def _one_segment_differs(a: str, b: str) -> bool:
+    """Guard 2: family members like mypy-boto3-emr and mypy-boto3-ec2."""
+    sa, sb = a.split("-"), b.split("-")
+    return len(sa) == len(sb) > 1 and sum(x != y for x, y in zip(sa, sb, strict=True)) == 1
+
+
+def _affix_variants(name: str) -> set[str]:
+    """Names reachable by removing or adding one common affix."""
+    variants = {name[len(p) :] for p in PREFIXES if name.startswith(p)}
+    variants |= {name[: -len(s)] for s in SUFFIXES if name.endswith(s)}
+    variants |= {p + name for p in PREFIXES} | {name + s for s in SUFFIXES}
+    return {v for v in variants if v and v != name}
+
+
+def find_lookalike(name: str, index: PopularIndex) -> str | None:
+    """Return the popular package NAME most resembles, or None. NAME must not be popular."""
+    name = normalize_name(name)
+    # (distance, rank, target): separator and affix matches count as distance 0.
+    matches: list[tuple[int, int, str]] = []
+
+    for target in index.squashed.get(name.replace("-", ""), []):
+        if target != name:
+            matches.append((0, index.rank[target], target))
+    for target in _affix_variants(name):
+        if target in index.rank:
+            matches.append((0, index.rank[target], target))
+
+    if len(name) >= MIN_EDIT_LENGTH:
+        limit = 2 if len(name) > LONG_NAME else 1
+        for target in index.names:
+            if abs(len(target) - len(name)) > limit:
+                continue
+            distance = edit_distance(name, target, limit)
+            if distance > limit:
+                continue
+            if distance == 2 and _one_segment_differs(name, target):
+                continue
+            matches.append((distance, index.rank[target], target))
+
+    return min(matches)[2] if matches else None
+
+
+async def check_lookalike(
+    name: str, client: PyPIClient, index: PopularIndex | None = None
+) -> CheckResult:
+    index = index or bundled_index()
+    if normalize_name(name) in index.rank:
+        return ("skip", "popular package", 0)
+
+    target = find_lookalike(name, index)
+    if target is None:
+        return ("pass", "no close match among popular packages", 0)
+
+    # Reuses the cached registry response, so this costs no extra request.
+    age_status, _, _ = await check_age(name, client)
+    if age_status == "pass":
+        return ("warn", f"looks like {target} (established package)", ESTABLISHED_LOOKALIKE_POINTS)
+    return ("warn", f"looks like {target}", LOOKALIKE_POINTS)

slopsentry/cli.py

@@ -0,0 +1,123 @@
+"""SlopSentry command-line interface."""
+
+import asyncio
+import json
+import sys
+from collections.abc import Callable
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from slopsentry import hook as hook_mod
+from slopsentry.registry import PyPIClient
+from slopsentry.scoring import BLOCK_AT, WARN_AT, Report, score
+from slopsentry.spec import InvalidPackageSpec, parse_package_name
+
+app = typer.Typer(help="Check packages for slopsquatting before they are installed.")
+console = Console()
+err_console = Console(stderr=True)
+
+# Tests replace these to inject a client backed by a mock transport.
+client_factory: Callable[[], PyPIClient] = PyPIClient
+
+
+def hook_client_factory() -> PyPIClient:
+    return PyPIClient(timeout=hook_mod.HOOK_TIMEOUT)
+
+
+VERDICT_EXIT = {"pass": 0, "warn": 0, "block": 1}
+STRICT_ERROR_EXIT = 2
+INVALID_INPUT_EXIT = 2
+
+VERDICT_STYLES = {"pass": "green", "warn": "yellow", "block": "red", "error": "red"}
+STATUS_STYLES = {"pass": "green", "warn": "yellow", "skip": "dim", "fail": "red", "error": "yellow"}
+
+
+async def _score(package: str) -> Report:
+    client = client_factory()
+    try:
+        return await score(package, client)
+    finally:
+        await client.aclose()
+
+
+def _print_table(report: Report) -> None:
+    table = Table(title=f"SlopSentry: {escape(report.package)}")
+    table.add_column("Check")
+    table.add_column("Status")
+    table.add_column("Detail")
+    table.add_column("Points", justify="right")
+    for r in report.results:
+        style = STATUS_STYLES[r.status]
+        table.add_row(r.check, f"[{style}]{r.status}[/{style}]", escape(r.detail), str(r.points))
+    console.print(table)
+    console.print(f"Total: {report.total} points (warn at {WARN_AT}, block at {BLOCK_AT})")
+
+
+def _print_summary(report: Report, strict_error: bool, with_reasons: bool) -> None:
+    label = "error" if strict_error else report.verdict
+    style = VERDICT_STYLES[label]
+    line = f"[{style}]{label.upper()}[/{style}] {escape(report.package)}: score {report.total}"
+    if strict_error:
+        line += ", could not be verified (--strict)"
+    elif report.has_errors:
+        line += ", could not be fully verified (allowing; use --strict to block)"
+    console.print(line)
+
+    if with_reasons and label != "pass":
+        for r in report.reasons:
+            console.print(f"  - {r.check}: {escape(r.detail)} (+{r.points})")
+
+
+@app.callback()
+def main() -> None:
+    """Check packages for slopsquatting before they are installed."""
+
+
+@app.command()
+def check(
+    spec: str = typer.Argument(
+        ..., metavar="PACKAGE", help="Package name or requirement, e.g. requests[socks]==2.31.0."
+    ),
+    strict: bool = typer.Option(
+        False, "--strict", help="Exit 2 instead of warning when the registry is unreachable."
+    ),
+    explain: bool = typer.Option(
+        False, "--explain", help="Show every check's status, detail and points."
+    ),
+) -> None:
+    """Score PACKAGE for slopsquatting risk: pass, warn or block."""
+    try:
+        package = parse_package_name(spec)
+    except InvalidPackageSpec as exc:
+        err_console.print(f"[red]ERROR[/red] {escape(str(exc))}", highlight=False)
+        raise typer.Exit(INVALID_INPUT_EXIT) from None
+
+    report = asyncio.run(_score(package))
+    strict_error = strict and report.has_errors
+
+    if explain:
+        _print_table(report)
+    _print_summary(report, strict_error, with_reasons=not explain)
+
+    raise typer.Exit(STRICT_ERROR_EXIT if strict_error else VERDICT_EXIT[report.verdict])
+
+
+@app.command()
+def hook(
+    debug: bool = typer.Option(False, "--debug", help="Also print swallowed exceptions to stderr."),
+) -> None:
+    """Claude Code PreToolUse hook: read the event on stdin, print a decision as JSON.
+
+    Always exits 0. Warn asks the user, block denies, anything else is allowed silently.
+    """
+    try:
+        output = hook_mod.run_hook(sys.stdin.read(), hook_client_factory)
+    except Exception:
+        hook_mod.log_exception(debug)
+        output = None
+    if output is not None:
+        sys.stdout.write(json.dumps(output) + "\n")
+    raise typer.Exit(0)

slopsentry/data/__init__.py

@@ -0,0 +1 @@
+"""Bundled data files."""