slopguard-cli 0.1.0__py3-none-any.whl

slopguard/__init__.py

@@ -0,0 +1,7 @@
+"""SlopGuard — defend against slopsquatting (LLM-hallucinated package names)."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

slopguard/__main__.py

@@ -0,0 +1,13 @@
+"""Enables ``python -m slopguard``."""
+
+from __future__ import annotations
+
+from slopguard.cli import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

slopguard/cli.py

@@ -0,0 +1,321 @@
+"""SlopGuard CLI — ``scan`` + ``version`` subcommands."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+import time
+import uuid
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from slopguard import __version__
+from slopguard.config import (
+    ConfigError,
+    ResolvedConfig,
+    default_config_path,
+    load_file_config,
+    resolve,
+)
+from slopguard.models import (
+    Dependency,
+    Ecosystem,
+    Finding,
+    ManifestInfo,
+    RiskTier,
+    ScanReport,
+    ScanSummary,
+    Signal,
+)
+from slopguard.parsers.base import Parser, ParserError
+from slopguard.parsers.npm import NpmParser
+from slopguard.parsers.python import PythonParser
+from slopguard.registry.base import RegistryClient
+from slopguard.registry.npm import NpmRegistryClient
+from slopguard.registry.pypi import PypiRegistryClient
+from slopguard.report.json import write_json_report
+from slopguard.report.terminal import render_terminal_report
+from slopguard.scoring.engine import ScoringConfig, ScoringEngine
+
+app = typer.Typer(
+    name="slopguard",
+    help="Defend developers and AI coding agents against slopsquatting (LLM-hallucinated packages).",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+logger = logging.getLogger("slopguard")
+
+
+class OutputFormat(StrEnum):
+    TERMINAL = "terminal"
+    JSON = "json"
+
+
+class FailOn(StrEnum):
+    ANY = "any"
+    HALLUCINATED = "hallucinated"
+    SUSPICIOUS = "suspicious"
+    NONE = "none"
+
+
+MANIFEST_PARSERS: dict[str, type[Parser]] = {
+    "package.json": NpmParser,
+    "package-lock.json": NpmParser,
+    "requirements.txt": PythonParser,
+    "pyproject.toml": PythonParser,
+    "Pipfile": PythonParser,
+}
+
+
+def _ecosystem_for(filename: str) -> Ecosystem:
+    return Ecosystem.NPM if filename in {"package.json", "package-lock.json"} else Ecosystem.PYPI
+
+
+def discover_manifests(path: Path) -> list[Path]:
+    """Find manifests in ``path``. Recurse up to 2 levels for directory targets."""
+    if path.is_file():
+        return [path] if path.name in MANIFEST_PARSERS else []
+    if not path.is_dir():
+        return []
+    found: list[Path] = []
+    seen: set[Path] = set()
+    for depth in range(3):  # 0 = path itself, 1 = children, 2 = grandchildren
+        for entry in _iter_at_depth(path, depth):
+            if entry.name in MANIFEST_PARSERS and entry.is_file() and entry not in seen:
+                # Skip lockfiles if the sibling package.json was already accepted; lockfiles
+                # tend to be far larger and the manifest gives us the directly-declared deps.
+                if entry.name == "package-lock.json":
+                    sibling = entry.with_name("package.json")
+                    if sibling in seen:
+                        continue
+                seen.add(entry)
+                found.append(entry)
+    # Stable ordering.
+    found.sort()
+    return found
+
+
+def _iter_at_depth(root: Path, depth: int) -> list[Path]:
+    if depth == 0:
+        return list(root.iterdir())
+    out: list[Path] = []
+    for sub in root.iterdir():
+        if not sub.is_dir():
+            continue
+        if sub.name in {"node_modules", ".venv", "venv", "__pycache__", ".git", "dist", "build"}:
+            continue
+        out.extend(_iter_at_depth(sub, depth - 1))
+    return out
+
+
+def _build_clients(cfg: ResolvedConfig) -> tuple[RegistryClient | None, RegistryClient | None]:
+    if not cfg.network_enabled:
+        return (None, None)
+    npm = NpmRegistryClient(timeout=cfg.timeout_seconds)
+    pypi = PypiRegistryClient(timeout=cfg.timeout_seconds)
+    return (npm, pypi)
+
+
+def _should_fail(summary: ScanSummary, fail_on: str) -> bool:
+    if fail_on == "none":
+        return False
+    if fail_on in {"any", "hallucinated"} and summary.hallucinated > 0:
+        return True
+    if fail_on == "any" and (summary.suspicious > 0 or summary.errors > 0):
+        return True
+    return fail_on == "suspicious" and (summary.hallucinated > 0 or summary.suspicious > 0)
+
+
+def _summarise(findings: list[Finding]) -> ScanSummary:
+    clean = sum(1 for f in findings if f.risk is RiskTier.CLEAN)
+    suspicious = sum(1 for f in findings if f.risk is RiskTier.SUSPICIOUS)
+    hallucinated = sum(1 for f in findings if f.risk is RiskTier.HALLUCINATED)
+    errors = sum(1 for f in findings if f.risk is RiskTier.ERROR)
+    return ScanSummary(
+        total=len(findings),
+        clean=clean,
+        suspicious=suspicious,
+        hallucinated=hallucinated,
+        errors=errors,
+    )
+
+
+def _ignored_finding(dep: Dependency) -> Finding:
+    return Finding(
+        name=dep.name,
+        version=dep.version,
+        ecosystem=dep.ecosystem,
+        manifest=dep.manifest,
+        risk=RiskTier.CLEAN,
+        score=0.0,
+        signals=[
+            Signal(
+                type="ignored_by_config",
+                weight=0.0,
+                detail="Matched an .slopguard.yaml ignore rule.",
+            )
+        ],
+        remediation="No action required (ignored).",
+    )
+
+
+async def _scan_async(
+    target: Path,
+    cfg: ResolvedConfig,
+    *,
+    verbose: bool,
+) -> tuple[ScanReport, float]:
+    started = time.monotonic()
+    manifests = discover_manifests(target)
+    if not manifests:
+        raise _error_exit("No supported manifests found at the given path.")
+
+    parsed: list[tuple[ManifestInfo, list[Dependency]]] = []
+    for m in manifests:
+        parser_cls = MANIFEST_PARSERS[m.name]
+        parser = parser_cls()
+        try:
+            deps = parser.parse(m)
+        except ParserError as exc:
+            raise _error_exit(f"Could not parse {m}: {exc}") from exc
+        ecosystem = _ecosystem_for(m.name)
+        rel = m.relative_to(target) if target.is_dir() else Path(m.name)
+        manifest_info = ManifestInfo(path=str(rel), ecosystem=ecosystem, dependency_count=len(deps))
+        # Rewrite each Dependency's manifest path to be the relative one (parsers default to basename).
+        deps = [d.model_copy(update={"manifest": str(rel)}) for d in deps]
+        parsed.append((manifest_info, deps))
+
+    all_deps = [d for _, deps in parsed for d in deps]
+    npm_client, pypi_client = _build_clients(cfg)
+
+    try:
+        engine = ScoringEngine(
+            npm_client=npm_client,
+            pypi_client=pypi_client,
+            config=ScoringConfig(
+                suspicious_min=cfg.suspicious_min,
+                hallucinated_min=cfg.hallucinated_min,
+                verbose=verbose,
+            ),
+            no_network=not cfg.network_enabled,
+            concurrency=cfg.concurrency,
+        )
+        # Pre-split deps into ignored vs to-score.
+        to_score: list[Dependency] = []
+        ignored: list[Finding] = []
+        for dep in all_deps:
+            if cfg.ignore.matches(dep.name):
+                ignored.append(_ignored_finding(dep))
+            else:
+                to_score.append(dep)
+        scored = await engine.score_all(to_score)
+    finally:
+        if npm_client is not None:
+            await npm_client.aclose()
+        if pypi_client is not None:
+            await pypi_client.aclose()
+
+    findings = ignored + scored
+    summary = _summarise(findings)
+    exit_code = 1 if _should_fail(summary, cfg.fail_on) else 0
+    report = ScanReport(
+        slopguard_version=__version__,
+        scan_id=str(uuid.uuid4()),
+        scanned_at=datetime.now(UTC),
+        path=str(target.resolve()),
+        manifests=[mi for mi, _ in parsed],
+        summary=summary,
+        findings=findings,
+        exit_code=exit_code,  # type: ignore[arg-type]  # Literal[0,1,2] — validated by Pydantic
+    )
+    return report, time.monotonic() - started
+
+
+def _error_exit(message: str) -> typer.Exit:
+    Console(stderr=True).print(f"[red]error:[/red] {message}")
+    return typer.Exit(code=2)
+
+
+@app.command("scan")
+def scan_cmd(
+    path: Annotated[
+        Path | None, typer.Argument(help="Project directory or manifest file. Defaults to CWD.")
+    ] = None,
+    format_: Annotated[
+        OutputFormat, typer.Option("--format", help="Output format.")
+    ] = OutputFormat.TERMINAL,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", help="Write JSON output to a file (--format=json only)."),
+    ] = None,
+    config: Annotated[
+        Path | None, typer.Option("--config", help="Path to .slopguard.yaml.")
+    ] = None,
+    fail_on: Annotated[
+        FailOn | None, typer.Option("--fail-on", help="Risk level that causes a non-zero exit.")
+    ] = None,
+    no_network: Annotated[bool, typer.Option("--no-network", help="Skip registry probes.")] = False,
+    timeout: Annotated[
+        float | None,
+        typer.Option("--timeout", help="Per-request timeout for registry probes (seconds)."),
+    ] = None,
+    concurrency: Annotated[
+        int | None, typer.Option("--concurrency", help="Maximum concurrent registry probes.")
+    ] = None,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show debug logs.")] = False,
+) -> None:
+    """Scan a project for slopsquatted / hallucinated dependencies."""
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG, format="%(levelname)s %(name)s: %(message)s")
+
+    target = (path or Path.cwd()).expanduser()
+    if not target.exists():
+        raise _error_exit(f"path does not exist: {target}")
+
+    config_path = config or default_config_path(target if target.is_dir() else target.parent)
+    try:
+        file_cfg = load_file_config(config_path)
+        resolved = resolve(
+            file_cfg,
+            cli_fail_on=fail_on.value if fail_on is not None else None,
+            cli_no_network=no_network,
+            cli_timeout=timeout,
+            cli_concurrency=concurrency,
+        )
+    except ConfigError as exc:
+        raise _error_exit(str(exc)) from exc
+
+    if format_ is OutputFormat.JSON and output is None and verbose:
+        logger.warning("--format=json without --output; printing to stdout")
+
+    report, duration = asyncio.run(_scan_async(target, resolved, verbose=verbose))
+
+    if format_ is OutputFormat.JSON:
+        text = write_json_report(report, path=output)
+        if output is None:
+            sys.stdout.write(text)
+    else:
+        render_terminal_report(report, duration_seconds=duration)
+
+    raise typer.Exit(code=report.exit_code)
+
+
+@app.command("version")
+def version_cmd() -> None:
+    """Print the SlopGuard version and exit 0."""
+    print(__version__)
+
+
+@app.command("update", hidden=True)
+def update_cmd() -> None:
+    """(Stub) refresh the embedded hallucination database. See TODO(v0.2)."""
+    from slopguard.update import run
+
+    raise typer.Exit(code=run())

