PeXeS – Playwright XSS Scanner

PeXeS (Playwright XSS Scanner) is an advanced XSS vulnerability scanner with multi-layer execution verification and industry-leading accuracy. Powered by Playwright, it excels at detecting Cross-Site Scripting (XSS) vulnerabilities with actual execution proof through dialog detection, console monitoring, and network tracking.

Designed for security researchers and bug bounty hunters, PeXeS eliminates false positives through CSP detection and confidence scoring while maintaining high performance through smart concurrency.

Key Features

Core Detection Capabilities

• Multi-Layer Verification: Real JavaScript execution detection via Playwright listeners
  • Dialog/Alert capture (alert, confirm, prompt)
  • Console message monitoring with execution markers
  • Network request tracking for exfiltration attempts
  • DOM mutation observation
• Confidence Scoring: Advanced scoring system (0-100) with levels: HIGH (90-100), MEDIUM (60-89), LOW (30-59), FALSE_POSITIVE (0-29)
• CSP Detection: Automatic Content-Security-Policy violation detection to eliminate false positives
• False Positive Filtering: Encoding detection (HTML entities, URL encoding, JS escaping) and context analysis

Scanning Modes

• Multi-Mode Scanning: Specialized scanners for URL, Form, DOM, Event, and API contexts
• Smart Concurrency: Optimized tab management that scales resources dynamically for maximum efficiency
• WAF Evasion & Detection: Built-in WAF detection and 10+ advanced evasion techniques
• API Security: Dedicated scanner for JSON body injection with reflection-based verification (93% false positive reduction)

Advanced Features

• Evidence Capture: Screenshots, DOM snapshots, console logs, network activity, and dialog transcripts
• Interactive Reporting: Generate detailed JSON, HTML, Markdown, or CSV reports with built-in server
• Resume Capability: Interrupt and resume scans without losing progress
• Authentication: Support for custom headers and cookies

Table of Contents

• Installation
• Quick Start
• Usage Guide
  • Basic Scanning
  • Scan Modes
  • Advanced Options
  • Debugging with Console
• Detection Methodology
• Reporting
• Configuration

Installation

Setup

PeXeS requires Python 3.10+ and Node.js (for Playwright).

1. Quick Installation (recommended)

git clone https://github.com/iqbalmh18/pexes.git
cd pexes
bash install.sh

2. Manual Installation

1. Clone this repository:

   git clone https://github.com/iqbalmh18/pexes.git
   cd pexes

2. Create virtual environment:

   python3 -m venv .venv

3. Activate virtual environment:

   # Linux/macOS
   python3 -m venv .venv
   source .venv/bin/activate
   
   # Windows (Command Prompt)
   python -m venv .venv
   .venv\Scripts\activate
   
   # Windows (PowerShell)
   python -m venv .venv
   .venv\Scripts\Activate.ps1

   Install dependencies:

   pip install --upgrade pip
   pip install -e .

   Install Playwright browsers:

   playwright install chromium

Quick Start

Check if installed correctly:

pexes --version

Run a full scan against a target:

pexes scan --url https://example.com --mode all --evidence

Usage Guide

Basic Scanning

Scan a specific URL with default settings:

pexes scan --url https://example.com

Scan with visual browser + DevTools console (for debugging):

pexes scan --url https://example.com --headless false --console

Scan Modes

PeXeS supports multiple scan modes, controlled by the --mode argument:

• all: Run all enabled scanners (default)
• url: Scan URL parameters (Reflected XSS)
• form: Scan HTML forms and inputs (Stored/Reflected XSS)
• dom: Scan for DOM-based XSS sinks
• event: Scan HTML event handlers
• api: Scan API endpoints (JSON injection)
• waf: Detect WAF presence only

Example:

pexes scan --url https://example.com --mode dom --evidence

Advanced Options

CLI Arguments Reference

