Character-level XSS detector

A small neural network (1,959,361 parameters) that scores how likely a string is a cross-site scripting (XSS) payload. It reads raw characters after undoing URL and HTML encoding, so %3Cscript%3E, <script> and <ScRiPt> look the same to it. It was trained from random weights; no pretrained model or tokenizer is involved.

Use it to triage inputs: request parameters, form fields, log lines, user-supplied HTML. A high score means "looks like an injection payload". It does not prove that a payload would execute, and a low score does not prove an input is safe. Keep context-aware output encoding and a Content Security Policy in place regardless.

Quick start

pip install torch numpy safetensors huggingface_hub

from huggingface_hub import hf_hub_download
import importlib.util

path = hf_hub_download("hareramray325/websec", "xss_detector.py")
spec = importlib.util.spec_from_file_location("xss_detector", path)
xss_detector = importlib.util.module_from_spec(spec)
spec.loader.exec_module(xss_detector)

detector = xss_detector.XSSDetector.from_pretrained("hareramray325/websec")
detector.predict(["<img src=x onerror=alert(1)>", "<b>hello</b>"])
# [{'text': '<img src=x onerror=alert(1)>', 'score': ..., 'is_xss': True},
#  {'text': '<b>hello</b>', 'score': ..., 'is_xss': False}]

xss_detector.py is plain Python in this repository; read it before running it. The weights are in model.safetensors, so loading them executes no code. detector.score(texts) returns calibrated probabilities; predict applies the threshold 0.7278, tuned on validation data for 0.1% false alarms. Pick your own threshold if your traffic differs.

How it works

1. Normalise: URL-decode and HTML-unescape up to 3 times, drop NUL bytes, collapse whitespace, lowercase.
2. Window: inputs longer than 1000 characters are split into windows with a stride of 500; the highest window score counts, so padding a payload with harmless text does not hide it.
3. Network: one token per character (code points 0-255 each have their own token; every other character shares one), convolutions over 1, 3, 5 and 7 characters, two stride-2 convolutions, 4 Transformer encoder blocks (width 192, 8 heads), and a head over max- and mean-pooled features.
4. Calibrate: logits are divided by a temperature of 1.676 fitted on validation data.

Trained for 12 epochs (epoch 9 kept) on an NVIDIA RTX 5050 laptop GPU in about 4 minutes, with AdamW, a cosine learning-rate schedule and an averaged copy of the weights.

Training data

After normalising, exact duplicates and texts with conflicting labels were removed, leaving 68,258 rows, split 70/15/15 into training, validation and test. During training, each epoch adds varied copies of training attacks (real actions such as cookie theft or redirects in place of alert(1), other event handlers, payloads placed inside ordinary text, URLs or JSON), template-built attacks, and benign look-alikes (prose and code that mention onclick, <script> or cookies). Site names in URLs are swapped in both classes so that no domain predicts a label. Validation and test rows are never varied.

The public web-attacks-long dataset was deliberately left out because it states no license. Every training row comes from an MIT-licensed source or was generated for this model.

Evaluation

Both columns use the same data and splits. The linear baseline is character TF-IDF with logistic regression, trained on the same training rows, at its own validation-tuned threshold.

External benchmark: 7,896 payloads from nine SecLists lists (MIT) and 6,993 paragraphs and messages from WikiText and OpenAssistant. Nothing was trained or tuned on it. Many SecLists payloads also occur in the training sources, so the row counting only lines that match no row of the training pool is the stricter one.

Challenge set: 140 hand-written strings. Its past mistakes guided the training-time variation, so treat it as a regression check, not an independent test. Missed: none

Limitations

• Unfamiliar benign text raises false alarms. Benign training text is mostly URLs, JavaScript, reviews and generated HTML. Measure the false-alarm rate on your own traffic and adjust the threshold before blocking anything.
• Programming help text is the riskiest benign input. 5 of 1,994 OpenAssistant messages were flagged (mostly answers that mix prose and code blocks), against 0 of 4,999 Wikipedia paragraphs.
• Injected markup counts as an attack. <iframe src=...>, <script src=...> and <form> in an input are scored high, as the training data labels them. Do not run it over whole web pages.
• Non-Latin text is coarse. Every character above code point 255 is one token, so Cyrillic, Devanagari or Chinese text looks alike. One external false alarm was a Russian-language message.
• A score is evidence, not proof. It does not know where the input is written (HTML body, attribute, script, URL), which decides whether it can execute.
• Exact deduplication only. Related payload families can sit in both training and test data, so held-out numbers are optimistic. The external benchmark is the better estimate.

Intended use

Defensive: triaging inputs and logs, flagging suspicious values for review, and measuring how well a filter copes with encoded payloads. It is not a web application firewall on its own, and it was not built or evaluated for generating payloads.