vulnlens 0.3.0__py3-none-any.whl

vulnlens/__init__.py

@@ -0,0 +1,3 @@
+"""VulnLens: find the security findings that actually matter."""
+
+__version__ = "0.3.0"

vulnlens/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

vulnlens/cli.py

@@ -0,0 +1,278 @@
+"""Command-line interface: `vulnlens scan <path-or-repo-url>`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import traceback
+from pathlib import Path
+
+from . import __version__, net
+from .engines import ALIASES, ENGINES, resolve_engine
+from .htmlreport import render_html
+from .ignore import IgnoreRules
+from .models import PRIORITIES
+from .report import render, use_color
+from .sarif import to_sarif
+from .scan import run_scan
+from .source import TargetError, is_remote, may_verify_secrets, resolve_target
+from .triage import DEFAULT_MODEL, Triager
+
+EXIT_OK, EXIT_FINDINGS, EXIT_ERROR = 0, 1, 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="vulnlens",
+        description="Scan code, dependencies and secrets, then rank findings by real-world exploitability.",
+    )
+    p.add_argument("--version", action="version", version=f"vulnlens {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("scan", help="scan a local directory or a public git repository URL")
+    s.add_argument("target", help="directory path or https://github.com/owner/repo")
+    s.add_argument("-f", "--format", choices=["table", "json", "sarif"], default="table",
+                   help="output format for stdout / --output (default: table)")
+    s.add_argument("-o", "--output", type=Path, help="write the --format output to this file instead of stdout")
+    s.add_argument("--sarif", type=Path, metavar="FILE", help="also write a SARIF 2.1.0 file")
+    s.add_argument("--json", type=Path, metavar="FILE", dest="json_out", help="also write a JSON report")
+    s.add_argument("--html", type=Path, metavar="FILE", dest="html_out",
+                   help="also write a standalone HTML report (the dashboard, no server needed)")
+    s.add_argument("--engines", default=",".join(ENGINES),
+                   help=f"comma-separated engines to run (default: {','.join(ENGINES)})")
+    s.add_argument("--offline", action="store_true",
+                   help="no network: skip OSV lookups, KEV/EPSS enrichment and secret verification")
+    s.add_argument("--ai-triage", action="store_true",
+                   help="have Claude review each code finding in context "
+                        "(needs ANTHROPIC_API_KEY; sends code snippets to the API)")
+    s.add_argument("--ai-model", default=DEFAULT_MODEL, help=f"model for --ai-triage (default: {DEFAULT_MODEL})")
+    s.add_argument("--ai-max-cost", type=float, default=2.0, metavar="USD",
+                   help="skip triage if its estimated cost is above this (default: 2.00)")
+    s.add_argument("--ai-dry-run", action="store_true",
+                   help="print how many findings triage would review and the estimated cost, then send nothing")
+    s.add_argument("--ai-effort", default="medium", choices=["low", "medium", "high", "xhigh", "max"],
+                   help="reasoning effort for --ai-triage (default: medium)")
+    s.add_argument("--ai-max", type=int, default=50, metavar="N",
+                   help="review at most N code findings, most urgent first (default: 50)")
+    s.add_argument("--no-verify-secrets", action="store_true",
+                   help="do not test found credentials against their provider (remote repository URLs are "
+                        "never verified; use this for local copies of code you don't own)")
+    s.add_argument("--fail-on", choices=[*PRIORITIES, "act", "review"], metavar="{act,review,P0-P4}",
+                   help="exit 1 if any finding is in the Act-now tier (act), in Act or Review (review), or at this "
+                        "priority or more urgent (P0-P4); exit 2 if an engine did not run (for CI)")
+    s.add_argument("--exclude", action="append", default=[], metavar="GLOB",
+                   help="skip findings in matching paths, e.g. 'tests/**' (repeatable)")
+    s.add_argument("--baseline", type=Path, metavar="REPORT.json",
+                   help="only report findings that are not in this earlier JSON report (for CI on pull requests)")
+    s.add_argument("--ignore-file", type=Path, metavar="FILE",
+                   help="extra ignore rules in .vulnlensignore format (the scan root's .vulnlensignore is "
+                        "read automatically for local scans)")
+    s.add_argument("--top", type=int, default=15, help="findings to show in the table (default: 15)")
+    s.add_argument("--semgrep-config", default="p/default", help="Semgrep ruleset (default: p/default)")
+    s.add_argument("--bin-dir", type=Path, help="directory containing semgrep/trufflehog binaries")
+    s.add_argument("--no-cache", action="store_true", help="do not read or write the intel cache")
+    s.add_argument("--no-color", action="store_true")
+    s.add_argument("-q", "--quiet", action="store_true", help="no progress messages on stderr")
+
+    t = sub.add_parser("html", help="turn saved JSON reports (from scan --json) into one standalone HTML page")
+    t.add_argument("reports", nargs="+", type=Path, metavar="REPORT.json")
+    t.add_argument("-o", "--output", type=Path, required=True, help="HTML file to write")
+    t.add_argument("--title", help="page title")
+
+    d = sub.add_parser("doctor", help="check that the scan engines are installed and current, and how to fix them")
+    d.add_argument("--bin-dir", type=Path, help="directory containing semgrep/trufflehog binaries")
+    d.add_argument("--offline", action="store_true", help="skip the network reachability checks")
+
+    v = sub.add_parser("serve", help="start the local web dashboard")
+    v.add_argument("--host", default="127.0.0.1", help="interface to bind (default: 127.0.0.1, local only)")
+    v.add_argument("--port", type=int, default=8765, help="port (default: 8765; 0 picks a free one)")
+    v.add_argument("--load", type=Path, action="append", default=[], metavar="REPORT.json",
+                   help="preload a JSON report written by `scan --json` (repeatable)")
+    v.add_argument("--semgrep-config", default="p/default", help="Semgrep ruleset (default: p/default)")
+    v.add_argument("--bin-dir", type=Path, help="directory containing semgrep/trufflehog binaries")
+    v.add_argument("--open", action="store_true", help="open the dashboard in your browser")
+    v.add_argument("--no-history", action="store_true",
+                   help="do not save finished scans or restore earlier ones (kept in the VulnLens cache folder)")
+    return p
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    from .doctor import render, run_checks
+
+    checks = run_checks(bin_dir=args.bin_dir, offline=args.offline)
+    print(render(checks))
+    return EXIT_OK if all(c.ok for c in checks if c.required) else EXIT_FINDINGS
+
+
+def cmd_html(args: argparse.Namespace) -> int:
+    reports = []
+    for path in args.reports:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as e:
+            print(f"vulnlens: could not read {path}: {e}", file=sys.stderr)
+            return EXIT_ERROR
+        if "findings" not in data or "summary" not in data:
+            print(f"vulnlens: {path} is not a VulnLens JSON report", file=sys.stderr)
+            return EXIT_ERROR
+        reports.append(data)
+    _write(args.output, render_html(reports, title=args.title))
+    print(f"wrote {args.output} ({len(reports)} report(s))", file=sys.stderr)
+    return EXIT_OK
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    import webbrowser
+
+    from .server import ScanStore, serve
+
+    if args.host not in ("127.0.0.1", "localhost", "::1"):
+        print(f"vulnlens: warning: binding to {args.host} exposes the dashboard (and the ability to start "
+              "scans) to your network", file=sys.stderr)
+    store = ScanStore(bin_dir=args.bin_dir, semgrep_config=args.semgrep_config,
+                      history_dir=None if args.no_history else net.default_cache_dir() / "history")
+    for path in args.load:
+        try:
+            store.load_report(path)
+        except (OSError, ValueError) as e:
+            print(f"vulnlens: could not load {path}: {e}", file=sys.stderr)
+            return EXIT_ERROR
+
+    def ready(url: str) -> None:
+        print(f"VulnLens dashboard running at {url}  (Ctrl+C to stop)", flush=True)
+        if args.open:
+            webbrowser.open(url)
+
+    try:
+        serve(args.host, args.port, store, on_ready=ready)
+    except OSError as e:
+        print(f"vulnlens: could not start server on {args.host}:{args.port}: {e}", file=sys.stderr)
+        return EXIT_ERROR
+    return EXIT_OK
+
+
+def _write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _next_steps(args: argparse.Namespace, report) -> list[str]:
+    """What a first-time user should do after reading the table."""
+    s, hints = report.summary, []
+    target = args.target if " " not in args.target else f'"{args.target}"'
+    if not s["complete"]:
+        hints.append("vulnlens doctor                      see which engine is missing and how to install it")
+    if not args.html_out:
+        hints.append(f"vulnlens scan {target} --html report.html   full interactive report (one offline file)")
+    if s.get("by_tier", {}).get("review") and not args.ai_triage:
+        hints.append("add --ai-dry-run, then --ai-triage    let Claude judge the Review pile (shows the cost first)")
+    if not args.fail_on:
+        hints.append("add it to CI: see 'GitHub Action' in the README (fails the build on Act-now findings)")
+    return hints
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    requested = [e.strip() for e in args.engines.split(",") if e.strip()]
+    unknown = [e for e in requested if not resolve_engine(e)]
+    engines = list(dict.fromkeys(resolve_engine(e) for e in requested if resolve_engine(e)))
+    if unknown:
+        names = ", ".join(f"{k} ({v})" for v, k in ALIASES.items())
+        print(f"vulnlens: unknown engine(s): {', '.join(unknown)} (choose from {names})", file=sys.stderr)
+        return EXIT_ERROR
+
+    def progress(msg: str) -> None:
+        if not args.quiet:
+            print(f"[vulnlens] {msg}", file=sys.stderr, flush=True)
+
+    verify = may_verify_secrets(args.target, requested=not args.no_verify_secrets)
+    if is_remote(args.target) and not args.no_verify_secrets:
+        progress("secret verification is off for remote repositories (their credentials are not yours to test)")
+    try:
+        with resolve_target(args.target) as root:
+            progress(f"cloned {args.target}" if is_remote(args.target) else f"scanning {root}")
+            report = run_scan(
+                root,
+                target_label=args.target,
+                engines=engines,
+                offline=args.offline,
+                verify_secrets=verify,
+                triager=(Triager(model=args.ai_model, effort=args.ai_effort, max_findings=args.ai_max,
+                                 cache=net.Cache(enabled=not args.no_cache), max_cost=args.ai_max_cost,
+                                 dry_run=args.ai_dry_run)
+                         if args.ai_triage or args.ai_dry_run else None),
+                semgrep_config=args.semgrep_config,
+                bin_dir=args.bin_dir,
+                cache=net.Cache(enabled=not args.no_cache),
+                progress=progress,
+                ignore=IgnoreRules.load(root, excludes=args.exclude, baseline=args.baseline,
+                                        trust_repo=not is_remote(args.target), ignore_file=args.ignore_file),
+            )
+    except TargetError as e:
+        print(f"vulnlens: {e}", file=sys.stderr)
+        return EXIT_ERROR
+
+    outputs = {
+        "table": lambda: render(report, top=args.top, color=use_color() and not args.no_color and not args.output,
+                                hints=_next_steps(args, report)),
+        "json": lambda: json.dumps(report.to_dict(), indent=2),
+        "sarif": lambda: json.dumps(to_sarif(report.findings), indent=2),
+    }
+    main_out = outputs[args.format]()
+    if args.output:
+        _write(args.output, main_out)
+        progress(f"wrote {args.format} report to {args.output}")
+    else:
+        sys.stdout.write(main_out if main_out.endswith("\n") else main_out + "\n")
+    if args.sarif:
+        _write(args.sarif, outputs["sarif"]())
+        progress(f"wrote SARIF to {args.sarif}")
+    if args.json_out:
+        _write(args.json_out, outputs["json"]())
+        progress(f"wrote JSON to {args.json_out}")
+    if args.html_out:
+        _write(args.html_out, render_html([report.to_dict()], title=args.target))
+        progress(f"wrote HTML report to {args.html_out}")
+
+    summary = report.summary
+    if not summary["complete"]:
+        progress(f"warning: scan incomplete ({', '.join(summary['incomplete_engines'])} did not run); "
+                 "`vulnlens doctor` shows what is missing")
+    if args.fail_on:
+        if not summary["complete"]:
+            return EXIT_ERROR  # a CI gate must not pass on a scan that did not fully run
+        if args.fail_on in ("act", "review"):
+            tiers = {"act"} if args.fail_on == "act" else {"act", "review"}
+            failing = any(f.tier in tiers for f in report.findings)
+        else:
+            threshold = PRIORITIES.index(args.fail_on)
+            failing = any(PRIORITIES.index(f.priority) <= threshold for f in report.findings)
+        if failing:
+            return EXIT_FINDINGS
+    return EXIT_OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    args = build_parser().parse_args(argv)
+    commands = {"scan": cmd_scan, "serve": cmd_serve, "html": cmd_html, "doctor": cmd_doctor}
+    try:
+        return commands[args.command](args)
+    except KeyboardInterrupt:
+        print("vulnlens: interrupted", file=sys.stderr)
+        return 130
+    except Exception as e:
+        # Exit 1 means "findings at or above --fail-on". A crash must never look like that to CI.
+        if os.environ.get("VULNLENS_DEBUG"):
+            traceback.print_exc()
+        print(f"vulnlens: internal error: {type(e).__name__}: {e}"
+              + ("" if os.environ.get("VULNLENS_DEBUG") else " (set VULNLENS_DEBUG=1 for the traceback)"),
+              file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vulnlens/context.py

@@ -0,0 +1,39 @@
+"""Where a finding lives: production code, or tests / examples / docs / vendored third-party code.
+
+The same bug matters far less in a test fixture or an example notebook than in the shipped app,
+and in the 50-repo study 62% of secret hits and over a fifth of code and dependency findings were
+in such paths. Prioritization caps non-production findings at P3 "Low" (see priority.py).
+"""
+
+from __future__ import annotations
+
+import re
+
+CONTEXTS = ("prod", "test", "example", "docs", "vendored")
+LABELS = {"test": "test code", "example": "example code", "docs": "documentation", "vendored": "vendored third-party code"}
+
+_RULES = [
+    ("vendored", re.compile(r"(^|/)(vendor|vendored|third[_-]?party|external|extern|bower_components|site-packages)(/|$)"
+                            r"|\.min\.(js|css)$|\.bundle\.js$", re.I)),
+    ("test", re.compile(r"(^|/)(tests?|testing|__tests__|__mocks__|specs?|fixtures?|mocks?|testdata|e2e)(/|$)"
+                        r"|(^|/)(tests?[_-][^/]*|[^/]*[_-]tests?\.[a-z0-9]+|[^/]*\.(test|spec)\.[a-z0-9]+|conftest\.py)$",
+                        re.I)),
+    ("example", re.compile(r"(^|/)(examples?|samples?|demos?|cookbooks?|tutorials?|notebooks?|playground|"
+                           r"research_projects|benchmarks?)(/|$)|\.ipynb$", re.I)),
+    ("docs", re.compile(r"(^|/)(docs?|documentation)(/|$)|\.(md|mdx|rst|adoc)$", re.I)),
+]
+
+
+def classify(path: str | None) -> str:
+    if not path:
+        return "prod"
+    for context, pattern in _RULES:
+        if pattern.search(path):
+            return context
+    return "prod"
+
+
+def best(paths: list[str | None]) -> str:
+    """Context of a finding seen in several files: production wins, since that's where it matters."""
+    found = [classify(p) for p in paths] or ["prod"]
+    return "prod" if "prod" in found else found[0]

