# s0md3v/xsstrike architecture

> Architecture diagram of the GitHub repository s0md3v/xsstrike, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/s0md3v/xsstrike
- Repository: https://github.com/s0md3v/xsstrike

## Overview

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: [`modes/scan.py`](https://github.com/s0md3v/xsstrike/blob/master/modes/scan.py) (Scan), [`core/requester.py`](https://github.com/s0md3v/xsstrike/blob/master/core/requester.py) (Requester), [`xsstrike.py`](https://github.com/s0md3v/xsstrike/blob/master/xsstrike.py) (xsstrike.py), [`core/generator.py`](https://github.com/s0md3v/xsstrike/blob/master/core/generator.py) (Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_xsstrike["xsstrike.py<br/>cli bootstrap<br/>[xsstrike.py]"]
end

subgraph group_workflows["Modes"]
  node_scan["Scan<br/>workflow<br/>[scan.py]"]
  node_crawl["Crawl<br/>workflow<br/>[crawl.py]"]
  node_singlefuzz["Single fuzz<br/>workflow<br/>[singleFuzz.py]"]
  node_bruteforcer["Bruteforcer<br/>workflow<br/>[bruteforcer.py]"]
end

subgraph group_engine["Core"]
  node_requester["Requester<br/>http boundary<br/>[requester.py]"]
  node_parser["Parser<br/>context analysis<br/>[htmlParser.py]"]
  node_contexter["JS context<br/>context analysis<br/>[jsContexter.py]"]
  node_dom["DOM<br/>context analysis<br/>[dom.py]"]
  node_zetanize["Zetanize<br/>context analysis<br/>[zetanize.py]"]
  node_generator["Generator<br/>payload synthesis<br/>[generator.py]"]
  node_fuzzer["Fuzzer<br/>payload validation<br/>[fuzzer.py]"]
  node_waf["WAF detector<br/>evasion control<br/>[wafDetector.py]"]
  node_checker["Checker<br/>scan control<br/>[checker.py]"]
  node_filterchecker["Filter check<br/>scan control<br/>[filterChecker.py]"]
  node_photon["Photon<br/>crawler integration<br/>[photon.py]"]
  node_config["Config<br/>scan control<br/>[config.py]"]
end

subgraph group_data["Data"]
  node_definitions["Definitions<br/>signature data<br/>[definitions.json]"]
  node_wafsignatures["WAF signatures<br/>signature data<br/>[wafSignatures.json]"]
end

subgraph group_extensions["Extensions"]
  node_retirejs["RetireJS<br/>plugin detector<br/>[retireJs.py]"]
end

node_xsstrike -->|"dispatch"| node_scan
node_xsstrike -->|"dispatch"| node_crawl
node_xsstrike -->|"dispatch"| node_singlefuzz
node_xsstrike -->|"dispatch"| node_bruteforcer
node_crawl -->|"discover"| node_photon
node_scan -->|"precheck"| node_checker
node_scan -->|"filter"| node_filterchecker
node_scan -->|"request"| node_requester
node_singlefuzz -->|"request"| node_requester
node_bruteforcer -->|"request"| node_requester
node_requester -->|"response"| node_parser
node_parser -->|"context"| node_contexter
node_parser -->|"context"| node_dom
node_contexter -->|"refine"| node_zetanize
node_dom -->|"signals"| node_generator
node_zetanize -->|"signals"| node_generator
node_waf -->|"evasion"| node_generator
node_generator -->|"candidates"| node_fuzzer
node_fuzzer -->|"re-request"| node_requester
node_requester -->|"result"| node_checker
node_checker -->|"rules"| node_definitions
node_waf -->|"signatures"| node_wafsignatures
node_scan -.->|"plugin"| node_retirejs
node_crawl -.->|"plugin"| node_retirejs
node_config -->|"controls"| node_scan
node_config -->|"controls"| node_singlefuzz
node_config -->|"controls"| node_bruteforcer

click node_xsstrike "https://github.com/s0md3v/xsstrike/blob/master/xsstrike.py"
click node_scan "https://github.com/s0md3v/xsstrike/blob/master/modes/scan.py"
click node_crawl "https://github.com/s0md3v/xsstrike/blob/master/modes/crawl.py"
click node_singlefuzz "https://github.com/s0md3v/xsstrike/blob/master/modes/singleFuzz.py"
click node_bruteforcer "https://github.com/s0md3v/xsstrike/blob/master/modes/bruteforcer.py"
click node_requester "https://github.com/s0md3v/xsstrike/blob/master/core/requester.py"
click node_parser "https://github.com/s0md3v/xsstrike/blob/master/core/htmlParser.py"
click node_contexter "https://github.com/s0md3v/xsstrike/blob/master/core/jsContexter.py"
click node_dom "https://github.com/s0md3v/xsstrike/blob/master/core/dom.py"
click node_zetanize "https://github.com/s0md3v/xsstrike/blob/master/core/zetanize.py"
click node_generator "https://github.com/s0md3v/xsstrike/blob/master/core/generator.py"
click node_fuzzer "https://github.com/s0md3v/xsstrike/blob/master/core/fuzzer.py"
click node_waf "https://github.com/s0md3v/xsstrike/blob/master/core/wafDetector.py"
click node_checker "https://github.com/s0md3v/xsstrike/blob/master/core/checker.py"
click node_filterchecker "https://github.com/s0md3v/xsstrike/blob/master/core/filterChecker.py"
click node_photon "https://github.com/s0md3v/xsstrike/blob/master/core/photon.py"
click node_config "https://github.com/s0md3v/xsstrike/blob/master/core/config.py"
click node_definitions "https://github.com/s0md3v/xsstrike/blob/master/db/definitions.json"
click node_wafsignatures "https://github.com/s0md3v/xsstrike/blob/master/db/wafSignatures.json"
click node_retirejs "https://github.com/s0md3v/xsstrike/blob/master/plugins/retireJs.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_xsstrike toneBlue
class node_scan,node_crawl,node_singlefuzz,node_bruteforcer toneAmber
class node_requester,node_parser,node_contexter,node_dom,node_zetanize,node_generator,node_fuzzer,node_waf,node_checker,node_filterchecker,node_photon,node_config toneMint
class node_definitions,node_wafsignatures toneRose
class node_retirejs toneIndigo
```

## Components

### CLI

Command-line entrypoint and dispatch

- [xsstrike.py](https://github.com/s0md3v/xsstrike/blob/master/xsstrike.py): cli bootstrap · Parses intent and dispatches to modes · `xsstrike.py`

### Modes

User-facing scan workflows

- [Scan](https://github.com/s0md3v/xsstrike/blob/master/modes/scan.py): workflow · End-to-end target scanning · `modes/scan.py`
- [Crawl](https://github.com/s0md3v/xsstrike/blob/master/modes/crawl.py): workflow · Discovers URLs and parameters · `modes/crawl.py`
- [Single fuzz](https://github.com/s0md3v/xsstrike/blob/master/modes/singleFuzz.py): workflow · Focused fuzzing for one URL or parameter · `modes/singleFuzz.py`
- [Bruteforcer](https://github.com/s0md3v/xsstrike/blob/master/modes/bruteforcer.py): workflow · Payload-file based attack mode · `modes/bruteforcer.py`

### Core

Scanning, analysis, and payload engine

- [Requester](https://github.com/s0md3v/xsstrike/blob/master/core/requester.py): http boundary · Handles outbound requests and responses · `core/requester.py`
- [Parser](https://github.com/s0md3v/xsstrike/blob/master/core/htmlParser.py): context analysis · HTML and JavaScript parsing layer · `core/htmlParser.py`
- [JS context](https://github.com/s0md3v/xsstrike/blob/master/core/jsContexter.py): context analysis · Determines JavaScript sink context · `core/jsContexter.py`
- [DOM](https://github.com/s0md3v/xsstrike/blob/master/core/dom.py): context analysis · Inspects DOM-related reflection context · `core/dom.py`
- [Zetanize](https://github.com/s0md3v/xsstrike/blob/master/core/zetanize.py): context analysis · Additional context and sink handling · `core/zetanize.py`
- [Generator](https://github.com/s0md3v/xsstrike/blob/master/core/generator.py): payload synthesis · Builds context-aware payload candidates · `core/generator.py`
- [Fuzzer](https://github.com/s0md3v/xsstrike/blob/master/core/fuzzer.py): payload validation · Mutates and validates candidate payloads · `core/fuzzer.py`
- [WAF detector](https://github.com/s0md3v/xsstrike/blob/master/core/wafDetector.py): evasion control · Detects WAFs and influences payload choices · `core/wafDetector.py`
- [Checker](https://github.com/s0md3v/xsstrike/blob/master/core/checker.py): scan control · Controls target and parameter validation · `core/checker.py`
- [Filter check](https://github.com/s0md3v/xsstrike/blob/master/core/filterChecker.py): scan control · Filters worth-testing inputs · `core/filterChecker.py`
- [Photon](https://github.com/s0md3v/xsstrike/blob/master/core/photon.py): crawler integration · Collects URLs and parameters for scanning · `core/photon.py`
- [Config](https://github.com/s0md3v/xsstrike/blob/master/core/config.py): scan control · Central scan configuration · `core/config.py`

### Data

Static rules and signatures

- [Definitions](https://github.com/s0md3v/xsstrike/blob/master/db/definitions.json): signature data · Static detection rules and definitions · `db/definitions.json`
- [WAF signatures](https://github.com/s0md3v/xsstrike/blob/master/db/wafSignatures.json): signature data · WAF signature database · `db/wafSignatures.json`

### Extensions

Optional detectors and add-ons

- [RetireJS](https://github.com/s0md3v/xsstrike/blob/master/plugins/retireJs.py): plugin detector · Outdated JavaScript library detection · `plugins/retireJs.py`

## Connections

- 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
