osv-scan 0.1.0__py3-none-any.whl

dep_scanner/__init__.py

@@ -0,0 +1,15 @@
+"""dep-scanner — zero-dependency CVE scanner for dependency manifests."""
+from __future__ import annotations
+
+from ._models import PackageFinding, ScanResult, Vulnerability
+from ._scanner import scan, scan_text
+
+__version__ = "0.1.0"
+__all__ = [
+    "scan",
+    "scan_text",
+    "ScanResult",
+    "PackageFinding",
+    "Vulnerability",
+    "__version__",
+]

dep_scanner/_cli.py

@@ -0,0 +1,177 @@
+"""CLI entry point for dep-scanner: dep-scan"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from ._parsers import detect_manifest
+from ._scanner import scan
+
+# ANSI colours (disabled when not a TTY)
+_TTY = sys.stdout.isatty()
+_C = {
+    "CRITICAL": "\033[91m\033[1m",
+    "HIGH":     "\033[93m\033[1m",
+    "MEDIUM":   "\033[94m\033[1m",
+    "LOW":      "\033[37m",
+    "GREEN":    "\033[92m",
+    "RESET":    "\033[0m",
+    "BOLD":     "\033[1m",
+    "DIM":      "\033[2m",
+}
+
+
+def _c(text: str, key: str) -> str:
+    if not _TTY:
+        return text
+    return f"{_C.get(key, '')}{text}{_C['RESET']}"
+
+
+def _print_result(result, use_json: bool, quiet: bool) -> None:
+    if use_json:
+        out = {
+            "source": result.source,
+            "ecosystem": result.ecosystem,
+            "packages_scanned": result.packages_scanned,
+            "highest_severity": result.highest_severity,
+            "elapsed_ms": result.elapsed_ms,
+            "findings": [
+                {
+                    "package": f.package,
+                    "version": f.version,
+                    "severity": f.highest_severity,
+                    "fix": f.fix_versions[0] if f.fix_versions else None,
+                    "vulnerabilities": [
+                        {
+                            "id": v.cve or v.id,
+                            "summary": v.summary,
+                            "severity": v.severity,
+                            "fixed_versions": v.fixed_versions,
+                        }
+                        for v in f.vulnerabilities
+                    ],
+                }
+                for f in result.findings
+            ],
+        }
+        print(json.dumps(out, indent=2))
+        return
+
+    if not quiet:
+        print(
+            f"\n{_c('dep-scan', 'BOLD')}  {result.source} "
+            f"{_c(f'({result.ecosystem})', 'DIM')} "
+            f"· {result.packages_scanned} packages\n"
+        )
+
+    if not result.has_findings:
+        if not quiet:
+            print(f"  {_c('✓ No vulnerabilities found', 'GREEN')}\n")
+        return
+
+    for finding in result.findings:
+        sev = finding.highest_severity or "MEDIUM"
+        print(f"  {_c(sev.ljust(9), sev)} {_c(finding.package, 'BOLD')} {finding.version}")
+
+        for vuln in finding.vulnerabilities:
+            vid = vuln.cve or vuln.id
+            print(f"             {_c(vid, 'DIM')}")
+            if vuln.summary:
+                summary = vuln.summary[:90] + ("…" if len(vuln.summary) > 90 else "")
+                print(f"             {summary}")
+
+        if finding.fix_versions:
+            print(f"             {_c('Fix: upgrade to ' + finding.fix_versions[0], 'BOLD')}")
+        print()
+
+    # Summary line
+    parts = []
+    for sev in ("CRITICAL", "HIGH", "MEDIUM", "LOW"):
+        count = len([f for f in result.findings if f.highest_severity == sev])
+        if count:
+            parts.append(_c(f"{count} {sev}", sev))
+
+    total = sum(len(f.vulnerabilities) for f in result.findings)
+    print(
+        f"  {' · '.join(parts)}"
+        f"  {_c(f'({total} vuln{"s" if total != 1 else ""} · {result.elapsed_ms}ms)', 'DIM')}\n"
+    )
+
+
+_FAIL_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "none": 99}
+_SEV_RANK = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}
+
+_AUTO_DETECT = [
+    "requirements.txt", "package-lock.json", "package.json",
+    "go.mod", "Cargo.toml", "pom.xml",
+]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="dep-scan",
+        description=(
+            "Scan dependency manifests for known CVEs using OSV.dev.\n"
+            "Supports: requirements.txt, package.json, package-lock.json, "
+            "go.mod, Cargo.toml, pom.xml"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        metavar="FILE",
+        help="Manifest files to scan (auto-detected if omitted)",
+    )
+    parser.add_argument(
+        "--json", action="store_true",
+        help="Output as JSON",
+    )
+    parser.add_argument(
+        "--fail-on",
+        default="critical",
+        choices=list(_FAIL_ORDER),
+        metavar="SEVERITY",
+        help="Exit 1 if findings at this level or above (default: critical)",
+    )
+    parser.add_argument(
+        "--quiet", "-q",
+        action="store_true",
+        help="Suppress informational output, print only findings",
+    )
+    args = parser.parse_args()
+
+    paths = args.paths or [p for p in _AUTO_DETECT if os.path.exists(p)]
+    if not paths:
+        print("No manifest files found. Pass a file or run from a project directory.", file=sys.stderr)
+        sys.exit(0)
+
+    threshold = _FAIL_ORDER[args.fail_on]
+    exit_code = 0
+
+    for path in paths:
+        if not os.path.exists(path):
+            print(f"File not found: {path}", file=sys.stderr)
+            continue
+        if detect_manifest(path) is None:
+            print(f"Unrecognised manifest: {path}", file=sys.stderr)
+            continue
+        try:
+            result = scan(path)
+        except Exception as exc:
+            print(f"Error scanning {path}: {exc}", file=sys.stderr)
+            continue
+
+        _print_result(result, use_json=args.json, quiet=args.quiet)
+
+        if result.highest_severity:
+            if _SEV_RANK.get(result.highest_severity, 99) <= threshold:
+                exit_code = 1
+
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

dep_scanner/_models.py

@@ -0,0 +1,112 @@
+"""Data models for dep-scanner findings."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Vulnerability:
+    id: str
+    cve: str
+    aliases: List[str]
+    summary: str
+    details: str
+    severity: str          # CRITICAL / HIGH / MEDIUM / LOW
+    fixed_versions: List[str]
+    published: str
+
+    @classmethod
+    def _from_dict(cls, d: Dict[str, Any]) -> "Vulnerability":
+        return cls(
+            id=d.get("id", ""),
+            cve=d.get("cve", ""),
+            aliases=d.get("aliases", []),
+            summary=d.get("summary", ""),
+            details=d.get("details", ""),
+            severity=d.get("severity", "MEDIUM"),
+            fixed_versions=d.get("fixed_versions", []),
+            published=d.get("published", ""),
+        )
+
+
+@dataclass
+class PackageFinding:
+    package: str
+    version: str
+    ecosystem: str
+    vulnerabilities: List[Vulnerability] = field(default_factory=list)
+
+    @property
+    def highest_severity(self) -> Optional[str]:
+        for sev in ("CRITICAL", "HIGH", "MEDIUM", "LOW"):
+            if any(v.severity == sev for v in self.vulnerabilities):
+                return sev
+        return None
+
+    @property
+    def fix_versions(self) -> List[str]:
+        """Unique fix versions across all vulnerabilities, sorted."""
+        seen: set = set()
+        result = []
+        for v in self.vulnerabilities:
+            for fv in v.fixed_versions:
+                if fv not in seen:
+                    seen.add(fv)
+                    result.append(fv)
+        return sorted(result)
+
+
+@dataclass
+class ScanResult:
+    source: str
+    ecosystem: str
+    packages_scanned: int
+    findings: List[PackageFinding]
+    elapsed_ms: int
+
+    @property
+    def has_findings(self) -> bool:
+        return bool(self.findings)
+
+    @property
+    def critical(self) -> List[PackageFinding]:
+        return [f for f in self.findings if f.highest_severity == "CRITICAL"]
+
+    @property
+    def high(self) -> List[PackageFinding]:
+        return [f for f in self.findings if f.highest_severity == "HIGH"]
+
+    @property
+    def medium(self) -> List[PackageFinding]:
+        return [f for f in self.findings if f.highest_severity == "MEDIUM"]
+
+    @property
+    def low(self) -> List[PackageFinding]:
+        return [f for f in self.findings if f.highest_severity == "LOW"]
+
+    @property
+    def highest_severity(self) -> Optional[str]:
+        for sev in ("CRITICAL", "HIGH", "MEDIUM", "LOW"):
+            if any(f.highest_severity == sev for f in self.findings):
+                return sev
+        return None
+
+    def to_dict(self) -> Dict[str, Any]:
+        result: Dict[str, Any] = {}
+        for sev in ("CRITICAL", "HIGH", "MEDIUM", "LOW"):
+            items = [f for f in self.findings if f.highest_severity == sev]
+            if items:
+                result[sev] = [
+                    {
+                        "package": f.package,
+                        "version": f.version,
+                        "fix": f.fix_versions[0] if f.fix_versions else None,
+                        "vulnerabilities": [
+                            {"id": v.cve or v.id, "summary": v.summary, "severity": v.severity}
+                            for v in f.vulnerabilities
+                        ],
+                    }
+                    for f in items
+                ]
+        return result

