# tx-c0re/xss-grenade architecture

> Architecture diagram of the GitHub repository tx-c0re/xss-grenade, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tx-c0re/xss-grenade
- Repository: https://github.com/tx-c0re/xss-grenade

## Overview

XSS Grenade is a modular XSS scanner with a desktop interface. The principal workflow is target and scan configuration → endpoint discovery → context-aware probing and specialized analyses → real-browser verification → ranked findings and exported reports. The graph preserves documented detection branches, including static and runtime DOM XSS, stored XSS, and modern vulnerability audits. The README identifies the main engine and several modules; other subsystem links reflect documented capabilities, since their implementation was not sampled.

Main entry points: [`xss_grenade.py`](https://github.com/tx-c0re/xss-grenade/blob/main/xss_grenade.py) (Scan engine), [`xss_grenade_gui.py`](https://github.com/tx-c0re/xss-grenade/blob/main/xss_grenade_gui.py) (Desktop GUI), [`_headless_crawler.py`](https://github.com/tx-c0re/xss-grenade/blob/main/_headless_crawler.py) (Endpoint crawler), [`_dom_v6.py`](https://github.com/tx-c0re/xss-grenade/blob/main/_dom_v6.py) (Runtime DOM XSS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_gui["Desktop GUI<br/>[xss_grenade_gui.py]"]
end

subgraph group_scan["Scan workflow"]
  node_engine["Scan engine<br/>[xss_grenade.py]"]
  node_auth["Authentication<br/>[_auth.py]"]
  node_crawler["Endpoint crawler"]
end

subgraph group_analysis["Detection analysis"]
  node_context["Reflection context<br/>[context_engine.py]"]
  node_payloads["Payload synthesis<br/>[_breakout_synth.py]"]
  node_reflected["Reflected XSS<br/>[_html_analyzer.py]"]
  node_domruntime["Runtime DOM XSS<br/>[_dom_v6.py]"]
  node_domengine["DOM exploit engine"]
  node_staticjs["Static JS taint"]
  node_stored["Stored XSS"]
  node_proto["Prototype pollution"]
  node_mutation["Mutation XSS<br/>[_mutation_xss.py]"]
  node_clobber["DOM clobbering<br/>[_dom_clobbering.py]"]
  node_trusted["Trusted Types audit"]
  node_cve["Library CVE audit"]
end

subgraph group_results["Verification and results"]
  node_verifier["Browser verifier"]
  node_scorer["Finding ranking<br/>[_finding_scorer.py]"]
  node_store[("Finding store<br/>[_finding_store.py]")]
  node_reports["Report exporters<br/>[_html_report.py]"]
end

node_user(("Security tester"))
node_target["Target application"]

node_user -->|"configures scan"| node_gui
node_gui -->|"starts scan"| node_engine
node_engine -->|"uses cookies"| node_auth
node_engine -->|"discovers endpoints"| node_crawler
node_crawler -->|"crawls pages"| node_target
node_engine -->|"sends probes"| node_target
node_engine -->|"classifies reflections"| node_context
node_engine -->|"synthesizes payloads"| node_payloads
node_engine -->|"checks reflections"| node_reflected
node_engine -->|"checks runtime DOM"| node_domruntime
node_domruntime -->|"tests source-sink paths"| node_domengine
node_engine -->|"analyzes scripts"| node_staticjs
node_engine -->|"checks round trips"| node_stored
node_engine -->|"audits gadget chains"| node_proto
node_engine -->|"checks mutation XSS"| node_mutation
node_engine -->|"checks clobbering"| node_clobber
node_engine -->|"audits policy"| node_trusted
node_engine -->|"checks library versions"| node_cve
node_engine -->|"verifies candidates"| node_verifier
node_verifier -->|"loads test pages"| node_target
node_engine -->|"ranks findings"| node_scorer
node_engine -->|"records findings"| node_store
node_engine -->|"exports reports"| node_reports
node_reports -->|"delivers results"| node_user

click node_gui "https://github.com/tx-c0re/xss-grenade/blob/main/xss_grenade_gui.py"
click node_engine "https://github.com/tx-c0re/xss-grenade/blob/main/xss_grenade.py"
click node_auth "https://github.com/tx-c0re/xss-grenade/blob/main/_auth.py"
click node_crawler "https://github.com/tx-c0re/xss-grenade/blob/main/_headless_crawler.py"
click node_context "https://github.com/tx-c0re/xss-grenade/blob/main/context_engine.py"
click node_payloads "https://github.com/tx-c0re/xss-grenade/blob/main/_breakout_synth.py"
click node_reflected "https://github.com/tx-c0re/xss-grenade/blob/main/_html_analyzer.py"
click node_domruntime "https://github.com/tx-c0re/xss-grenade/blob/main/_dom_v6.py"
click node_domengine "https://github.com/tx-c0re/xss-grenade/blob/main/_dom_exploit_engine.py"
click node_staticjs "https://github.com/tx-c0re/xss-grenade/blob/main/_static_js_analyzer.py"
click node_stored "https://github.com/tx-c0re/xss-grenade/blob/main/_stored_xss_tracker.py"
click node_proto "https://github.com/tx-c0re/xss-grenade/blob/main/_proto_pollution_analyzer.py"
click node_mutation "https://github.com/tx-c0re/xss-grenade/blob/main/_mutation_xss.py"
click node_clobber "https://github.com/tx-c0re/xss-grenade/blob/main/_dom_clobbering.py"
click node_trusted "https://github.com/tx-c0re/xss-grenade/blob/main/_trusted_types_analyzer.py"
click node_cve "https://github.com/tx-c0re/xss-grenade/blob/main/_library_cve_feed.py"
click node_verifier "https://github.com/tx-c0re/xss-grenade/blob/main/_headless_verifier.py"
click node_scorer "https://github.com/tx-c0re/xss-grenade/blob/main/_finding_scorer.py"
click node_store "https://github.com/tx-c0re/xss-grenade/blob/main/_finding_store.py"
click node_reports "https://github.com/tx-c0re/xss-grenade/blob/main/_html_report.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_gui toneBlue
class node_engine,node_auth,node_crawler toneAmber
class node_context,node_payloads,node_reflected,node_domruntime,node_domengine,node_staticjs,node_stored,node_proto,node_mutation,node_clobber,node_trusted,node_cve toneMint
class node_verifier,node_scorer,node_store,node_reports toneRose
class node_user,node_target toneIndigo
```

## Components

### User interface

- [Desktop GUI](https://github.com/tx-c0re/xss-grenade/blob/main/xss_grenade_gui.py): `xss_grenade_gui.py`

### Scan workflow

- [Scan engine](https://github.com/tx-c0re/xss-grenade/blob/main/xss_grenade.py): `xss_grenade.py`
- [Authentication](https://github.com/tx-c0re/xss-grenade/blob/main/_auth.py): `_auth.py`
- [Endpoint crawler](https://github.com/tx-c0re/xss-grenade/blob/main/_headless_crawler.py): `_headless_crawler.py`

### Detection analysis

- [Reflection context](https://github.com/tx-c0re/xss-grenade/blob/main/context_engine.py): `context_engine.py`
- [Payload synthesis](https://github.com/tx-c0re/xss-grenade/blob/main/_breakout_synth.py): `_breakout_synth.py`
- [Reflected XSS](https://github.com/tx-c0re/xss-grenade/blob/main/_html_analyzer.py): `_html_analyzer.py`
- [Runtime DOM XSS](https://github.com/tx-c0re/xss-grenade/blob/main/_dom_v6.py): `_dom_v6.py`
- [DOM exploit engine](https://github.com/tx-c0re/xss-grenade/blob/main/_dom_exploit_engine.py): `_dom_exploit_engine.py`
- [Static JS taint](https://github.com/tx-c0re/xss-grenade/blob/main/_static_js_analyzer.py): `_static_js_analyzer.py`
- [Stored XSS](https://github.com/tx-c0re/xss-grenade/blob/main/_stored_xss_tracker.py): `_stored_xss_tracker.py`
- [Prototype pollution](https://github.com/tx-c0re/xss-grenade/blob/main/_proto_pollution_analyzer.py): `_proto_pollution_analyzer.py`
- [Mutation XSS](https://github.com/tx-c0re/xss-grenade/blob/main/_mutation_xss.py): `_mutation_xss.py`
- [DOM clobbering](https://github.com/tx-c0re/xss-grenade/blob/main/_dom_clobbering.py): `_dom_clobbering.py`
- [Trusted Types audit](https://github.com/tx-c0re/xss-grenade/blob/main/_trusted_types_analyzer.py): `_trusted_types_analyzer.py`
- [Library CVE audit](https://github.com/tx-c0re/xss-grenade/blob/main/_library_cve_feed.py): `_library_cve_feed.py`

### Verification and results

- [Browser verifier](https://github.com/tx-c0re/xss-grenade/blob/main/_headless_verifier.py): `_headless_verifier.py`
- [Finding ranking](https://github.com/tx-c0re/xss-grenade/blob/main/_finding_scorer.py): `_finding_scorer.py`
- [Finding store](https://github.com/tx-c0re/xss-grenade/blob/main/_finding_store.py): `_finding_store.py`
- [Report exporters](https://github.com/tx-c0re/xss-grenade/blob/main/_html_report.py): `_html_report.py`

### Other components

- **Security tester**
- **Target application**

## Connections

- Security tester → Desktop GUI: configures scan
- Desktop GUI → Scan engine: starts scan
- Scan engine → Authentication: uses cookies
- Scan engine → Endpoint crawler: discovers endpoints
- Endpoint crawler → Target application: crawls pages
- Scan engine → Target application: sends probes
- Scan engine → Reflection context: classifies reflections
- Scan engine → Payload synthesis: synthesizes payloads
- Scan engine → Reflected XSS: checks reflections
- Scan engine → Runtime DOM XSS: checks runtime DOM
- Runtime DOM XSS → DOM exploit engine: tests source-sink paths
- Scan engine → Static JS taint: analyzes scripts
- Scan engine → Stored XSS: checks round trips
- Scan engine → Prototype pollution: audits gadget chains
- Scan engine → Mutation XSS: checks mutation XSS
- Scan engine → DOM clobbering: checks clobbering
- Scan engine → Trusted Types audit: audits policy
- Scan engine → Library CVE audit: checks library versions
- Scan engine → Browser verifier: verifies candidates
- Browser verifier → Target application: loads test pages
- Scan engine → Finding ranking: ranks findings
- Scan engine → Finding store: records findings
- Scan engine → Report exporters: exports reports
- Report exporters → Security tester: delivers results