---
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`