Argument	Type	Default	Description
--url	str	Required	Target URL to scan.
--mode	choice	all	Scan mode: all, url, form, dom, event, api, waf.
--headless	choice	true	Run browser in headless mode (true/false).
--console	flag	False	Open DevTools console (only with --headless false).
--max-tab	int	5	Max concurrent tabs (URL scan only).
--max-payload-dom	int	3	Max payloads for DOM scanner.
--max-payload-event	int	3	Max payloads for Event scanner.
--proxy	str	None	Proxy URL (e.g., http://127.0.0.1:8080).
--evidence	flag	False	Capture screenshots and DOM snapshots.
--resume	flag	False	Resume a previously interrupted scan.
--header	str	None	Custom header (repeatable).
--cookie	str	None	Custom cookie (repeatable).
--delay	float	0.0	Delay between requests (seconds).
--waf-evasion	flag	False	Enable automatic WAF evasion.
--detect-waf	flag	False	Detect WAF presence only.
--output-format	choice	json	Output format: json, html, md, csv.
--output-path	path	./reports	Output file or directory.

Advance Usage Examples

Full Authenticated Scan with Evidence:

pexes scan --url https://example.com/dashboard \
  --mode all \
  --header "Authorization: Bearer <token>" \
  --cookie "session_id=xyz123" \
  --evidence \
  --max-tab 5

API Fuzzing with Reflection Verification:

pexes scan --url https://api.target.com/v1/user \
  --mode api \
  --proxy http://127.0.0.1:8080 \
  --output-format json

CSP-Protected Site Scan:

pexes scan --url https://google.com \
  --mode dom \
  --evidence \
  --headless true
# Automatically detects CSP blocking and filters false positives

Debugging with Console

Open browser with DevTools console for real-time monitoring:

pexes scan --url https://example.com \
  --mode dom \
  --headless false \
  --console

Note: DevTools opens in Elements tab by default (Chromium limitation). Click Console tab to view logs.

Detection Methodology

Multi-Layer Verification

PeXeS uses a comprehensive verification approach:

1. Execution Detection (Highest Priority)

   • Dialog/Alert capture with auto-accept
   • Console message monitoring for markers
   • Network request tracking
   • DOM mutation observation

2. Reflection Analysis

   • Context detection (HTML, JavaScript, attribute, JSON)
   • Encoding detection (HTML entities, URL, JavaScript)
   • Dangerous context identification

3. False Positive Filtering

   • CSP violation detection from console errors
   • Payload encoding verification
   • Reflection-based confidence scoring

Confidence Scoring

Scoring Logic:

• HIGH (90-100): Dialog triggered OR verified execution + reflection
• MEDIUM (60-89): Reflected in executable context, no execution proof
• LOW (30-59): Reflected but encoded/sanitized
• FALSE_POSITIVE (0-29): Not reflected OR CSP blocking OR fully encoded

Example:

{
  "payload": "<script>alert(1)</script>",
  "confidence_score": 90,
  "confidence_level": "HIGH",
  "evidence": {
    "dialogs": [{
      "type": "alert",
      "message": "1",
      "timestamp": "2025-11-23T14:54:49.196844"
    }]
  }
}

Reporting

PeXeS generates detailed reports in JSON, HTML, Markdown, and CSV formats.

Sample JSON Report

{
  "metadata": {
    "scanner": "PeXeS",
    "version": "1.0.5",
    "target": "https://example.com",
    "date": "2025-11-23T10:00:00"
  },
  "summary": {
    "total_vulnerabilities": 4,
    "risk_level": "HIGH",
    "breakdown": {
      "url": 4,
      "dom": 0,
      "form": 0,
      "event": 0,
      "api": 0
    }
  },
  "vulnerabilities": [
    {
      "id": "XSS-001",
      "type": "Reflected XSS",
      "severity": "MEDIUM",
      "url": "https://example.com/?q=<payload>",
      "payload": "<script>alert(1)</script>",
      "confidence_score": 90,
      "confidence_level": "HIGH",
      "evidence": {
        "dialogs": [{
          "type": "alert",
          "message": "1",
          "timestamp": "2025-11-23T14:54:49.196844"
        }],
        "screenshots": ["reports/evidence/screenshot_001.png"],
        "console_logs": ["PEXES execution marker detected"]
      }
    }
  ]
}

Generate and View HTML Report:

pexes report --file ./reports/scan.json --html

This command will convert the JSON report to HTML and launch a local server to view it in your browser.

Other Formats:

pexes scan ... --output-format md --output-path report.md
pexes scan ... --output-format csv --output-path report.csv

Configuration

Manage global settings:

• View Config: pexes config --get max_tab
• Set Config: pexes config --set max_tab 2
• Reset Config: pexes config --reset

Project Structure

pexes/
├── pexes/              # Main package
│   ├── browser/        # Playwright driver and browser management
│   ├── cli/            # Command-line interface arguments
│   ├── core/           # Core engine and controller
│   ├── payloads/       # XSS payload lists and management
│   ├── plugins/        # Plugin system (e.g., WAF evasion)
│   ├── reports/        # Report generation logic
│   ├── scanners/       # Vulnerability scanners (URL, DOM, API, etc.)
│   ├── utils/          # Utilities (XSS detection, evidence, logging)
│   └── main.py         # Entry point
├── reports/            # Default output directory for scan reports
├── README.md           # Documentation
├── pyproject.toml      # Project configuration and dependencies
└── requirements.txt    # Python dependencies
└── install.sh          # PeXeS installer scripts

Advanced Features

WAF Evasion

Detect WAF:

pexes scan --url https://example.com --detect-waf

Scan with Evasion:

pexes scan --url https://example.com --mode all --waf-evasion

Payload Management

• List Payloads: pexes payload --list
• Add Payload: pexes payload --add custom.json
• Remove Payload: pexes payload --remove payload_name

Performance Tuning

Fast Scan (Higher FP risk):

pexes scan --url https://example.com \
  --max-payload-dom 2 \
  --max-payload-event 2 \
  --delay 0

Thorough Scan (Slower, more accurate):

pexes scan --url https://example.com \
  --max-payload-dom 10 \
  --max-payload-event 10 \
  --delay 1.0 \
  --evidence

Troubleshooting

Issue: No vulnerabilities detected on known vulnerable site

• Ensure --evidence flag is enabled
• Try --headless false --console to visually verify
• Check if CSP is blocking (scanner auto-detects this)

Issue: Too many false positives

• Update to latest version (v1.0.5+)
• CSP detection and confidence scoring should filter these
• Check confidence_level in reports (ignore FALSE_POSITIVE)

Issue: Scan too slow

• Reduce max payloads: --max-payload-dom 3
• Increase tabs: --max-tab 5 (URL scan only)
• Disable evidence: Remove --evidence flag

License

MIT License. See LICENSE for details.

Contributing

Contributions welcome! Please submit pull requests or open issues for bugs/features.

---

Made with ❤️ for Security Research
_{Remember: With great power comes great responsibility}