SecFathy / xss-specialist

# xss-specialist
### A Kev-style XSS decision model **+** an execution-authoritative live assessment system
*Can a small language model become a deep XSS expert through gated continual learning — and can a
browser oracle turn its reasoning into evidence-backed, hard-to-fool findings?*
**We built it, measured it honestly, and report the negatives.**
---
> **Authorized-use only.** This project assists **authorized** penetration testers, application-security
> engineers, and researchers. It does **not** autonomously attack third-party systems, and every path
> to active testing is gated behind explicit scope + authorization. See Security & Boundaries.
---
## Table of contents
- The one-paragraph version
- Why this exists
- Two systems, one repo
- Kev-style XSS decision model
- Headline results
- The research: KEV-gated continual learning
- The live system: execution-authoritative assessment
- The near-miss problem (the interesting part)
- Quick Install
- How to use
- Repository layout
- Benchmarks & reproducibility
- Security & boundaries
- Honest limitations
- Research questions, answered
- Roadmap / blockers to production
- License & credits
---
## The one-paragraph version
`xss-specialist` is a **research prototype** with two halves. The first is an offline study: can a small
(8B) open model be specialized into a deep XSS reasoner using retrieval, LoRA fine-tuning, and a
**KEV-gated continual-learning pipeline** where a frozen decision model (Kev-4B) decides what knowledge
is even *allowed* to reach the weights? The second is a **live, authorized assessment system** that
crawls a target in scope, plans **marker-first, non-destructive** probes, and confirms XSS with a
**headless-browser oracle** — where *execution*, not model confidence, is the sole authority for a
`CONFIRMED` finding. The most important results are the **honest negatives**: a specialist model can
fix false positives and execution-context accuracy but **cannot** solve near-miss sanitizer/entity
leakage — so the frozen promotion gate **rejected every model candidate**, while the **live layer**
neutralizes the same problem at the execution boundary (leakage `1.00 → 0.00`).
---
## Why this exists
Most "AI security scanner" projects overclaim: they wire an LLM to a crawler and trust its verdicts.
Two things go wrong:
1. **LLMs hallucinate safety.** They pattern-match names — a function called `DOMPvrify.sanitize`
 *looks* safe, so the model says safe. That's **near-miss entity leakage**, and it is dangerous.
2. **Confidence ≠ vulnerability.** A model that's 0.9 confident is still wrong often enough to bury
 analysts in false positives, or worse, miss real bugs.
This project takes the opposite stance:
- **Knowledge must be earned, not absorbed.** A gate + independent verification decide what becomes
 model weights vs. what stays in retrieval. Poisoning and prompt-injection must never reach training.
- **The browser is the judge.** A finding is only `CONFIRMED` when a real headless brow