🛡️ IronJean WAF v2.5 (ModernBERT Landmark Pooling)

IronJean WAF v2.5 is an enterprise-grade, transformer-based Web Application Firewall (WAF) classification model engineered on top of ModernBERT-base and purpose-built for REST API Gateways and modern backend microservices. It combines Vectorized Landmark Pooling, Multi-Pass Recursive Anti-Evasion Normalization, and Exploit-Aware Network Landmark Anonymization, leveraging ModernBERT's 8,192-token context window (RoPE + Flash Attention / Unpadding) to inspect complete HTTP headers and API request bodies without truncation, delivering deterministic, sub-millisecond threat detection across structured API payload trees without lexical keyword overfitting.

Unlike traditional regex rules, legacy 512-token BERT classifiers, or naive [CLS] sequence transformers, IronJean WAF is specifically tailored to the semantic grammar of REST API protocols (REST/JSON, GraphQL, XML/SOAP, Form/Multipart, gRPC, OAuth2/JWT) while achieving a benchmarked 100.00% Global Accuracy (100.00% Precision / 0.00% FPR, 100.00% Recall / 0.00% FNR) across 160,500 payloads sourced exclusively from fully cleaned open-source and synthetic datasets as part of my independent research.

Supported Attack Vectors: 22 attack families, modern 2024–2025 CVEs, and evasion techniques natively detected out-of-the-box by IronJean WAF v2 across all 4 HTTP landmarks (METHOD, URI, HEADERS, BODY).

Zero-Forgetting WAF Domain Adaptation: ModernBERT Landmark Pooling + WiSE-FT + Swagger Synthesizer ingests any local or remote Swagger 2.0 / OpenAPI 3.x contract, endpoints, path parameters, query types, and JSON/XML/Form schemas.

🛠️ Pre-Trained WAF Baseline & Transfer-Learning Checkpoint: Rather than a rigid black-box rule engine, IronJean v2 is designed as an open WAF baseline checkpoint. Having already learned HTTP landmark structure and common OWASP exploit patterns, it provides a solid starting point for Shadow Mode evaluation, threshold calibration, or lightweight domain adaptation (e.g., via WiSE-FT) on your own production telemetry.

---

🆕 News notes v2.5 - 11/11/2026

• Upgraded HTTPNormalizer v2.5: Pre-compiled LRU regex engine (maxsize=2048), multi-block/double-encoded MySQL /*!...*/ comment unwrapping, UTF-16LE/ASCII hex SQL literal decoding (0x...), standalone WAITFOR DELAY canonicalization, strengthened Cookie/Redirect/CMD guards, and strict key=value raw-payload framing—validated across 204/204 production Postman-Echo tests.
• Sub-Route CMS Topological Rebalancing (v34b): Balanced level-3 WordPress /blog/* sub-routes (wp-content/themes, uploads, plugins, wp-includes/js, my-account) to ~50/50 Safe/Attack parity to eliminate sub-route prior skew.
• Spike-Free Convergence (eval_loss: 0.000015) & SOTA Benchmarks: Achieved 100.00% (1.0) Validation Accuracy, Precision, Recall, and F1 (1.51e-5 loss — 99.9985% confidence), 100.00% on v34b (160,500/160,500 at 719.25 req/s), waf-bench (77/77), gotestwaf (822/822), and openappsec-attacks (73,924/73,924), 99.93% on shengqin-waf (0 FP at 0.85 prod threshold), and 100.00% Precision (0 FP) on http-attack-requests.
• Terminal Phase of Training (v34 → v34b): Early low-LR warmup alignment of the classification head combined with lossless Cookie: exploit preservation (HTTPNormalizer v2.5) eliminated contradictory [SEP] header signals and late Focal Loss (γ = 2.0) gradient spikes—driving eval_loss 4.6× lower at Epoch 2 (2.14e-5, 0 FP) and 2.3× lower at Epoch 3 (1.51e-5, zero loss spikes across Epochs 2–3).
• Unified Landmark Pooling & TensorBoard Telemetry (runs/): Unified async GPU/ONNX landmark_pool kernel across training and Hugging Face trust_remote_code=True, with interactive TensorBoard logs published in ./runs.

Click to expand / Release Notes Archives

🆕 News notes v2.4 - 7/11/2026

• Upgraded HTTPNormalizer v2.4 Generic Rule Refactoring & Zero-ReDoS Architecture: Removed all one-off dataset patches in favor of generic, ReDoS-safe anti-evasion and canonicalization rules:
  • Double-Encoded & Truncated HTML Entity Unwrapping: Recursively unwraps & before numeric or named HTML/XSS entities (&#0000106, <, :), supports truncated HTML5 &perio with a query-parameter negative lookahead (?![a-zA-Z0-9_]*=) (preventing collisions with benign URL parameters such as &period=5y), and expands inline numeric entity decoding across 5-digit decimal padding and attribute delimiters.
  • Unified LFI & SQL Comment De-Obfuscation: Non-backtracking LFI traversal canonicalization across Unix/Windows targets (etc/(passwd|shadow|issue|hosts|group)|boot.ini|win.ini|system.ini), overlong UTF-8 %c0n dot-evasion decoding, and targeted SQL function comment unwrapping (database/**...**/() → database()) that preserves LDAP wildcard filters (/*)(uid=*))(|(uid=*/) and /**/ SQLi tokens.
  • Canonical SQLi, CMDi & XSS Structural Normalization: Generic canonicalization for UNION ALL SELECT, negative-ID -\d+ UNION SELECT, standalone CONCAT(...) with SQL introspection functions (database(), version(), user(), information_schema), long hex literals (0x[0-9a-f]{24,}), boolean OR/AND x BETWEEN y AND z, || col IS [NOT] NULL, AND user_name() =, chained shell commands (& dir, | id, ; whoami), malformed self-closing event tags (<img </onload=...>), and bare/encoded < parameter probes.
  • Benign Query Parameter Canonicalization: Generic normalization for example.com/org/net test URLs, international postal addresses (street, number), non-OAST email addresses in query parameters, intra-word */$ typos, and leading-dot uppercase acronyms (=.DOTe) while strictly preserving Unix dotfile reconnaissance probes (.env, .npmrc, .htaccess, .dockerenv).
