Target URL ──► Async Scanner ──► Reflection Engine ──► DOM Parser ──► Findings
                    │                     │                  │
               Concurrency          Encoding          Context Label
               Semaphore            Fingerprint       Confidence Score
               (aiohttp)            (html/url/js)     Exploit Notes

xss-framework/
│
├── cli/                        # Typer + Rich command-line interface
│   ├── main.py                 # Entry point → xsf command
│   ├── console.py              # Banner, panels, themed output
│   └── commands/
│       ├── scan.py             # xsf scan
│       ├── crawl.py            # xsf crawl
│       ├── payloads.py         # xsf payloads
│       ├── report.py           # xsf report
│       └── config_cmd.py       # xsf config
│
├── core/                       # Framework engine
│   ├── config.py               # FrameworkConfig, ScannerConfig, CrawlerConfig
│   ├── scanner.py              # Async injection orchestrator
│   ├── crawler.py              # Async crawler — link/form/JS endpoint discovery
│   └── reflection.py           # DOM-aware reflection analysis engine
│       ├── _EncodingAnalyzer       (char-level encoding fingerprint)
│       ├── _ScriptContextClassifier (JS lexer state machine)
│       ├── _DomContextDetector     (BeautifulSoup DOM walker)
│       ├── _FalsePositiveDetector  (statistical FP heuristics)
│       └── _ResponseDiffer         (token-level baseline diff)
│
├── modules/                    # Pluggable scan module system
│   ├── base.py                 # ModuleResult, BaseModule ABC
│   └── xss/
│       └── reflective.py       # ReflectiveXSSModule (orchestrates scan + report)
│
├── payloads/                   # Payload management
│   ├── engine.py               # PayloadEngine, FilterDetector, PayloadPrioritizer
│   ├── generator.py            # Mutation engine, encoding variants
│   ├── models.py               # PayloadEntry, PayloadCategory
│   └── data/                   # Bundled YAML payload sets
│       ├── basic.yaml
│       ├── polyglot.yaml
│       ├── waf_bypass.yaml
│       ├── attribute_injection.yaml
│       ├── js_context.yaml
│       └── svg.yaml
│
├── reports/                    # Multi-format output
│   ├── base.py                 # BaseReporter ABC
│   ├── session.py              # ScanSession (ID, timestamps, metadata)
│   ├── json_reporter.py        # Machine-readable JSON (schema v2)
│   ├── html_reporter.py        # Self-contained HTML report
│   ├── csv_reporter.py         # Flat CSV export
│   └── console.py              # Rich terminal output
│
├── utils/
│   ├── http.py                 # Async HTTPClient (aiohttp wrapper)
│   ├── helpers.py              # URL manipulation, marker injection
│   └── logging_setup.py        # Structured logging
│
├── tests/
│   ├── conftest.py             # Shared fixtures + mock aiohttp server
│   ├── test_reflection.py      # Reflection engine unit tests
│   ├── test_payloads.py        # Payload engine unit tests
│   ├── test_scanner.py         # Scanner unit tests
│   ├── test_crawler.py         # Crawler unit tests
│   ├── test_reporters.py       # Reporter unit tests (57 tests)
│   ├── test_integration.py     # Live aiohttp server integration tests
│   └── benchmarks/
│       ├── conftest.py         # Module-scoped event loop fixture
│       └── test_bench_scanner.py  # pytest-benchmark performance suite
│
└── config/
    └── default.yaml            # Default framework configuration

xsf scan "https://target.com/search?q=test" --forms --waf-bypass

         ┌─────────────┐
         │   CLI Layer  │  parse args → build FrameworkConfig
         └──────┬──────┘
                │
         ┌──────▼──────────┐
         │ ReflectiveXSSModule │  orchestrates crawl + scan + report
         └──────┬──────────┘
                │
      ┌─────────┼──────────┐
      │         │          │
┌─────▼───┐ ┌──▼────┐ ┌───▼──────────┐
│ Crawler  │ │Payload│ │   Scanner    │
│(async)  │ │Engine │ │(async + sem) │
└─────┬───┘ └──┬────┘ └───┬──────────┘
      │        │           │
   URLs +    Payloads   HTTP GET/POST
   Forms      list       (aiohttp)
      │        │           │
      └────────┴─────┬─────┘
                     │
            ┌────────▼────────┐
            │ ReflectionAnalyzer│
            │  DOM parse       │
            │  Encoding check  │
            │  FP filter       │
            └────────┬────────┘
                     │
              ┌──────▼──────┐
              │  Reporters   │
              │ JSON/HTML/CSV│
              └─────────────┘