vulnlens/doctor.py

@@ -0,0 +1,102 @@
+"""`vulnlens doctor`: check that every engine is installed and current, and say exactly how to fix it.
+
+`pip install vulnlens` brings no scanners, so without this a first scan just says "INCOMPLETE".
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import net
+from .engines.base import find_tool
+from .engines.secrets import MIN_VERSION, RECOMMENDED_VERSION, tool_version
+from .engines.semgrep import _semgrep_version
+from .intel.exploit import EPSS_API, KEV_FEED
+from .intel.osv import OSV_API
+
+RELEASES = "https://github.com/trufflesecurity/trufflehog/releases"
+
+
+@dataclass
+class Check:
+    name: str
+    ok: bool
+    detail: str
+    fix: str = ""
+    required: bool = True
+
+
+def _trufflehog_fix() -> str:
+    v = RECOMMENDED_VERSION
+    system = platform.system()
+    if system == "Darwin":
+        return "brew install trufflehog"
+    arch = "arm64" if platform.machine().lower() in ("arm64", "aarch64") else "amd64"
+    os_name = "windows" if system == "Windows" else "linux"
+    return (f"download trufflehog_{v}_{os_name}_{arch}.tar.gz and trufflehog_{v}_checksums.txt from "
+            f"{RELEASES}/tag/v{v}, check the SHA-256, extract it, and put trufflehog on your PATH "
+            "(or pass --bin-dir to vulnlens)")
+
+
+def run_checks(bin_dir: Path | None = None, offline: bool = False) -> list[Check]:
+    checks = [Check("python", sys.version_info >= (3, 10), platform.python_version(), "VulnLens needs Python 3.10+")]
+    checks.append(Check("git", bool(shutil.which("git")), shutil.which("git") or "not found",
+                        "install git (needed to scan repository URLs)", required=False))
+
+    semgrep = find_tool("semgrep", bin_dir) or find_tool("pysemgrep", bin_dir)
+    if semgrep:
+        checks.append(Check("semgrep", True, f"{_semgrep_version(semgrep) or 'unknown version'} at {semgrep}"))
+    else:
+        checks.append(Check("semgrep", False, "not found", 'pip install semgrep   (or: pip install "vulnlens[semgrep]")'))
+
+    trufflehog = find_tool("trufflehog", bin_dir)
+    if trufflehog:
+        version = tool_version(trufflehog)
+        shown = ".".join(map(str, version)) if version else "unknown version"
+        current = version is not None and version >= MIN_VERSION
+        checks.append(Check("trufflehog", current, f"{shown} at {trufflehog}",
+                            "" if current else f"outdated (noisy detectors); upgrade to {RECOMMENDED_VERSION}: "
+                            + _trufflehog_fix()))
+    else:
+        checks.append(Check("trufflehog", False, "not found", _trufflehog_fix()))
+
+    if not offline:
+        for name, url in (("osv.dev", f"{OSV_API}/vulns/GHSA-jfh8-c2jp-5v3q"), ("CISA KEV", KEV_FEED),
+                          ("FIRST EPSS", f"{EPSS_API}?cve=CVE-2021-44228")):
+            try:
+                net.get_json(url, timeout=20)
+                checks.append(Check(name, True, "reachable"))
+            except net.NetworkError as e:
+                checks.append(Check(name, False, str(e)[:120], "check your network or proxy; scans will be incomplete"))
+
+    try:
+        import anthropic  # noqa: F401
+        has_sdk = True
+    except ImportError:
+        has_sdk = False
+    import os
+
+    has_key = bool(os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_AUTH_TOKEN"))
+    checks.append(Check("ai triage", has_sdk and has_key,
+                        "ready" if has_sdk and has_key else ("no API key set" if has_sdk else "SDK not installed"),
+                        'optional: pip install "vulnlens[ai]" and set ANTHROPIC_API_KEY', required=False))
+    return checks
+
+
+def render(checks: list[Check]) -> str:
+    lines = ["", "VulnLens doctor", ""]
+    for c in checks:
+        mark = "ok  " if c.ok else ("MISSING" if c.required else "optional")
+        lines.append(f"  {c.name:<11} {mark:<9} {c.detail}")
+    fixes = [c for c in checks if not c.ok and c.fix]
+    if fixes:
+        lines += ["", "To fix:"]
+        lines += [f"  {c.name}: {c.fix}" for c in fixes]
+    ready = all(c.ok for c in checks if c.required)
+    lines += ["", "Ready to scan." if ready else
+              "Not ready: a missing engine makes scans incomplete, an outdated one makes them noisy.", ""]
+    return "\n".join(lines)

vulnlens/engines/__init__.py

@@ -0,0 +1,20 @@
+from .deps import DependencyEngine
+from .secrets import TruffleHogEngine
+from .semgrep import SemgrepEngine
+
+ENGINES = {
+    "code": SemgrepEngine,
+    "deps": DependencyEngine,
+    "secrets": TruffleHogEngine,
+}
+# Reports name engines by tool; the CLI by area. Accept either.
+ALIASES = {"semgrep": "code", "osv": "deps", "trufflehog": "secrets"}
+
+
+def resolve_engine(name: str) -> str | None:
+    name = name.strip().lower()
+    name = ALIASES.get(name, name)
+    return name if name in ENGINES else None
+
+
+__all__ = ["ALIASES", "ENGINES", "DependencyEngine", "SemgrepEngine", "TruffleHogEngine", "resolve_engine"]

vulnlens/engines/base.py

@@ -0,0 +1,67 @@
+"""Shared helpers for engines that wrap an external CLI tool."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..models import EngineState
+
+
+@dataclass
+class ToolRun:
+    state: EngineState
+    stdout: str = ""
+    stderr: str = ""
+    exit_code: int | None = None
+
+
+def find_tool(name: str, bin_dir: Path | None = None) -> str | None:
+    if bin_dir:
+        for candidate in (bin_dir / name, bin_dir / f"{name}.exe"):
+            if candidate.is_file() and candidate.stat().st_size > 1024:
+                return str(candidate)
+    return shutil.which(name)
+
+
+def run_tool(cmd: list[str], cwd: Path, timeout: int, ok_codes: tuple[int, ...] = (0,)) -> ToolRun:
+    env = {**os.environ, "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8"}
+    try:
+        proc = subprocess.run(
+            cmd,
+            cwd=cwd,
+            capture_output=True,
+            timeout=timeout,
+            env=env,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except subprocess.TimeoutExpired:
+        return ToolRun(EngineState.TIMEOUT, stderr=f"timed out after {timeout}s")
+    except OSError as e:
+        return ToolRun(EngineState.ERROR, stderr=str(e))
+    state = EngineState.OK if proc.returncode in ok_codes else EngineState.ERROR
+    return ToolRun(state, proc.stdout, proc.stderr, proc.returncode)
+
+
+def failure_message(run: ToolRun) -> str:
+    """Most useful part of a failed tool's stderr: error lines first, skipping info-level log noise."""
+    lines = [ln for ln in run.stderr.splitlines() if ln.strip() and '"level":"info' not in ln]
+    errors = [ln for ln in lines if "error" in ln.lower() or "fatal" in ln.lower()] or lines
+    prefix = f"exit code {run.exit_code}: " if run.exit_code is not None else ""
+    return (prefix + " | ".join(errors[-3:]))[-400:] or prefix.rstrip(": ")
+
+
+def relpath(path: str | None, root: Path) -> str | None:
+    if not path:
+        return None
+    p = Path(path)
+    if p.is_absolute():
+        try:
+            p = p.resolve().relative_to(root.resolve())
+        except ValueError:
+            pass
+    return p.as_posix().removeprefix("./")

vulnlens/engines/deps.py

@@ -0,0 +1,59 @@
+"""Software composition analysis: lockfiles -> OSV.dev, no external binary needed."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from .. import net
+from ..intel import osv
+from ..lockfiles import collect_packages, uncovered_manifests
+from ..models import EngineResult, EngineState
+
+
+class DependencyEngine:
+    name = "osv"
+
+    def __init__(self, offline: bool = False, cache: net.Cache | None = None, **_):
+        self.offline = offline
+        self.cache = cache or net.Cache()
+
+    def run(self, root: Path) -> EngineResult:
+        start = time.monotonic()
+        unpinned: dict[str, int] = {}
+        packages, lockfiles, errors = collect_packages(root, unpinned)
+        unread = uncovered_manifests(root)
+        gaps = [f"{_names(unread)} not read (format not supported yet)"] if unread else []
+        if errors:
+            gaps.append(f"{_names(e.split(':', 1)[0] for e in errors)} failed to parse")
+        if unpinned:
+            gaps.append(f"{sum(unpinned.values())} dependencies without an exact version in {_names(sorted(unpinned))} "
+                        "(a range like >=2.0 can't be matched to advisories; pin them or add a lockfile)")
+        if not lockfiles:
+            msg = "no supported lockfile found" + (f"; found {_names(unread)}, which VulnLens can't read yet" if unread else "")
+            return EngineResult(self.name, EngineState.SKIPPED, message=msg)
+        if self.offline:
+            return EngineResult(self.name, EngineState.SKIPPED,
+                                message=f"offline mode: {len(packages)} packages not checked against OSV")
+        stats: dict[str, int] = {}
+        try:
+            findings = osv.scan_packages(packages, self.cache, stats=stats)
+        except net.NetworkError as e:
+            return EngineResult(self.name, EngineState.ERROR, duration=time.monotonic() - start, message=str(e))
+        msg = f"{len(packages)} packages from {len(lockfiles)} file(s)"
+        if errors:
+            msg += f"; {len(errors)} file(s) failed to parse"
+        if stats.get("withdrawn"):
+            msg += f"; {stats['withdrawn']} withdrawn advisory(ies) ignored"
+        state = EngineState.OK
+        if stats.get("details_failed"):
+            # Without the advisory record a finding has no severity, summary or fix: the ranking is incomplete.
+            state = EngineState.PARTIAL
+            msg += f"; {stats['details_failed']} advisory record(s) could not be fetched, so their findings are unranked"
+        return EngineResult(self.name, state, findings, time.monotonic() - start, msg, coverage_gaps=gaps)
+
+
+def _names(paths, limit: int = 3) -> str:
+    paths = list(paths)
+    shown = ", ".join(paths[:limit])
+    return shown + (f" and {len(paths) - limit} more" if len(paths) > limit else "")