nr-network-known-class-detector

A binary attack-vs-benign detector for blockchain-node network/resource attacks, trained entirely on faithful reproductions of publicly-disclosed attacks. Every attack class in the corpus reproduces a specific public disclosure — a CVE, a GHSA, or a named third-party security audit — and each carries a provenance.source_class recording how public its sourcing is. Part of NullRabbit's work on autonomous defence for decentralised networks — watch the outside of the perimeter.

STATUS: DIAGNOSTIC, not a deployment claim. Trained on synthetic localnet reproductions (lab fidelity), not real production traffic. See Evaluation and Limitations.

Model description

Given the network-layer signal of a short capture window against a blockchain node (packet-rate / size statistics from the pcap, and amplification / request-response / timing statistics from the RPC responses), the model emits a calibrated attack probability. It is one multi-family model over the network-v1 feature manifold — it spans 18 chains, all public-sourced (this published cut is trained on public-cve-replication primitives only).

Architecture

• HistGradientBoostingClassifier + isotonic calibration (scikit-learn), NaN-native.
• pcap aggregates + RPC-response aggregates, degenerate columns dropped by a per-fit robust-column guard. No host-load features (the containerised lab node is root-owned, so host metrics are unreadable).
• Decision threshold 0.5 (calibrated). Inference is scoreability-gated: a record with no network signal (e.g. an economic/DeFi bundle) returns scoreable=False with no verdict.

Training data — 140 public-CVE attack primitives, 18 chains, 919 bundles

This is the public-CVE cut (public-cve-replication only): 716 attack + 203 benign bundles (pcap + responses + manifest), 142 chain×primitive instances. Benign traffic exercises the same methods / wire messages the attacks abuse, at normal scale — so the model separates attack-use from benign-use, not message type. Every attack reproduces an external public disclosure with a provenance.public_source URL. (0 original primitives — NullRabbit's own measurement of vendor-acknowledged RPC amplification, for which no CVE exists — are held in the full corpus but excluded from this published cut, so the "trained entirely on public disclosures" claim above is literal.)

Distribution: 716 public-cve-replication attack bundles — 140 distinct primitives across 18 chains (Bitcoin, conflux, Cosmos, Dogecoin, Ethereum, http2, http3, ipfs, libp2p, Litecoin, Monero, namada, nimiq, polkadot, quic, Solana, Sui, Zcash) — plus 203 benign. This published cut contains no original bundles; the original RPC-measurement primitives live in the full internal corpus and ship only if the operator explicitly opts in, always under their honest label.

Training procedure (methodology is the contribution)

Per NullRabbit's pre-registration discipline: the corpus is built attack-by-attack from a public disclosure with provenance.public_source; a Cleanlab data-quality scan gates label-issues and duplicates before training; a methodology auditor reviews each gate event with sanity floors and falsification holdouts; honest limitations are stated; cycles — not the final number — are the contribution. This card + model are regenerated automatically from the cut on each training run, so the numbers below always match the shipped model.

Evaluation

Diagnostic ML checks (the corpus of faithfully-modelled public attacks is the deliverable; these are secondary). Reproduced by scripts/known_class_loco_eval.py + scripts/corpus_quality.py.

• Within-corpus held-out — binary attack-vs-benign ROC-AUC, GroupKFold by primitive: 0.9441. corpus_sha256 known-class-v10-publiccve.
• Leave-one-chain-out — binary ROC-AUC (HARD zero-shot transfer, not a deployment metric): Sui 1.000 / Ethereum 0.992 / Monero 0.985 / libp2p 0.897 / Bitcoin 0.818 / Cosmos 0.789 / Zcash 0.590. Chains with few public-CVE primitives have the fewest cross-chain near-neighbours; the companion nr-bundles-public dataset card reports the stricter held-out-chain 7-class family macro-F1 (0.17 Sui / 0.35 Solana vs ~0.14 floor). Reported honestly, not a deployment claim.
• Leave-one-attack-primitive-out within Bitcoin (leak-clean disjoint-benign): all Bitcoin primitives ≥ 0.958. Detection is on traffic shape, not deep wire-semantics.

Intended uses

Research and benchmarking of network/resource-abuse detection on blockchain infrastructure; a worked, public-provenance reference corpus; downstream training. Not a turnkey production IDS.

Limitations

• Synthetic lab fidelity — generated localnet traffic, not a real-world deployment claim. A deployment claim needs a real-traffic validation gate (real mainnet RPC + real attack instances).
• Detection is on traffic shape (volume / rate / size / connection-churn), not deep wire semantics — adequate for these volumetric/crash DoS classes; it would not separate two attacks with identical traffic profiles.
• No host-load features (root-owned container).
• This is the public-CVE cut — every shipped attack class reproduces an external public disclosure. The original RPC-amplification measurements (vendor-acknowledged but not CVE-backed) are excluded from this model; they exist in the full internal corpus and ship only on explicit operator opt-in.

How to use

from predict import load, predict
model = load("model.joblib")
out = predict(model, [{"pcap.packet_rate": 850.0, "resp.amp_ratio_max": 224.0}])
# -> [{"scoreable": True, "score": ..., "verdict": "attack"|"benign", "threshold": 0.5}]

Run python inference_example.py for a worked example on real captured vectors.

Reproduce or train your own. A self-contained, runnable example that trains a family (mechanism) detector on the openly-available bundles — download → read manifest + Parquet → featurise → train → evaluate both in-distribution and cross-chain (leave-one-chain-out) — is in nr-bundle-spec: examples/train_a_family_detector.py (and the matching .ipynb). The leave-one-chain-out number it reports is the earned-autonomy line — where the mechanism signal genuinely transfers to a chain the detector never trained on, and where it does not (so the honest move is to gate the detector to chains you have data for). See docs/integration-bundles-taxonomy-autonomy.md.

Licensing

Apache-2.0 (see LICENSE). Attribution appreciated.

Citation

@software{nullrabbit_network_known_class_2026,
  author = {NullRabbit Labs},
  title  = {nr-network-known-class-detector: a public-provenance blockchain network-attack detector},
  year   = {2026},
  url    = {https://huggingface.co/NullRabbit/nr-network-known-class-detector}
}

Related: the open bundle format (nr-bundle-spec), the family taxonomy (mechanism-defined), the earned-autonomy framework (Zenodo 10.5281/zenodo.18406828), the dataset NullRabbit/nr-bundles-public, and nullrabbit.ai.

Contact

NullRabbit Labs — huggingface.co/NullRabbit · nullrabbit.ai