python-checkup 0.0.1__py3-none-any.whl

python_checkup/analyzers/dependency_vulns.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import time
+from pathlib import Path
+
+import httpx
+
+from python_checkup.analysis_request import AnalysisRequest
+from python_checkup.dependencies.discovery import (
+    DependencySource,
+    LockedPackage,
+    discover_dependency_source,
+)
+from python_checkup.models import Category, Diagnostic, Severity
+
+logger = logging.getLogger("python_checkup")
+
+OSV_QUERY_BATCH_URL = "https://api.osv.dev/v1/querybatch"
+
+# Advisory cache lives in a separate namespace from the per-file cache.
+ADVISORY_CACHE_DIR = "v2/advisories"
+# Cache entries are valid for 24 hours.
+ADVISORY_CACHE_TTL_SECONDS = 24 * 60 * 60
+
+
+class AdvisoryCache:
+    """Local filesystem cache for OSV advisory responses.
+
+    Each entry is keyed by ``{package_name}:{version}`` and stores the
+    raw list of vulnerability dicts returned by OSV.  Entries older than
+    ``ADVISORY_CACHE_TTL_SECONDS`` are treated as stale and ignored.
+
+    Cache directory: ``.python-checkup-cache/v2/advisories/``
+    """
+
+    def __init__(self, project_root: Path, *, enabled: bool = True) -> None:
+        self.enabled = enabled
+        self.cache_dir = project_root / ".python-checkup-cache" / ADVISORY_CACHE_DIR
+        self._hits = 0
+        self._misses = 0
+        if self.enabled:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    # -- key helpers --------------------------------------------------
+
+    @staticmethod
+    def _safe_key(name: str, version: str) -> str:
+        """Deterministic, filesystem-safe key for a package+version."""
+        raw = f"{name}:{version}"
+        return hashlib.sha256(raw.encode()).hexdigest()[:24]
+
+    def _path(self, name: str, version: str) -> Path:
+        return self.cache_dir / f"{self._safe_key(name, version)}.json"
+
+    # -- public API ---------------------------------------------------
+
+    def get(self, name: str, version: str) -> list[dict[str, object]] | None:
+        """Return cached advisory list or ``None`` on miss / stale."""
+        if not self.enabled:
+            return None
+        path = self._path(name, version)
+        if not path.exists():
+            self._misses += 1
+            return None
+        try:
+            data = json.loads(path.read_text())
+            ts = data.get("ts", 0)
+            if time.time() - ts > ADVISORY_CACHE_TTL_SECONDS:
+                path.unlink(missing_ok=True)
+                self._misses += 1
+                return None
+            self._hits += 1
+            vulns: list[dict[str, object]] = data.get("vulns", [])
+            return vulns
+        except (json.JSONDecodeError, OSError, KeyError, TypeError):
+            path.unlink(missing_ok=True)
+            self._misses += 1
+            return None
+
+    def set(self, name: str, version: str, vulns: list[dict[str, object]]) -> None:
+        """Persist advisory list for ``name==version``."""
+        if not self.enabled:
+            return
+        path = self._path(name, version)
+        try:
+            path.write_text(json.dumps({"ts": time.time(), "vulns": vulns}))
+        except OSError as exc:
+            logger.debug("advisory cache write failed: %s", exc)
+
+    def stats(self) -> dict[str, int]:
+        total = self._hits + self._misses
+        return {
+            "hits": self._hits,
+            "misses": self._misses,
+            "total": total,
+            "hit_rate_pct": round(self._hits / total * 100) if total else 0,
+        }
+
+
+def _extract_fix_versions(vuln: dict[str, object]) -> list[str]:
+    """Extract fix version strings from an OSV vulnerability dict.
+
+    OSV stores fix info in ``affected[].ranges[].events`` where each event
+    is either ``{"introduced": "..."}`` or ``{"fixed": "..."}``.  We collect
+    all unique ``fixed`` values across all affected entries and ranges.
+    """
+    fixes: list[str] = []
+    seen: set[str] = set()
+    affected_list = vuln.get("affected", [])
+    if not isinstance(affected_list, list):
+        return fixes
+    for affected in affected_list:
+        if not isinstance(affected, dict):
+            continue
+        for rng in affected.get("ranges", []):
+            if not isinstance(rng, dict):
+                continue
+            for event in rng.get("events", []):
+                if not isinstance(event, dict):
+                    continue
+                fixed = event.get("fixed")
+                if fixed and isinstance(fixed, str) and fixed not in seen:
+                    seen.add(fixed)
+                    fixes.append(fixed)
+    return fixes
+
+
+class DependencyVulnerabilityAnalyzer:
+    """Scan dependency versions from the target project against OSV."""
+
+    @property
+    def name(self) -> str:
+        return "dependency-vulns"
+
+    @property
+    def category(self) -> Category:
+        return Category.DEPENDENCIES
+
+    async def is_available(self) -> bool:
+        try:
+            import httpx as _httpx  # noqa: F401
+
+            return True
+        except ImportError:
+            return False
+
+    async def analyze(self, request: AnalysisRequest) -> list[Diagnostic]:
+        source = discover_dependency_source(request.project_root)
+        if source is None or not source.packages:
+            request.metadata["dependency_vulns_note"] = (
+                "no lockfile or dependency manifest with version data"
+            )
+            return []
+
+        request.metadata["dependency_vulns_source"] = source.kind
+        request.metadata["dependency_vulns_locked"] = source.is_locked
+        request.metadata["dependency_vulns_package_count"] = len(source.packages)
+
+        pinned = [pkg for pkg in source.packages if pkg.version]
+        if not pinned:
+            request.metadata["dependency_vulns_note"] = (
+                "dependencies are declared but not pinned"
+            )
+            return []
+
+        cache = AdvisoryCache(request.project_root, enabled=not request.no_cache)
+
+        # Split packages into cached vs uncached
+        cached_vulns: dict[int, list[dict[str, object]]] = {}
+        uncached_indices: list[int] = []
+        for i, pkg in enumerate(pinned):
+            if pkg.version is None:  # guaranteed False by filter above
+                continue
+            hit = cache.get(pkg.name, pkg.version)
+            if hit is not None:
+                cached_vulns[i] = hit
+            else:
+                uncached_indices.append(i)
+
+        # Query OSV only for uncached packages
+        remote_vulns = await self._query_osv(
+            pinned, uncached_indices, cache, request.config.timeout
+        )
+
+        # Merge cached + remote and build diagnostics
+        all_vulns = {**cached_vulns, **remote_vulns}
+        diagnostics = self._build_vulnerability_diagnostics(pinned, all_vulns, source)
+
+        # Store cache stats for reporting
+        stats = cache.stats()
+        if stats["total"] > 0:
+            logger.info(
+                "Advisory cache: %d hits, %d misses (%d%% hit rate)",
+                stats["hits"],
+                stats["misses"],
+                stats["hit_rate_pct"],
+            )
+
+        return diagnostics
+
+    async def _query_osv(
+        self,
+        pinned: list[LockedPackage],
+        uncached_indices: list[int],
+        cache: AdvisoryCache,
+        timeout: float,
+    ) -> dict[int, list[dict[str, object]]]:
+        """Call the OSV batch API for *uncached_indices* and update *cache*.
+
+        Returns a mapping from pinned-list index to vulnerability dicts.
+        """
+        if not uncached_indices:
+            return {}
+
+        payload = {
+            "queries": [
+                {
+                    "package": {
+                        "ecosystem": "PyPI",
+                        "name": pinned[i].name,
+                    },
+                    "version": pinned[i].version,
+                }
+                for i in uncached_indices
+            ]
+        }
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            response = await client.post(OSV_QUERY_BATCH_URL, json=payload)
+            response.raise_for_status()
+            data = response.json()
+
+        remote_vulns: dict[int, list[dict[str, object]]] = {}
+        results = data.get("results", [])
+        if not isinstance(results, list):
+            return remote_vulns
+
+        for j, result in enumerate(results):
+            if j >= len(uncached_indices):
+                break
+            idx = uncached_indices[j]
+            pkg = pinned[idx]
+            vulns: list[dict[str, object]] = []
+            if isinstance(result, dict):
+                raw = result.get("vulns", [])
+                if isinstance(raw, list):
+                    vulns = raw
+            remote_vulns[idx] = vulns
+            cache.set(pkg.name, pkg.version, vulns)
+
+        return remote_vulns
+
+    @staticmethod
+    def _build_vulnerability_diagnostics(
+        pinned: list[LockedPackage],
+        all_vulns: dict[int, list[dict[str, object]]],
+        source: DependencySource,
+    ) -> list[Diagnostic]:
+        """Build :class:`Diagnostic` objects from aggregated vulnerability data."""
+        diagnostics: list[Diagnostic] = []
+        for i, pkg in enumerate(pinned):
+            vulns = all_vulns.get(i, [])
+            for vuln in vulns:
+                if not isinstance(vuln, dict):
+                    continue
+                vuln_id = str(vuln.get("id", "UNKNOWN"))
+                fix_versions = _extract_fix_versions(vuln)
+                if fix_versions:
+                    fix_text = (
+                        f"Upgrade {pkg.name} to {' or '.join(fix_versions)} "
+                        f"and refresh your lockfile."
+                    )
+                else:
+                    fix_text = (
+                        "Upgrade the package to a non-vulnerable version "
+                        "and refresh your lockfile."
+                    )
+                diagnostics.append(
+                    Diagnostic(
+                        file_path=source.path,
+                        line=0,
+                        column=0,
+                        severity=Severity.ERROR,
+                        rule_id=vuln_id,
+                        tool="dependency-vulns",
+                        category=Category.DEPENDENCIES,
+                        message=(
+                            f"{pkg.name}=={pkg.version} has known vulnerability "
+                            f"{vuln_id}"
+                        ),
+                        fix=fix_text,
+                        help_url=f"https://osv.dev/vulnerability/{vuln_id}",
+                    )
+                )
+
+        return diagnostics