dep_scanner/_osv.py

@@ -0,0 +1,151 @@
+"""OSV.dev API client for dep-scanner.
+
+Uses the batch query endpoint to check multiple packages in one request.
+No API key required — OSV.dev is free and open.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+OSV_BATCH_URL = "https://api.osv.dev/v1/querybatch"
+BATCH_SIZE = 100          # OSV hard limit is 1000; we use 100 for safety
+TIMEOUT = 30              # seconds
+
+
+# ---------------------------------------------------------------------------
+# Severity helpers
+# ---------------------------------------------------------------------------
+
+_SEV_MAP = {
+    "critical": "CRITICAL",
+    "high": "HIGH",
+    "moderate": "MEDIUM",
+    "medium": "MEDIUM",
+    "low": "LOW",
+}
+
+
+def _parse_severity(vuln: Dict[str, Any]) -> str:
+    # 1. database_specific.severity (GitHub Advisory style — most reliable)
+    db = vuln.get("database_specific") or {}
+    raw = str(db.get("severity", "")).lower()
+    if raw in _SEV_MAP:
+        return _SEV_MAP[raw]
+
+    # 2. database_specific.cvss_score (numeric)
+    score = db.get("cvss_score")
+    if score is not None:
+        return _score_to_sev(float(score))
+
+    # 3. severity array (CVSS vector or numeric string)
+    for entry in vuln.get("severity") or []:
+        raw_score = entry.get("score", "")
+        try:
+            return _score_to_sev(float(raw_score))
+        except (ValueError, TypeError):
+            pass
+
+    return "MEDIUM"     # conservative default
+
+
+def _score_to_sev(score: float) -> str:
+    if score >= 9.0:
+        return "CRITICAL"
+    if score >= 7.0:
+        return "HIGH"
+    if score >= 4.0:
+        return "MEDIUM"
+    return "LOW"
+
+
+def _extract_fixed_versions(vuln: Dict[str, Any]) -> List[str]:
+    fixed: set = set()
+    for affected in vuln.get("affected") or []:
+        for rng in affected.get("ranges") or []:
+            if rng.get("type") == "ECOSYSTEM":
+                for event in rng.get("events") or []:
+                    if "fixed" in event:
+                        fixed.add(event["fixed"])
+    return sorted(fixed)
+
+
+def _get_cve(vuln: Dict[str, Any]) -> str:
+    for alias in vuln.get("aliases") or []:
+        if alias.startswith("CVE-"):
+            return alias
+    return ""
+
+
+def _parse_vuln(raw: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "id": raw.get("id", ""),
+        "cve": _get_cve(raw),
+        "aliases": raw.get("aliases") or [],
+        "summary": raw.get("summary", ""),
+        "details": (raw.get("details") or "")[:500],
+        "severity": _parse_severity(raw),
+        "fixed_versions": _extract_fixed_versions(raw),
+        "published": (raw.get("published") or "")[:10],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Batch query
+# ---------------------------------------------------------------------------
+
+def query_batch(packages: List[Dict[str, str]]) -> List[List[Dict[str, Any]]]:
+    """
+    Query OSV.dev for vulnerabilities in a list of packages.
+
+    Parameters
+    ----------
+    packages:
+        [{"name": "requests", "version": "2.27.0", "ecosystem": "PyPI"}, ...]
+
+    Returns
+    -------
+    Parallel list of vulnerability lists — one entry per input package.
+    Empty list means no known vulnerabilities for that package.
+    """
+    if not packages:
+        return []
+
+    all_results: List[List[Dict[str, Any]]] = []
+
+    for i in range(0, len(packages), BATCH_SIZE):
+        batch = packages[i : i + BATCH_SIZE]
+        payload = {
+            "queries": [
+                {
+                    "version": p["version"],
+                    "package": {"name": p["name"], "ecosystem": p["ecosystem"]},
+                }
+                for p in batch
+            ]
+        }
+        req = Request(
+            OSV_BATCH_URL,
+            data=json.dumps(payload).encode(),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": "dep-scanner/0.1.0 (https://github.com/SpiderCob/dep-scanner)",
+            },
+        )
+        try:
+            with urlopen(req, timeout=TIMEOUT) as resp:
+                data = json.loads(resp.read().decode())
+        except HTTPError as exc:
+            raise RuntimeError(f"OSV.dev API returned HTTP {exc.code}") from exc
+        except URLError as exc:
+            raise RuntimeError(f"OSV.dev API unreachable: {exc.reason}") from exc
+
+        for result in data.get("results") or []:
+            raw_vulns = result.get("vulns") or []
+            all_results.append([_parse_vuln(v) for v in raw_vulns])
+
+    return all_results

dep_scanner/_parsers.py

@@ -0,0 +1,237 @@
+"""Manifest file parsers for dep-scanner.
+
+Each parser returns List[Tuple[name, version, ecosystem]].
+Only pinned / resolved versions are returned — unpinned ranges
+cannot be looked up in OSV and are silently skipped.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import xml.etree.ElementTree as ET
+from typing import Dict, List, Optional, Tuple
+
+# Ecosystem labels used by OSV.dev
+ECOSYSTEM_MAP: Dict[str, str] = {
+    "requirements": "PyPI",
+    "package_json": "npm",
+    "package_lock": "npm",
+    "go_mod": "Go",
+    "cargo_toml": "crates.io",
+    "pom_xml": "Maven",
+}
+
+Package = Tuple[str, str, str]  # (name, version, ecosystem)
+
+
+# ---------------------------------------------------------------------------
+# Manifest type detection
+# ---------------------------------------------------------------------------
+
+def detect_manifest(path: str) -> Optional[str]:
+    name = os.path.basename(path).lower()
+    if name == "package-lock.json":
+        return "package_lock"
+    if name == "package.json":
+        return "package_json"
+    if name == "go.mod":
+        return "go_mod"
+    if name in ("cargo.toml",):
+        return "cargo_toml"
+    if name == "pom.xml":
+        return "pom_xml"
+    # requirements.txt, requirements-dev.txt, requirements/*.txt …
+    if "requirements" in name and name.endswith(".txt"):
+        return "requirements"
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Individual parsers
+# ---------------------------------------------------------------------------
+
+def parse_requirements(content: str) -> List[Package]:
+    """Parse requirements.txt — only pinned (==) versions."""
+    packages: List[Package] = []
+    for line in content.splitlines():
+        line = line.strip()
+        if not line or line.startswith(("#", "-")):
+            continue
+        line = line.split("#")[0].split(";")[0].strip()
+        m = re.match(r"^([A-Za-z0-9_.-]+)\s*==\s*([^\s,]+)", line)
+        if m:
+            name = m.group(1).lower().replace("_", "-")
+            packages.append((name, m.group(2).strip(), "PyPI"))
+    return packages
+
+
+def parse_package_json(content: str) -> List[Package]:
+    """Parse package.json dependencies + devDependencies."""
+    try:
+        data = json.loads(content)
+    except Exception:
+        return []
+
+    packages: List[Package] = []
+    for section in ("dependencies", "devDependencies", "peerDependencies"):
+        for name, spec in (data.get(section) or {}).items():
+            if not isinstance(spec, str):
+                continue
+            if spec in ("*", "latest", "next", "beta") or re.match(r"^(file:|git[+@]|http)", spec):
+                continue
+            # Strip leading range operators and take first part
+            clean = re.sub(r"^[\^~>=<v]+", "", spec.split("||")[0].strip())
+            clean = re.split(r"\s+", clean)[0]
+            if re.match(r"^\d+\.\d+", clean):
+                packages.append((name, clean, "npm"))
+    return packages
+
+
+def parse_package_lock(content: str) -> List[Package]:
+    """Parse package-lock.json (v1, v2, v3)."""
+    try:
+        data = json.loads(content)
+    except Exception:
+        return []
+
+    packages: List[Package] = []
+
+    if "packages" in data:
+        # v2 / v3
+        for path, info in data["packages"].items():
+            if not path or not isinstance(info, dict) or info.get("link"):
+                continue
+            version = info.get("version", "")
+            if version and re.match(r"^\d+\.\d+", version):
+                name = re.sub(r"^.*node_modules/", "", path)
+                packages.append((name, version, "npm"))
+    elif "dependencies" in data:
+        # v1
+        def _walk(deps: dict) -> None:
+            for name, info in deps.items():
+                if not isinstance(info, dict):
+                    continue
+                ver = info.get("version", "")
+                if ver and re.match(r"^\d+\.\d+", ver):
+                    packages.append((name, ver, "npm"))
+                if "dependencies" in info:
+                    _walk(info["dependencies"])
+        _walk(data["dependencies"])
+
+    return packages
+
+
+def parse_go_mod(content: str) -> List[Package]:
+    """Parse go.mod require blocks."""
+    packages: List[Package] = []
+    in_block = False
+
+    for line in content.splitlines():
+        line = line.strip()
+        if re.match(r"^require\s*\(", line):
+            in_block = True
+            continue
+        if in_block and line == ")":
+            in_block = False
+            continue
+        # single-line: require github.com/foo/bar v1.2.3
+        m = re.match(r"^require\s+(\S+)\s+(v[\d.][^\s]*)", line)
+        if m:
+            packages.append((m.group(1), m.group(2), "Go"))
+            continue
+        if in_block and not line.startswith("//"):
+            m = re.match(r"^(\S+)\s+(v[\d.][^\s]*)", line)
+            if m:
+                packages.append((m.group(1), m.group(2), "Go"))
+
+    return packages
+
+
+def parse_cargo_toml(content: str) -> List[Package]:
+    """Parse Cargo.toml [dependencies] / [dev-dependencies] sections."""
+    packages: List[Package] = []
+    in_deps = False
+
+    for line in content.splitlines():
+        stripped = line.strip()
+        if stripped in ("[dependencies]", "[dev-dependencies]", "[build-dependencies]"):
+            in_deps = True
+            continue
+        if in_deps and stripped.startswith("["):
+            in_deps = False
+            continue
+        if not in_deps or not stripped or stripped.startswith("#"):
+            continue
+
+        # name = "1.0.0"  or  name = "^1.0.0"
+        m = re.match(r'^([a-zA-Z0-9_-]+)\s*=\s*"([^"]+)"', stripped)
+        if m:
+            ver = re.sub(r"^[\^~>=<]+", "", m.group(2))
+            if re.match(r"^\d+", ver):
+                packages.append((m.group(1), ver, "crates.io"))
+            continue
+
+        # name = { version = "1.0.0", ... }
+        m = re.match(r'^([a-zA-Z0-9_-]+)\s*=\s*\{[^}]*version\s*=\s*"([^"]+)"', stripped)
+        if m:
+            ver = re.sub(r"^[\^~>=<]+", "", m.group(2))
+            if re.match(r"^\d+", ver):
+                packages.append((m.group(1), ver, "crates.io"))
+
+    return packages
+
+
+def parse_pom_xml(content: str) -> List[Package]:
+    """Parse Maven pom.xml <dependency> blocks."""
+    packages: List[Package] = []
+    try:
+        root = ET.fromstring(content)
+    except Exception:
+        return []
+
+    ns = ""
+    if root.tag.startswith("{"):
+        ns = root.tag.split("}")[0] + "}"
+
+    for dep in root.iter(f"{ns}dependency"):
+        group = (dep.findtext(f"{ns}groupId") or "").strip()
+        artifact = (dep.findtext(f"{ns}artifactId") or "").strip()
+        version = (dep.findtext(f"{ns}version") or "").strip()
+        if not (group and artifact and version) or version.startswith("$"):
+            continue
+        packages.append((f"{group}:{artifact}", version, "Maven"))
+
+    return packages
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+PARSERS = {
+    "requirements": parse_requirements,
+    "package_json": parse_package_json,
+    "package_lock": parse_package_lock,
+    "go_mod": parse_go_mod,
+    "cargo_toml": parse_cargo_toml,
+    "pom_xml": parse_pom_xml,
+}
+
+
+def parse_manifest(path: str) -> Tuple[List[Package], str]:
+    """
+    Parse a dependency manifest and return (packages, ecosystem).
+
+    Raises ValueError for unrecognised files.
+    """
+    manifest_type = detect_manifest(path)
+    if manifest_type is None:
+        raise ValueError(
+            f"Unrecognised manifest: {path}\n"
+            "Supported: requirements.txt, package.json, package-lock.json, "
+            "go.mod, Cargo.toml, pom.xml"
+        )
+    with open(path, encoding="utf-8", errors="replace") as fh:
+        content = fh.read()
+    return PARSERS[manifest_type](content), ECOSYSTEM_MAP[manifest_type]