• Fixed ONNX Exporter (export_onnx.py) for FP16 (model_fp16.onnx) & Dynamic INT8 (model_quantized_int8.onnx):
  • FP16 RoPE Cast Graph Fix: Replaced legacy onnxconverter_common.float16—which mutated ModernBERT's Rotary Position Embedding node (/model/layers.*/attn/rotary_emb/Cast_1) without updating downstream ValueInfoProto signatures (ORT_FAIL: Type (tensor(float16)) ... does not match expected type (tensor(float)))—with ONNX Runtime's transformer-aware onnxruntime.transformers.float16.convert_float_to_float16(onnx_model, keep_io_types=True). This produces a valid FP16 graph (285 MB, optimized for NVIDIA Tensor Core GPUs) while keeping I/O logits in tensor(float) (FP32) for direct Java DJL compatibility.
  • Lossless Dynamic INT8 Quantization (100% Holdout Parity on CPU): Fixed the weight/logit collapse caused by naive QuantType.QInt8 dynamic quantization on ModernBERT (where multiplying unsigned uint8 activations by signed int8 weights overflows AVX2 vpmaddubsw 16-bit accumulators on high-amplitude GeGLU layers, while quantizing Gather and Gemm degrades token embeddings and Landmark Pooling logits). Switching to weight_type=QuantType.QUInt8 (32-bit accumulation), restricting quantization to op_types_to_quantize=['MatMul'] (keeping token embeddings in FP32), and excluding the final Landmark classification head (nodes_to_exclude=['/classifier/Gemm']) restores 100.00% (50/50) Holdout accuracy at a 254 MB footprint (~2–4 ms production CPU latency alongside native FP32).