slopguard/config.py

@@ -0,0 +1,139 @@
+"""``.slopguard.yaml`` loader and merged config."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field, ValidationError
+
+from slopguard.scoring.engine import DEFAULT_HALLUCINATED_MIN, DEFAULT_SUSPICIOUS_MIN
+
+
+class IgnoreConfig(BaseModel):
+    packages: list[str] = Field(default_factory=list)
+    patterns: list[str] = Field(default_factory=list)
+
+
+class NetworkConfig(BaseModel):
+    enabled: bool = True
+    timeout_seconds: float = 5.0
+    concurrency: int = 16
+
+
+class ScoringFileConfig(BaseModel):
+    suspicious_min_score: float = DEFAULT_SUSPICIOUS_MIN
+    hallucinated_min_score: float = DEFAULT_HALLUCINATED_MIN
+
+
+class FileConfig(BaseModel):
+    """The schema of ``.slopguard.yaml``. All fields optional."""
+
+    ignore: IgnoreConfig = Field(default_factory=IgnoreConfig)
+    fail_on: str = "suspicious"
+    network: NetworkConfig = Field(default_factory=NetworkConfig)
+    scoring: ScoringFileConfig = Field(default_factory=ScoringFileConfig)
+
+
+class ConfigError(Exception):
+    """Raised when ``.slopguard.yaml`` is malformed."""
+
+
+@dataclass(frozen=True)
+class IgnoreRules:
+    names: frozenset[str]
+    patterns: tuple[re.Pattern[str], ...]
+
+    def matches(self, name: str) -> bool:
+        if name in self.names:
+            return True
+        return any(p.search(name) for p in self.patterns)
+
+
+@dataclass(frozen=True)
+class ResolvedConfig:
+    """Merged config used by the CLI. CLI flags > file > defaults."""
+
+    fail_on: str
+    network_enabled: bool
+    timeout_seconds: float
+    concurrency: int
+    suspicious_min: float
+    hallucinated_min: float
+    ignore: IgnoreRules = field(default_factory=lambda: IgnoreRules(frozenset(), ()))
+
+
+def load_file_config(path: Path | None) -> FileConfig:
+    """Load the YAML config. Returns defaults if ``path`` is None or missing."""
+    if path is None or not path.exists():
+        return FileConfig()
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"invalid YAML in {path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise ConfigError(f"expected a YAML mapping at top level of {path}")
+    try:
+        return FileConfig.model_validate(raw)
+    except ValidationError as exc:
+        raise ConfigError(f"invalid .slopguard.yaml schema: {exc}") from exc
+
+
+def resolve(
+    file_cfg: FileConfig,
+    *,
+    cli_fail_on: str | None,
+    cli_no_network: bool,
+    cli_timeout: float | None,
+    cli_concurrency: int | None,
+) -> ResolvedConfig:
+    fail_on = cli_fail_on or file_cfg.fail_on
+    if fail_on not in {"any", "hallucinated", "suspicious", "none"}:
+        raise ConfigError(f"invalid fail_on value: {fail_on!r}")
+    network_enabled = file_cfg.network.enabled and not cli_no_network
+    timeout = cli_timeout if cli_timeout is not None else file_cfg.network.timeout_seconds
+    concurrency = cli_concurrency if cli_concurrency is not None else file_cfg.network.concurrency
+    ignore = IgnoreRules(
+        names=frozenset(file_cfg.ignore.packages),
+        patterns=tuple(_compile_patterns(file_cfg.ignore.patterns)),
+    )
+    return ResolvedConfig(
+        fail_on=fail_on,
+        network_enabled=network_enabled,
+        timeout_seconds=timeout,
+        concurrency=concurrency,
+        suspicious_min=file_cfg.scoring.suspicious_min_score,
+        hallucinated_min=file_cfg.scoring.hallucinated_min_score,
+        ignore=ignore,
+    )
+
+
+def _compile_patterns(patterns: list[str]) -> list[re.Pattern[str]]:
+    compiled: list[re.Pattern[str]] = []
+    for raw in patterns:
+        try:
+            compiled.append(re.compile(raw))
+        except re.error as exc:
+            raise ConfigError(f"invalid ignore pattern {raw!r}: {exc}") from exc
+    return compiled
+
+
+def default_config_path(start: Path) -> Path | None:
+    """Search for ``.slopguard.yaml`` in ``start`` and its parents (up to 3 levels)."""
+    cur = start.resolve()
+    for _ in range(3):
+        candidate = cur / ".slopguard.yaml"
+        if candidate.exists():
+            return candidate
+        if cur.parent == cur:
+            break
+        cur = cur.parent
+    return None
+
+
+def _ensure_yaml_safe(data: Any) -> None:  # pragma: no cover — diagnostic only
+    """Belt-and-braces sanity check used by tests."""
+    yaml.safe_dump(data)

slopguard/data/__init__.py

@@ -0,0 +1,40 @@
+"""Embedded data: hallucination seed DB + popular-package lists."""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib.resources import files
+
+from slopguard.models import Ecosystem, HallucinationDB, HallucinationEntry, PopularPackages
+
+
+@lru_cache(maxsize=1)
+def load_hallucination_db() -> HallucinationDB:
+    """Load and validate the embedded hallucination seed database."""
+    raw = files("slopguard.data").joinpath("hallucinations_seed.json").read_text(encoding="utf-8")
+    payload = json.loads(raw)
+    # Strip non-schema keys (operator notes, etc.) before validating.
+    keep = {"schema_version", "updated", "entries"}
+    cleaned = {k: v for k, v in payload.items() if k in keep}
+    return HallucinationDB.model_validate(cleaned)
+
+
+@lru_cache(maxsize=1)
+def load_popular_packages() -> PopularPackages:
+    """Load the embedded top-1000 popularity lists."""
+    raw = files("slopguard.data").joinpath("popular_packages.json").read_text(encoding="utf-8")
+    return PopularPackages.model_validate_json(raw)
+
+
+def hallucination_index() -> dict[tuple[Ecosystem, str], HallucinationEntry]:
+    """Return a lookup of (ecosystem, lowercased name) → seed entry."""
+    db = load_hallucination_db()
+    return {(entry.ecosystem, entry.name.lower()): entry for entry in db.entries}
+
+
+def popular_set(ecosystem: Ecosystem) -> frozenset[str]:
+    """Return the lowercased popular-package set for an ecosystem."""
+    pkgs = load_popular_packages()
+    names = pkgs.npm_top_1000 if ecosystem is Ecosystem.NPM else pkgs.pypi_top_1000
+    return frozenset(name.lower() for name in names)