dep_scanner/_scanner.py

@@ -0,0 +1,128 @@
+"""Core scanner logic for dep-scanner."""
+from __future__ import annotations
+
+import time
+from typing import Dict, List
+
+from ._models import PackageFinding, ScanResult, Vulnerability
+from ._osv import query_batch
+from ._parsers import ECOSYSTEM_MAP, PARSERS, detect_manifest, parse_manifest
+
+_SEV_ORDER = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3, None: 4}
+
+
+def _build_result(
+    raw_packages: list,
+    ecosystem: str,
+    source: str,
+    start: float,
+) -> ScanResult:
+    # Deduplicate by (name, version, ecosystem)
+    seen: set = set()
+    unique: List[Dict[str, str]] = []
+    for name, version, eco in raw_packages:
+        key = (name, version, eco)
+        if key not in seen:
+            seen.add(key)
+            unique.append({"name": name, "version": version, "ecosystem": eco})
+
+    if not unique:
+        return ScanResult(
+            source=source,
+            ecosystem=ecosystem,
+            packages_scanned=0,
+            findings=[],
+            elapsed_ms=int((time.time() - start) * 1000),
+        )
+
+    osv_results = query_batch(unique)
+
+    findings: List[PackageFinding] = []
+    for pkg, vulns in zip(unique, osv_results):
+        if not vulns:
+            continue
+        findings.append(
+            PackageFinding(
+                package=pkg["name"],
+                version=pkg["version"],
+                ecosystem=pkg["ecosystem"],
+                vulnerabilities=[Vulnerability._from_dict(v) for v in vulns],
+            )
+        )
+
+    findings.sort(key=lambda f: _SEV_ORDER.get(f.highest_severity, 4))
+
+    return ScanResult(
+        source=source,
+        ecosystem=ecosystem,
+        packages_scanned=len(unique),
+        findings=findings,
+        elapsed_ms=int((time.time() - start) * 1000),
+    )
+
+
+def scan(path: str) -> ScanResult:
+    """
+    Scan a dependency manifest file for known CVEs via OSV.dev.
+
+    Supported files: requirements.txt, package.json, package-lock.json,
+    go.mod, Cargo.toml, pom.xml
+
+    Parameters
+    ----------
+    path:
+        Path to the manifest file.
+
+    Returns
+    -------
+    ScanResult
+        Findings grouped by severity with fix versions.
+
+    Examples
+    --------
+    >>> import dep_scanner
+    >>> result = dep_scanner.scan("requirements.txt")
+    >>> result.highest_severity
+    'CRITICAL'
+    >>> result.critical[0].package
+    'requests'
+    >>> result.critical[0].fix_versions
+    ['2.31.0']
+    """
+    start = time.time()
+    packages, ecosystem = parse_manifest(path)
+    return _build_result(packages, ecosystem, path, start)
+
+
+def scan_text(content: str, ecosystem: str, source: str = "<text>") -> ScanResult:
+    """
+    Scan dependency file content directly (no file needed).
+
+    Parameters
+    ----------
+    content:
+        Raw manifest content as a string.
+    ecosystem:
+        One of: "PyPI", "npm", "Go", "crates.io", "Maven"
+    source:
+        Label shown in results (default: "<text>").
+
+    Examples
+    --------
+    >>> result = dep_scanner.scan_text(
+    ...     "requests==2.27.0\\ndjango==3.2.1",
+    ...     ecosystem="PyPI",
+    ... )
+    """
+    start = time.time()
+
+    eco_to_type = {v: k for k, v in ECOSYSTEM_MAP.items()}
+    manifest_type = eco_to_type.get(ecosystem)
+    if not manifest_type:
+        raise ValueError(
+            f"Unknown ecosystem: {ecosystem!r}. "
+            f"Valid options: {sorted(ECOSYSTEM_MAP.values())}"
+        )
+
+    packages = PARSERS[manifest_type](content)
+    return _build_result(packages, ecosystem, source, start)