• Macro-Topological URI Prefix & Query-Key De-Biasing (v33 Dataset): Audited and rebalanced all 14 URI prefix families (/api/v1/*, /api/*, /blog/*, /wp-*, /publico/*, /actuator/*, /nexus.*, /assets/*, /auth/*), single-letter query keys (?q=, ?s=, ?p=, ?id=), and natural-language punctuation/numeric templates to strict ~50/50 Safe/Attack parity—eliminating structural prefix and parameter-name shortcuts.
• 100.00% Accuracy Across Internal & Major External WAF Benchmarks: Achieved 100.00% Global Accuracy (0 FP, 0 FN) on the 160,500-request v33 corpus, 100.00% on waf-bench (77/77), 100.00% on gotestwaf (822/822), 100.00% on openappsec-attacks (73,924/73,924), 99.73% on shengqin-waf (1 FP / 0.10% FPR), and 98.46% on http-attack-requests with 100.00% Precision (0 FP / 0.00% FPR).

🆕 News notes v2.3 - 31/10/2026

• Upgraded HTTPNormalizer v2.3: Now bundled via trust_remote_code=True. Added in-distribution OPTIONS / HEAD verb canonicalization (GET when EMPTY_BODY, POST if a body is present) and Origin authority anonymization for zero-false-positive CORS preflight inspection, smart Windows CRLF (\r\n → \n) body normalization (preserving multipart/form-data and CRLF/Smuggling payloads), recursive [SEP] landmark anti-collision filtering across URI/HEADERS/BODY, deep payload inspection across non-target HTTP headers (Accept-Encoding, Accept with MIME wildcard stripping, Cache-Control, Connection), 100% deterministic User-Agent canonicalization (canonicalize_healthy_user_agent) with a configurable BLOCK_SCANNER_USER_AGENTS toggle, strengthened Cookie/UA/Host/JWT exploit guards, and new anti-evasion decoders.
• Dotted False-Friends, Technical Markdown & Root-URI Parity (v28): Introduced a parametric "Dotted False-Friends" generator, symmetric root-URI containers (/?q=, /?p=, /?s=, POST / form-urlencoded), technical cybersecurity Markdown documentation (nested links, release notes, YAML/code blocks), and complex punctuation/SQL-keyword prose.
• New Attack Signatures: Added stacked SQLi, Windows arithmetic & network recon CMD injection, SMTP/IMAP CRLF command splitting, LDAP OID filter injection, and OAST SSRF/Log4Shell callback domains.

🆕 News notes v2.2 - 25/10/2026

• Balanced 22 Attack Families: Expanded from 12 to 22 offensive families (Next.js/Vite/PHP CVEs, Prototype Pollution, Cloud SSRF, JWT, SSTI, Deserialization, NoSQL, GraphQL) with strict 50/50 anti-shortcut parity across all keywords and User-Agents.
• Upgraded HTTPNormalizer v2.2: Added authority IP normalization (Host/Referer → <DOMAIN>, local LAN IPs), exploit-aware <DOMAIN>/<IP> guards, and recursive \u00XX Unicode decoding.
• Broader Threat & Benchmark Coverage: Maintained 99.9994% Global Accuracy — "Five Nines" — internally while boosting zero-shot scores across shengqin-waf (99.38%), secureai-waf (98.36%), waf-bench (96.10%), nosql-waf (94.39%), and ai-waf (89.97%).

🆕 News notes v2.1 - 20/10/2026

• Balanced Protocol & Verb Coverage: Expanded to 160,500 requests with strict 50/50 Safe/Attack parity across all HTTP methods (GET, POST, PUT, PATCH, DELETE) and Content-Type formats (JSON objects/arrays, XML/SOAP, Form, Multipart, gRPC).
• Markdown & HTML5 False-Positive Immunity: Native support for text/markdown (technical prose, code blocks) and text/html documents without false alarms.
• Upgraded HTTPNormalizer v2.1: Added smart cookie/telemetry anonymization (anonymize_cookies), advanced anti-evasion decoding (Log4j, decimal IPv4, sponge-case), and non-target header inspection.
• Broader Threat & Benchmark Coverage: Added detection for dotfile recon, open redirects, and HTTP request smuggling, validated across 9 external Hugging Face benchmarks.

🆕 News notes v2.0 - Initial release 11/10/2026

---

⚡ Key Architectural Innovations

1. Vectorized Landmark Pooling (trust_remote_code=True)

Traditional sentence transformers collapse sequence representations onto the initial [CLS] token, discarding spatial boundary relationships between HTTP fields. IronJean WAF implements Vectorized Landmark Pooling:

• Delimiter tokens ([SEP]) segment the request into four discrete landmarks: METHOD, URI, HEADERS, and BODY.
• The final representation is computed via parallel vectorized pooling over [SEP] hidden states:

$$\text{Pooled} = \frac{1}{\max\left(1, \sum \mathbf{M}{\text{SEP}}\right)} \sum{t=1}^S \mathbf{h}t \cdot \mathbf{M}{\text{SEP}, t}$$

• Native Hugging Face Integration (trust_remote_code=True): Packaged with custom modeling (modeling_ironjean.py) registered under AutoModelForSequenceClassification and pipeline("text-classification"). External developers can load the full landmark-pooling architecture zero-shot without defining custom PyTorch boilerplate.
• Fully Exportable to ONNX: For zero-trust production environments, the pooling graph is baked directly into model.onnx, requiring no Python runtime.

2. Multi-Pass Recursive Anti-Evasion Decoding & Anti-DoS Compression

Attackers frequently chain multiple encoding layers and padding buffers to evade signature inspection or overflow context windows. IronJean WAF incorporates a deterministic pre-inference unwrapping pipeline (convergence loop up to depth = 3) that:

• Recursively unwraps URL-encoding, Base64 (including unpadded and /-delimited path tokens), ASCII Unicode escapes (\u00XX), HTML numeric/named entities, Log4j JNDI lookups (${lower:x}, ${::-x}), decimal IPv4 SSRF targets (http://2852039166), SQL inline comments (/*!50000...*/), Sponge-Case keywords (sElEcT → SELECT), and Null-Byte extension bypasses (%00.jpg → \x00.jpg).
• Compresses repetitive character floods ((.)\1{127,} → 32 chars) to defeat Context-Window Flooding and ReDoS while preserving buffer-overflow/fuzzing anomaly signatures.

3. Exploit-Aware Network Landmark Anonymization (<IP> & <DOMAIN>)

To prevent the neural network from memorizing environment-specific corporate hostnames, LAN subnets, or proxy topologies, authority and forwarding headers (Host, Referer, Origin, X-Forwarded-For, X-Real-IP, True-Client-IP, CF-Connecting-IP, X-Forwarded-Host) are mapped to canonical <DOMAIN> and <IP> landmarks.

• Exploit-Aware Negative Lookaheads: Explicitly preserve Cloud Metadata SSRF targets (169.254.169.254, 100.100.100.200, metadata.google.internal), OAST callback domains (interact.sh, oastify.com, burpcollaborator.net), Java/PHP gadget namespaces (class.module.classLoader, convert.iconv.*), and JS DOM objects (document.cookie, window.location) so attacks are never masked.
• In-Distribution CORS & Verb Canonicalization: Automatically maps bodiless OPTIONS and HEAD requests to METHOD: GET (or POST if a body is present), ensuring CORS preflights are evaluated strictly inside the model's nominal training distribution.

4. Two-Stage Curriculum: Focal Hard-Mining to Cross-Entropy Calibration

Trained via a two-stage curriculum across 3 epochs:

• Epochs 1–2 (Hard-Example Mining): Focal Loss (α = 1.0, γ = 2.0) down-weights easy canonical exploits to focus gradient updates on hard boundary cases (e.g., "Dotted False-Friends" like Shell.me / System.Text.Json, root-URI short parameters /?q=, technical cybersecurity Markdown, and French/English apostrophes vs. SQL quotes).
• Epoch 3 (Logit Calibration Smoothing): Switches to standard Cross-Entropy under cosine learning-rate decay (1 × 10⁻⁵) to recalibrate output probabilities, driving validation Precision to 100.00% (0 FP).