╭─────────────────────────────────────────────────────────────────────╮
│                          TARGET                                      │
│  Target       : https://target.com/search?q=test                    │
│  Scan mode    : url-params                                           │
│  Concurrency  : 10   Timeout: 10.0s   Retries: 3   SSL: skip        │
│  WAF bypass   : off  Mutations: off                                  │
╰─────────────────────────────────────────────────────────────────────╯

  ⣾ Scanning for reflected XSS…

  1 VULNERABILITY CONFIRMED

╭─────────────────────────────────────────────────────────────────────╮
│  [HIGH]  Finding #1 — Reflected XSS                                 │
│  Parameter  : q                                                      │
│  Context    : HTML_TEXT                                              │
│  Difficulty : TRIVIAL                                                │
│  Payload    : <script>alert(AbCdEfGh)</script>                       │
│  Attack URL : https://target.com/search?q=%3Cscript%3Ealert%28...   │
│  Evidence   : ...Results for: <script>alert(AbCdEfGh)</script>...   │
│  Notes      : Both < and > are unencoded — tag injection possible.  │
╰─────────────────────────────────────────────────────────────────────╯

╭─────────────────────────────────────────────────────────────────────╮
│                        SCAN SUMMARY                                  │
│  Payloads loaded    50                                               │
│  Payloads tested    1                                                │
│  Parameters tested  1                                                │
│  Vulnerabilities    1                                                │
│  Errors             0                                                │
│  Elapsed            0.38s                                            │
╰─────────────────────────────────────────────────────────────────────╯

  Context    : SCRIPT_STRING
  Difficulty : EASY
  Notes      : Marker in JS string literal (delimiter: '). Need ' to break out.
               Exploitation difficulty: EASY.
  Encoding   : none
  Chars kept : ' ( ) ; \

xsf [COMMAND] [OPTIONS]

Commands:
  scan      Scan a URL for Reflected XSS vulnerabilities
  crawl     Crawl a site and discover endpoints, forms, and injectable parameters
  payloads  Payload management — list, inspect, and export payload sets
  report    Generate a report from a previously saved JSON scan file
  config    Configuration management — init, display, and validate config files

<script>alert(1)</script>
<img src=x onerror=alert(1)>
"><script>alert(1)</script>

session_id, scan_id, generated_at, target, finding_number, type, severity,
severity_score, confidence, confidence_label, parameter, payload, attack_url,
evidence, reflection_context, exploitation_notes, encoding_types,
dangerous_chars_preserved, exploitation_difficulty

pytest tests/benchmarks/ -v --benchmark-sort=mean

---------------------------------------- benchmark: 14 tests ----------------------------------------
Name                                           Min        Mean       Max      Rounds
---------------------------------------------------------------------------------------------
test_bench_payload_loading_default           0.8ms      1.1ms      2.3ms       412
test_bench_payload_loading_with_mutations    2.1ms      2.7ms      4.8ms       201
test_bench_payload_load_entries              1.4ms      1.9ms      3.5ms       308
test_bench_payload_load_with_waf_bypass      1.7ms      2.2ms      4.1ms       256
---------------------------------------------------------------------------------------------
test_bench_reflection_html_text              0.4ms      0.6ms      1.2ms       819
test_bench_reflection_script_string          0.5ms      0.7ms      1.4ms       712
test_bench_reflection_event_handler          0.4ms      0.6ms      1.1ms       844
test_bench_reflection_no_match               0.1ms      0.1ms      0.3ms      3241
test_bench_reflection_large_page             3.2ms      4.1ms      7.8ms        98
test_bench_reflection_all_contexts           1.8ms      2.4ms      4.6ms       204
---------------------------------------------------------------------------------------------
test_bench_scan_single_param                 8.3ms     11.2ms     18.4ms        45
test_bench_scan_multi_param                 14.6ms     19.8ms     31.2ms        26
test_bench_payload_throughput               41.2ms     52.7ms     78.9ms        10
test_bench_scan_with_reflection_analysis    10.1ms     13.9ms     22.6ms        38
---------------------------------------------------------------------------------------------

MIT License — Copyright (c) 2026 CyVen

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions: ...