Metadata-Version: 2.4
Name: sm0g-xss
Version: 0.1.5
Summary: SM0GXSS — XSS scanner for authorized security testing
License: AGPL-3.0-or-later
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: sm0g-engine>=0.1.5
Provides-Extra: browser
Requires-Dist: selenium; extra == 'browser'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: requests-mock; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# SM0GXSS

> **Context-aware XSS scanner** — reflected, DOM, stored, and blind XSS with headless-browser verification and WAF evasion.

[![Python](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg)](https://www.python.org/)
[![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)

```text
+----------------------------------------------------------------+
|                                                                |
|   _____ __  __  ___   _______   __ _____ _____                 |
|  / ____|  \/  |/ _ \ / ____\ \ / // ____/ ____|                |
| | (___ | \  / | | | | |  __ \ V /| (___| (___                  |
|  \___ \| |\/| | | | | | |_ | > <  \___ \\___ \                 |
|  ____) | |  | | |_| | |__| |/ . \ ____) |___) |                |
| |_____/|_|  |_|\___/ \_____/_/ \_\_____/_____/                 |
+================================================================+
```

---

## Highlights

- 🎯 **Many techniques** — reflected, DOM, stored, blind, header-injected, path-based, CRLF, open-redirect, GraphQL, and WebSocket XSS.
- 🧠 **Context-aware payloads** — detects the injection context (HTML body / attribute / JS / URL) and tailors the payload set per zone.
- 🛡️ **WAF fingerprinting + evasion** — identifies the wall and adapts payload encodings to get past it.
- 🌐 **Headless-browser verification** — confirms DOM/stored XSS by actually loading the page and watching for `alert()` (optional, via `[browser]`).
- 🕸️ **Surface discovery** — built-in crawler, form discovery, and OpenAPI ingestion.
- 📄 **Reports** — terminal summary plus JSON, SARIF (CI / code-scanning), and HTML output.

## Install

```bash
pip install sm0g-xss                 # core scanner
pip install "sm0g-xss[browser]"      # + headless-browser verification (selenium)
```

This pulls the engine dependency (`sm0g_engine`) automatically.

<details>
<summary>From source (development)</summary>

```bash
git clone <repo> && cd SM0GXSS
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"     # editable install + test/lint tooling
pytest -q                   # run the suite
```
</details>

## Quick start

```bash
# scan a single URL
sm0gxss "https://target.tld/page?q=test"

# crawl first, then scan reflected + DOM
sm0gxss "https://target.tld/" --crawl --crawl-depth 2 --technique RD

# DOM XSS with headless-browser confirmation (needs the browser extra)
sm0gxss "https://target.tld/#q=test" --technique D --browser --poc
```

## Techniques

Pass any combination to `--technique` (default: all):

| Flag | Technique        |
|:----:|------------------|
| `R`  | Reflected XSS    |
| `D`  | DOM-based XSS    |
| `B`  | Blind XSS (needs `--blind-host`) |
| `S`  | Stored XSS (needs `--stored-url`) |
| `H`  | Header-injected XSS |
| `P`  | Path-based XSS   |
| `C`  | CRLF injection   |
| `W`  | WebSocket XSS (with `--websocket`) |
| `G`  | GraphQL XSS (with `--graphql`) |
| `Q`  | Open redirect    |

```bash
sm0gxss "https://target.tld/?q=1" --technique RD --risk 2 --level 2
```

## Usage

```text
sm0gxss <url> [options]
```

| Option | Description | Default |
|--------|-------------|:-------:|
| `--technique RDBSHPCWGQ` | Techniques to run (see table above) | all |
| `--risk 1-3` | Payload aggressiveness | `1` |
| `--level 1-3` | Injection-point depth | `1` |
| `--crawl` / `--crawl-depth N` | Crawl the site first / crawler depth | off / `3` |
| `--browser` | Headless-browser verification (needs `[browser]`) | off |
| `--blind-host HOST` | Callback host for blind XSS | — |
| `--stored-url URL` | Where to read back stored XSS | — |
| `--probe-headers` | Inject into HTTP request headers | off |
| `--graphql` / `--websocket` | Enable GraphQL / WebSocket probing | off |
| `--openapi PATH/URL` | Seed surfaces from an OpenAPI spec | — |
| `--evasion MODE` | WAF-evasion transform(s) | — |
| `--shuffle` | Shuffle payload order | off |
| `--poc` | Emit ready-to-click PoC links | off |
| `--login-url / --login-user / --login-pass` | Authenticate before scanning | — |
| `-H "Name: Value"` | Add a header (repeatable) | — |
| `--cookies "k=v; ..."` | Cookie string | — |
| `--proxy URL` | Route through an HTTP proxy | — |
| `--random-agent` | Rotate the User-Agent | off |
| `--threads N` | Concurrency | `5` |
| `--timeout N` / `--delay S` | Request timeout / per-request delay | `15` / `0` |
| `--verify-ssl` | Verify TLS certificates | off |
| `-d, --data BODY` | POST body | — |
| `--output-json / --output-sarif / --output-html PATH` | Write reports | — |
| `-v, --verbose` | Verbose output | off |

## Output & reports

- **Terminal** — a summary table of every finding (active + passive).
- **`--output-json` / `--output-sarif` / `--output-html`** — machine-readable / CI / shareable reports. SARIF plugs straight into code-scanning pipelines.

## Ethical use & authorization

SM0GXSS is built for **authorized security testing only** — penetration tests, bug-bounty
programs **within their stated scope**, CTFs, security research, and systems you own or
operate (lab/staging).

- **Get explicit, written permission** before scanning any system you do not own. Running an
  active scanner against third-party systems without authorization is illegal in most
  jurisdictions and can cause disruption.
- **Stay in scope.** Respect bug-bounty rules, rate limits, and out-of-scope lists. Use
  `--delay`/`--threads` to avoid overloading a target.
- **Blind/OOB and headless modes reach external infrastructure** (your callback host, a real
  browser loading the page) — only point them at assets you control or are authorized to test.
- **Handle findings responsibly** — disclose privately to the asset owner; never exploit,
  pivot, or exfiltrate beyond what the engagement authorizes.

You are solely responsible for how you use this tool. The authors assume no liability for
misuse or damage.

## License

[AGPL-3.0-or-later](LICENSE) — Copyright (c) 2026 SM0G-SEC by roc1t1z3not.