osv_scan-0.1.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: osv-scan
+Version: 0.1.0
+Summary: Zero-dependency CVE scanner for dependency manifests — wraps the free OSV.dev API
+Project-URL: Homepage, https://github.com/SpiderCob/dep-scanner
+Project-URL: Repository, https://github.com/SpiderCob/dep-scanner
+Project-URL: Issues, https://github.com/SpiderCob/dep-scanner/issues
+Author-email: SpiderCob <dev@spidercob.com>
+License: Apache-2.0
+Keywords: cve,dependencies,osv,security,vulnerability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# dep-scanner
+
+Zero-dependency Python library that scans your dependency manifests for known CVEs using the free [OSV.dev](https://osv.dev) API.
+
+No API key. No signup. No rate limits for normal use.
+
+```
+pip install osv-scan
+```
+
+---
+
+## Why
+
+- `safety` went paid in 2023
+- `osv-scanner` is a Go binary — not embeddable in Python
+- `pip-audit` is great but Python-only and pulls in several dependencies
+
+`dep-scanner` fills the gap: a **pure stdlib** Python library that scans six ecosystems and works anywhere Python runs.
+
+---
+
+## Supported manifest files
+
+| File | Ecosystem |
+|---|---|
+| `requirements.txt` | PyPI |
+| `package.json` | npm |
+| `package-lock.json` | npm |
+| `go.mod` | Go |
+| `Cargo.toml` | crates.io |
+| `pom.xml` | Maven |
+
+---
+
+## CLI
+
+```bash
+# auto-detect manifest in current directory
+dep-scan
+
+# scan a specific file
+dep-scan requirements.txt
+
+# multiple files
+dep-scan requirements.txt package-lock.json
+
+# JSON output (great for CI)
+dep-scan --json requirements.txt
+
+# fail CI only on HIGH or above (default: critical)
+dep-scan --fail-on high requirements.txt
+
+# quiet mode — only print findings
+dep-scan -q requirements.txt
+```
+
+### Example output
+
+```
+dep-scan  requirements.txt (PyPI) · 42 packages
+
+  CRITICAL  django 3.2.1
+             CVE-2023-36053
+             Potential ReDoS via cached 'urlsplit' results
+             Fix: upgrade to 3.2.20
+
+  HIGH      requests 2.27.0
+             CVE-2023-32681
+             Unintended leak of proxy-authorization header
+             Fix: upgrade to 2.31.0
+
+  1 CRITICAL · 1 HIGH  (2 vulns · 840ms)
+```
+
+---
+
+## Python API
+
+```python
+import dep_scanner
+
+# scan a file on disk
+result = dep_scanner.scan("requirements.txt")
+
+print(result.highest_severity)       # 'CRITICAL'
+print(result.packages_scanned)       # 42
+print(len(result.findings))          # 3
+
+for finding in result.critical:
+    print(finding.package, finding.version)
+    print("Fix:", finding.fix_versions[0] if finding.fix_versions else "none")
+
+# scan content directly (no file needed)
+result = dep_scanner.scan_text(
+    "requests==2.27.0\ndjango==3.2.1",
+    ecosystem="PyPI",
+)
+
+# convert to dict
+data = result.to_dict()
+# {
+#   "CRITICAL": [{"package": "django", "version": "3.2.1", ...}],
+#   "HIGH": [{"package": "requests", ...}],
+# }
+```
+
+### ScanResult properties
+
+| Property | Type | Description |
+|---|---|---|
+| `source` | `str` | File path or label |
+| `ecosystem` | `str` | e.g. `"PyPI"` |
+| `packages_scanned` | `int` | Total unique packages checked |
+| `findings` | `list[PackageFinding]` | Packages with vulnerabilities |
+| `elapsed_ms` | `int` | Wall time in milliseconds |
+| `highest_severity` | `str \| None` | `"CRITICAL"`, `"HIGH"`, `"MEDIUM"`, `"LOW"` |
+| `critical` | `list[PackageFinding]` | Only CRITICAL findings |
+| `high` | `list[PackageFinding]` | Only HIGH findings |
+| `has_findings` | `bool` | True if any vulnerabilities found |
+
+---
+
+## GitHub Actions
+
+```yaml
+- name: Scan dependencies
+  run: |
+    pip install dep-scanner
+    dep-scan --fail-on high requirements.txt
+```
+
+---
+
+## pre-commit hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/SpiderCob/dep-scanner
+    rev: v0.1.0
+    hooks:
+      - id: dep-scan
+```
+
+---
+
+## How it works
+
+1. Parses your manifest file to extract `(name, version, ecosystem)` tuples
+2. Sends a single batch POST to `https://api.osv.dev/v1/querybatch`
+3. Parses severity from `database_specific.severity` → `cvss_score` → CVSS vector
+4. Returns structured findings sorted by severity
+
+Packages with unpinned version ranges (`^1.0`, `>=2.0`) are skipped — OSV requires exact versions.
+
+---
+
+## License
+
+Apache 2.0 — free to use in commercial projects.
+
+Built by [SpiderCob](https://spidercob.com).

osv_scan-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dep_scanner/__init__.py,sha256=VQ-zOvRopjnIefIrGt6aVbHcsAwJ2K8fJl5lCuOHvk8,359
+dep_scanner/_cli.py,sha256=cJOh5nSD8Hs9lg0wEmflJeomA8NOcCKEsUbfzicNUTE,5483
+dep_scanner/_models.py,sha256=wm0Ymqb1DLWi22Sm0KdgysW1D70z5_9Mq3gcA6bRwo4,3422
+dep_scanner/_osv.py,sha256=0Rj03xQMHqnuYqe47G1SNlM611r-M1_H98ssvOks9BE,4717
+dep_scanner/_parsers.py,sha256=vIM6FbfPAP1PbURnElaz6AfgDUgKqzasxmazl82STSc,7982
+dep_scanner/_scanner.py,sha256=qjmwDpMHXq_aBRNaEBE_JPjaocDtnq77QXnd9q3qM8Y,3493
+osv_scan-0.1.0.dist-info/METADATA,sha256=_698OYmPlZyNI3DHNiAWljM16zOeqxify2Z2zp_UG4g,4760
+osv_scan-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+osv_scan-0.1.0.dist-info/entry_points.txt,sha256=MDeNvQCfST0ZAyNLIzqSBTp0wCnCCmj0gWQrVC-gXqY,51
+osv_scan-0.1.0.dist-info/RECORD,,

osv_scan-0.1.0.dist-info/WHEEL

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

osv_scan-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dep-scan = dep_scanner._cli:main