jscope 0.4.2__py3-none-any.whl

jscope/plugin/sandbox.py

@@ -0,0 +1,207 @@
+"""Parent side of plugin isolation (FR-09): run untrusted plugin code in a restricted child process.
+
+What the parent guarantees, regardless of what the plugin does:
+  * plugin code is never imported into the JScope process (discovery also happens in the child)
+  * the child gets a scrubbed environment (no tokens, no HOME), an empty temp cwd, hard wall-clock timeout, rlimits
+  * its output is parsed as data and validated: only Candidate-shaped dicts, bounded sizes, known evidence types
+  * a plugin can never create a Finding or a confirmed status: output goes through AnalyzerManager like any analyzer's
+  * every run is recorded (identity, version, outcome, duration, policy violations)
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import jscope
+from jscope.analyzers.base import Analyzer, ProjectContext
+from jscope.core.evidence import Candidate, Evidence, EvidenceType
+
+WORKER = str(Path(__file__).with_name("_worker.py"))
+JSCOPE_ROOT = str(Path(jscope.__file__).resolve().parent.parent)
+MARK = "@@JSCOPE-RESULT@@"
+MAX_OUTPUT_BYTES = 32 * 1024 * 1024
+
+
+@dataclass
+class SandboxPolicy:
+    timeout_seconds: float = 30.0
+    memory_mb: int = 1024
+    grant_read: list[str] = field(default_factory=list)       # extra read-only roots the plugin may open
+    max_candidates: int = 5000
+
+
+@dataclass
+class PluginRun:
+    plugin: str
+    analyzer: str
+    version: str
+    tier: str
+    isolation: str                                            # "process" | "none"
+    outcome: str = "pending"                                  # ok | error | timeout | resource_exhausted | policy_violation | invalid_output
+    duration_s: float = 0.0
+    violations: list[str] = field(default_factory=list)
+    detail: str = ""
+    candidates: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self.__dict__)
+
+
+def _child_env() -> dict[str, str]:
+    return {"PATH": "/usr/bin:/bin", "LANG": "C.UTF-8", "PYTHONDONTWRITEBYTECODE": "1", "PYTHONHASHSEED": "0"}
+
+
+def _run_worker(request: dict, policy: SandboxPolicy) -> tuple[dict | None, str, str]:
+    """Returns (parsed_result|None, outcome_if_failed, detail)."""
+    with tempfile.TemporaryDirectory(prefix="jscope-sbx-") as cwd:
+        try:
+            proc = subprocess.run(
+                [sys.executable, "-I", "-B", WORKER], input=json.dumps(request), capture_output=True, text=True, cwd=cwd,
+                env=_child_env(), timeout=policy.timeout_seconds)
+        except subprocess.TimeoutExpired:
+            return None, "timeout", f"killed after {policy.timeout_seconds:g}s wall-clock limit"
+    out = proc.stdout or ""
+    if len(out.encode("utf-8", "ignore")) > MAX_OUTPUT_BYTES:
+        return None, "invalid_output", "plugin output exceeded the size limit"
+    idx = out.rfind(MARK)
+    if idx < 0:
+        if proc.returncode < 0:
+            return None, "resource_exhausted", f"worker terminated by signal {-proc.returncode} (CPU/memory limit?)"
+        return None, "error", f"worker produced no result (exit {proc.returncode}): {(proc.stderr or '')[-300:].strip()}"
+    try:
+        return json.loads(out[idx + len(MARK):].strip().splitlines()[0]), "", ""
+    except (ValueError, IndexError):
+        return None, "invalid_output", "worker result was not valid JSON"
+
+
+def _base_request(op: str, plugin_path: str, policy: SandboxPolicy) -> dict:
+    return {"op": op, "plugin_path": os.path.abspath(plugin_path), "jscope_root": JSCOPE_ROOT,
+            "limits": {"cpu_seconds": int(policy.timeout_seconds), "memory_mb": policy.memory_mb},
+            "grant_read": policy.grant_read}
+
+
+def discover(plugin_path: str, policy: SandboxPolicy) -> tuple[list[dict], str | None, list[str]]:
+    """Import the plugin inside the sandbox and report its analyzers' metadata. Returns (metas, error, violations)."""
+    res, outcome, detail = _run_worker(_base_request("discover", plugin_path, policy), policy)
+    if res is None:
+        return [], f"sandboxed import failed ({outcome}): {detail}", []
+    if not res.get("ok"):
+        return [], f"import failed in sandbox: {res.get('error')}", res.get("violations", [])
+    if not res.get("declared"):
+        return [], "defines neither ANALYZERS nor register(); skipped", []
+    return res.get("analyzers", []), None, res.get("violations", [])
+
+
+class _Foreign:
+    """Stand-in for a non-Candidate object the plugin returned; keeps the manager's wording identical."""
+
+
+def _foreign(name: str):
+    return type(name, (_Foreign,), {})()
+
+
+class SandboxedAnalyzer(Analyzer):
+    """Proxy Analyzer whose analyze_project runs in the sandbox worker."""
+
+    def __init__(self, meta: dict, plugin_path: str, policy: SandboxPolicy, tier: str = "community"):
+        self.name = meta["name"]
+        self.version = meta.get("version", "0.1.0")
+        self.depends_on = list(meta.get("depends_on", []))
+        self.run_after = list(meta.get("run_after", []))
+        self.produces_categories = list(meta.get("produces_categories", []))
+        self.tier = tier
+        self.plugin_path = plugin_path
+        self.policy = policy
+        self.sandboxed = True
+
+    def analyze_project(self, ctx: ProjectContext) -> list[Any]:
+        run = PluginRun(self.plugin_path, self.name, self.version, self.tier, "process")
+        ctx.shared.setdefault("plugin_runs", []).append(run)
+        t0 = time.monotonic()
+        req = _base_request("analyze", self.plugin_path, self.policy)
+        req.update({
+            "analyzer": self.name, "max_candidates": self.policy.max_candidates,
+            "files": [{"path": pf.path, "data": base64.b64encode(pf.source).decode(), "origin": pf.origin}
+                      for pf in ctx.files if not pf.skipped_reason],
+            "artifacts": [{"kind": a.kind, "path": a.path, "data": base64.b64encode(a.data).decode(),
+                           "content_hash": a.content_hash, "origin": a.origin} for a in ctx.artifacts],
+            "framework_hints": _json_safe(ctx.framework_hints), "config": _json_safe(ctx.config), "shared": _json_safe(ctx.shared),
+        })
+        res, outcome, detail = _run_worker(req, self.policy)
+        run.duration_s = round(time.monotonic() - t0, 3)
+        if res is None:
+            run.outcome, run.detail = outcome, detail
+            ctx.diagnostics.append(f"[plugin-isolation] {self.name}: {outcome}: {detail}")
+            return []
+        run.violations = list(res.get("violations", []))
+        if not res.get("ok"):
+            err = res.get("error", "")
+            run.outcome = "resource_exhausted" if err.startswith("MemoryError") else "error"
+            run.detail = err
+            if run.violations:
+                ctx.diagnostics.append(f"[plugin-isolation] {self.name} attempted forbidden operations: {'; '.join(run.violations)}")
+            raise RuntimeError(err)                                   # manager records "[name] crashed: ..." like any analyzer
+        if res.get("returned"):
+            run.outcome = "invalid_output"
+            return _foreign_list(res["returned"])
+        out: list[Any] = []
+        for d in res.get("candidates", []):
+            if "_rejected" in d:
+                out.append(_foreign(str(d["_rejected"])))
+                continue
+            c = _candidate_from_dict(d, ctx)
+            if c is not None:
+                out.append(c)
+        run.candidates = len(out)
+        run.outcome = "policy_violation" if run.violations else "ok"
+        if run.violations:
+            ctx.diagnostics.append(f"[plugin-isolation] {self.name} attempted forbidden operations (blocked): {'; '.join(run.violations)}")
+        for d in res.get("diagnostics", []):
+            ctx.diagnostics.append(f"[{self.name}] {d}")
+        return out
+
+
+def _foreign_list(name: str):
+    return _foreign(name)
+
+
+def _json_safe(obj, depth=0):
+    if depth > 5:
+        return None
+    if isinstance(obj, (str, int, float, bool)) or obj is None:
+        return obj
+    if isinstance(obj, dict):
+        return {str(k): _json_safe(v, depth + 1) for k, v in obj.items() if not str(k).startswith("_")}
+    if isinstance(obj, (list, tuple, set)):
+        return [_json_safe(v, depth + 1) for v in obj]
+    return None
+
+
+_VALID_TYPES = {e.value: e for e in EvidenceType}
+
+
+def _candidate_from_dict(d: dict, ctx: ProjectContext) -> Candidate | None:
+    try:
+        ev = []
+        for e in d.get("evidence", []):
+            t = _VALID_TYPES.get(e.get("type"))
+            if t is None:
+                ctx.diagnostics.append(f"[plugin-isolation] unknown evidence type {e.get('type')!r} dropped")
+                continue
+            ev.append(Evidence(t, str(e.get("description", "")), str(e.get("analyzer", "")), e.get("file"),
+                               e.get("line") if isinstance(e.get("line"), int) else None, e.get("snippet"), dict(e.get("metadata") or {})))
+        return Candidate(category=str(d["category"]), subject=str(d["subject"]), analyzer=str(d.get("analyzer", "")), evidence=ev,
+                         attack_surface=d.get("attack_surface"), suggested_test=d.get("suggested_test"),
+                         related=list(d.get("related") or []), metadata=dict(d.get("metadata") or {}))
+    except (KeyError, TypeError, ValueError) as exc:
+        ctx.diagnostics.append(f"[plugin-isolation] malformed candidate dropped: {type(exc).__name__}")
+        return None