python_checkup/analyzers/deptry.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import shutil
+from pathlib import Path
+
+from python_checkup.analysis_request import AnalysisRequest
+from python_checkup.models import Category, Diagnostic, Severity
+
+logger = logging.getLogger("python_checkup")
+
+# Error code descriptions and severity mappings
+DEPTRY_CODES: dict[str, tuple[str, Severity]] = {
+    "DEP001": ("Missing dependency", Severity.ERROR),
+    "DEP002": ("Unused dependency", Severity.WARNING),
+    "DEP003": ("Transitive dependency", Severity.WARNING),
+    "DEP004": ("Misplaced dev dependency", Severity.WARNING),
+}
+
+
+class DeptryAnalyzer:
+    """Check for unused, missing, and transitive dependencies."""
+
+    @property
+    def name(self) -> str:
+        return "deptry"
+
+    @property
+    def category(self) -> Category:
+        return Category.DEPENDENCIES
+
+    async def is_available(self) -> bool:
+        """Check if deptry is on PATH."""
+        return shutil.which("deptry") is not None
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        """Run deptry with JSON output.
+
+        deptry analyzes the project root, not individual files.
+        """
+        config = request.config_dict()
+        project_root = str(request.project_root)
+
+        cmd = ["deptry", project_root, "--json-output", "-"]
+
+        timeout: int = 30
+        if "timeout" in config and isinstance(config["timeout"], int | float):
+            timeout = int(config["timeout"])
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(),
+                timeout=timeout,
+            )
+        except asyncio.TimeoutError:
+            logger.warning("deptry timed out")
+            return []
+        except FileNotFoundError:
+            logger.warning("deptry not found")
+            return []
+
+        # deptry writes JSON to stdout when --json-output - is used
+        output = stdout.decode()
+        if not output.strip():
+            return []
+
+        try:
+            issues: list[dict[str, object]] = json.loads(output)
+        except json.JSONDecodeError:
+            logger.error("Failed to parse deptry JSON")
+            return []
+
+        diagnostics: list[Diagnostic] = []
+        for issue in issues:
+            if not isinstance(issue, dict):
+                continue
+
+            error = issue.get("error", {})
+            if not isinstance(error, dict):
+                error = {}
+            code = str(error.get("code", "DEP000"))
+
+            location = issue.get("location", {})
+            if not isinstance(location, dict):
+                location = {}
+            module = str(issue.get("module", "unknown"))
+
+            desc, severity = DEPTRY_CODES.get(
+                code, ("Dependency issue", Severity.WARNING)
+            )
+
+            file_path = str(location.get("file", "pyproject.toml"))
+            line_val = location.get("line")
+            col_val = location.get("column")
+
+            diagnostics.append(
+                Diagnostic(
+                    file_path=Path(file_path),
+                    line=int(line_val) if isinstance(line_val, int | float) else 0,
+                    column=int(col_val) if isinstance(col_val, int | float) else 0,
+                    severity=severity,
+                    rule_id=code,
+                    tool="deptry",
+                    category=Category.DEPENDENCIES,
+                    message=f"{desc}: {module}",
+                    fix=_fix_suggestion(code, module),
+                )
+            )
+
+        return diagnostics
+
+
+def _fix_suggestion(code: str, module: str) -> str:
+    match code:
+        case "DEP001":
+            return f"Add '{module}' to your project dependencies in pyproject.toml"
+        case "DEP002":
+            return (
+                f"Remove '{module}' from your project dependencies (it's not imported)"
+            )
+        case "DEP003":
+            return (
+                f"Add '{module}' as a direct dependency instead of "
+                "relying on it transitively"
+            )
+        case "DEP004":
+            return (
+                f"Move '{module}' from dev dependencies to main dependencies "
+                "(it's imported in non-dev code)"
+            )
+        case _:
+            return f"Review the dependency '{module}'"

