How s0md3v/xsstrike works
XSStrike is a Python command-line XSS detection suite. Architecturally it is organized around a central scanning engine in core/, a small mode layer in modes/, and static detection data in db/.
The top-level entrypoint is xsstrike.py. It is the CLI bootstrap: it parses user intent and dispatches into one of the operational modes rather than doing the scanning itself.
modes/ is the user-facing workflow boundary. The main modes are:
• scan for end-to-end scanning,
• crawl for multi-page discovery,
• singleFuzz for focused fuzzing of one parameter/URL,
• bruteforcer for trying payloads from a file.
These modes orchestrate the same lower-level engine components in different combinations.
core/ contains the scanning pipeline. The important roles here are:
• request execution and response handling,
• parsing HTML/JavaScript context,
• deciding whether a parameter is injectable,
• generating context-aware payloads,
• fuzzing and validating candidate payloads,
• logging/reporting results.
This is the part that turns a target URL and parameters into actual XSS findings.
The central data flow is: target input → HTTP request/response → response parsing and context analysis → payload generation → fuzzing/re-requesting → detection result. XSStrike’s distinguishing feature is that payloads are crafted after analyzing the reflected context rather than blindly injected first.
core/requester.py is the network boundary. It isolates outbound HTTP behavior from the rest of the scanner so that scanning logic can be reused across modes. This is also where headers, request customization, and response retrieval converge.
core/htmlParser.py, core/jsContexter.py, core/dom.py, and core/zetanize.py form the parsing and context-analysis layer. Together they inspect HTML and JavaScript to understand where input lands, which is what enables the tool to generate payloads appropriate to the sink/context instead of using one-size-fits-all strings.
core/generator.py, core/fuzzer.py, core/encoders.py, and core/prompt.py are the payload synthesis and mutation layer. They build candidate XSS payloads, mutate them for different encodings or evasions, and interactively collect or adjust inputs when needed.
core/wafDetector.py and db/wafSignatures.json implement WAF detection. WAF identification is used as a pre-check and influences payload selection/evasion behavior. This is a distinct control point in the pipeline because it changes how subsequent requests are formed.
core/filterChecker.py, core/checker.py, and core/config.py provide scan control and validation. They appear to manage whether a target/parameter is worth testing, how scan behavior is configured, and how checks are sequenced.
The db/definitions.json and db/wafSignatures.json files are the repository’s static knowledge base. They hold the signatures and definitions that drive detection logic, so they are an important architecture boundary between code and rules/data.
core/photon.py and modes/crawl.py show the crawler integration. XSStrike uses crawling as an upstream discovery step to collect URLs and parameters before active testing, which means the crawler feeds the scanner with attack surface rather than being the scanner itself.
plugins/retireJs.py is a separate plugin boundary for outdated JavaScript library detection. This extends the scanner beyond reflected/DOM XSS into library-level risk discovery, and it likely plugs into crawl or scan workflows when JavaScript assets are found.
Support modules such as core/log.py, core/colors.py, core/utils.py, core/updater.py, and core/fuzzer.py handle output formatting, shared helpers, maintenance, and scan ergonomics. They are auxiliary, but they keep the engine modules focused on analysis and request generation.
Overall, the architecture is a pipeline-based security scanner: discovery feeds analysis, analysis feeds payload generation, payloads feed repeated HTTP requests, and results are reported back through a CLI workflow. The main diagram should emphasize the separation between the mode dispatcher, the core analysis/fuzzing engine, the HTTP boundary, and the static signature/data stores.
Main entry points: scan.py Scan · requester.py Requester · xsstrike.py xsstrike.py · generator.py Generator
Components 20
CLI
Command-line entrypoint and dispatch
- xsstrike.py · Parses intent and dispatches to modes
xsstrike.py
Modes
User-facing scan workflows
- Scan · End-to-end target scanning
modes/scan.py - Crawl · Discovers URLs and parameters
modes/crawl.py - Single fuzz · Focused fuzzing for one URL or parameter
modes/singleFuzz.py - Bruteforcer · Payload-file based attack mode
modes/bruteforcer.py
Core
Scanning, analysis, and payload engine
- Requester · Handles outbound requests and responses
core/requester.py - Parser · HTML and JavaScript parsing layer
core/htmlParser.py - JS context · Determines JavaScript sink context
core/jsContexter.py - DOM · Inspects DOM-related reflection context
core/dom.py - Zetanize · Additional context and sink handling
core/zetanize.py - Generator · Builds context-aware payload candidates
core/generator.py - Fuzzer · Mutates and validates candidate payloads
core/fuzzer.py - WAF detector · Detects WAFs and influences payload choices
core/wafDetector.py - Checker · Controls target and parameter validation
core/checker.py - Filter check · Filters worth-testing inputs
core/filterChecker.py - Photon · Collects URLs and parameters for scanning
core/photon.py - Config · Central scan configuration
core/config.py
Data
Static rules and signatures
- Definitions · Static detection rules and definitions
db/definitions.json - WAF signatures · WAF signature database
db/wafSignatures.json
Extensions
Optional detectors and add-ons
- RetireJS · Outdated JavaScript library detection
plugins/retireJs.py
Connections 27
- xsstrike.py → Scan: dispatch · CLI selects scan workflow
- xsstrike.py → Crawl: dispatch · CLI selects crawl workflow
- xsstrike.py → Single fuzz: dispatch · CLI selects focused fuzzing workflow
- xsstrike.py → Bruteforcer: dispatch · CLI selects payload-file workflow
- Crawl → Photon: discover · Crawl mode gathers targets and parameters
- Scan → Checker: precheck · Scan mode validates what to test
- Scan → Filter check: filter · Scan mode reduces invalid candidates
- Scan → Requester: request · Scan mode executes HTTP traffic
- Single fuzz → Requester: request · Focused fuzzing reuses the HTTP boundary
- Bruteforcer → Requester: request · Bruteforcer sends payload attempts
- Requester → Parser: response · Responses are parsed for reflection and context
- Parser → JS context: context · HTML parsing feeds JS context analysis
- Parser → DOM: context · Parsed markup feeds DOM inspection
- JS context → Zetanize: refine · Context analysis is refined for sink handling
- DOM → Generator: signals · Context signals guide payload generation
- Zetanize → Generator: signals · Context details shape payload synthesis
- WAF detector → Generator: evasion · WAF detection influences payload selection
- Generator → Fuzzer: candidates · Generated payloads are mutated and validated
- Fuzzer → Requester: re-request · Fuzzing replays candidate payloads over HTTP
- Requester → Checker: result · Responses are assessed for injection evidence
- Checker → Definitions: rules · Detection logic uses stored definitions
- WAF detector → WAF signatures: signatures · WAF detection consults signature data
- Scan → RetireJS: plugin · Scan workflow can extend into JS library detection
- Crawl → RetireJS: plugin · Crawl can surface JavaScript assets for plugin analysis
- Config → Scan: controls · Configuration shapes scan behavior
- Config → Single fuzz: controls · Configuration shapes focused fuzzing behavior
- Config → Bruteforcer: controls · Configuration shapes brute-force behavior