---

⚙️ Dataset Provenance

To ensure a comprehensive and resilient mapping of HTTP threat vectors, the dataset was meticulously aggregated and curated from the following sources:

• Simulated Enterprise Telemetry (WAF Factory datasets): Rigorously generated HTTP logs designed to mirror the natural variance, structural complexity, and edge cases of legitimate enterprise traffic, ensuring realistic baseline behaviors without using proprietary production data.
• CAPEC™ (Common Attack Pattern Enumeration and Classification): Integration of standardized, industry-recognized attack patterns to guarantee baseline coverage of known exploit topologies.
• miomit/xss_generation: Synthetic, deeply obfuscated cross-site scripting payloads to train the model's attention mechanism against advanced evasion and mutation techniques.
• Custom Synthetic & Noise Data: Custom-engineered synthetic payloads combined with deliberate label noise, specifically designed to force structural learning and provide maximum resilience.

---

🛸 Training Dynamics: Focal Hard-Mining to Cross-Entropy Smoothing

During training on the 160,500-request corpus (90% train / 10% hold-out validation split of 16,050 requests), IronJean v2.5 exhibits a characteristic three-epoch phase transition driven by the switch from Focal Loss to Cross-Entropy Calibration Smoothing (max-length 2048 tokens):

Behavioral Dynamics:

• Epoch 1.0: Rapid, spike-free structural convergence across HTTP landmarks (METHOD, URI, HEADERS, BODY) reaching 99.9564% validation Accuracy and 99.9630% Precision (eval_loss: 0.000352).
• Epoch 2.0: Hard-Example Mining (eval_loss drops by 16.4× to 0.000021 / 2.14e-05): Focal Loss concentrates gradients on subtle Dotted False-Friends (Shell.me, Select.io), short-key parameters (?q=, ?p=), /blog/* WordPress sub-routes, and complex punctuation edge cases, already reaching 100.0000% (1.0) Validation Precision (0 FP) and 99.9938% Accuracy (16,049 / 16,050).
• Epoch 3.0: Terminal Phase of Training & Boundary Calibration (eval_loss: 0.000015 / 1.51e-05 — 99.9985% mean probability confidence): Switching to standard Cross-Entropy under linear LR decay (1e-5) compacts [SEP] Landmark representations and widens class logit margins with zero training loss spikes, driving validation Accuracy, Precision, Recall, and F1-Score to 100.0000% (1.0 across all 16,050 validation samples) and 100.0000% Global Accuracy (160,500 / 160,500, 0 FP, 0 FN) across the full 160,500-request corpus (train_loss: 0.010006, train_runtime: 6,624.38s).

---

🗿 Benchmark

Tested against internal and external Hugging Face / industry WAF benchmarks (max-length 4096 tokens, default 0.50 classification threshold):

💡 * Note: On third-party Hugging Face datasets (SecureAI-SE/http-attack-requests and shengqin/web-attacks), the remaining anomalies marked with * stem from non-executable wordlist/CSV artifacts (isolated CSIC DOM event names without =/< such as onchange/onmouseenter, browser HTML comments, Excel #NAME? export errors, or 50-char CSV-truncated JSON/prose). At the recommended production decision threshold (0.85), both 50-char truncated shengqin-waf edge cases (0.62 and 0.80) are allowed—yielding 100.00% Precision (0 FP across all 6 benchmarks).

---

📐 Input Format (Sequence Template)

Input sequences must conform strictly to the four-landmark template:

METHOD: <HTTP_METHOD> [SEP] URI: <REQUEST_URI> [SEP] HEADERS: <FILTERED_HEADERS> [SEP] BODY: <NORMALIZED_BODY>

• METHOD: Standard HTTP verb (GET, POST, PUT, DELETE, PATCH; OPTIONS and HEAD are automatically canonicalized to GET or POST by HTTPNormalizer).
• [SEP]: Delimiter token (50282 in ModernBERT tokenizer) mapped to Vectorized Landmark Pooling.
• URI: Recursively decoded path and parameters (e.g. /api/v1/resource?id=10).
• HEADERS: Pipe-separated key-value pairs formatted by HTTPNormalizer.
• BODY: Recursively decoded payload, or EMPTY_BODY.

---

🛠️ Mandatory Pre-Inference Normalization Pipeline

To reproduce the benchmarked 100.00% Global Accuracy (100.00% Precision / 100.00% Recall) and avoid false alarms, incoming HTTP requests must pass through the IronJean Normalization Pipeline before tokenization.

This pipeline strips multi-layer evasion obfuscation, prevents neural overfitting on hostnames/IPs, enforces header length guards, and structures input into canonical HTTP landmarks.

Incoming HTTP Request
       │
       ▼
┌────────────────────────────────────────────────────────┐
│ 1. Multi-Pass Recursive Anti-Evasion (Max Depth = 3)   │
│    URL / Base64 / Unicode \u00XX / HTML / Log4j unwrap │
│    Anti-DoS padding compression (>128 chars -> 32)     │
└────────────────────────────────────────────────────────┘
       │
       ▼
┌────────────────────────────────────────────────────────┐
│ 2. Exploit-Aware Network Landmark Anonymization        │
│    Host, Referer, Origin, X-Forwarded-* -> <DOMAIN>/<IP>│
│    Preserves Cloud IMDS (169.254.169.254) & OAST hosts │
└────────────────────────────────────────────────────────┘
       │
       ▼
┌────────────────────────────────────────────────────────┐
│ 3. Header Canonicalization & Flooding Guard (512 max)  │
│    Keep target + suspicious non-target headers         │
│    Canonicalize healthy User-Agent & Bearer tokens     │
│    Cookie: drop telemetry (_ga, __cf_bm), anonymize    │
│    session tokens (JSESSIONID=NONE), preserve attacks  │
└────────────────────────────────────────────────────────┘
       │
       ▼
┌────────────────────────────────────────────────────────┐
│ 4. Body & Token Stabilization                          │
│    Empty/Null -> 'EMPTY_BODY', strip benign HTML5      │
│    <!DOCTYPE html>, normalize benign Windows \r\n->\n, │
│    strip injected [SEP] tokens & healthy JWT sigs      │
└────────────────────────────────────────────────────────┘
       │
       ▼
┌────────────────────────────────────────────────────────┐
│ 5. Landmark Sequence Serialization                     │
│    OPTIONS/HEAD -> GET (or POST if body present)       │
│    METHOD: <M> [SEP] URI: <U> [SEP] HEADERS: <H> ...   │
└────────────────────────────────────────────────────────┘

⚗️ Python Normalizer (HTTPNormalizer — Bundled via trust_remote_code=True)

To ensure exact parity with production environments and prevent false alarms, raw requests must be normalized before inference. Because modeling_ironjean.py imports normalizer_ironjean.py via a relative import (from .normalizer_ironjean import HTTPNormalizer), Hugging Face Hub automatically downloads normalizer_ironjean.py alongside the model weights whenever trust_remote_code=True is enabled:

• Zero-file remote access (from Hugging Face Hub): HTTPNormalizer = model.normalizer (or directly model.serialize_http(...) / classifier.normalizer).
• Direct local import: from normalizer_ironjean import HTTPNormalizer (also re-exported by core.normalizer and bundled in test_hf.py).
• Scanner User-Agent Policy Toggle: Set HTTPNormalizer.BLOCK_SCANNER_USER_AGENTS = True to block offensive scanner banners (sqlmap, Nikto, Nuclei, OpenVAS, ffuf) even without an exploit payload (default False = Payload-Only mode).

from transformers import AutoModelForSequenceClassification

model = AutoModelForSequenceClassification.from_pretrained(
    "Metabaron6/IronJean-v2-ModernBERT-WAF",
    trust_remote_code=True
)
HTTPNormalizer = model.normalizer  # Automatically fetched from normalizer_ironjean.py on HF Hub

sequence = HTTPNormalizer.serialize_http(
    method="POST",
    uri="/api/v1/checkout?redirect=%2Fdashboard",
    headers={
        "Host": "192.168.1.16:8080",
        "Cookie": "JSESSIONID=5d41402abc4b2a76b9719d911017c592; _ga=GA1.2.123456789",
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
    },
    body='{"cart_id": 98712, "coupon": "WELCOME10"}'
)
# -> METHOD: POST [SEP] URI: /api/v1/checkout?redirect=/dashboard [SEP] HEADERS: host: <DOMAIN> | cookie: JSESSIONID=NONE | user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) [SEP] BODY: {"cart_id": 98712, "coupon": "WELCOME10"}

---

💻 Python Quickstart

Prerequisites

• Python: >= 3.10 (Python 3.11 or 3.12 recommended)
• PyTorch: torch >= 2.4.0 (with CUDA 12.1+ recommended for hardware bfloat16 and FlashAttention-2 / SDPA acceleration)
• Hugging Face Transformers: transformers >= 4.48.0 (mandatory — native ModernBERT support requires 4.48.0+)

Native Hugging Face Loading (trust_remote_code=True)

Thanks to modeling_ironjean.py and normalizer_ironjean.py (trust_remote_code=True), IronJean's Vectorized Landmark Pooling architecture and HTTPNormalizer pipeline are downloaded and instantiated dynamically from the Hugging Face Hub—without requiring any local Python files or custom PyTorch boilerplate:

• pipeline("text-classification", ..., trust_remote_code=True) loads IronJeanWAFPipeline, which accepts raw HTTP dictionaries ({"method": "GET", "uri": "...", "headers": {...}, "body": None}) or Landmark strings and normalizes them automatically (max_length=8192).
• AutoModelForSequenceClassification.from_pretrained(..., trust_remote_code=True) exposes model.normalizer (HTTPNormalizer) and model.serialize_http(...) directly on the loaded model instance.

👉 Click to expand a basic test.py code

import torch
from transformers import AutoModelForSequenceClassification, AutoTokenizer, pipeline

model_id = "Metabaron6/IronJean-v2-ModernBERT-WAF"
device = "cuda" if torch.cuda.is_available() else "cpu"

# =====================================================================
# Option 1: Native Hugging Face Pipeline (Auto-Normalizes Raw HTTP Dicts)
# =====================================================================
classifier = pipeline(
    "text-classification",
    model=model_id,
    trust_remote_code=True,
    device=0 if device == "cuda" else -1
)

# Pass a raw HTTP request dict directly — IronJeanWAFPipeline normalizes it automatically!
result = classifier({
    "method": "GET",
    "uri": "/products?category=1' UNION SELECT null,password FROM users--",
    "headers": {"Host": "api.corporate.net", "User-Agent": "Mozilla/5.0"},
    "body": None
})
print("Pipeline Result:", result)

# =====================================================================
# Option 2: Native AutoModel with BFloat16 Acceleration & model.normalizer
# =====================================================================
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForSequenceClassification.from_pretrained(
    model_id,
    trust_remote_code=True,
    dtype=torch.bfloat16 if device == "cuda" else torch.float32
).to(device).eval()

# Access HTTPNormalizer directly from the downloaded HF model (normalizer_ironjean.py)
HTTPNormalizer = model.normalizer
# Optional: set HTTPNormalizer.BLOCK_SCANNER_USER_AGENTS = True for strict scanner-banner blocking

def classify_http_request(raw_sequence: str, threshold: float = 85.0):
    # Step 1: Tokenize with up to 8192 context window
    inputs = tokenizer(raw_sequence, return_tensors="pt", truncation=True, max_length=8192).to(device)
    
    # Step 2: Vectorized Landmark Pooling inference
    with torch.no_grad():
        if device == "cuda":
            with torch.amp.autocast("cuda", dtype=torch.bfloat16):
                outputs = model(**inputs)
        else:
            outputs = model(**inputs)
        probs = torch.softmax(outputs.logits.float(), dim=-1)
        attack_prob = probs[0][1].item() * 100.0
    
    is_attack = attack_prob >= threshold
    return is_attack, attack_prob

# 2. Format requests using HTTPNormalizer & run inference
# Case A: SQL Injection in URI
sample_attack = HTTPNormalizer.serialize_http(
    method="GET",
    uri="/api/v1/users?id=1' OR '1'='1",
    headers={"Host": "api.corporate.net", "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"},
    body=None
)
blocked, prob = classify_http_request(sample_attack)
print(f"Attack URI Probability: {prob:.2f}% | Decision: {'🛑 BLOCKED' if blocked else '✅ ALLOWED'}")

# Case B: Benign Business Form with Natural Text / Apostrophe
sample_safe = HTTPNormalizer.serialize_http(
    method="POST",
    uri="/api/v1/profile",
    headers={"Host": "api.corporate.net", "User-Agent": "curl/8.11.1", "Content-Type": "application/json"},
    body='{"name": "O\'Connor", "bio": "Software Engineer. It\'s a genuine profile.", "settings": {"theme": "dark"}}'
)
blocked, prob = classify_http_request(sample_safe)
print(f"Safe Request Attack Probability: {prob:.2f}% | Decision: {'🛑 BLOCKED' if blocked else '✅ ALLOWED'}")

# Case C: Malicious Attack Injected Inside User-Agent Header (Log4Shell / SQLi)
# is_healthy_user_agent flags the suspicious pattern, preserves raw payload, and blocks it!
sample_ua_attack = HTTPNormalizer.serialize_http(
    method="GET",
    uri="/api/v1/users",
    headers={"Host": "api.corporate.net", "User-Agent": "Mozilla/5.0' OR '1'='1--"},
    body=None
)
blocked, prob = classify_http_request(sample_ua_attack)
print(f"User-Agent Attack Probability: {prob:.2f}% | Decision: {'🛑 BLOCKED' if blocked else '✅ ALLOWED'}")

# Case D: Cookie Anonymization vs Malicious Cookie Injection (WAFFilter Parity)
# Benign telemetry cookies (_ga, __cf_bm) are dropped, session cookie is neutralized to NONE:
sample_cookie_safe = HTTPNormalizer.serialize_http(
    method="POST",
    uri="/api/v1/checkout",
    headers={
        "Host": "api.corporate.net",
        "Cookie": "JSESSIONID=5d41402abc4b2a76b9719d911017c592; _ga=GA1.2.123456789.1234567890; __cf_bm=abcdef123456",
        "User-Agent": "Mozilla/5.0"
    },
    body="cart_id=98712&item=44"
)
blocked, prob = classify_http_request(sample_cookie_safe)
print(f"Safe Cookie Request Attack Probability: {prob:.2f}% | Decision: {'🛑 BLOCKED' if blocked else '✅ ALLOWED'}")

# Malicious Injection inside Cookie (SQLi preserved and deterministically blocked):
sample_cookie_attack = HTTPNormalizer.serialize_http(
    method="GET",
    uri="/dashboard",
    headers={"Host": "api.corporate.net", "Cookie": "JSESSIONID=1' OR '1'='1--", "User-Agent": "Mozilla/5.0"},
    body=None
)
blocked, prob = classify_http_request(sample_cookie_attack)
print(f"Cookie SQLi Attack Probability: {prob:.2f}% | Decision: {'🛑 BLOCKED' if blocked else '✅ ALLOWED'}")

---

🧪 Live Benchmark Suite & Empirical Validation (OWASP Top 10)

You can run the complete evaluation suite locally using test_hf.py:

python test_hf.py --hub

Real Console Output (CUDA bfloat16, Decision Threshold = 85.0%):

====================================================================
🛡️  IRONJEAN-v2.5 HUGGING FACE NATIVE BENCHMARK (AutoModel / Pipeline)
📦  Model Source: Metabaron6/IronJean-v2-ModernBERT-WAF
⚙️  Architecture: Vectorized Landmark Pooling (trust_remote_code=True)
====================================================================
Loading IronJean-v2.5 via AutoModelForSequenceClassification (trust_remote_code=True)...
   Target Source: Metabaron6/IronJean-v2-ModernBERT-WAF
   ✓ Config loaded | Target Labels: {0: 'SAFE', 1: 'ATTACK'}
   ✓ Tokenizer loaded | Vocabulary size: 50280 tokens
   ✓ Architecture resolved: IronJeanWAFClassifier
   ✓ Bundled Normalizer resolved (trust_remote_code=True): HTTPNormalizer
   ✓ Successfully initialized on CUDA.

Starting evaluation suite (max_length=8192, decision_threshold=85.0%)...

SCENARIO : ATTACK (Command Injection / OS Cmd)                         -> [ATTACK BLOCKED] 🛑 (100.00%) 261.76 ms
SCENARIO : BENIGN (Standard REST API Request)                          -> [SAFE ALLOWED]   ✅ (100.00%) 26.31 ms
SCENARIO : ATTACK (Base64 Evasion / Java Deserialization)              -> [ATTACK BLOCKED] 🛑 (100.00%) 24.58 ms
SCENARIO : BENIGN (OAuth2 Token Exchange)                              -> [SAFE ALLOWED]   ✅ (100.00%) 26.78 ms
SCENARIO : BENIGN (JSON Form with Natural Apostrophe)                  -> [SAFE ALLOWED]   ✅ (100.00%) 27.27 ms
SCENARIO : ATTACK (SQL Injection UNION SELECT)                         -> [ATTACK BLOCKED] 🛑 (100.00%) 27.81 ms
SCENARIO : BENIGN (WordPress Registration Form)                        -> [SAFE ALLOWED]   ✅ (100.00%) 43.38 ms
SCENARIO : ATTACK (User-Agent SQL Injection)                           -> [ATTACK BLOCKED] 🛑 (100.00%) 25.76 ms
SCENARIO : ATTACK (User-Agent Log4Shell JNDI)                          -> [ATTACK BLOCKED] 🛑 (100.00%) 25.85 ms
SCENARIO : BENIGN (Cookie Anonymization - Session & Telemetry Dropped) -> [SAFE ALLOWED]   ✅ (100.00%) 28.13 ms
SCENARIO : ATTACK (Cookie SQL Injection)                               -> [ATTACK BLOCKED] 🛑 (100.00%) 27.67 ms

====================================================================
Verifying Hugging Face pipeline('text-classification', trust_remote_code=True):
====================================================================
1. Landmark String : METHOD: GET [SEP] URI: /products?category=1' UNION SELECT null,password FROM users-- [SEP] HEADERS: host: <DOMAIN> [SEP] BODY: EMPTY_BODY
   Pipeline Result : [{'label': 'ATTACK', 'score': 1.0}]
2. Raw HTTP Dict   : /api/query?param=eyJAdHlwZSI6ImNvbS5zdW4ucm93c2V0LkpkYmNSb3dTZXRJbXBsIn0= (Auto-decoded by IronJeanWAFPipeline)
   Pipeline Result : [{'label': 'ATTACK', 'score': 0.9999990463256836}]

====================================================================
✅ All Hugging Face AutoModel & Pipeline tests completed successfully!
====================================================================

---

☕ Enterprise Java & Tomcat Integration (ONNX Runtime)

For low-latency production deployments in Java (Spring Boot / Spring Cloud Gateway, Jakarta EE / Tomcat Filter, Quarkus), IronJean WAF provides three ONNX model variants (model.onnx, model_quantized_int8.onnx, model_fp16.onnx) executed via ONNX Runtime and the Deep Java Library (DJL) HuggingFace tokenizer:

• 1:1 Normalization Parity (WAFInferenceNormalization.java ↔ HTTPNormalizer): The Java Servlet filter normalizes incoming HttpServletRequest objects into canonical 4-landmark sequences (METHOD, URI, HEADERS, BODY), validated across 204/204 production Postman anti-regression tests (GET, POST, PUT, PATCH, DELETE, OPTIONS CORS preflights, complex Markdown documentation, nested JSON, XML/SOAP, and multipart uploads) and live e-banking REST API traffic.
• Zero-GC Native Tensor Lifecycle & Thread-Safety: Uses ThreadLocal<Predictor<NDList, NDList>> over a shared thread-safe ZooModel instance, paired with scoped try (NDManager manager = onnxModel.getNDManager().newSubManager()) blocks to deterministically free C++ ONNX tensors immediately after each request without pressuring the JVM Garbage Collector.

📊 ONNX Model Variants: Production Latency, Footprint & Precision Comparison

💡 * Architecture Notes on INT8 & FP16 ONNX Exports:

• model_quantized_int8.onnx (QUInt8 Hybrid Quantization): Uses unsigned 8-bit dynamic quantization (QuantType.QUInt8) restricted to transformer MatMul layers while keeping the token embedding table (/model/embeddings/tok_embeddings/Gather) and the final Landmark Pooling classification head (/classifier/Gemm) in native FP32. This prevents AVX2/AVX-512 vpmaddubsw 16-bit signed accumulator saturation on GeGLU activations and preserves 100.00% (50/50) classification parity with a minimal logit margin reduction (Δlogit ≈ 0.9, shifting benign request probability from 0.0006% to 0.0038%, both rounding to 0.0000).
• model_fp16.onnx (FP16 with keep_io_types=True): Exported via onnxruntime.transformers.float16 with FP32 output logits for plug-and-play Java DJL compatibility. On x86-64 CPUs lacking native AVX512-FP16 FMA units, FP16 incurs a ~2.3× latency penalty compared to FP32 due to continuous F16C (FP16 ↔ FP32) register conversions; reserve model_fp16.onnx for NVIDIA Tensor Core GPU deployments (0.8–1.4 ms) and deploy model.onnx (FP32) or model_quantized_int8.onnx (QUInt8) on CPU servers (2–7 ms).

👉 Click to expand ModernBertWafPredictor.java

package com.security.waf;

import ai.djl.inference.Predictor;
import ai.djl.ndarray.NDArray;
import ai.djl.ndarray.NDList;
import ai.djl.ndarray.NDManager;
import ai.djl.repository.zoo.ZooModel;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class ModernBertWafPredictor {

   private static final Logger log = LoggerFactory.getLogger(ModernBertWafPredictor.class);

   // The loaded ONNX model, thread-safe and shared across the application
   private final ZooModel<NDList, NDList> onnxModel;

   // ThreadLocal predictor since Predictor objects are NOT thread-safe in DJL
   private final ThreadLocal<Predictor<NDList, NDList>> predictorPool;

   public ModernBertWafPredictor(ZooModel<NDList, NDList> onnxModel) {
      this.onnxModel = onnxModel;
      this.predictorPool = ThreadLocal.withInitial(onnxModel::newPredictor);
   }

   /**
    * Executes the WAF inference using dynamic sequence lengths.
    *
    * @param tokenIds The tokenized HTTP payload, inherently variable in length.
    * @return true if the payload is classified as an Attack, false if Safe.
    */
   public boolean isMalicious(long[] tokenIds) {
      Predictor<NDList, NDList> predictor = predictorPool.get();
      int actualSequenceLength = tokenIds.length;

      long startTime = System.currentTimeMillis();

      // CRITICAL: Try-with-resources to prevent C++ native memory leaks.
      // Bypasses the Java Garbage Collector for immediate tensor destruction.
      try (NDManager manager = onnxModel.getNDManager().newSubManager()) {

         // 1. Construct input_ids with shape [1, actualSequenceLength]
         // This perfectly matches the dynamic_axes 'sequence_length' configured in Python
         NDArray inputIds = manager.create(new long[][]{ tokenIds });
         inputIds.setName("input_ids");

         // 2. Construct attention_mask with shape [1, actualSequenceLength]
         // Since we use exact sizing instead of padding, all tokens are real.
         // Therefore, the mask is simply an array of 1s of the same length.
         long[] maskArray = new long[actualSequenceLength];
         java.util.Arrays.fill(maskArray, 1L);
         NDArray attentionMask = manager.create(new long[][]{ maskArray });
         attentionMask.setName("attention_mask");

         // 3. Package tensors into an NDList for the ONNX session
         NDList inputs = new NDList(inputIds, attentionMask);

         // 4. Run native C++ inference
         NDList outputs = predictor.predict(inputs);

         // 5. Extract logits. 
         // Shape is [1, 2] (Batch size 1, 2 probability classes: Safe vs Attack)
         NDArray logits = outputs.getFirst();

         // Apply softmax to convert raw logits to probabilities [0.0 - 1.0]
         NDArray probabilities = logits.softmax(1);

         // Extract the probability for class 1 (Attack)
         float attackProbability = probabilities.getFloat(0, 1);

         // Apply custom threshold (0.85 balances aggressive threat detection with dev/scanner tolerance)
         float threshold = 0.85f;
         boolean isMalicious = attackProbability > threshold;

         if (log.isDebugEnabled()) {
            //WafLogitAnalyzer.analyzeOnnxOutput(outputs);
            long duration = System.currentTimeMillis() - startTime;
            log.debug("WAF Inference - SeqLength: {} | AttackProb: {} | Prediction: {} | Execution Time: {} ms",
                    actualSequenceLength, String.format("%.4f", attackProbability), isMalicious ? "ATTACK" : "SAFE", duration);
         }

         return isMalicious;

      } catch (Exception e) {
         log.error("WAF Inference failed. Failsafe activated: blocking request.", e);
         // Default deny in security contexts
         return true;
      }
   }

   /**
    * Called during Tomcat shutdown or application undeploy to release native ONNX resources.
    */
   public void close() {
      if (predictorPool != null) {
         predictorPool.remove();
      }
      if (onnxModel != null) {
         onnxModel.close();
      }
   }
}

---

📃 License

Licensed under the Apache License, Version 2.0. Free for academic, personal, and commercial enterprise use.

🖇️ Author

@software{IronJean-v2-ModernBERT-WAF,
  author = {Franck Andriano},
  title = {IronJean WAF v2.5: Enterprise Web Application Firewall Powered by ModernBERT and Landmark Pooling},
  year = {2026},
  publisher = {Hugging Face},
  url = {https://huggingface.co/Metabaron6/IronJean-v2-ModernBERT-WAF}
}