python_checkup/analyzers/detect_secrets.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+
+from python_checkup.analysis_request import AnalysisRequest
+from python_checkup.models import Category, Diagnostic, Severity
+
+logger = logging.getLogger("python_checkup")
+
+
+class DetectSecretsAnalyzer:
+    """Find hardcoded secrets using entropy and pattern analysis."""
+
+    @property
+    def name(self) -> str:
+        return "detect-secrets"
+
+    @property
+    def category(self) -> Category:
+        return Category.SECURITY
+
+    async def is_available(self) -> bool:
+        """Check if detect-secrets is importable."""
+        try:
+            from detect_secrets.core.secrets_collection import (
+                SecretsCollection,  # noqa: F401
+            )
+
+            return True
+        except ImportError:
+            return False
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        """Scan files for hardcoded secrets.
+
+        Uses the detect-secrets library API with default settings.
+        Runs in a thread because the scan is CPU-bound.
+        """
+        files = request.files
+        if not files:
+            return []
+        return await asyncio.to_thread(self._analyze_sync, files)
+
+    def _analyze_sync(self, files: list[Path]) -> list[Diagnostic]:
+        """Synchronous scan — called via ``asyncio.to_thread``."""
+        try:
+            from detect_secrets.core.secrets_collection import SecretsCollection
+            from detect_secrets.settings import (
+                default_settings,
+            )
+        except ImportError:
+            return []
+
+        secrets = SecretsCollection()
+
+        with default_settings():
+            for f in files:
+                try:
+                    secrets.scan_file(str(f))
+                except Exception as exc:
+                    logger.debug("detect-secrets failed on %s: %s", f, exc)
+                    continue
+
+        diagnostics: list[Diagnostic] = []
+        for filename, secret_list in secrets.json().items():
+            if not isinstance(secret_list, list):
+                continue
+            for secret in secret_list:
+                if not isinstance(secret, dict):
+                    continue
+                secret_type = str(secret.get("type", "unknown"))
+                rule_id = f"SECRET-{secret_type.upper().replace(' ', '-')}"
+
+                line_number = secret.get("line_number", 0)
+                if not isinstance(line_number, int):
+                    line_number = 0
+
+                diagnostics.append(
+                    Diagnostic(
+                        file_path=Path(str(filename)),
+                        line=line_number,
+                        column=0,
+                        severity=Severity.ERROR,
+                        rule_id=rule_id,
+                        tool="detect-secrets",
+                        category=Category.SECURITY,
+                        message=f"Potential {secret_type} detected",
+                        fix=(
+                            "Move this secret to an environment variable or a "
+                            "secrets manager (e.g., AWS Secrets Manager, HashiCorp "
+                            "Vault, or a .env file excluded from version control)."
+                        ),
+                    )
+                )
+
+        return diagnostics