docs: add security-researcher severity analysis (§7) + fig7

New section and figure on what raises severity: (a) attacker-reachability drives
it — consensus_divergence (lift x1.55), resource_exhaustion (x1.39), integer
overflow (x1.28) are over-represented in Critical/High, while race_condition has
lift ~0 (needs local timing). (b) The central paradox: the severe classes are
patched silently 91-98% of the time (consensus_divergence 162/174 = 93% unrated),
so the rated column understates the severe population ~10x. Reporting bias: geth
= 41% of rated-high because it publishes advisories, not because it has more
severe bugs; fix size doesn't separate severity. scripts/make_figures.py adds
fig7.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: grandchildrice

docs/analysis.md

@@ -7,7 +7,7 @@ security fixes across the eleven production Ethereum clients.*
 > **Summary.** The corpus is dominated by *silently patched* fixes (≈94% ship
 > with no advisory), its vulnerability profile is **availability- and
 > consensus-centric** rather than the memory-corruption profile of generic C/C++
-> datasets, its fixes are **localized** (43% single-file), and it spans **six
+> datasets, its fixes are **localized** (43% single-file), its **severe classes are the ones most often patched silently**, and it spans **six
 > languages implementing one protocol** — a diversity axis absent from prior
 > vulnerability datasets. We interpret each finding against the
 > vulnerability-dataset literature (CVEfixes, BigVul, Devign, CrossVul,
@@ -112,7 +112,49 @@ across implementations. It is the diversity dimension DiverseVul and CrossVul
 argue reduces overfitting, obtained here **within a single well-specified
 domain**.
 
-## 7. Data quality and coverage
+## 7. A security-researcher reading — what raises severity
+
+Only 143 rows carry a rated severity and 66 are Critical/High, so this is a small,
+biased sample (see the reporting-bias caveat below) — but the signal is sharp.
+
+![Figure 7](figures/fig7_severity_drivers.png)
+
+**(a) Attacker-reachability is the severity driver.** Among Critical/High fixes,
+38% are triggered by `malformed_input` and the rest by `malicious_tx` /
+`malicious_p2p_message` — externally reachable, adversary-controlled paths. By
+root cause, three classes are *over-represented* in the high-severity slice:
+**consensus_divergence (lift ×1.55)**, **resource_exhaustion / DoS (×1.39)**, and
+**integer_overflow (×1.28)**. Strikingly, **`race_condition` has lift ≈ 0** — it
+is 10% of all fixes but essentially never rated Critical/High, because it
+typically needs local timing rather than a remote trigger. Severity here tracks
+*reachability × blast-radius* (chain split, node crash, fund-affecting
+arithmetic), not code-level bug class alone.
+
+**(b) The severe classes are the ones most often patched silently — the central
+paradox.** Every root cause, including the severe ones, is shipped *silently*
+91–98% of the time: **consensus_divergence is 93% unrated, integer_overflow 96%,
+resource_exhaustion 94%.** Concretely, of **174 `consensus_divergence` fixes only
+12 are rated — 162 (93%) carry no severity at all**, despite consensus divergence
+being the single highest-severity-lift class. The rated-severity column therefore
+*understates* the severe population by roughly an order of magnitude.
+
+**Reporting bias, not a severity map.** Geth accounts for **41% (27/66)** of all
+Critical/High rows — not because Geth has more severe bugs, but because it
+publishes GitHub Security Advisories while most clients patch silently. So the
+rated slice is a **publication artifact**: a client's presence in it measures its
+disclosure policy, not its security posture. And fix size does **not** separate
+severity (median 51 LOC high-severity vs 45 overall) — you cannot spot a critical
+bug by diff size.
+
+*Takeaways for a researcher.* (i) Prioritize by **attacker-reachability ×
+subsystem** (p2p, rpc, crypto, consensus state-transition) rather than by whether
+a CVE exists. (ii) The **unrated `consensus_divergence` / `resource_exhaustion`
+rows are a hunting ground** for under-triaged severe bugs — the corpus surfaces
+exactly the silent, high-impact fixes that CVE-anchored datasets miss. (iii)
+Because one spec is implemented eleven ways, a severe fix in one client is a lead
+to look for its **silent analogue in the others** (§6).
+
+## 8. Data quality and coverage
 
 ![Figure 6](figures/fig6_coverage.png)
 
@@ -137,7 +179,7 @@ The low bars — `severity` (6.4%) and `silent_fix_prob` (40%) — are structura
 not defects: unrated severity *is* the silent-fix signal (§2), and full-commit
 LLM classification was deliberately bounded (§8).
 
-## 8. Implications for use
+## 9. Implications for use
 
 1. **Selection under a <1% base rate.** Security fixes are a fraction of a
    percent of commits — VulFixMiner's "needle in a haystack." The pipeline

docs/figures/fig7_severity_drivers.png

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 """make_figures.py — regenerate docs/figures/*.png from data/ethereum_vulns.parquet.
-
-Run from the repo root:  uv run --with matplotlib python scripts/make_figures.py
-Used by docs/analysis.md."""
+Run from repo root:  uv run --with matplotlib python scripts/make_figures.py"""
+import pandas as pd, numpy as np, json
+import matplotlib as mpl; mpl.use("Agg")
 import matplotlib.pyplot as plt
 from matplotlib.ticker import PercentFormatter
 
@@ -130,3 +130,36 @@ def loc(s):
 print("figures written to",FG)
 import os
 for f in sorted(os.listdir(FG)): print("  ",f, round(os.path.getsize(FG+"/"+f)/1024),"KB")
+
+# ---- FIG 7: what raises severity (security-researcher view) -----------------
+sev=d.severity.str.lower()
+hi=d[sev.isin(['critical','high'])]
+causes=[c for c in d.root_cause.value_counts().head(8).index if c!='other']
+lift=[]; silent=[]
+for rc in causes:
+    p_all=(d.root_cause==rc).mean(); p_hi=(hi.root_cause==rc).mean()
+    lift.append(p_hi/p_all if p_all else 0)
+    sub=d[d.root_cause==rc]
+    silent.append(100*(~sub.severity.str.lower().isin(['critical','high','medium','low'])).mean())
+order=np.argsort(lift)
+causes=[causes[i] for i in order]; lift=[lift[i] for i in order]; silent=[silent[i] for i in order]
+fig,(a1,a2)=plt.subplots(1,2,figsize=(11.5,4.3))
+y=np.arange(len(causes))
+cols=[RED if l>1.15 else (GRAY if l<0.85 else BLUE) for l in lift]
+a1.hlines(y,1,lift,color=cols,lw=2,zorder=1)
+a1.scatter(lift,y,color=cols,s=60,zorder=2)
+a1.axvline(1,color="#888",lw=1,ls="--")
+a1.set_yticks(y); a1.set_yticklabels([c.replace('_',' ') for c in causes])
+a1.set_xlabel("severity lift   P(cause | Crit+High) / P(cause | all)")
+a1.set_title("(a) What raises severity",loc="left",fontsize=12,color=INK,fontweight="bold")
+a1.text(1.02,len(causes)-0.5,"over-\nrepresented →",color=RED,fontsize=8,va="top")
+a1.grid(axis="y",visible=False)
+a2.barh(y,silent,color=[ORANGE if s>85 else TEAL for s in silent],height=0.7)
+a2.set_yticks(y); a2.set_yticklabels([c.replace('_',' ') for c in causes])
+a2.set_xlabel("% shipped silently (no rated severity)")
+a2.xaxis.set_major_formatter(PercentFormatter()); a2.set_xlim(0,100)
+for yi,s in zip(y,silent): a2.text(s-3,yi,f"{s:.0f}%",va="center",ha="right",color="white",fontsize=8.5,fontweight="bold")
+a2.set_title("(b) …yet the severe classes are patched silently",loc="left",fontsize=12,color=INK,fontweight="bold")
+a2.grid(axis="y",visible=False)
+plt.tight_layout(); plt.savefig(f"{FG}/fig7_severity_drivers.png",bbox_inches="tight"); plt.close()
+print("fig7 written")