jscope 0.4.2__py3-none-any.whl

jscope/pipeline.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from jscope.analyzers.auth_analyzer import AuthAnalyzer
+from jscope.analyzers.authorization_analyzer import AuthorizationAnalyzer
+from jscope.analyzers.base import Analyzer, ProjectContext
+from jscope.analyzers.dataflow_analyzer import DataFlowAnalyzer
+from jscope.analyzers.endpoint_analyzer import EndpointAnalyzer
+from jscope.analyzers.framework_detector import FrameworkDetector
+from jscope.analyzers.graphql_analyzer import GraphQLAnalyzer
+from jscope.analyzers.graphql_schema_analyzer import GraphQLSchemaAnalyzer
+from jscope.analyzers.html_analyzer import HtmlAnalyzer
+from jscope.analyzers.openapi_analyzer import OpenApiAnalyzer
+from jscope.analyzers.wasm_analyzer import WasmAnalyzer
+from jscope.analyzers.manager import AnalyzerManager
+from jscope.analyzers.router_analyzer import RouterAnalyzer
+from jscope.analyzers.secret_analyzer import SecretAnalyzer
+from jscope.analyzers.service_worker_analyzer import ServiceWorkerAnalyzer
+from jscope.analyzers.source_map_analyzer import SourceMapAnalyzer, expand_source_maps
+from jscope.analyzers.storage_analyzer import StorageAnalyzer
+from jscope.config import Config
+from jscope.core.artifacts import collect_artifacts
+from jscope.core.evidence import Confidence, EvidenceEngine, Finding
+from jscope.core.graph import KnowledgeGraph
+from jscope.parsing.ast_engine import ASTEngine
+from jscope.parsing.html import extract_inline_scripts
+from jscope.core.graph import EdgeKind, NodeKind
+from jscope.plugin.loader import load_plugins
+
+CORE_ANALYZERS = [FrameworkDetector, EndpointAnalyzer, SecretAnalyzer, RouterAnalyzer, AuthAnalyzer,
+                  AuthorizationAnalyzer, StorageAnalyzer, GraphQLAnalyzer, ServiceWorkerAnalyzer,
+                  SourceMapAnalyzer, HtmlAnalyzer, OpenApiAnalyzer, GraphQLSchemaAnalyzer, WasmAnalyzer,
+                  DataFlowAnalyzer]
+_EXTS = (".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".mts", ".cts")
+_NOT_JS = (".html", ".htm", ".vue", ".wasm", ".graphql", ".gql", ".graphqls", ".json", ".yaml", ".yml", ".d.ts")
+
+
+def core_analyzers() -> list[Analyzer]:
+    return [cls() for cls in CORE_ANALYZERS]
+
+
+# kept for backward compatibility with Phase 1 callers
+ALL_ANALYZERS = core_analyzers()
+
+
+@dataclass
+class AnalysisResult:
+    findings: list[Finding]
+    frameworks: list[str]
+    file_count: int
+    engine: EvidenceEngine
+    graph: KnowledgeGraph
+    diagnostics: list[str] = field(default_factory=list)
+    analyzer_counts: dict[str, int] = field(default_factory=dict)
+    tiers: dict[str, str] = field(default_factory=dict)
+    expanded_sources: int = 0
+    file_hashes: dict[str, str] = field(default_factory=dict)   # path -> content hash (disk files only)
+    artifact_counts: dict[str, int] = field(default_factory=dict)   # Phase 4: kind -> files analyzed
+    dataflow: dict = field(default_factory=dict)                    # 0.5: every flow incl. sanitized/unreachable + limitations
+    file_diagnostics: dict[str, list[str]] = field(default_factory=dict)   # 0.5: per-file "skipped / partially analyzed"
+    plugin_runs: list[dict] = field(default_factory=list)           # 0.5: plugin identity/version/isolation/outcome
+
+
+def _collect_js_files(paths: list[str], exclude: list[str]) -> list[str]:
+    out: list[str] = []
+    for p in paths:
+        path = Path(p)
+        if path.is_file():
+            if path.suffix.lower() not in _NOT_JS:        # html/vue/wasm/spec files are artifacts, not JS (Phase 4)
+                out.append(str(path))
+        elif path.is_dir():
+            for f in path.rglob("*"):
+                if f.suffix not in _EXTS or not f.is_file():
+                    continue
+                rel = str(f)
+                if any(fnmatch.fnmatch(rel, pat) for pat in exclude):
+                    continue
+                out.append(str(f))
+    return sorted(set(out))
+
+
+def collect_manifest(paths: list[str], config: Config) -> dict[str, str]:
+    """path -> content hash for every file that can influence an analysis. Cheap (no parsing).
+    Includes sibling `.map` files when source-map expansion is on, since they change the result."""
+    exclude = config.get("exclude", [])
+    files = _collect_js_files(paths, exclude)
+    if config.get("source_maps.expand", False):
+        for p in paths:
+            if Path(p).is_dir():
+                files += [str(f) for f in Path(p).rglob("*.map") if f.is_file()]
+    out = {f: ASTEngine.hash_bytes(Path(f).read_bytes()) for f in sorted(set(files))}
+    if config.get("artifacts.enabled", True):
+        for a in collect_artifacts(paths, exclude):
+            out[a.path] = a.content_hash
+    return out
+
+
+def run_analysis(paths: list[str], config: Config) -> AnalysisResult:
+    from jscope.analyzers.common import set_analysis_roots
+    set_analysis_roots(paths)
+    exclude = config.get("exclude", [])
+    files = _collect_js_files(paths, exclude)
+
+    ast_engine = ASTEngine(max_bytes=config.get("max_file_bytes", 5 * 1024 * 1024))
+    parsed = [ast_engine.parse_file(f) for f in files]
+
+    diagnostics: list[str] = []
+    artifacts = collect_artifacts(paths, exclude) if config.get("artifacts.enabled", True) else []
+    for art in artifacts:
+        if art.kind in ("html", "vue"):                   # inline <script> / .vue <script> become ordinary JS files
+            pfs, d = extract_inline_scripts(art, ast_engine)
+            parsed += pfs
+            diagnostics += d
+    expanded = 0
+    if config.get("source_maps.expand", False):
+        extra, expanded = expand_source_maps(parsed, ast_engine)
+        parsed += extra
+
+    ctx = ProjectContext(files=parsed, ast=ast_engine, config=config.data, artifacts=artifacts)
+    if config.get("incremental.cache_dir") and config.get("incremental.enabled", True):
+        from jscope.core.cache import AnalysisCache
+        ctx.shared["dataflow_cache"] = AnalysisCache(config.get("incremental.cache_dir"))
+
+    analyzers = core_analyzers()
+    core_names = {a.name for a in analyzers}
+    from jscope.plugin.sandbox import SandboxPolicy
+    plugin_res = load_plugins(config.get("plugins.paths", []), core_names,
+                              set(config.get("plugins.verified", [])),
+                              use_entry_points=config.get("plugins.entry_points", True),
+                              isolation=config.get("plugins.isolation", "auto"),
+                              sandbox_policy=SandboxPolicy(timeout_seconds=float(config.get("plugins.timeout_seconds", 30)),
+                                                           memory_mb=int(config.get("plugins.memory_mb", 1024)),
+                                                           grant_read=list(config.get("plugins.grant_read", []))))
+    analyzers += plugin_res.analyzers
+    diagnostics += [f"[plugin-loader] {e}" for e in plugin_res.errors]
+    diagnostics += [f"[plugin-isolation] {w}" for w in plugin_res.warnings]
+
+    enabled = set(config.get("analyzers.enabled", [a.name for a in analyzers]))
+    enabled |= {a.name for a in plugin_res.analyzers}        # loaded plugins are opt-in by being configured
+    tiers = {a.name: a.tier for a in analyzers}
+
+    min_conf = Confidence[config.get("min_confidence", "LOW")]
+    cap = Confidence[config.get("plugins.community_confidence_cap", "MEDIUM")]
+    engine = EvidenceEngine(min_display_confidence=min_conf, analyzer_tiers=tiers, community_cap=cap)
+
+    manager = AnalyzerManager(analyzers)
+    counts = manager.run(ctx, engine, enabled=enabled)
+    findings = engine.promote()
+    _attach_findings_to_graph(ctx.graph, findings)
+    for pf in parsed:                                      # surface per-file parse problems even if no analyzer needed them
+        if pf.skipped_reason:
+            ctx.add_file_diagnostic(pf.path, f"not analyzed: {pf.skipped_reason}")
+        elif pf.syntax_errors:
+            ctx.add_file_diagnostic(pf.path, f"partially analyzed: {pf.syntax_errors} syntax error node(s)")
+
+    return AnalysisResult(
+        findings=findings, frameworks=sorted(ctx.framework_hints.keys()),
+        file_count=sum(1 for p in parsed if p.origin not in ("html-inline", "vue-sfc")) + len(artifacts),
+        engine=engine, graph=ctx.graph, diagnostics=diagnostics + ctx.diagnostics,
+        analyzer_counts=counts, tiers=tiers, expanded_sources=expanded,
+        file_hashes={**{p.path: p.content_hash for p in parsed if p.origin == "disk"}, **{a.path: a.content_hash for a in artifacts}},
+        artifact_counts={k: sum(1 for a in artifacts if a.kind == k) for k in sorted({a.kind for a in artifacts})},
+        dataflow=ctx.shared.get("dataflow", {}), file_diagnostics=ctx.file_diagnostics,
+        plugin_runs=[r.to_dict() for r in ctx.shared.get("plugin_runs", [])] + [
+            {"plugin": plugin_res.sources.get(a.name, "?"), "analyzer": a.name, "version": a.version, "tier": a.tier,
+             "isolation": "none", "outcome": "ok" if a.name in enabled else "skipped"}
+            for a in plugin_res.analyzers if a.name not in plugin_res.isolated])
+
+
+def analyze_paths(paths: list[str], config: Config) -> tuple[list[Finding], list[str], int, EvidenceEngine]:
+    """Phase 1 signature, preserved."""
+    r = run_analysis(paths, config)
+    return r.findings, r.frameworks, r.file_count, r.engine
+
+
+def _attach_findings_to_graph(graph, findings) -> None:
+    """FR-05: link each promoted Finding back into the graph as a first-class node, so a UI/CLI consumer can walk
+    finding -> evidence files -> related data-flow / route / endpoint context in one structure."""
+    for f in findings:
+        fid = f"finding:{f.id}"
+        graph.add_node(fid, NodeKind.FINDING, f.subject, category=f.category, confidence=f.confidence.value, score=f.score)
+        flow = f.metadata.get("flow")
+        if flow:
+            sink_id = f"dsink:{flow['sink']['file']}:{flow['sink']['line']}:{flow['sink']['name']}"
+            if sink_id in graph.nodes:
+                graph.add_edge(sink_id, fid, EdgeKind.DESCRIBES, "evidence_engine", "DATA_FLOW")
+        seen_files = set()
+        for e in f.evidence:
+            if e.file and e.file not in seen_files:
+                seen_files.add(e.file)
+                file_node = f"file:{e.file}"
+                graph.add_node(file_node, NodeKind.FILE, e.file.rsplit("/", 1)[-1])
+                graph.add_edge(fid, file_node, EdgeKind.SUPPORTED_BY, "evidence_engine", e.type.value, e.file, e.line)

jscope/plugin/_worker.py

@@ -0,0 +1,199 @@
+"""Sandbox worker (FR-09). Runs in a SEPARATE Python process started with `-I` by jscope.plugin.sandbox.
+
+Defence-in-depth, not a hard security boundary (see docs/PLUGIN_ISOLATION.md):
+  1. scrubbed environment, empty temp cwd, request on stdin, result on the original stdout as one JSON line
+  2. POSIX resource limits: CPU seconds, address space, open files, file size 0 (no file can be written)
+  3. a Python audit hook (cannot be removed once installed) that denies: new sockets / DNS, process creation, ctypes,
+     any write/delete/rename/chmod, reads outside an allow-list of roots, and imports of network/process modules.
+     Every denied attempt is recorded and returned to the parent as a `violation`.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import sys
+
+_REAL_STDOUT = sys.stdout
+_violations: list[str] = []
+_BLOCKED_IMPORTS = {"ctypes", "_ctypes", "subprocess", "_posixsubprocess", "socket", "_socket", "ssl", "_ssl", "multiprocessing",
+                    "http.client", "urllib.request", "ftplib", "smtplib", "telnetlib", "poplib", "imaplib", "asyncio.subprocess",
+                    "requests", "urllib3", "httpx", "aiohttp", "pty", "webbrowser", "mmap", "_multiprocessing", "ensurepip"}
+_DENY_ALWAYS = {
+    "socket.__new__", "socket.connect", "socket.bind", "socket.getaddrinfo", "socket.gethostbyname", "socket.gethostbyaddr",
+    "socket.sendto", "socket.sendmsg", "subprocess.Popen", "os.system", "os.exec", "os.posix_spawn", "os.spawn", "os.fork",
+    "os.forkpty", "os.startfile", "ctypes.dlopen", "ctypes.dlsym", "ctypes.cdata", "ctypes.call_function",
+    "os.remove", "os.rename", "os.mkdir", "os.rmdir", "os.chmod", "os.chown", "os.link", "os.symlink", "os.truncate",
+    "os.mkfifo", "os.mknod", "os.chroot", "os.kill", "os.killpg", "os.setuid", "os.setgid", "shutil.copyfile", "shutil.copytree",
+    "shutil.rmtree", "shutil.move", "shutil.make_archive", "shutil.unpack_archive", "tempfile.mkstemp", "tempfile.mkdtemp",
+    "winreg.OpenKey", "webbrowser.open", "pty.spawn", "sys.addaudithook_removed",
+}
+_READ_ROOTS: list[str] = []
+
+
+def _deny(event: str, detail: str = "") -> None:
+    msg = f"{event}{(' ' + detail) if detail else ''}"
+    if msg not in _violations:
+        _violations.append(msg)
+    raise PermissionError(f"JScope sandbox: {msg} is not permitted for plugins")
+
+
+def _under(path: str) -> bool:
+    try:
+        p = os.path.realpath(path)
+    except (OSError, ValueError):
+        return False
+    return any(p == r or p.startswith(r.rstrip(os.sep) + os.sep) for r in _READ_ROOTS)
+
+
+def _hook(event: str, args: tuple) -> None:
+    if event in _DENY_ALWAYS:
+        _deny(event, repr(args[:1])[:80])
+    if event == "import":
+        name = str(args[0])
+        if name in _BLOCKED_IMPORTS or name.split(".")[0] in {"ctypes", "_ctypes", "subprocess", "socket", "multiprocessing"}:
+            _deny("import", name)
+        return
+    if event == "open":
+        path, mode, flags = args[0], args[1], args[2] if len(args) > 2 else 0
+        if isinstance(path, int):
+            return                                                    # already-open fd
+        m = mode or "r"
+        if any(c in str(m) for c in "wax+") or (isinstance(flags, int) and flags & (os.O_WRONLY | os.O_RDWR | os.O_CREAT | os.O_TRUNC | os.O_APPEND)):
+            _deny("open-for-write", str(path)[:80])
+        if not _under(os.fsdecode(path)):
+            _deny("read-outside-allowed-roots", str(path)[:80])
+        return
+    if event in ("os.listdir", "os.scandir", "glob.glob", "os.walk"):
+        p = args[0]
+        if p is not None and not isinstance(p, int) and not _under(os.fsdecode(p)):
+            _deny("list-outside-allowed-roots", str(p)[:80])
+        return
+    if event in ("os.putenv", "os.unsetenv"):
+        return
+
+
+def _limits(cfg: dict) -> None:
+    try:
+        import resource
+    except ImportError:                                               # Windows: only the audit hook + parent timeout apply
+        return
+    cpu = int(cfg.get("cpu_seconds", 30))
+    mem = int(cfg.get("memory_mb", 1024)) * 1024 * 1024
+    for res, val in ((resource.RLIMIT_CPU, (cpu, cpu + 1)), (resource.RLIMIT_AS, (mem, mem)),
+                     (resource.RLIMIT_NOFILE, (128, 128)), (resource.RLIMIT_FSIZE, (0, 0)), (resource.RLIMIT_CORE, (0, 0))):
+        try:
+            resource.setrlimit(res, val)
+        except (ValueError, OSError):
+            pass
+
+
+def _serialize_candidate(c) -> dict:
+    from jscope.core.evidence import Candidate
+    if not isinstance(c, Candidate):
+        return {"_rejected": type(c).__name__}
+    return {
+        "category": str(c.category)[:200], "subject": str(c.subject)[:1000], "analyzer": str(c.analyzer)[:200],
+        "attack_surface": c.attack_surface if c.attack_surface is None else str(c.attack_surface)[:100],
+        "suggested_test": c.suggested_test if c.suggested_test is None else str(c.suggested_test)[:2000],
+        "related": [str(x)[:500] for x in (c.related or [])][:50],
+        "metadata": _json_safe(c.metadata),
+        "evidence": [{"type": getattr(e.type, "value", str(e.type)), "description": str(e.description)[:2000], "analyzer": str(e.analyzer)[:200],
+                      "file": None if e.file is None else str(e.file)[:1000], "line": e.line if isinstance(e.line, int) else None,
+                      "snippet": None if e.snippet is None else str(e.snippet)[:2000], "metadata": _json_safe(e.metadata)}
+                     for e in (c.evidence or [])][:200],
+    }
+
+
+def _json_safe(obj, depth=0):
+    if depth > 6:
+        return None
+    if isinstance(obj, (str, int, float, bool)) or obj is None:
+        return obj
+    if isinstance(obj, dict):
+        return {str(k)[:100]: _json_safe(v, depth + 1) for k, v in list(obj.items())[:200]}
+    if isinstance(obj, (list, tuple, set)):
+        return [_json_safe(v, depth + 1) for v in list(obj)[:200]]
+    return str(obj)[:200]
+
+
+def _find_analyzers(plugin_path: str):
+    import importlib.util
+    import inspect
+    from jscope.analyzers.base import Analyzer
+    spec = importlib.util.spec_from_file_location("jscope_sandboxed_plugin", plugin_path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    items = list(getattr(mod, "ANALYZERS", []) or [])
+    if not items and callable(getattr(mod, "register", None)):
+        items = list(mod.register() or [])
+    out = []
+    for it in items:
+        inst = it() if inspect.isclass(it) else it
+        if isinstance(inst, Analyzer):
+            out.append(inst)
+    return out, bool(items)
+
+
+def main() -> int:
+    req = json.loads(sys.stdin.read())
+    sys.path.insert(0, req["jscope_root"])
+    # Import everything the plugin API needs BEFORE the hook goes in; the hook then only polices what the plugin does.
+    import jscope.analyzers.base  # noqa: F401
+    import jscope.core.evidence  # noqa: F401
+    import jscope.parsing.ast_engine  # noqa: F401
+    import jscope.parsing.queries  # noqa: F401
+    import jscope.core.artifacts  # noqa: F401
+    import jscope.core.graph  # noqa: F401
+    import jscope.parsing.html  # noqa: F401
+    import importlib.util, inspect, glob, tempfile, shutil, re, collections, itertools, functools, dataclasses, typing, enum  # noqa: F401,E401
+
+    roots = {os.path.realpath(p) for p in (sys.prefix, sys.base_prefix, sys.exec_prefix, req["jscope_root"], "/dev/null", "/dev/urandom")}
+    roots |= {os.path.realpath(p) for p in sys.path if p and os.path.exists(p)}
+    roots |= {os.path.realpath(req["plugin_path"]), os.path.realpath(os.path.dirname(req["plugin_path"]))}
+    roots |= {os.path.realpath(p) for p in req.get("grant_read", [])}
+    _READ_ROOTS.extend(sorted(roots))
+    sys.stdout = sys.stderr                                           # plugin prints must not corrupt the result channel
+    _limits(req.get("limits", {}))
+    sys.addaudithook(_hook)
+
+    result: dict = {"ok": True}
+    try:
+        analyzers, declared = _find_analyzers(req["plugin_path"])
+        if req["op"] == "discover":
+            result["declared"] = declared
+            result["analyzers"] = [{"name": a.name, "version": getattr(a, "version", "0.1.0"), "class": type(a).__name__,
+                                    "depends_on": list(a.depends_on), "run_after": list(getattr(a, "run_after", [])),
+                                    "produces_categories": list(a.produces_categories)} for a in analyzers]
+        else:
+            target = next((a for a in analyzers if a.name == req["analyzer"]), None)
+            if target is None:
+                raise RuntimeError(f"analyzer {req['analyzer']!r} not found in plugin")
+            from jscope.analyzers.base import ProjectContext
+            from jscope.core.artifacts import Artifact
+            from jscope.parsing.ast_engine import ASTEngine
+            ast = ASTEngine(max_bytes=req.get("max_file_bytes", 5 * 1024 * 1024))
+            files = [ast.parse_bytes(base64.b64decode(f["data"]), path=f["path"]) for f in req["files"]]
+            for pf, f in zip(files, req["files"]):
+                pf.origin = f.get("origin", "disk")
+            arts = [Artifact(kind=a["kind"], path=a["path"], data=base64.b64decode(a["data"]), content_hash=a["content_hash"],
+                             origin=a.get("origin", "disk")) for a in req.get("artifacts", [])]
+            ctx = ProjectContext(files=files, ast=ast, framework_hints=req.get("framework_hints", {}), config=req.get("config", {}),
+                                 artifacts=arts, shared=req.get("shared", {}))
+            out = target.analyze_project(ctx)
+            if not isinstance(out, list):
+                result["returned"] = type(out).__name__
+                out = []
+            result["candidates"] = [_serialize_candidate(c) for c in out[: req.get("max_candidates", 5000)]]
+            result["diagnostics"] = [str(d)[:500] for d in ctx.diagnostics][:100]
+    except BaseException as exc:                                      # noqa: BLE001 - includes MemoryError, PermissionError
+        result = {"ok": False, "error": f"{type(exc).__name__}: {str(exc)[:500]}"}
+    result["violations"] = list(_violations)
+    _REAL_STDOUT.write("\n@@JSCOPE-RESULT@@" + json.dumps(result) + "\n")
+    _REAL_STDOUT.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

jscope/plugin/loader.py

@@ -0,0 +1,225 @@
+"""Plugin loader.
+
+A plugin is a Python module that exposes either
+    ANALYZERS = [MyAnalyzer, ...]            (classes or instances), or
+    def register() -> list[Analyzer | type]
+Plugins are discovered from (1) directories listed in `plugins.paths` and
+(2) installed packages exposing the `jscope.analyzers` entry-point group.
+
+Trust model (see docs/PLUGINS.md):
+  * plugins can only PROPOSE evidence; the AnalyzerManager enforces that at runtime
+  * every plugin analyzer gets tier "community" unless its name appears in
+    `plugins.verified`; core analyzers are tier "core"
+  * a finding supported ONLY by community-tier analyzers is capped at
+    `plugins.community_confidence_cap` (default MEDIUM)
+
+Loading a plugin executes its Python code. Only load plugins you trust --
+the tier system limits what a plugin can do to the *report*, not to your machine.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import importlib.util
+import inspect
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from jscope.analyzers.base import Analyzer
+
+PLUGIN_API_VERSION = "0.2"
+
+
+@dataclass
+class LoadResult:
+    analyzers: list[Analyzer] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    sources: dict[str, str] = field(default_factory=dict)      # analyzer name -> where it came from
+    warnings: list[str] = field(default_factory=list)          # FR-09: plugins running WITHOUT isolation, policy notes
+    isolated: set[str] = field(default_factory=set)            # analyzer names running in the sandbox
+
+
+def _coerce(obj, origin: str, res: LoadResult, taken: set[str], verified: set[str]) -> None:
+    inst = obj() if inspect.isclass(obj) else obj
+    if not isinstance(inst, Analyzer):
+        res.errors.append(f"{origin}: {inst!r} is not an Analyzer subclass; skipped")
+        return
+    if not inst.name or inst.name == "base":
+        res.errors.append(f"{origin}: analyzer {type(inst).__name__} must define a unique `name`; skipped")
+        return
+    if inst.name in taken:
+        res.errors.append(f"{origin}: analyzer name '{inst.name}' already registered; skipped")
+        return
+    inst.tier = "verified" if inst.name in verified else "community"
+    taken.add(inst.name)
+    res.analyzers.append(inst)
+    res.sources[inst.name] = origin
+
+
+def _from_module(mod, origin: str, res: LoadResult, taken: set[str], verified: set[str]) -> None:   # noqa: C901
+    items = list(getattr(mod, "ANALYZERS", []) or [])
+    if not items and callable(getattr(mod, "register", None)):
+        items = list(mod.register() or [])
+    if not items:
+        res.errors.append(f"{origin}: defines neither ANALYZERS nor register(); skipped")
+        return
+    for it in items:
+        try:
+            _coerce(it, origin, res, taken, verified)
+        except Exception as exc:
+            res.errors.append(f"{origin}: could not instantiate {it!r}: {type(exc).__name__}: {exc}")
+
+
+def _load_isolated(f: Path, res: LoadResult, taken: set[str], verified: set[str], isolation: str, policy) -> bool:
+    """FR-09: discover the plugin INSIDE the sandbox (its code never runs in this process unless it is verified and
+    isolation == "auto"). Returns True when the file was handled here, False to fall back to in-process import."""
+    from jscope.plugin.sandbox import SandboxedAnalyzer, discover
+    metas, err, violations = discover(str(f), policy)
+    if err:
+        res.errors.append(f"{f}: {err}")
+        return True
+    if violations:
+        res.warnings.append(f"plugin {f.name} attempted forbidden operations while loading (blocked): {'; '.join(violations)}")
+    wants_in_process = isolation == "auto" and any(m["name"] in verified for m in metas)
+    if wants_in_process:
+        return False                                            # operator explicitly trusts this analyzer by name
+    for m in metas:
+        if not m.get("name") or m["name"] == "base":
+            res.errors.append(f"{f}: analyzer {m.get('class')} must define a unique `name`; skipped")
+            continue
+        if m["name"] in taken:
+            res.errors.append(f"{f}: analyzer name '{m['name']}' already registered; skipped")
+            continue
+        taken.add(m["name"])
+        an = SandboxedAnalyzer(m, str(f), policy, tier="verified" if m["name"] in verified else "community")
+        res.analyzers.append(an)
+        res.sources[an.name] = str(f)
+        res.isolated.add(an.name)
+    return True
+
+
+def load_plugins(paths: list[str], core_names: set[str], verified: set[str] | None = None,
+                 use_entry_points: bool = True, isolation: str = "none", sandbox_policy=None) -> LoadResult:
+    """isolation: "none" (in-process, full trust), "auto" (community plugins sandboxed, verified-by-name in-process),
+    "always" (everything from `paths` sandboxed). Entry-point plugins are installed packages and always run in-process."""
+    res = LoadResult()
+    taken = set(core_names)
+    verified = verified or set()
+    if isolation not in ("none", "auto", "always"):
+        res.errors.append(f"unknown plugins.isolation {isolation!r}; falling back to 'always'")
+        isolation = "always"
+    if isolation != "none" and sandbox_policy is None:
+        from jscope.plugin.sandbox import SandboxPolicy
+        sandbox_policy = SandboxPolicy()
+
+    for p in paths:
+        base = Path(p).expanduser()
+        files = [base] if base.is_file() else sorted(base.glob("*.py")) if base.is_dir() else []
+        if not files:
+            res.errors.append(f"plugin path not found or empty: {p}")
+        for f in files:
+            if f.name.startswith("_"):
+                continue
+            if isolation != "none" and _load_isolated(f, res, taken, verified, isolation, sandbox_policy):
+                continue
+            modname = f"jscope_plugin_{f.stem}"
+            try:
+                spec = importlib.util.spec_from_file_location(modname, f)
+                mod = importlib.util.module_from_spec(spec)
+                sys.modules[modname] = mod
+                spec.loader.exec_module(mod)                   # executes plugin code
+            except Exception as exc:
+                res.errors.append(f"{f}: import failed: {type(exc).__name__}: {exc}")
+                continue
+            before = len(res.analyzers)
+            _from_module(mod, str(f), res, taken, verified)
+            for a in res.analyzers[before:]:
+                res.warnings.append(f"plugin '{a.name}' ({f.name}) runs WITHOUT isolation"
+                                    + (" (plugins.isolation=none)" if isolation == "none" else " (verified by name)")
+                                    + ": it has the same access to this machine as JScope itself")
+
+    if use_entry_points:
+        try:
+            eps = importlib.metadata.entry_points(group="jscope.analyzers")
+        except TypeError:                                       # very old importlib.metadata
+            eps = []
+        for ep in eps:
+            try:
+                obj = ep.load()
+            except Exception as exc:
+                res.errors.append(f"entry-point {ep.name}: import failed: {type(exc).__name__}: {exc}")
+                continue
+            before = len(res.analyzers)
+            if inspect.ismodule(obj):
+                _from_module(obj, f"entry-point:{ep.name}", res, taken, verified)
+            else:
+                try:
+                    _coerce(obj, f"entry-point:{ep.name}", res, taken, verified)
+                except Exception as exc:
+                    res.errors.append(f"entry-point {ep.name}: {type(exc).__name__}: {exc}")
+    return res
+
+
+TEMPLATE = '''"""{name}: a JScope analyzer plugin.
+
+Rules of the road (docs/EVIDENCE_SCHEMA.md, docs/PLUGINS.md):
+  * you PROPOSE Candidates backed by typed Evidence; the Evidence Engine decides
+    what becomes a finding and at what confidence
+  * evidence.analyzer must be your analyzer's name (it is enforced)
+  * you cannot emit CROSS_ANALYZER_AGREEMENT -- the engine adds it when a
+    DIFFERENT analyzer independently proposes the same (category, subject)
+  * prefer AST evidence over bare string matches; always add negative evidence
+    (DEAD_CODE, TEST_FIXTURE_CONTEXT) when you can see it
+"""
+
+from jscope.analyzers.base import Analyzer, ProjectContext
+from jscope.core.evidence import Candidate, Evidence, EvidenceType
+from jscope.parsing import queries as Q
+
+
+class {cls}(Analyzer):
+    name = "{name}"
+    depends_on = ["framework_detector"]
+    produces_categories = ["{name}"]
+
+    def analyze_project(self, ctx: ProjectContext) -> list[Candidate]:
+        out = []
+        for pf in ctx.files:
+            if pf.skipped_reason or pf.tree is None:
+                continue
+            for site in Q.iter_calls(ctx.ast, pf):
+                if site.callee != "dangerousThing":       # <- your detection here
+                    continue
+                evidence = [Evidence(
+                    type=EvidenceType.AST_PATTERN_MATCH,
+                    description="call to dangerousThing()",
+                    analyzer=self.name, file=pf.path, line=site.line,
+                    snippet=(site.args_raw[0][:80] if site.args_raw else None),
+                )]
+                if ctx.ast.is_in_dead_branch(pf, site.node):
+                    evidence.append(Evidence(EvidenceType.DEAD_CODE, "in a dead branch", self.name))
+                out.append(Candidate(
+                    category="{name}", subject=f"dangerousThing@{{pf.path}}:{{site.line}}",
+                    analyzer=self.name, evidence=evidence,
+                    suggested_test="What should a human try next?",
+                ))
+        return out
+
+
+ANALYZERS = [{cls}]
+'''
+
+
+def scaffold(name: str, out_dir: str) -> Path:
+    ident = "".join(ch if ch.isalnum() else "_" for ch in name).strip("_").lower()
+    if not ident or ident[0].isdigit():
+        raise ValueError("plugin name must start with a letter and contain letters/digits/underscores")
+    cls = "".join(p.capitalize() for p in ident.split("_")) + "Analyzer"
+    d = Path(out_dir)
+    d.mkdir(parents=True, exist_ok=True)
+    target = d / f"{ident}.py"
+    if target.exists():
+        raise FileExistsError(str(target))
+    target.write_text(TEMPLATE.format(name=ident, cls=cls))
+    return target