README.md

---
title: nr-bundle-classifier
emoji: 🛡️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
python_version: "3.12"
license: apache-2.0
short_description: Bundle v1 classifier — V8 + multi-class folded
tags:
  - cybersecurity
  - blockchain
  - network-security
  - validator-security
  - sui
  - solana
---

# nr-bundle-classifier

Interactive Gradio Space for NullRabbit's published bundle v1 classifiers. Accepts a user-uploaded bundle (zip or directory), validates against the open [bundle v1 spec](https://github.com/NullRabbitLabs/nr-bundle-spec), and runs both the V8 cipher-agnostic byte-amplification binary detector and the multi-class softmax folded 9-class unified detector. Returns per-class probabilities + scoreability + feature-coverage flags.

This is the data-layer artefact of NullRabbit Labs' research on **autonomous defence for decentralised networks**. The methodology is the contribution; the Space is a worked demonstration of the spec → corpus → model → unified-detector path end-to-end on user-supplied data.

## What it shows

For each uploaded bundle, the Space displays:

1. **Bundle metadata** parsed from `manifest.json` (corpus_id, primitive_id, family, chain, fidelity_class, ground_truth_label).
2. **Modality state** (`responses_rows`, `packets_pcap_present`).
3. **V8 binary verdict** — attack/benign + calibrated P(attack).
4. **Multi-class folded verdict** — 9-class softmax (benign + V8/V9/V10/V11/V12/V13/V14/V16) with per-class P + feature_coverage flag + coverage_warning when the predicted class is sensitive to missing modalities.

## How to try it

- Upload a bundle directory or `.zip` of one. Sample bundles are available at [NullRabbit/nr-bundles-public](https://huggingface.co/datasets/NullRabbit/nr-bundles-public) (CC-BY-4.0).
- Quickest path: download one bundle from the public dataset (e.g. `crp_1ef98f1fc0644369`, a `sui_F14` compute-amp attack) and upload the directory zipped.

## Backing models

- **V8 cipher-agnostic byte-amplification detector** (Apache-2.0): [NullRabbit/v8-cipher-agnostic](https://huggingface.co/NullRabbit/v8-cipher-agnostic). Binary classifier over 7 cipher-agnostic features. Reference detector for byte-amplification attacks against validator JSON-RPC.
- **Multi-class softmax folded detector** (Apache-2.0): [NullRabbit/multiclass-folded](https://huggingface.co/NullRabbit/multiclass-folded). 9-class joint classifier over 107 features. Unified detector for the V8-V14 + V16 attack-family taxonomy.

Both models are products of NullRabbit's pre-registration discipline applied to network-layer attack detection. The iterative leak-surface peeling pattern is documented in their model cards.

## Honest limitations

- **Public dataset bundles have raw `packets.pcap` dropped** per their safety policy. Some class manifolds (V8 response_amp, V13 service_misconfig, V14 compute_amp) survive this and produce correct verdicts; others (V11 rate_limiter_bypass, benign-with-traffic, V16 gossip-abuse) are load-bearing on `pcap.*` features and skew accordingly. Coverage warnings emit when the predicted class is sensitive to the missing modality.
- **n=1 OOF fragility** on the V16 load-bearing benign (SOL_BG01). Documented in the multiclass-folded model card. The fitted model routes SOL_BG01 to benign correctly; OOF held-out is fragile. Production V16 deployment requires corpus scale-up.
- **No streaming detection**: this Space scores single bundles, not live packet streams. Production deployment uses IBSR (an eBPF-based extractor) feeding the same models in a real-time loop; that's the operator-side runbook, not this Space.

## Methodology

NullRabbit's training cycles follow pre-registration discipline. Each detector cycle has a design document committed before the trainer runs. Audits run on close against sanity floors, per-feature ablation trails, and falsification holdouts. Where an audit fires, training halts, the design is re-registered, and the prior version is retracted in writing.

The **iterative leak-surface peeling pattern** is the methodology contribution. The current model cycle (V16 → multi-class folded v2, 2026-05-13) is the worked example at the unified-detector layer: V15 binary pre-registered a leak caveat (manifest may learn protocol shape, not attack shape); cycle2 corpus expansion provided the load-bearing UDP benign that made the caveat empirically testable; V15 evaluation confirmed the caveat; V16 binary retrained with corpus augmentation closed the caveat at the n=1 fragile level; multi-class folded v2 absorbed V16 into the unified detector with the load-bearing benign test passing at training-set scale and the OOF fragility surfaced honestly.

The corpus format and family taxonomy are open at `nr-bundle-spec`. The methodology is open (in preparation as the substrate paper). The specific corpus contents beyond `nr-bundles-public` are proprietary.

## Related

- **Bundle format spec**: [`nr-bundle-spec`](https://github.com/NullRabbitLabs/nr-bundle-spec) (MIT)
- **Reference public bundles**: [NullRabbit/nr-bundles-public](https://huggingface.co/datasets/NullRabbit/nr-bundles-public) (CC-BY-4.0)
- **V8 binary detector**: [NullRabbit/v8-cipher-agnostic](https://huggingface.co/NullRabbit/v8-cipher-agnostic) (Apache-2.0)
- **Multi-class folded detector**: [NullRabbit/multiclass-folded](https://huggingface.co/NullRabbit/multiclass-folded) (Apache-2.0)
- **Earned-autonomy paper** (governance layer): [Zenodo DOI 10.5281/zenodo.18406828](https://doi.org/10.5281/zenodo.18406828)
- **Substrate paper** (data-layer methodology, in preparation)
- **NullRabbit Labs**: [huggingface.co/NullRabbit](https://huggingface.co/NullRabbit)
- **Website**: [nullrabbit.ai](https://nullrabbit.ai)

## Contact

Research enquiries: simon@nullrabbit.ai

Spec compliance or format questions — open an issue at [`nr-bundle-spec`](https://github.com/NullRabbitLabs/nr-bundle-spec).