| --- |
| language: |
| - en |
| license: apache-2.0 |
| tags: |
| - security |
| - cybersecurity |
| - waf |
| - web-application-firewall |
| - multi-label-classification |
| - injection-detection |
| - capec |
| - owasp |
| - distilbert |
| pipeline_tag: text-classification |
| widget: |
| - text: "[METHOD] GET [PATH] /?id=1%27%20OR%201=1-- [UA] Mozilla/5.0" |
| - text: "[METHOD] POST [PATH] /submit [UA] Mozilla/5.0 [CT] application/x-www-form-urlencoded [BODY] id=%3Cscript%3Ealert(1)%3C/script%3E" |
| - text: "[METHOD] GET [PATH] /../../../../etc/passwd [UA] Mozilla/5.0" |
| - text: "[METHOD] GET [PATH] /blog/index.php/2020/04/04/hello-world [UA] Mozilla/5.0" |
| --- |
| |
| # 4thwall-WAF-v2.1b: Hardened Multi-Label Neural Web Application Firewall |
|
|
| **4thwall-WAF-v2.1b** is an enterprise-grade multi-label transformer model designed for real-time inspection, classification, and blocking of malicious web traffic. Fine-tuned on `distilbert-base-uncased` across 363,000+ real-world and honeypot HTTP requests using strict template-disjoint grouping, it eliminates structural URI leakage and achieves state-of-the-art semantic injection detection without relying on brittle regex patterns. |
|
|
| - **Developer**: 4thwall Security Team |
| - **Base Architecture**: `distilbert-base-uncased` (6 layers, 768 hidden dimension, 12 attention heads) |
| - **Output Classes**: 13 multi-label CAPEC categories (Normal + 12 attack vectors) |
| - **Primary Metrics (Test Unique-Template, 29,996 novel URIs)**: |
| - **Macro-F1 (Excl. 272)**: **0.9923** |
| - **Macro-F1 (All 13)**: **0.9830** |
| - **Micro-F1**: **0.9912** |
| - **Exploit Catch Rate**: **99.41%** (22,448 / 22,582 attack rows) |
| - **Clean Benign False Positive Rate**: **0.782%** (58 / 7,414) |
|
|
| --- |
|
|
| ## Quickstart: Running Inference |
|
|
| ```bash |
| pip install torch transformers safetensors |
| ``` |
|
|
| ```python |
| import torch |
| from transformers import AutoTokenizer, AutoModelForSequenceClassification |
| |
| MODEL_ID = "your-username/4thwall-waf-v2.1b" |
| |
| # 1. Load tokenizer and model |
| tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, trust_remote_code=True) |
| model = AutoModelForSequenceClassification.from_pretrained(MODEL_ID, trust_remote_code=True) |
| model.eval() |
| |
| # 2. Serialize an incoming HTTP request |
| raw_text = model.serialize_request( |
| method="GET", |
| path="/?id=1' OR '1'='1", |
| ua="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" |
| ) |
| |
| # 3. Predict probabilities |
| inputs = tokenizer(raw_text, return_tensors="pt") |
| with torch.no_grad(): |
| outputs = model(**inputs) |
| probs = torch.sigmoid(outputs.logits)[0] |
| |
| # 4. Apply calibrated decision thresholds |
| thresholds = model.config.thresholds |
| id2label = model.config.id2label |
| |
| print(f"Input: {raw_text}\n") |
| for idx, p in enumerate(probs): |
| label = id2label[idx] |
| thresh = thresholds.get(label, 0.5) |
| if p.item() >= thresh: |
| print(f" [ALERT] {label:<38}: Score = {p.item():.4f} >= {thresh:.2f}") |
| ``` |
|
|
| --- |
|
|
| ## Two-Tier Operational Enforcement Policy |
|
|
| In production, do not treat all classes as automated block targets. The model is designed to operate under a two-tier policy: |
|
|
| ``` |
| +-------------------------------------------------------------------------------+ |
| | INCOMING REQUEST -> [METHOD] [PATH] [UA] [CT] [BODY] -> DISTILBERT INFERENCE | |
| +-------------------------------------------------------------------------------+ |
| | | |
| v (Score >= Threshold) v (Score >= Threshold) |
| +------------------------------------+ +------------------------------------+ |
| | BLOCK TIER (10 Classes) | | ALERT TIER (2 Classes) | |
| | SQLi (66), Code Injection (242), | | Protocol Manipulation (272) | |
| | OS Command Injection (88), LFI(126)| | Vulnerability Scanning (310) | |
| | Verb Tampering (274), SSRF (194), | | | |
| | Response Splitting (34), etc. | | | |
| +------------------------------------+ +------------------------------------+ |
| | | |
| v v |
| [HTTP 403 FORBIDDEN] [SIEM LOG / RATE LIMIT] |
| (0.737% Benign Block Rate, (Zero drops on crawler bursts; |
| 97.30%–98.82% Catch Rate) mitigates scanner reconnaissance) |
| ``` |
|
|
| --- |
|
|
| ## Calibrated Decision Thresholds |
|
|
| | Index | Class Name | Calibrated Threshold ($T_j$) | Enforcement Tier | Operational Rationale | |
| |:---:|---|:---:|:---:|---| |
| | 0 | `000 - Normal` | **0.55** | Baseline | Neutral benign traffic gate | |
| | 1 | `272 - Protocol Manipulation` | **0.99** | **ALERT** | Tuned to eliminate 36,109 crawler false alarms on headerless traffic | |
| | 2 | `242 - Code Injection` | **0.65** | **BLOCK** | Captures XSS and PHP execution exploits | |
| | 3 | `88 - OS Command Injection` | **0.90** | **BLOCK** | Shell command execution (includes merged CAPEC-248) | |
| | 4 | `126 - Path Traversal` | **0.90** | **BLOCK** | Directory traversal and `/etc/passwd` local file inclusion | |
| | 5 | `66 - SQL Injection` | **0.70** | **BLOCK** | High recall (99.2%) with strict precision (0.996) | |
| | 6 | `16 - Dictionary-based Password Attack` | **0.60** | **BLOCK** | Brute-force credential stuffing signatures | |
| | 7 | `310 - Scanning for Vulnerable Software` | **0.55** | **ALERT** | Scanner reconnaissance (`sqlmap`, `nikto`, `nuclei`) | |
| | 8 | `153 - Input Data Manipulation` | **0.65** | **BLOCK** | Parameter tampering and data sanitization bypass | |
| | 9 | `274 - HTTP Verb Tampering` | **0.90** | **BLOCK** | Unauthorized HTTP verbs (`TRACK`, `PROPFIND`, `PUT`) | |
| | 10 | `194 - Fake the Source of Data` | **0.90** | **BLOCK** | Header spoofing and SSRF proxy injection | |
| | 11 | `34 - HTTP Response Splitting` | **0.60** | **BLOCK** | CRLF header injection and response splitting | |
| | 12 | `33 - HTTP Request Smuggling` | **0.95** | **BLOCK** | TE/CL desynchronization attacks | |
| |
| --- |
| |
| ## Request Serialization Specification |
| |
| The model consumes raw HTTP transactions serialized using structured markup tokens: |
| ``` |
| [METHOD] {method} [PATH] {path} [UA] {user_agent} [CT] {content_type} [BODY] {body} |
| ``` |
| - **Max Body Truncation**: Body text is truncated to 500 characters to prevent token starvation of URI components. |
| - **User-Agent Fallback**: Unspecified/empty User-Agents default to standard browser strings (`Mozilla/5.0...`) to prevent false alarms on scanning heuristics. |
| |
| --- |
| |
| ## Dual-WAF Defense with OWASP CRS |
| |
| In benchmark evaluations across 29,996 novel templates and 200 canonical textbook payloads: |
| - **Neural Model Strength**: Deep semantic understanding of evasion (whitespace-to-comment, SQL comments, inline encoding) in query parameters, paths, and POST bodies without rigid regex brittleness. |
| - **OWASP CRS Strength**: Rigorous protocol enforcement on HTTP headers and cookies (which the model serializer omits). |
| - **Union Benchmark**: Combining Model v2.1b with OWASP CRS v4 achieved a **99.57% Exploit Catch Rate** on 22,582 attack rows, and **93.8% catch rate** across textbook test vectors. |
| |
| --- |
| |
| ## Citation & License |
| - **License**: Apache 2.0 |
| - **Model Checkpoint**: Frozen Epoch 2 Checkpoint `v2_1b_best.pt` |
| |