jscope/reporting/formats.py

@@ -0,0 +1,208 @@
+"""Report formats rendered from a saved payload dict (Phase 4: Report Mode, PRD sections 6 and 15).
+
+Because they consume the JSON payload, any past scan (a --save-findings file, a workspace scan, a `confirm` output) can be
+re-rendered without re-analysis. Everything that originates in analyzed code (subjects, snippets, file paths) is UNTRUSTED
+and is escaped for the target format: HTML is entity-escaped, Markdown is neutralised, SARIF is data not markup.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import json
+from typing import Any
+
+from jscope import __version__
+
+_ORDER = ["CONFIRMED", "HIGH", "MEDIUM", "LOW", "INFORMATIONAL"]
+_SARIF_LEVEL = {"CONFIRMED": "error", "HIGH": "warning", "MEDIUM": "note", "LOW": "note", "INFORMATIONAL": "none"}
+
+
+def _prio(payload: dict) -> dict[str, dict]:
+    return {p["id"]: p for p in payload.get("priority", [])}
+
+
+def _counts(payload: dict) -> dict[str, int]:
+    out: dict[str, int] = {}
+    for f in payload["findings"]:
+        out[f["confidence"]] = out.get(f["confidence"], 0) + 1
+    return out
+
+
+def _first_loc(f: dict) -> tuple[str | None, int | None]:
+    for e in f["evidence"]:
+        if e.get("file"):
+            return e["file"], e.get("line")
+    return None, None
+
+
+# ----------------------------------------------------------------------------- markdown
+def _md(s: Any) -> str:
+    """Neutralise untrusted text for inline Markdown: no formatting, links, HTML or table breaks."""
+    t = str(s).replace("\\", "\\\\").replace("\n", " ").replace("\r", " ")
+    t = t.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+    for ch in "`*_[]|#!":
+        t = t.replace(ch, "\\" + ch)
+    return t
+
+
+def _fence(s: str) -> str:
+    longest = max([len(r) for r in __import__("re").findall(r"`+", s)] + [0])
+    bar = "`" * max(3, longest + 1)
+    return f"{bar}\n{s}\n{bar}"
+
+
+def to_markdown(payload: dict, top_n: int = 10) -> str:
+    fs, prio = payload["findings"], _prio(payload)
+    by_id = {f["id"]: f for f in fs}
+    L = ["# JScope report", "", f"_JScope {__version__} · schema {payload.get('schema_version', '?')}_", ""]
+    s = payload["summary"]
+    L += ["## Snapshot", "", f"- files analyzed: **{s['file_count']}**",
+          f"- frameworks: {', '.join(map(_md, s['frameworks'])) or 'none detected'}", f"- findings: **{len(fs)}** (" +
+          ", ".join(f"{k} {v}" for k, v in sorted(_counts(payload).items(), key=lambda kv: _ORDER.index(kv[0]))) + ")", ""]
+    ranked = sorted((p for p in payload.get("priority", []) if p["id"] in by_id), key=lambda p: -p["priority"])[:top_n]
+    if ranked:
+        L += ["## Where to start testing", "", "| # | Priority | Confidence | Finding | Why |", "|---|---|---|---|---|"]
+        for i, p in enumerate(ranked, 1):
+            f = by_id[p["id"]]
+            L.append(f"| {i} | {p['priority']} | {f['confidence']} | `{f['id']}` {_md(f['category'])}: {_md(f['subject'])} | {_md('; '.join(p['reasons']))} |")
+        L.append("")
+        L += ["### Suggested first tests", ""]
+        for p in ranked[:5]:
+            f = by_id[p["id"]]
+            if f.get("suggested_test"):
+                L.append(f"- **{f['id']}** {_md(f['subject'])}: {_md(f['suggested_test'])}")
+        L.append("")
+    routes = payload.get("route_map") or []
+    if routes:
+        L += ["## Route map", "", "| Route | Protection | Endpoints |", "|---|---|---|"]
+        for r in routes[:40]:
+            prot = "**UNPROTECTED**" if r["unguarded"] else _md(", ".join(r["guards"] or ["meta"]) + (" / roles: " + ", ".join(r["roles"]) if r["roles"] else ""))
+            L.append(f"| `{_md(r['route'])}` | {prot} | {_md(', '.join(r['endpoints'][:6]))} |")
+        L.append("")
+    L += ["## Findings", ""]
+    cats: dict[str, list[dict]] = {}
+    for f in fs:
+        cats.setdefault(f["category"], []).append(f)
+    for cat in sorted(cats):
+        L += [f"### {_md(cat)} ({len(cats[cat])})", ""]
+        for f in cats[cat]:
+            L += [f"#### `{f['id']}` {_md(f['subject'])}", "",
+                  f"**{f['confidence']}** (score {f['score']}) · analyzers: {_md(', '.join(f['contributing_analyzers']))}"
+                  + (f" · surface: {_md(f['attack_surface'])}" if f["attack_surface"] else ""), ""]
+            cl = f.get("classification") or {}
+            if cl:
+                L += [f"Class: **{_md(cl.get('evidence_class', '?'))}** · verification: **{_md(cl.get('verification_status', '?'))}**"
+                      " (confidence is not exploitability)", ""]
+                L += [f"- limitation: {_md(x)}" for x in cl.get("limitations", [])] + ([""] if cl.get("limitations") else [])
+            if f.get("suggested_test"):
+                L += [f"> {_md(f['suggested_test'])}", ""]
+            L += ["Reasoning:", ""] + [f"- {_md(r)}" for r in f["reasoning"]] + [""]
+            ev = [e for e in f["evidence"] if e.get("snippet")][:3]
+            for e in ev:
+                loc = f"{e['file']}:{e['line']}" if e.get("file") else "-"
+                L += [f"`{_md(e['type'])}` {_md(loc)}", "", _fence(str(e["snippet"])), ""]
+    if payload.get("diagnostics"):
+        L += ["## Diagnostics", ""] + [f"- {_md(d)}" for d in payload["diagnostics"]] + [""]
+    return "\n".join(L)
+
+
+# ----------------------------------------------------------------------------- html
+_CSS = ("body{font:15px/1.5 system-ui,sans-serif;max-width:980px;margin:2rem auto;padding:0 1rem;color:#1b1f23;background:#fff}"
+        "h1,h2{border-bottom:1px solid #d0d7de;padding-bottom:.3rem}code,pre{background:#f6f8fa;border-radius:4px;font-size:13px}"
+        "pre{padding:.6rem;overflow:auto}code{padding:.1rem .3rem}table{border-collapse:collapse;width:100%}"
+        "td,th{border:1px solid #d0d7de;padding:.35rem .5rem;text-align:left;vertical-align:top}"
+        ".c{display:inline-block;border-radius:10px;padding:0 .55rem;font-size:12px;font-weight:600;color:#fff}"
+        ".CONFIRMED{background:#8250df}.HIGH{background:#cf222e}.MEDIUM{background:#bc4c00}.LOW{background:#9a6700}.INFORMATIONAL{background:#57606a}"
+        "details{border:1px solid #d0d7de;border-radius:6px;margin:.4rem 0;padding:.3rem .7rem}summary{cursor:pointer}"
+        "@media(prefers-color-scheme:dark){body{background:#0d1117;color:#e6edf3}code,pre{background:#161b22}td,th,details,h1,h2{border-color:#30363d}}")
+
+
+def to_html(payload: dict, top_n: int = 10) -> str:
+    e = html.escape
+    fs, prio = payload["findings"], _prio(payload)
+    by_id = {f["id"]: f for f in fs}
+    s = payload["summary"]
+    chip = lambda c: f'<span class="c {e(c)}">{e(c)}</span>'
+    h = ["<!doctype html><html lang=en><head><meta charset=utf-8>",
+         "<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'; style-src 'unsafe-inline'; img-src data:\">",
+         f"<meta name=viewport content=\"width=device-width,initial-scale=1\"><title>JScope report</title><style>{_CSS}</style></head><body>",
+         f"<h1>JScope report</h1><p><small>JScope {e(__version__)} · schema {e(str(payload.get('schema_version', '?')))}</small></p>",
+         "<h2>Snapshot</h2><ul>"
+         f"<li>files analyzed: <b>{s['file_count']}</b></li><li>frameworks: {e(', '.join(s['frameworks']) or 'none detected')}</li>"
+         f"<li>findings: <b>{len(fs)}</b> " + " ".join(f"{chip(k)} {v}" for k, v in sorted(_counts(payload).items(), key=lambda kv: _ORDER.index(kv[0]))) + "</li></ul>"]
+    ranked = sorted((p for p in payload.get("priority", []) if p["id"] in by_id), key=lambda p: -p["priority"])[:top_n]
+    if ranked:
+        h.append("<h2>Where to start testing</h2><table><tr><th>#<th>Priority<th>Finding<th>Why / first test</tr>")
+        for i, p in enumerate(ranked, 1):
+            f = by_id[p["id"]]
+            h.append(f"<tr><td>{i}<td>{p['priority']}<td>{chip(f['confidence'])} <code>{e(f['id'])}</code> {e(f['category'])}: {e(f['subject'])}"
+                     f"<td>{e('; '.join(p['reasons']))}" + (f"<br><b>Test:</b> {e(f['suggested_test'])}" if f.get("suggested_test") else "") + "</tr>")
+        h.append("</table>")
+    routes = payload.get("route_map") or []
+    if routes:
+        h.append("<h2>Route map</h2><table><tr><th>Route<th>Protection<th>Endpoints</tr>")
+        for r in routes[:60]:
+            prot = "<b>UNPROTECTED</b>" if r["unguarded"] else e(", ".join(r["guards"] or ["meta"]) + (" / roles: " + ", ".join(r["roles"]) if r["roles"] else ""))
+            h.append(f"<tr><td><code>{e(r['route'])}</code><td>{prot}<td>{e(', '.join(r['endpoints'][:8]))}</tr>")
+        h.append("</table>")
+    h.append("<h2>Findings</h2>")
+    for f in fs:
+        h.append(f"<details><summary>{chip(f['confidence'])} <code>{e(f['id'])}</code> {e(f['category'])}: {e(f['subject'])}</summary>"
+                 f"<p>score {f['score']} · analyzers: {e(', '.join(f['contributing_analyzers']))}"
+                 + (f" · surface: {e(f['attack_surface'])}" if f["attack_surface"] else "") + "</p>"
+                 + (f"<p><b>Class:</b> {e((f.get('classification') or {}).get('evidence_class', '?'))} · <b>verification:</b> "
+                    f"{e((f.get('classification') or {}).get('verification_status', '?'))} <small>(confidence is not exploitability)</small></p>"
+                    + "".join(f"<p><small>limitation: {e(x)}</small></p>" for x in (f.get('classification') or {}).get('limitations', [])))
+                 + (f"<p><b>Suggested test:</b> {e(f['suggested_test'])}</p>" if f.get("suggested_test") else "")
+                 + "<p><b>Reasoning</b></p><ul>" + "".join(f"<li>{e(r)}</li>" for r in f["reasoning"]) + "</ul>")
+        for ev in [x for x in f["evidence"] if x.get("snippet")][:4]:
+            loc = f"{ev['file']}:{ev['line']}" if ev.get("file") else "-"
+            h.append(f"<p><small>{e(ev['type'])} · {e(loc)}</small></p><pre>{e(str(ev['snippet']))}</pre>")
+        h.append("</details>")
+    if payload.get("diagnostics"):
+        h.append("<h2>Diagnostics</h2><ul>" + "".join(f"<li>{e(d)}</li>" for d in payload["diagnostics"]) + "</ul>")
+    h.append("</body></html>")
+    return "".join(h)
+
+
+# ----------------------------------------------------------------------------- SARIF 2.1.0
+def to_sarif(payload: dict) -> str:
+    prio = _prio(payload)
+    rules: dict[str, dict] = {}
+    results = []
+    for f in payload["findings"]:
+        rid = f"jscope/{f['category']}" + (f"/{f['attack_surface']}" if f["attack_surface"] else "")
+        rules.setdefault(rid, {"id": rid, "name": rid.replace("/", "."),
+                               "shortDescription": {"text": f"JScope {f['category']} finding" + (f" ({f['attack_surface']})" if f["attack_surface"] else "")},
+                               "helpUri": "https://github.com/jscope/jscope/blob/main/docs/EVIDENCE_SCHEMA.md"})
+        file, line = _first_loc(f)
+        key = hashlib.sha256(f"{f['category']}|{f['subject']}".encode()).hexdigest()[:32]       # stable across scans (JS-#### ids are not)
+        msg = f"{f['subject']} [{f['confidence']}, score {f['score']}]" + (f". Suggested test: {f['suggested_test']}" if f.get("suggested_test") else "")
+        res: dict[str, Any] = {
+            "ruleId": rid, "level": _SARIF_LEVEL.get(f["confidence"], "note"), "message": {"text": msg},
+            "partialFingerprints": {"jscopeKey/v1": key},
+            "properties": {"jscopeId": f["id"], "evidenceClass": (f.get("classification") or {}).get("evidence_class"),
+                           "verificationStatus": (f.get("classification") or {}).get("verification_status"), "confidence": f["confidence"], "score": f["score"], "attackSurface": f["attack_surface"],
+                           "analyzers": f["contributing_analyzers"], "reasoning": f["reasoning"],
+                           **({"priority": prio[f["id"]]["priority"]} if f["id"] in prio else {})}}
+        if file:
+            loc: dict[str, Any] = {"artifactLocation": {"uri": str(file).replace("\\", "/")}}
+            if line:
+                loc["region"] = {"startLine": int(line)}
+            res["locations"] = [{"physicalLocation": loc}]
+        results.append(res)
+    doc = {"$schema": "https://json.schemastore.org/sarif-2.1.0.json", "version": "2.1.0",
+           "runs": [{"tool": {"driver": {"name": "JScope", "version": __version__, "informationUri": "https://github.com/jscope/jscope",
+                                         "rules": sorted(rules.values(), key=lambda r: r["id"])}},
+                     "results": results,
+                     "invocations": [{"executionSuccessful": True, "toolExecutionNotifications":
+                                      [{"level": "note", "message": {"text": d}} for d in payload.get("diagnostics", [])]}]}]}
+    return json.dumps(doc, indent=2)
+
+
+FORMATS = {"markdown": to_markdown, "md": to_markdown, "html": to_html, "sarif": to_sarif}
+
+
+def render_payload(payload: dict, fmt: str) -> str:
+    return FORMATS[fmt](payload)

jscope/reporting/human.py

@@ -0,0 +1,137 @@
+"""Human-readable report. Structure per design-brainstorm.md §7:
+executive snapshot -> attack-surface dossiers -> full findings appendix.
+Greppable, not decorative -- no ASCII art, stable field ordering."""
+
+from __future__ import annotations
+
+from jscope.core.evidence import Confidence, Finding
+from jscope.core.graph import KnowledgeGraph, NodeKind
+from jscope.reporting.priority import PriorityDelta, prioritize
+
+_CONF_ORDER = [Confidence.CONFIRMED, Confidence.HIGH, Confidence.MEDIUM,
+               Confidence.LOW, Confidence.INFORMATIONAL]
+
+
+def render(findings: list[Finding], frameworks: list[str], file_count: int,
+           verbose: bool = False, top_n: int = 5, graph: KnowledgeGraph | None = None,
+           diagnostics: list[str] | None = None, delta: PriorityDelta | None = None,
+           preface: str | None = None, artifacts: dict | None = None) -> str:
+    lines: list[str] = []
+    lines.append("=" * 70)
+    lines.append("JSCOPE ANALYSIS REPORT")
+    lines.append("=" * 70)
+    lines.append("")
+    if preface:
+        lines.append(preface)
+        lines.append("")
+    lines.append(f"[executive snapshot]")
+    lines.append(f"  files analyzed : {file_count}")
+    lines.append(f"  frameworks     : {', '.join(frameworks) if frameworks else 'none detected'}")
+    if artifacts:
+        lines.append("  artifacts      : " + ", ".join(f"{k}={v}" for k, v in sorted(artifacts.items())))
+    lines.append(f"  findings       : {len(findings)}")
+    for level in _CONF_ORDER:
+        n = sum(1 for f in findings if f.confidence == level)
+        if n:
+            lines.append(f"    {level.value:<14} {n}")
+    lines.append("")
+
+    ranked = prioritize(findings, graph, delta)
+    if ranked:
+        lines.append("[where to start testing]  (deterministic ranking; reasons shown)")
+        for f, pts, why in ranked[:top_n]:
+            lines.append(f"  {pts:>3}  [{f.confidence.value}] {f.id}  {f.category}: {f.subject}")
+            if f.suggested_test:
+                lines.append(f"       test: {f.suggested_test}")
+            if verbose:
+                lines.append(f"       why : {'; '.join(why)}")
+        lines.append("")
+
+    if graph is not None and graph.by_kind(NodeKind.ROUTE):
+        chains = graph.route_chains()
+        lines.append(f"[route map]  {len(chains)} route(s)   (R=route G=guard role=declared role E=endpoint)")
+        shown = chains if verbose else sorted(chains, key=lambda c: (not c["unguarded"], c["route"]))[:top_n * 2]
+        for c in shown:
+            prot = "UNPROTECTED" if c["unguarded"] else "guards=" + ",".join(c["guards"] or ["meta"]) + (
+                " roles=" + ",".join(c["roles"]) if c["roles"] else "")
+            lines.append(f"  R {c['route']:<28} {prot}")
+            for ep in c["endpoints"]:
+                lines.append(f"      E {ep}")
+        if not verbose and len(chains) > len(shown):
+            lines.append(f"  ... {len(chains) - len(shown)} more (use --verbose)")
+        lines.append("")
+
+    surfaces: dict[str, list[Finding]] = {}
+    for f in findings:
+        if f.attack_surface:
+            surfaces.setdefault(f.attack_surface, []).append(f)
+
+    if surfaces:
+        lines.append("[priority attack surfaces]")
+        ranked = sorted(surfaces.items(), key=lambda kv: -len(kv[1]))
+        for surface, items in ranked[:top_n]:
+            lines.append(f"  * {surface}  ({len(items)} finding(s))")
+            for f in sorted(items, key=lambda x: -x.score)[:3]:
+                lines.append(f"      - [{f.confidence.value}] {f.id}  {f.subject}")
+                if f.suggested_test:
+                    lines.append(f"          test: {f.suggested_test}")
+        lines.append("")
+
+    lines.append("[findings appendix]")
+    by_category: dict[str, list[Finding]] = {}
+    for f in findings:
+        by_category.setdefault(f.category, []).append(f)
+
+    for category, items in sorted(by_category.items()):
+        lines.append(f"  -- {category} ({len(items)}) --")
+        for f in items:
+            lines.append(f"  {f.id}  [{f.confidence.value:<13} score={f.score:>2}]  {f.subject}")
+            if verbose:
+                lines.append(f"       analyzers: {', '.join(f.contributing_analyzers)}")
+                for r in f.reasoning:
+                    lines.append(f"       - {r}")
+        lines.append("")
+
+    if diagnostics:
+        lines.append("[diagnostics]")
+        for d in diagnostics:
+            lines.append(f"  ! {d}")
+        lines.append("")
+    lines.append(f"(run `jscope explain <finding-id>` for the full evidence chain on any finding)")
+    return "\n".join(lines)
+
+
+def render_explain(finding: Finding) -> str:
+    lines = [f"Finding {finding.id}: {finding.subject}", "-" * 60]
+    lines.append(f"category        : {finding.category}")
+    lines.append(f"confidence      : {finding.confidence.value} (score={finding.score})")
+    lines.append(f"attack_surface  : {finding.attack_surface or '-'}")
+    tiers = finding.metadata.get("analyzer_tiers", {})
+    lines.append("contributed_by  : " + ", ".join(f"{a} [{tiers.get(a, 'core')}]" for a in finding.contributing_analyzers))
+    lines.append(f"suggested_test  : {finding.suggested_test or '-'}")
+    from jscope.core.classification import classify
+    cl = classify(finding.category, finding.metadata, {e.type.value for e in finding.evidence}, finding.confidence.value)
+    lines.append(f"evidence_class  : {cl['evidence_class']}")
+    lines.append(f"verification    : {cl['verification_status']}  (confidence is not exploitability)")
+    for lim in cl.get("limitations", []):
+        lines.append(f"limitation      : {lim}")
+    flow = finding.metadata.get("flow")
+    if flow:
+        lines.append("")
+        lines.append("data-flow path:")
+        for st in flow["path"]:
+            lines.append(f"  {st['file'].split('/')[-1]}:{st['line']}  {st['step']}")
+        for m in flow.get("mitigations", []):
+            lines.append(f"  mitigation: {m['name']} effective_for={m['effective_for']} uncertain_for={m['uncertain_for']}")
+    lines.append("")
+    lines.append("reasoning chain:")
+    for r in finding.reasoning:
+        lines.append(f"  - {r}")
+    lines.append("")
+    lines.append("raw evidence:")
+    for e in finding.evidence:
+        loc = f"{e.file}:{e.line}" if e.file else "-"
+        lines.append(f"  [{e.type.value}] ({loc}) {e.description}")
+        if e.snippet:
+            lines.append(f"      snippet: {e.snippet}")
+    return "\n".join(lines)

jscope/reporting/json_report.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import json
+
+from jscope.core.evidence import Finding
+from jscope.core.graph import KnowledgeGraph
+from jscope.reporting.priority import PriorityDelta, prioritize
+
+
+def payload(findings: list[Finding], frameworks: list[str], file_count: int,
+            graph: KnowledgeGraph | None = None, diagnostics: list[str] | None = None,
+            delta: PriorityDelta | None = None, dataflow: dict | None = None,
+            file_diagnostics: dict | None = None) -> dict:
+    out = {
+        "schema_version": "0.5",
+        "summary": {"file_count": file_count, "frameworks": frameworks, "finding_count": len(findings)},
+        "findings": [f.to_dict() for f in findings],
+        "priority": [{"id": f.id, "priority": pts, "reasons": why} for f, pts, why in prioritize(findings, graph, delta)],
+        "diagnostics": diagnostics or [],
+    }
+    if dataflow:
+        out["dataflow"] = dataflow
+    if file_diagnostics:
+        out["file_diagnostics"] = file_diagnostics
+    if graph is not None:
+        out["graph"] = graph.to_dict()
+        out["route_map"] = graph.route_chains()
+    return out
+
+
+def render(findings: list[Finding], frameworks: list[str], file_count: int,
+           graph: KnowledgeGraph | None = None, diagnostics: list[str] | None = None,
+           delta: PriorityDelta | None = None, dataflow: dict | None = None,
+           file_diagnostics: dict | None = None) -> str:
+    return json.dumps(payload(findings, frameworks, file_count, graph, diagnostics, delta, dataflow, file_diagnostics), indent=2)