🔍 Simple XSS Scanner

Context-Aware Reflected XSS Vulnerability Detector

A lightweight, Python-based security tool designed to intelligently detect Reflected Cross-Site Scripting (XSS) vulnerabilities in GET parameters.

---

What Makes This Scanner Special?

Unlike basic scanners that simply look for input reflections, this is context-aware. It intelligently distinguishes between:

• 🚨 Unsafe Reflections — raw <script> tags, unescaped event handlers
• ✅ Safe Sanitizations — HTML entities (<), Unicode escapes (\u003c), quoted attributes

This drastically reduces false positives and provides reliable results.

📌 Note: MVP (Minimum Viable Product) developed for educational purposes. Currently supports GET parameters.

---

📦 Installation

Clone the Repository

git clone https://github.com/PhabloAlves/xss_scanner.git
cd xss_scanner

Install Dependencies

pip install requests flask

---

🧪 Local Testing Lab

The project includes the xss_lab_page folder with two servers to verify the tool's logic and accuracy:

Server	Description	Behavior
vuln_server.py	Deliberately vulnerable Flask app	Reflects input without sanitization
safe_server.py	Secure HTTP server	Properly escapes/encodes input

---

Test Against Vulnerable Server

Start the Server

python xss_lab_page/vuln_server.py
# Server runs on http://localhost:8000

Run the Scanner (in a new terminal)

python scanner.py --url "http://localhost:8000/?nome=test" --i-have-permission

Expected Result: The scanner flags the parameter as VULNERABLE (High/Medium Severity) ✅

---

Test Against Safe Server

Start the Server

python xss_lab_page/safe_server.py
# Server runs on http://localhost:8001

Run the Scanner (in a new terminal)

python scanner.py --url "http://localhost:8001/multi?q=test&cat=1" --i-have-permission

Expected Result: The scanner marks the parameters as Safe (e.g., REFLECTION_ENCODED_HTML), proving it avoids false positives ✅

---

⚙️ Usage & Parameters

Command Line Arguments

Argument	Description	Example
--url [URL]	Single target URL with parameters	--url "http://example.com/?q=test"
--urls-file [FILE]	Text file with URL list (one per line)	--urls-file urls.txt
--output-json [FILE]	Save results in structured JSON	--output-json findings.json
--timeout-seconds [N]	Request timeout (default: 5.0s)	--timeout-seconds 10
--i-have-permission	Required. Confirms authorization to test	—

---

📋 Bulk Mode — Multiple URLs

Create a urls.txt file with the URLs to test:

http://example.com/search?q=test
http://localhost:8000/?nome=guest
http://localhost:8001/attr?name=user

Run the bulk scan:

python scanner.py --urls-file urls.txt --i-have-permission --output-json findings.json

The scanner reads URLs from the file, executes the scan, and saves a detailed report to findings.json.

---

📊 Output Format

🖥️ Console Output

[!] nome: VULNERABLE - The payload was reflected unsafely
[i] q: Safe - The payload was reflected safely or not reflected
[-] cat: ok - No reflection found

📄 JSON Output

With --output-json, you get a structured report for analysis:

[
  {
    "status": "VULNERABLE",
    "rule": "UNSAFE_REFLECTION",
    "severity": "MEDIUM",
    "parameter": "nome",
    "context": "text",
    "evidence": "<h1>Hello, CANARY_123<'\"</h1>",
    "url": "http://localhost:8000/?nome=CANARY_123%3C%27%22"
  }
]

---

⚠️ Disclaimer

This is educational software. Use only on systems you own or have explicit permission to test.