sqlguard-ninja 0.1.0__py3-none-any.whl

sqlguard_ninja/privacy/suggest.py

@@ -0,0 +1,46 @@
+"""Name-based classification *suggestions* for humans to review.
+
+The guard never uses these heuristics to enforce anything: column names are unreliable
+(``notes`` may hold health data, ``email`` may hold a hash). They exist to speed up writing a
+first policy, which a data owner must then confirm.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from sqlguard_ninja.policy.model import Catalog
+
+_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("payment_card", re.compile(r"(card_?(number|no|num)|pan|cc_?num)")),
+    ("financial", re.compile(r"(iban|bank|account_?number|salary|wage|income)")),
+    ("government_id", re.compile(r"(ssn|national_?id|passport|tax_?id|nin\b)")),
+    ("contact", re.compile(r"(e_?mail|phone|mobile|address|postcode|zip)")),
+    ("personal_identifier", re.compile(r"(full_?name|first_?name|last_?name|birth|dob)")),
+    ("special_category", re.compile(r"(health|medical|diagnos|religio|ethnic|biometric)")),
+    ("credentials", re.compile(r"(password|passwd|secret|token|api_?key)")),
+]
+
+
+@dataclass(frozen=True)
+class Suggestion:
+    table: str
+    column: str
+    label: str
+    matched: str
+
+
+def suggest_labels(catalog: Catalog) -> list[Suggestion]:
+    """Suggest labels for unlabelled columns whose names match common patterns."""
+    out: list[Suggestion] = []
+    for tname, table in catalog.tables.items():
+        for cname, col in table.columns.items():
+            if col.labels:
+                continue
+            for label, pattern in _PATTERNS:
+                m = pattern.search(cname)
+                if m:
+                    out.append(Suggestion(tname, cname, label, m.group(0)))
+                    break
+    return out

sqlguard_ninja/query_cost/__init__.py

@@ -0,0 +1 @@
+"""query_cost package."""

sqlguard_ninja/query_cost/postgres.py

@@ -0,0 +1,226 @@
+"""Optional PostgreSQL execution-plan inspection.
+
+Safety rules (see ADR-007):
+
+* Only ``EXPLAIN (FORMAT JSON)`` is run — never ``EXPLAIN ANALYZE``, which executes the query.
+* A statement is inspected only after :class:`~sqlguard_ninja.Guard` ALLOWed it. Planning can
+  still evaluate immutable functions during constant folding, which is why the guard's
+  function policy must run first.
+* The EXPLAIN runs in a ``READ ONLY`` transaction with ``statement_timeout`` set locally,
+  and the transaction is always rolled back.
+* Connect with a low-privilege role. Never inspect untrusted SQL with privileged credentials.
+
+Planner estimates are not guarantees of runtime or resource use.
+
+Requires ``pip install "sqlguard-ninja[postgres]"``.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Iterator, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlguard_ninja.core.analysis import analyse
+from sqlguard_ninja.core.findings import Action, Category, Decision, Finding, Severity
+from sqlguard_ninja.core.guard import Guard
+from sqlguard_ninja.query_cost.static import StaticCostReport, analyse_static_cost
+
+
+class PlanInspectionRefused(PermissionError):
+    """The statement was not allowed by the guard, so it is not sent to the planner."""
+
+
+@dataclass(frozen=True)
+class PlanNodeSummary:
+    node_type: str
+    relation: str | None
+    plan_rows: float
+    total_cost: float
+
+
+@dataclass
+class PlanReport:
+    total_cost: float
+    plan_rows: float
+    nodes: list[PlanNodeSummary]
+    findings: list[Finding] = field(default_factory=list)
+    static: StaticCostReport | None = None
+    raw_plan: Any = None
+
+    @property
+    def decision(self) -> Decision:
+        actions = {f.action for f in self.findings}
+        if Action.DENY in actions:
+            return Decision.DENY
+        if Action.REVIEW in actions:
+            return Decision.REVIEW
+        return Decision.ALLOW
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "decision": self.decision.value,
+            "planner": {"total_cost": self.total_cost, "plan_rows": self.plan_rows},
+            "static": self.static.as_dict() if self.static else None,
+            "nodes": [n.__dict__ for n in self.nodes],
+            "findings": [f.model_dump(mode="json") for f in self.findings],
+        }
+
+
+def _walk(plan: Mapping[str, Any]) -> Iterator[Mapping[str, Any]]:
+    yield plan
+    for child in plan.get("Plans", ()) or ():
+        yield from _walk(child)
+
+
+def summarise_plan(explain_json: Any) -> tuple[float, float, list[PlanNodeSummary]]:
+    """Extract total cost, estimated rows and per-node summaries from EXPLAIN JSON output."""
+    doc = explain_json[0] if isinstance(explain_json, list) else explain_json
+    root = doc["Plan"]
+    nodes = [
+        PlanNodeSummary(
+            node_type=str(n.get("Node Type")),
+            relation=n.get("Relation Name"),
+            plan_rows=float(n.get("Plan Rows", 0)),
+            total_cost=float(n.get("Total Cost", 0)),
+        )
+        for n in _walk(root)
+    ]
+    return float(root.get("Total Cost", 0)), float(root.get("Plan Rows", 0)), nodes
+
+
+def plan_findings(
+    total_cost: float,
+    plan_rows: float,
+    nodes: list[PlanNodeSummary],
+    *,
+    max_total_cost: float | None,
+    max_plan_rows: float | None,
+    large_table_rows: int,
+) -> list[Finding]:
+    findings: list[Finding] = []
+    if max_total_cost is not None and total_cost > max_total_cost:
+        findings.append(
+            Finding(
+                rule_id="cost.planner_total_cost",
+                category=Category.COST,
+                severity=Severity.HIGH,
+                action=Action.REVIEW,
+                message=f"Planner cost estimate {total_cost:,.0f} exceeds the limit "
+                f"{max_total_cost:,.0f}. Estimates are not guarantees.",
+                metadata={"total_cost": total_cost},
+            )
+        )
+    if max_plan_rows is not None and plan_rows > max_plan_rows:
+        findings.append(
+            Finding(
+                rule_id="cost.planner_rows",
+                category=Category.COST,
+                severity=Severity.MEDIUM,
+                action=Action.REVIEW,
+                message=f"Planner expects {plan_rows:,.0f} result rows; the limit is "
+                f"{max_plan_rows:,.0f}.",
+                metadata={"plan_rows": plan_rows},
+            )
+        )
+    for node in nodes:
+        if node.node_type == "Seq Scan" and node.plan_rows >= large_table_rows:
+            findings.append(
+                Finding(
+                    rule_id="cost.planner_seq_scan",
+                    category=Category.COST,
+                    severity=Severity.LOW,
+                    action=Action.WARN,
+                    message=f"Sequential scan of {node.relation} (~{node.plan_rows:,.0f} rows).",
+                    table=node.relation,
+                )
+            )
+        if node.node_type == "Nested Loop" and node.plan_rows >= large_table_rows:
+            findings.append(
+                Finding(
+                    rule_id="cost.planner_nested_loop",
+                    category=Category.COST,
+                    severity=Severity.MEDIUM,
+                    action=Action.WARN,
+                    message=f"Nested loop producing ~{node.plan_rows:,.0f} rows.",
+                )
+            )
+    return findings
+
+
+ConnectionFactory = Callable[[], Any]
+
+
+class PostgresPlanInspector:
+    """Run guarded, non-executing ``EXPLAIN`` and compare planner and static estimates."""
+
+    def __init__(
+        self,
+        guard: Guard,
+        connect: ConnectionFactory,
+        *,
+        statement_timeout_ms: int = 2000,
+    ) -> None:
+        self.guard = guard
+        self.connect = connect
+        self.statement_timeout_ms = statement_timeout_ms
+
+    @classmethod
+    def from_conninfo(
+        cls, guard: Guard, conninfo: str, **kwargs: Any
+    ) -> PostgresPlanInspector:  # pragma: no cover - thin wrapper
+        import psycopg  # noqa: PLC0415 - optional dependency
+
+        return cls(guard, lambda: psycopg.connect(conninfo), **kwargs)
+
+    def inspect(
+        self,
+        sql: str,
+        *,
+        role: str | None,
+        context: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> PlanReport:
+        """Validate, then EXPLAIN ``sql``. ``params`` are bound client-side by psycopg."""
+        result = self.guard.validate(sql, role=role, dialect="postgres", context=context)
+        if result.decision is not Decision.ALLOW:
+            raise PlanInspectionRefused(
+                f"guard decision is {result.decision.value}; only allowed statements are explained"
+            )
+        policy = self.guard.policy
+        analysis = analyse(sql, "postgres", policy.catalog, max_nodes=policy.limits.max_ast_nodes)
+        static = analyse_static_cost(analysis, policy)
+        explain_json = self._explain(sql, params or {})
+        total, rows, nodes = summarise_plan(explain_json)
+        findings = plan_findings(
+            total,
+            rows,
+            nodes,
+            max_total_cost=policy.cost.max_plan_total_cost,
+            max_plan_rows=policy.cost.max_plan_rows,
+            large_table_rows=policy.cost.large_table_rows,
+        )
+        return PlanReport(total, rows, nodes, findings, static, explain_json)
+
+    def _explain(self, sql: str, params: Mapping[str, Any]) -> Any:
+        import psycopg  # noqa: PLC0415 - optional dependency
+
+        conn = self.connect()
+        try:
+            with conn.transaction(force_rollback=True):
+                conn.execute("SET TRANSACTION READ ONLY")
+                conn.execute(
+                    "SELECT set_config('statement_timeout', %s, true)",
+                    (str(self.statement_timeout_ms),),
+                )
+                # Client-side binding: EXPLAIN cannot take server-side parameters.
+                cur = psycopg.ClientCursor(conn)
+                cur.execute("EXPLAIN (FORMAT JSON) " + sql, dict(params) or None)
+                row = cur.fetchone()
+        finally:
+            conn.close()
+        if row is None:  # pragma: no cover - EXPLAIN always returns one row
+            raise RuntimeError("EXPLAIN returned no rows")
+        value = row[0]
+        return json.loads(value) if isinstance(value, str) else value

sqlguard_ninja/query_cost/static.py

@@ -0,0 +1,241 @@
+"""Static, explainable query-cost heuristics.
+
+The score is a sum of documented factor weights, capped at 100. It is a *risk indicator* for
+gating and review, not a prediction of runtime. Row estimates come from the policy catalog
+(``estimated_rows``); without them, size-dependent factors are skipped and reported as such.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+from sqlglot import exp
+
+from sqlguard_ninja.core.analysis import QueryAnalysis, ScopeFacts
+from sqlguard_ninja.core.findings import Action, Category, Finding, Severity
+from sqlguard_ninja.core.rules.base import RuleContext
+from sqlguard_ninja.policy.model import Policy
+
+HUGE_LITERAL = 1_000_000
+
+_GENERATOR_FUNCS = {"generate_series", "range", "sequence"}
+_BLOWUP_FUNCS = {"repeat", "lpad", "rpad", "replicate", "space"}
+_REGEX_TYPES: tuple[type[exp.Expr], ...] = tuple(
+    getattr(exp, n) for n in ("RegexpLike", "RegexpILike", "RegexpExtract") if hasattr(exp, n)
+)
+
+
+@dataclass(frozen=True)
+class CostFactor:
+    code: str
+    points: int
+    explanation: str
+
+
+@dataclass
+class StaticCostReport:
+    score: int
+    factors: list[CostFactor] = field(default_factory=list)
+    unknown_row_estimates: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "score": self.score,
+            "factors": [f.__dict__ for f in self.factors],
+            "unknown_row_estimates": self.unknown_row_estimates,
+        }
+
+
+def _int_literal(node: exp.Expr | None) -> int | None:
+    while isinstance(node, (exp.Paren, exp.Cast)):
+        node = node.this
+    if isinstance(node, exp.Literal) and not node.is_string:
+        try:
+            return int(float(str(node.this)))
+        except ValueError:
+            return None
+    return None
+
+
+def _linked(select: exp.Select, left: str, right: str) -> bool:
+    """True if WHERE contains an equality between columns of the two aliases."""
+    where = select.args.get("where")
+    if where is None:
+        return False
+    for eq in where.find_all(exp.EQ):
+        tables = {c.table for c in eq.find_all(exp.Column)}
+        if left in tables and right in tables:
+            return True
+    return False
+
+
+def analyse_static_cost(analysis: QueryAnalysis, policy: Policy) -> StaticCostReport:
+    factors: list[CostFactor] = []
+    unknown: set[str] = set()
+    large = policy.cost.large_table_rows
+    catalog = policy.catalog
+
+    def rows(name: str) -> int | None:
+        t = catalog.tables.get(name)
+        if t is None or t.estimated_rows is None:
+            unknown.add(name)
+            return None
+        return t.estimated_rows
+
+    root_has_limit = bool(analysis.scopes) and analysis.scopes[-1].has_limit
+    for facts in analysis.scopes:
+        factors.extend(_scope_factors(facts, rows, large, root_has_limit))
+
+    if analysis.join_count > 3:
+        factors.append(
+            CostFactor(
+                "many_joins",
+                5 * (analysis.join_count - 3),
+                f"{analysis.join_count} joins; each join beyond three adds planning and "
+                "execution cost.",
+            )
+        )
+    if analysis.max_depth > 2:
+        factors.append(
+            CostFactor(
+                "deep_nesting",
+                5 * (analysis.max_depth - 2),
+                f"subqueries nested {analysis.max_depth} levels deep",
+            )
+        )
+    root = analysis.qualified
+    if root is not None:
+        factors.extend(_expression_factors(root))
+    score = min(100, sum(f.points for f in factors))
+    return StaticCostReport(score=score, factors=factors, unknown_row_estimates=sorted(unknown))
+
+
+def _scope_factors(
+    facts: ScopeFacts, rows: object, large: int, root_has_limit: bool
+) -> Iterator[CostFactor]:
+    assert callable(rows)
+    select = facts.expression
+    if not isinstance(select, exp.Select):
+        return
+    base = [t for t in facts.tables if not t.is_function]
+    sizes = {t.alias: rows(t.name) for t in base}
+    big = [a for a, n in sizes.items() if n is not None and n >= large]
+    has_where = select.args.get("where") is not None
+
+    joins: list[exp.Join] = list(select.args.get("joins") or [])
+    from_ = select.args.get("from_") or select.args.get("from")
+    first_alias = from_.this.alias_or_name if from_ is not None and from_.this else None
+    for join in joins:
+        alias = join.alias_or_name
+        kind = (join.kind or "").upper()
+        no_condition = not join.args.get("on") and not join.args.get("using")
+        if (kind == "CROSS" or no_condition) and not (
+            first_alias and _linked(select, first_alias, alias)
+        ):
+            n_left = sizes.get(first_alias or "")
+            n_right = sizes.get(alias)
+            weight = 40 if (n_left or 0) >= large or (n_right or 0) >= large else 25
+            yield CostFactor(
+                "cartesian_join",
+                weight,
+                f"join with {alias} has no join condition (Cartesian product)",
+            )
+    if len(big) >= 2 and any(sizes[a] is not None for a in big):
+        names = sorted({t.name for t in base if t.alias in big})
+        if len(names) < len(big):
+            yield CostFactor("large_self_join", 10, "a large table is joined with itself")
+
+    for alias in big:
+        if not has_where:
+            yield CostFactor(
+                "large_scan_no_filter",
+                25,
+                f"{alias} has an estimated {sizes[alias]:,} rows and is read without a filter",
+            )
+    if big and not root_has_limit and facts.depth == 0:
+        yield CostFactor("no_limit_on_large", 10, "large result possible and no LIMIT")
+    if big and select.args.get("order") and not facts.has_limit:
+        yield CostFactor("sort_without_limit", 10, "sorting a large input without LIMIT")
+    if big and select.args.get("distinct"):
+        yield CostFactor("distinct_on_large", 5, "DISTINCT over a large input")
+    if big and has_where:
+        where = select.args["where"]
+        for like in where.find_all(exp.Like, exp.ILike):
+            pattern = like.expression
+            if isinstance(pattern, exp.Literal) and str(pattern.this).startswith("%"):
+                yield CostFactor(
+                    "leading_wildcard", 10, "LIKE pattern starts with % and cannot use an index"
+                )
+                break
+        if _REGEX_TYPES and any(True for _ in where.find_all(*_REGEX_TYPES)):
+            yield CostFactor("regex_filter", 5, "regular-expression filter on a large table")
+    if big and any(isinstance(p, exp.Subquery) or p.find(exp.Subquery) for p in select.expressions):
+        yield CostFactor(
+            "correlated_select_subquery",
+            10,
+            "subquery in the SELECT list may run once per row of a large table",
+        )
+
+
+def _expression_factors(root: exp.Expr) -> Iterator[CostFactor]:
+    with_ = root.args.get("with_") or root.args.get("with")
+    if isinstance(with_, exp.With) and with_.args.get("recursive"):
+        yield CostFactor(
+            "recursive_cte", 30, "recursive CTE; termination cannot be verified statically"
+        )
+        for cte in with_.expressions:
+            body = cte.this
+            if isinstance(body, exp.Union):
+                recursive_arm = body.expression
+                if (
+                    isinstance(recursive_arm, exp.Select)
+                    and recursive_arm.args.get("where") is None
+                ):
+                    yield CostFactor(
+                        "unbounded_recursion",
+                        30,
+                        f"recursive arm of {cte.alias_or_name} has no terminating condition",
+                    )
+    for func in root.find_all(exp.Func):
+        name = func.name.lower() if isinstance(func, exp.Anonymous) else func.sql_name().lower()
+        if isinstance(func, getattr(exp, "GenerateSeries", ())):
+            name = "generate_series"
+        if name in _GENERATOR_FUNCS:
+            values = [_int_literal(a) for a in func.args.values() if isinstance(a, exp.Expr)]
+            numbers = [v for v in values if v is not None]
+            if numbers and max(map(abs, numbers)) >= HUGE_LITERAL:
+                yield CostFactor("row_generator", 60, f"{name}() generating a very large range")
+            elif not numbers or len(numbers) < len(values):
+                yield CostFactor("row_generator", 40, f"{name}() with a non-literal bound")
+        elif name in _BLOWUP_FUNCS:
+            values = [_int_literal(a) for a in func.args.values() if isinstance(a, exp.Expr)]
+            if any(v is not None and v >= HUGE_LITERAL for v in values):
+                yield CostFactor("string_blowup", 60, f"{name}() with a very large size argument")
+
+
+class StaticCostRule:
+    """Turn the static cost score into findings using the policy thresholds."""
+
+    rule_ids = ("cost.static_score",)
+
+    def check(self, ctx: RuleContext) -> Iterator[Finding]:
+        cfg = ctx.policy.cost
+        if not cfg.enabled:
+            return
+        report = analyse_static_cost(ctx.analysis, ctx.policy)
+        if report.score < cfg.review_score:
+            return
+        action = Action.DENY if report.score >= cfg.deny_score else Action.REVIEW
+        top = sorted(report.factors, key=lambda f: -f.points)[:3]
+        yield Finding(
+            rule_id="cost.static_score",
+            category=Category.COST,
+            severity=Severity.HIGH if action is Action.DENY else Severity.MEDIUM,
+            action=action,
+            message=f"Estimated query cost risk is {report.score}/100: "
+            + "; ".join(f.explanation for f in top)
+            + ".",
+            metadata=report.as_dict(),
+            remediation="Add selective filters, join conditions and a LIMIT.",
+        )

sqlguard_ninja/reporting/__init__.py

@@ -0,0 +1 @@
+"""Report rendering."""

sqlguard_ninja/reporting/markdown.py

@@ -0,0 +1,137 @@
+"""Human-readable Markdown reports (also used for the GitHub Actions job summary)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlguard_ninja.benchmarking.compare import Comparison
+
+
+def _pct(value: float | None) -> str:
+    return "n/a" if value is None else f"{value * 100:.1f}%"
+
+
+def _ms(value: float | None) -> str:
+    return "n/a" if value is None else f"{value:.2f}"
+
+
+def _row(name: str, m: dict[str, Any]) -> str:
+    return (
+        f"| {name} | {m['cases']} | {_pct(m['recall'])} | {_pct(m['precision'])} | "
+        f"{_pct(m['false_positive_rate'])} | {_pct(m['false_negative_rate'])} | "
+        f"{_pct(m['exact_match_rate'])} | {m['fn']} | {m['fp']} |"
+    )
+
+
+_HEADER = (
+    "| Slice | Cases | Recall | Precision | FPR | FNR | Exact match | FN | FP |\n"
+    "|---|---:|---:|---:|---:|---:|---:|---:|---:|"
+)
+
+
+def benchmark_report(result: dict[str, Any], *, max_examples: int = 15) -> str:
+    m = result["metrics"]
+    b, a, env = result["benchmark"], result["adapter"], result["environment"]
+    lat = m["overall"]["latency_ms"]
+    lines = [
+        f"# SQL security benchmark — `{a['name']}` {a['version']}",
+        "",
+        f"Benchmark **{b['name']} {b['version']}** (fingerprint `{b['fingerprint']}`), "
+        f"{b['cases_evaluated']} evaluations. Python {env['python']}, sqlglot "
+        f"{env.get('sqlglot')}, {env['platform']}.",
+        "",
+        "Positive class = cases that must not run unattended (expected deny or review).",
+        "",
+        "## Summary",
+        "",
+        _HEADER,
+        _row("all cases", m["overall"]),
+        _row("within declared capability", m["within_capability"]),
+        "",
+        f"Latency per evaluation (ms): p50 {_ms(lat['p50'])}, p95 {_ms(lat['p95'])}, "
+        f"p99 {_ms(lat['p99'])}, max {_ms(lat['max'])}. Validator errors: "
+        f"{m['overall']['errors']}.",
+        "",
+        "## By category",
+        "",
+        _HEADER,
+        *(_row(k, v) for k, v in m["by_category"].items()),
+        "",
+        "## By dialect",
+        "",
+        _HEADER,
+        *(_row(k, v) for k, v in m["by_dialect"].items()),
+        "",
+        "## By provenance",
+        "",
+        _HEADER,
+        *(_row(k, v) for k, v in m["by_provenance"].items()),
+        "",
+    ]
+    by_id = {c["id"]: c for c in result["cases"]}
+    for title, key in (
+        ("False negatives (unsafe, allowed)", "false_negative_examples"),
+        ("False positives (safe, blocked)", "false_positive_examples"),
+    ):
+        ids = m[key][:max_examples]
+        lines += [f"## {title}", ""]
+        if not ids:
+            lines += ["None.", ""]
+            continue
+        lines += ["| Case | Category | Expected | Actual | Reasons |", "|---|---|---|---|---|"]
+        for cid in ids:
+            c = by_id[cid]
+            reasons = ", ".join(c["reasons"][:3]) or "—"
+            lines.append(
+                f"| `{cid}` | {c['category']} | {c['expected']} | {c['actual']} | {reasons} |"
+            )
+        lines.append("")
+    return "\n".join(lines)
+
+
+def comparison_report(comp: Comparison, *, max_items: int = 20) -> str:
+    status = "✅ PASSED" if comp.passed else "❌ FAILED"
+    b, n = comp.baseline, comp.candidate
+    bm, nm = b["metrics"]["overall"], n["metrics"]["overall"]
+    lines = [
+        f"# SQL safety regression check: {status}",
+        "",
+        f"Baseline `{b['adapter']['name']} {b['adapter']['version']}` "
+        f"(benchmark `{b['benchmark']['fingerprint']}`) vs candidate "
+        f"`{n['adapter']['name']} {n['adapter']['version']}` "
+        f"(benchmark `{n['benchmark']['fingerprint']}`).",
+        "",
+        "| Metric | Baseline | Candidate |",
+        "|---|---:|---:|",
+        f"| Recall | {_pct(bm['recall'])} | {_pct(nm['recall'])} |",
+        f"| Precision | {_pct(bm['precision'])} | {_pct(nm['precision'])} |",
+        f"| False-positive rate | {_pct(bm['false_positive_rate'])} | "
+        f"{_pct(nm['false_positive_rate'])} |",
+        f"| p95 latency (ms) | {_ms(bm['latency_ms']['p95'])} | {_ms(nm['latency_ms']['p95'])} |",
+        "",
+    ]
+    if comp.failures:
+        lines += ["## Gate failures", "", *(f"- {f}" for f in comp.failures), ""]
+    sections = [
+        ("Security regressions (unsafe query now allowed)", comp.security_regressions),
+        ("  of which privacy", comp.sensitive_regressions),
+        ("  of which tenant isolation", comp.tenant_regressions),
+        ("Newly blocked legitimate queries", comp.usability_regressions),
+        ("New validator errors", comp.new_errors),
+        ("New parse failures on legitimate queries", comp.new_parse_failures),
+        ("Changed expected labels (need explicit approval)", comp.label_changes),
+        ("Other decision changes", comp.decision_changes),
+        ("Improvements", comp.improvements),
+    ]
+    for title, ids in sections:
+        lines.append(f"- **{title.strip()}**: {len(ids)}")
+        for cid in ids[:max_items]:
+            lines.append(f"  - `{cid}`")
+    if comp.p95_change_pct is not None:
+        lines.append(f"- **p95 latency change**: {comp.p95_change_pct:+.1f}%")
+    lines += [
+        "",
+        "Baselines are never updated automatically. To accept intentional changes, run "
+        "`sqlninja benchmark baseline` locally and commit the result for review.",
+    ]
+    return "\n".join(lines)