slopguard-cli 0.1.0__py3-none-any.whl

slopguard/scoring/signals.py

@@ -0,0 +1,183 @@
+"""Individual risk-signal functions.
+
+Each function consumes the dependency, optional registry metadata, and optional
+context (popularity sets, hallucination DB hits). They return a :class:`Signal`
+or ``None``. The engine composes them.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta
+
+from slopguard.models import Dependency, HallucinationEntry, Signal
+from slopguard.registry.base import PackageMetadata
+
+# Weights mirror the spec section 9 table.
+W_DB_HIT = 0.90
+W_NOT_FOUND = 0.85
+W_RECENT_30 = 0.20
+W_RECENT_7 = 0.35
+W_LOW_DOWNLOADS = 0.15
+W_NEW_PUBLISHER = 0.20
+W_SOLO_NEW = 0.30
+W_LEVENSHTEIN = 0.25
+W_NAME_PATTERN = 0.10
+
+_NAME_PATTERN_RE = re.compile(
+    r"^(?:[a-z0-9]+[-_])+(helpers?|utils?|async|pro|kit|sdk|tools?|extras?|plus|next|core)$",
+    re.IGNORECASE,
+)
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _ensure_aware(dt: datetime) -> datetime:
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=UTC)
+    return dt
+
+
+def hallucination_db_hit(dep: Dependency, entry: HallucinationEntry | None) -> Signal | None:
+    if entry is None:
+        return None
+    models = ", ".join(entry.models_observed) if entry.models_observed else "unspecified models"
+    return Signal(
+        type="hallucination_db_hit",
+        weight=W_DB_HIT,
+        detail=(f"Matched seed DB entry; recurrence {entry.recurrence_rate:.2f} across {models}."),
+    )
+
+
+def registry_not_found(meta: PackageMetadata) -> Signal | None:
+    if meta.exists:
+        return None
+    return Signal(
+        type="registry_not_found",
+        weight=W_NOT_FOUND,
+        detail="Registry returned 404 — package name is not currently published.",
+    )
+
+
+def recently_published(meta: PackageMetadata) -> tuple[Signal | None, Signal | None]:
+    """Return (very_recent, recent) signals — at most one will be non-None."""
+    if not meta.exists or meta.first_release is None:
+        return (None, None)
+    age = _now() - _ensure_aware(meta.first_release)
+    if age < timedelta(days=7):
+        return (
+            Signal(
+                type="very_recently_published",
+                weight=W_RECENT_7,
+                detail=f"First release {age.days} day(s) ago.",
+            ),
+            None,
+        )
+    if age < timedelta(days=30):
+        return (
+            None,
+            Signal(
+                type="recently_published",
+                weight=W_RECENT_30,
+                detail=f"First release {age.days} day(s) ago.",
+            ),
+        )
+    return (None, None)
+
+
+def low_downloads(meta: PackageMetadata) -> Signal | None:
+    if not meta.exists or meta.downloads_recent is None:
+        return None
+    if meta.downloads_recent >= 100:
+        return None
+    return Signal(
+        type="low_downloads",
+        weight=W_LOW_DOWNLOADS,
+        detail=f"{meta.downloads_recent} recent downloads.",
+    )
+
+
+def new_publisher(meta: PackageMetadata) -> Signal | None:
+    if not meta.exists or meta.publisher_created is None:
+        return None
+    age = _now() - _ensure_aware(meta.publisher_created)
+    if age < timedelta(days=30):
+        return Signal(
+            type="new_publisher",
+            weight=W_NEW_PUBLISHER,
+            detail=f"Publisher account created {age.days} day(s) ago.",
+        )
+    return None
+
+
+def single_release_new_account(meta: PackageMetadata) -> Signal | None:
+    if not meta.exists or meta.publisher_created is None or meta.publisher_package_count is None:
+        return None
+    age = _now() - _ensure_aware(meta.publisher_created)
+    if meta.publisher_package_count == 1 and age < timedelta(days=60):
+        return Signal(
+            type="single_release_new_account",
+            weight=W_SOLO_NEW,
+            detail=(f"Publisher's only release; account {age.days} day(s) old."),
+        )
+    return None
+
+
+def levenshtein(a: str, b: str) -> int:
+    """Iterative Levenshtein distance. Small inputs — no heuristic shortcuts."""
+    if a == b:
+        return 0
+    if not a:
+        return len(b)
+    if not b:
+        return len(a)
+    prev = list(range(len(b) + 1))
+    for i, ca in enumerate(a, start=1):
+        curr = [i] + [0] * len(b)
+        for j, cb in enumerate(b, start=1):
+            cost = 0 if ca == cb else 1
+            curr[j] = min(
+                curr[j - 1] + 1,  # insertion
+                prev[j] + 1,  # deletion
+                prev[j - 1] + cost,  # substitution
+            )
+        prev = curr
+    return prev[-1]
+
+
+def levenshtein_typo(dep: Dependency, popular: frozenset[str]) -> Signal | None:
+    """Flag when the dep name is Levenshtein 1 or 2 from a popular package (and not that package)."""
+    lower = dep.name.lower()
+    if lower in popular:
+        return None
+    best: tuple[int, str] | None = None
+    for candidate in popular:
+        # Quick length-based prune.
+        if abs(len(candidate) - len(lower)) > 2:
+            continue
+        d = levenshtein(lower, candidate)
+        if d <= 2 and (best is None or d < best[0]):
+            best = (d, candidate)
+            if d == 1:
+                break
+    if best is None:
+        return None
+    d, candidate = best
+    return Signal(
+        type="levenshtein_typo",
+        weight=W_LEVENSHTEIN,
+        detail=f"Levenshtein {d} from popular package '{candidate}'.",
+    )
+
+
+def name_pattern_suspicious(dep: Dependency) -> Signal | None:
+    """Flag classic hallucination shapes like `<stem>-helpers`, `<stem>-utils`."""
+    if not _NAME_PATTERN_RE.match(dep.name):
+        return None
+    return Signal(
+        type="name_pattern_suspicious",
+        weight=W_NAME_PATTERN,
+        detail="Name matches a known hallucination shape (e.g. <stem>-helpers / -utils / -async / -pro).",
+    )

slopguard/update.py

@@ -0,0 +1,15 @@
+"""Stub for the future ``slopguard update`` remote DB refresh.
+
+# TODO(v0.2): implement a signed-bundle download from a trusted host.
+"""
+
+from __future__ import annotations
+
+
+def run() -> int:
+    """Print a not-yet-implemented message and exit 0."""
+    print(
+        "slopguard update is not implemented in v0.1. The embedded seed database "
+        "ships with the package and is refreshed by upgrading slopguard itself."
+    )
+    return 0

slopguard_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: slopguard-cli
+Version: 0.1.0
+Summary: Defend developers and AI coding agents against slopsquatting (hallucinated package names).
+Project-URL: Homepage, https://github.com/hariomunknownslab/slopguard
+Project-URL: Repository, https://github.com/hariomunknownslab/slopguard
+Project-URL: Issues, https://github.com/hariomunknownslab/slopguard/issues
+Author-email: SlopGuard <contact@unknownslab.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,llm,package-hallucination,security,slopsquatting,supply-chain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: jsonschema>=4.21.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SlopGuard
+
+[![CI](https://github.com/hariomunknownslab/slopguard/actions/workflows/ci.yml/badge.svg)](https://github.com/hariomunknownslab/slopguard/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/slopguard.svg)](https://pypi.org/project/slopguard/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Slopsquatting** is what happens when an LLM hallucinates a plausible-sounding
+package name that does not exist on the public registry — and then an attacker
+registers that exact name with malware so the *next* developer (or AI agent)
+who follows the suggestion installs it. SlopGuard scans your project's
+dependencies, flags entries that are either known LLM hallucinations or that
+show the behavioural fingerprint of a slopsquat, and exits non-zero so CI
+fails the build before the malware reaches `node_modules` or `site-packages`.
+
+> SlopGuard stops AI coding agents from installing packages that LLMs hallucinated.
+
+## Install
+
+```bash
+pip install slopguard-cli
+# Homebrew formula ships in a later release:
+# brew install slopguard
+```
+
+> The PyPI **distribution** name is `slopguard-cli` (the name `slopguard`
+> overlapped with an unrelated existing package on PyPI). The installed
+> command, the Python import, and everything else stays `slopguard`.
+
+Python 3.11+ is required.
+
+## Usage
+
+### 1. Scan the current directory
+
+```bash
+slopguard scan
+```
+
+SlopGuard auto-discovers `package.json`, `package-lock.json`,
+`requirements.txt`, `pyproject.toml`, and `Pipfile` (up to two levels deep),
+probes each name against the public registry, and prints a Rich table:
+
+```text
+SlopGuard v0.1.0 — scanning /home/dev/myproj
+
+Detected manifests:
+  • package.json (npm, 32 deps)
+  • requirements.txt (pypi, 15 deps)
+
+Scanned 47 dependencies in 3.1s.
+
+┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Package            ┃ Risk       ┃ Reason                                       ┃
+┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ react-codeshift    │ HALLUCIN.  │ Matched seed DB entry; recurrence 0.71.      │
+│ langchain-helpers  │ SUSPICIOUS │ Created 14 days ago, 48 downloads, new auth. │
+│ openai-utils       │ SUSPICIOUS │ Levenshtein 2 from popular package 'openai'. │
+│ requests           │ CLEAN      │ Established package.                         │
+└────────────────────┴────────────┴──────────────────────────────────────────────┘
+
+Summary: 1 hallucinated, 2 suspicious, 44 clean, 0 error(s).
+Exit code: 1
+```
+
+### 2. Scan a specific path
+
+```bash
+slopguard scan ./mono/services/api
+```
+
+### 3. CI mode — JSON output, strict failure threshold
+
+```bash
+slopguard scan --format json --output report.json --fail-on hallucinated
+```
+
+See [`.github/workflows/slopguard.yml.example`](.github/workflows/slopguard.yml.example)
+for a drop-in GitHub Actions workflow and [`docs/ci-integration.md`](docs/ci-integration.md)
+for details on other CI providers.
+
+## How it works
+
+For every dependency, SlopGuard computes a small set of independent signals
+and combines them into a single risk score in `[0.0, 1.0]`:
+
+- **Hallucination-DB hit** (weight 0.90) — exact match in an embedded seed
+  database of names known to be hallucinated by major LLMs.
+- **Registry not found** (0.85) — the registry returns 404 for the name. The
+  most common slopsquat shape: a name that doesn't exist *yet*.
+- **Very recently / recently published** (0.35 / 0.20) — first release < 7
+  days / < 30 days old.
+- **Low downloads** (0.15) — < 100 downloads in the last month (npm) or last
+  week (PyPI).
+- **New publisher** (0.20) and **single-release new account** (0.30) — a
+  brand-new account whose only release is the package you're about to install.
+- **Levenshtein typo** (0.25) — name is 1–2 edits away from a top-1000
+  popular package (likely a typosquat).
+- **Suspicious name pattern** (0.10) — matches a classic LLM-hallucination
+  shape like `<stem>-helpers`, `<stem>-utils`, `<stem>-async`, `<stem>-pro`.
+
+The default cutoffs map scores `≥ 0.85` → **hallucinated**, `≥ 0.40` →
+**suspicious**, else **clean**. Both thresholds are tunable in
+`.slopguard.yaml`. See [`docs/detection.md`](docs/detection.md) for the full
+table, the order of operations, and edge cases.
+
+## Configuration
+
+`.slopguard.yaml`, picked up automatically from the scan target or any
+ancestor (up to 3 levels):
+
+```yaml
+ignore:
+  packages: ["internal-tool"]
+  patterns: ["^@mycompany/"]
+
+fail_on: suspicious        # any | hallucinated | suspicious | none
+
+network:
+  enabled: true
+  timeout_seconds: 5
+  concurrency: 16
+
+scoring:
+  suspicious_min_score: 0.4
+  hallucinated_min_score: 0.85
+```
+
+CLI flags override the file. See [`docs/usage.md`](docs/usage.md) for the full
+reference.
+
+## What it does NOT do (v0.1)
+
+- No live LLM probing — the hallucination database is a static seed for v0.1.
+- No SaaS dashboard, no auth, no billing, no telemetry to any remote server.
+- No tarpit registry, no defensive package registration.
+- No Cursor / Claude Code / Copilot IDE plugins.
+- No support for crates.io, pkg.go.dev, Maven Central, RubyGems, NuGet —
+  Python and JavaScript only.
+- No license scanning, no CVE matching, no SBOM generation.
+- No remote configuration, no SaaS API client.
+
+The full v0.2+ roadmap is tracked in the build spec, section 14.
+
+## Privacy & trust
+
+SlopGuard makes **only** the network calls you opt into (the public registry
+probes against `registry.npmjs.org` and `pypi.org`). No analytics, no
+ping-home, no telemetry. The trust model is the moat: run `--no-network` if
+you want to be sure.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome — especially curated
+additions to the hallucination database.
+
+## License
+
+MIT. Copyright © 2026 SlopGuard. See [LICENSE](LICENSE).

slopguard_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+slopguard/__init__.py,sha256=N7XKzw5SjJe5DhhJFB7TyZBBbtCWs98fKxuKuKhFE94,169
+slopguard/__main__.py,sha256=-G9dcipk-3ulFo3WkJ3XEedb9dNQwG-gCpOmjzxiYcs,178
+slopguard/cli.py,sha256=jod0Oo-66G6P5GMKVA8G1JN7t54uzxtmFU_R-SMqMVk,10676
+slopguard/config.py,sha256=ImXQe4yiaJEu74rG3kNPqT9RPkeFJvvUpJ9irpjhzLs,4437
+slopguard/models.py,sha256=mr8dhFabHFSFrkd5ykPkQZpRLyN8j85OVhPkPqP-zjM,3126
+slopguard/update.py,sha256=68_ziw1EBw3uxw69ejgxpBnMZxajtCNea2CoApA4bKA,446
+slopguard/data/__init__.py,sha256=YeEejiB_6P1XOQLAvc2cK7bZt6NZRHxS4jLuGmG-WMo,1632
+slopguard/parsers/__init__.py,sha256=HS-tbUIOz3z0mCgDCTz8Du3dv4ncD2V1ao7njVc_wNo,306
+slopguard/parsers/base.py,sha256=Iz4Y5vAXvnK-tdSGGANeJOxgXr5HcaV4D03v5HsIdS4,700
+slopguard/parsers/npm.py,sha256=YgIaHUachzFQOGFqJW1Kc2sA2W_8D7NgbkmN7hpxeEI,5616
+slopguard/parsers/python.py,sha256=Ve-EAJNuoozpVstes_RkNRE9QMyPED9frgm6_kOXKHA,10635
+slopguard/registry/__init__.py,sha256=b-ucqaPqh5G9E14C5hEsyZD7MTchAzeSrysZkVXxnJI,361
+slopguard/registry/base.py,sha256=EHXL0EB5RYIZU5DxaUlxI4crVDnojdzpER3_erTd_3Q,3870
+slopguard/registry/npm.py,sha256=_dOJ4KDvIg3TKQ-thjpwkAu3MubFZilaAHlvFfnZeB8,2857
+slopguard/registry/pypi.py,sha256=txgNcdycePL_RO-6BxddGAPPi0kqsA7bQ71UUeLPWBs,3499
+slopguard/report/__init__.py,sha256=g7l1qlNFip6ZYb4VDGA-ioHwZnQfAfPWoBfIdOwo_U8,234
+slopguard/report/json.py,sha256=MwgXj7-7Ao1RRv-7JL6yaa51ixSJLeTPUiXHzWUOido,522
+slopguard/report/terminal.py,sha256=80SPLI8xhyyBcSJp6xHsgB350qw9RRwFmYAoh0HhU_w,2866
+slopguard/scoring/__init__.py,sha256=1kfQQ_QATivy1lDcdPmeZqbPX2WSlRfUQGJpn1C3g7A,144
+slopguard/scoring/engine.py,sha256=cPfKRlL4y4D74jAxnDcR5xutK5I1khw9mKn_2AUAS0I,8595
+slopguard/scoring/signals.py,sha256=wTwSFDto7l_BIs17780jxLsO9EbK0R3V0BIfSbNwZ3Y,5732
+slopguard/data/hallucinations_seed.json,sha256=5zqSAqAFe6xZhwMl1GYs5EsSKg4DdfLSt2rPBcr81HE,162120
+slopguard/data/popular_packages.json,sha256=kLzd3KX5W2QBd_FM9ZZ03pPx-sB7yUmqykiykbla-wU,35020
+slopguard_cli-0.1.0.dist-info/METADATA,sha256=Uh97auOxGIPtALJ8ukxfnM5Uxe5f-JZ_pDZk2fVyZMo,8070
+slopguard_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+slopguard_cli-0.1.0.dist-info/entry_points.txt,sha256=h_zIuznebScv0IDoby-nTcA2mBiS0rWJnDSKzlwfzTI,48
+slopguard_cli-0.1.0.dist-info/licenses/LICENSE,sha256=C7LCX7SDI6sNelsCL7-nRLejbHbLa4OOJwJcSTO6kL4,1066
+slopguard_cli-0.1.0.dist-info/RECORD,,

slopguard_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

slopguard_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+slopguard = slopguard.cli:app

slopguard_cli-0.1.0.dist-info/licenses/LICENSE

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