XSSPECTER

DOM & Reflected XSS Scanner — hunt Cross-Site Scripting in web app parameters, from fast reflection heuristics to real browser-confirmed execution.

XSSPECTER is a lightweight, original XSS scanner written in Python 3. It parses a target URL's query parameters (and optional POST body), injects a curated set of payloads one parameter at a time, and reports whether each payload is merely reflected, safely filtered, or actually executed in a real browser.

---

✨ Features

• Two engines in one tool
  • Reflected (default, no browser) — pure requests, with an HTML-context heuristic that distinguishes unencoded reflection from HTML-escaped output.
  • DOM / Headless (--headless) — drives real Chromium via Playwright, hooks alert / prompt / confirm and DOM write sinks, and reports confirmed execution.
• ~40 built-in payloads — <script>, img/onerror, svg/onload, event handlers, attribute/tag breakouts, javascript: URIs, template-injection style, and WAF-evasion (case/encoding) mutations. Override with --payloads.
• Payload mutation helper — auto-generates case & encoding variants to slip past naive blacklist filters (disable with --no-mutate).
• GET and POST parameter testing (--data "a=1&b=2").
• Colored console output (colorama) + optional standalone dark-themed HTML report with inline CSS (--html report.html).
• Lazy Playwright import — reflected mode works even without Playwright installed; a clear install hint is printed if --headless is requested without it.
• Robust error handling, TLS toggle, request delay/timeout controls.

---

🧠 Reflected vs. Headless mode

	Reflected (default)	Headless (--headless)
Engine	requests HTTP client	Playwright + Chromium
Detects	Payload echoed unencoded in response	Payload that actually executes
Needs a browser?	No	Yes (playwright install chromium)
Speed	Very fast	Slower (real page loads)
Verdicts	REFLECTED / FILTERED / SAFE	EXECUTED (+ reflected fallback)
Best for	Quick triage, POST params, CI	Confirming exploitability, DOM XSS

Reflected mode always runs. Adding --headless runs the DOM engine as well, so you get fast triage plus browser-confirmed proof.

---

📦 Install

git clone https://github.com/<your-user>/XSSPECTER.git
cd XSSPECTER
pip install -r requirements.txt

Optional — only for --headless DOM execution detection:

pip install playwright
playwright install chromium

---

🚀 Usage

# Fast reflected scan of a query parameter
python xsspecter.py -u "https://target.tld/search?q=test"

# Test POST parameters as well
python xsspecter.py -u "https://target.tld/login" --data "user=admin&pass=x"

# Confirm execution in a real headless browser
python xsspecter.py -u "https://target.tld/page?id=1" --headless

# Use a custom payload file and write an HTML report
python xsspecter.py -u "https://target.tld/s?q=1" --payloads my-payloads.txt --html report.html

# Disable mutations, add a delay, skip TLS verification (lab targets)
python xsspecter.py -u "https://target.tld/s?q=1" --no-mutate --delay 0.3 --insecure

Options

-u, --url        Target URL (with query params)          [required]
    --data       POST body params, e.g. "a=1&b=2"
    --headless   Enable DOM engine (Playwright/Chromium)
    --payloads   Custom payload file (overrides built-in)
    --html       Write an HTML report to this path
    --no-mutate  Disable case/encoding payload variants
    --timeout    Per-request timeout in seconds (default 15)
    --delay      Delay between requests in seconds
    --insecure   Do not verify TLS certificates
    --version    Show version and exit

---

🖥️ Sample output

 __  __ ____  ____  ____  _____ ____ _____ _____ ____
 \ \/ // ___|/ ___||  _ \| ____/ ___|_   _| ____|  _ \
  \  / \___ \\___ \| |_) |  _|| |     | | |  _| | |_) |
  /  \  ___) |___) |  __/| |__| |___  | | | |___|  _ <
 /_/\_\|____/|____/|_|   |_____\____| |_| |_____|_| \_\

        DOM & Reflected XSS Scanner  ·  v1.0.0
        by Əliəsgər Fətullayev

[*] Target : https://target.tld/search?q=test
[*] Payloads loaded : 45

[*] Reflected scan: 45 payloads x 1 parameter(s)

== GET param: q ==
  REFLECTED  q (GET) [html]  <img src=x onerror=alert(1)>xsp7k
  FILTERED   q (GET) [encoded]  <script>alert(1)</script>xsp7k
  SAFE       q (GET)  <svg onload=alert(1)>xsp7k

== DOM param: q ==
  EXECUTED   q (GET) [dom]  <img src=x onerror=alert(1)>xsp7k

====================================================
[*] Scan summary
    EXECUTED : 1
    REFLECTED: 6
    FILTERED : 12
    SAFE     : 26

[!] 7 potentially exploitable finding(s) — review manually.
[*] HTML report written to: report.html

---

⚠️ Legal / Ethical Use

XSSPECTER is intended for authorised security testing and education only. Only run it against systems that you own or for which you have explicit, written permission to test. Unauthorised scanning or exploitation of systems you do not control is illegal in most jurisdictions and unethical. The author accepts no liability for misuse or for any damage caused by this tool. You are solely responsible for your actions.

---

👤 Author

Əliəsgər Fətullayev — cybersecurity student & offensive-security enthusiast.

Released under the MIT License · © 2026.