xssmap 2.8.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
xssmap/cli.py ADDED
@@ -0,0 +1,1375 @@
1
+ """xssmap command line interface."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import datetime as dt
6
+ import os
7
+ import random
8
+ import re
9
+ import shlex
10
+ import sys
11
+ import time
12
+ import urllib.parse
13
+
14
+ from . import fuzz as fuzzmod
15
+ from . import jslib as jslibmod
16
+ from . import params as paramdisc
17
+ from . import report as rp
18
+ from . import sarif
19
+ from . import state as stateio
20
+ from . import subdomains as subs
21
+ from . import waf as wafmod
22
+ from .browser import BrowserVerifier
23
+ from .callback import CallbackListener
24
+ from .crawler import Crawler, Scope, normalize_url
25
+ from .domscan import DomScanner
26
+ from .exploit import ExploitProver
27
+ from .htmlparse import Form, parse_qs_ordered
28
+ from .net import HTTP, Throttle
29
+ from .payloads import build_payload_set
30
+ from .report import VERSION, Console
31
+ from .scanner import (
32
+ CookiePoint,
33
+ HeaderPoint,
34
+ Scanner,
35
+ points_from_form,
36
+ points_from_json,
37
+ points_from_url,
38
+ )
39
+ from .session import CookieJar, Session, is_login_form
40
+ from .stored import StoredScanner
41
+
42
+ EPILOG = """examples:
43
+ xssmap -u "https://target.tld/search?q=test"
44
+ xssmap -u https://target.tld --crawl --depth 3 --max-pages 200
45
+ xssmap --domain example.com --autonomous
46
+ xssmap --domain example.com --subdomains --max-hosts 30 --depth 3
47
+ xssmap -u https://target.tld/page --data "name=x&comment=y" --method POST
48
+ xssmap -u https://target.tld/api/login --json-body '{"user":"a","pass":"b"}'
49
+ xssmap -u https://target.tld --cookie "sid=abc; theme=dark" --headers-points
50
+ xssmap -u https://target.tld --level 3 --risk 3 --browser --html report.html
51
+ xssmap -u https://target.tld/search?q=1 --browser --verify --callback 9000
52
+ xssmap -u https://target.tld -p q --param "INJECT_HERE" --proxy http://127.0.0.1:8080
53
+
54
+ testing notes:
55
+ --level 1 classic HTML/attribute contexts
56
+ --level 2 adds JS string/code, comments, RCDATA, forms (default)
57
+ --level 3 adds polyglots, header and cookie points, hidden fields
58
+ --risk 1 non-interactive payloads only
59
+ --risk 2 adds autofocus/onfocus handlers (default)
60
+ --risk 3 adds interaction-required payloads and variants
61
+
62
+ POST forms are only submitted with --forms (they can create records).
63
+ """
64
+
65
+
66
+ def build_parser() -> argparse.ArgumentParser:
67
+ p = argparse.ArgumentParser(
68
+ prog="xssmap",
69
+ description="xssmap - context-aware cross-site scripting scanner with a crawler",
70
+ epilog=EPILOG,
71
+ formatter_class=argparse.RawDescriptionHelpFormatter,
72
+ )
73
+ tgt = p.add_argument_group("target")
74
+ tgt.add_argument("-u", "--url", help="target URL")
75
+ tgt.add_argument("--domain", metavar="DOMAIN",
76
+ help="scan a whole domain: picks https (falling back to http) and "
77
+ "crawls every host it finds; implies --subdomains")
78
+ tgt.add_argument("-m", "--urls", metavar="FILE",
79
+ help="file with one target URL per line")
80
+ tgt.add_argument("--method", default=None, help="HTTP method for the supplied body (default POST)")
81
+ tgt.add_argument("--data", "--body", dest="data", help="request body, e.g. 'a=1&b=2'")
82
+ tgt.add_argument("--json-body", dest="json_body", help="JSON request body")
83
+ tgt.add_argument("-H", "--header", action="append", default=[], metavar="'K: V'",
84
+ help="extra header (repeatable)")
85
+ tgt.add_argument("--cookie", help="Cookie header value, e.g. 'sid=abc; theme=dark'")
86
+ tgt.add_argument("-A", "--user-agent", help="User-Agent string")
87
+ tgt.add_argument("--random-agent", action="store_true", help="pick a random browser User-Agent")
88
+ tgt.add_argument("-p", "--param", help="comma separated list of parameters to test")
89
+ tgt.add_argument("--param-value", help="value to use for the baseline request")
90
+
91
+ auto = p.add_argument_group("autonomy")
92
+ auto.add_argument("--autonomous", action="store_true",
93
+ help="one-flag sweep: subdomain discovery, deep crawl, forms, stored, "
94
+ "DOM, browser confirmation, headers and screenshots "
95
+ "(explicit flags always win)")
96
+ auto.add_argument("--max-minutes", type=float, default=0.0, metavar="N",
97
+ help="wall-clock budget in minutes, enforced between phases and "
98
+ "inside the scan/stored loops (0 = unlimited; --autonomous 30)")
99
+
100
+ crawl = p.add_argument_group("crawling")
101
+ crawl.add_argument("--crawl", dest="crawl", action="store_true", default=None,
102
+ help="force crawling (default when -u is given)")
103
+ crawl.add_argument("--no-crawl", dest="no_crawl", action="store_true",
104
+ help="do not crawl, only test the supplied URL")
105
+ crawl.add_argument("--crawl-depth", "--depth", dest="crawl_depth", type=int, default=2,
106
+ metavar="N", help="link depth (default 2)")
107
+ crawl.add_argument("--max-pages", type=int, default=150, help="page budget (default 150)")
108
+ crawl.add_argument("--scope", choices=["host", "subdomain", "any"], default="host",
109
+ help="crawl scope (default host); --subdomains widens it to subdomain")
110
+ crawl.add_argument("--subdomains", action="store_true",
111
+ help="discover subdomains (certificate transparency + DNS) and crawl "
112
+ "them too")
113
+ crawl.add_argument("--no-subdomain-brute", dest="subdomain_brute", action="store_false",
114
+ default=True,
115
+ help="passive discovery only: skip the DNS wordlist sweep")
116
+ crawl.add_argument("--subdomain-wordlist", metavar="FILE",
117
+ help="extra DNS names to try, one label per line (adds to the "
118
+ "built-in list)")
119
+ crawl.add_argument("--subdomain-base", choices=["auto", "host", "registrable"],
120
+ default="auto",
121
+ help="how the enumeration base is derived (default auto): auto strips "
122
+ "www. and widens registrable names under multi-label suffixes "
123
+ "(shop.example.co.uk -> example.co.uk); host uses the target "
124
+ "host verbatim; registrable always widens (PSL + 1 label)")
125
+ crawl.add_argument("--public-suffix-list", metavar="FILE",
126
+ help="Public Suffix List file used by --subdomain-base (supports "
127
+ "*. and ! rules); replaces the small built-in table")
128
+ crawl.add_argument("--max-hosts", type=int, default=25, metavar="N",
129
+ help="cap on discovered hosts crawled per target (default 25)")
130
+ crawl.add_argument("--exclude", action="append", default=[], metavar="REGEX",
131
+ help="skip URLs matching this regex (repeatable)")
132
+ crawl.add_argument("--include", action="append", default=[], metavar="REGEX",
133
+ help="only crawl URLs matching this regex (repeatable)")
134
+ crawl.add_argument("--no-js", action="store_true", help="do not mine JS for endpoints")
135
+ crawl.add_argument("--robots", action="store_true", help="honour robots.txt disallow rules")
136
+ crawl.add_argument("--common-paths", action="store_true",
137
+ help="probe a small list of conventional parameterised paths")
138
+
139
+ scan = p.add_argument_group("scanning")
140
+ scan.add_argument("--level", type=int, choices=[1, 2, 3], default=2,
141
+ help="payload level 1-3 (default 2)")
142
+ scan.add_argument("--risk", type=int, choices=[1, 2, 3], default=2,
143
+ help="payload risk 1-3 (default 2)")
144
+ scan.add_argument("--forms", action="store_true",
145
+ help="also submit POST forms (can create records)")
146
+ scan.add_argument("--no-forms", dest="no_forms", action="store_true",
147
+ help="never submit POST forms (overrides --autonomous)")
148
+ scan.add_argument("--headers-points", action="store_true",
149
+ help="test User-Agent/Referer/X-Forwarded-Host reflection")
150
+ scan.add_argument("--threads", type=int, default=5, help="worker threads (default 5)")
151
+ scan.add_argument("--delay", type=float, default=0.0, help="minimum delay between requests")
152
+ scan.add_argument("--timeout", type=float, default=15.0, help="per-request timeout")
153
+ scan.add_argument("--retries", type=int, default=2, help="retries on transport errors")
154
+ scan.add_argument("--proxy", help="http://host:port or socks5://host:port")
155
+ scan.add_argument("--insecure", action="store_true", help="do not verify TLS certificates")
156
+ scan.add_argument("--max-points", type=int, default=1500, help="cap on injection points")
157
+ scan.add_argument("--state", metavar="FILE", default=None,
158
+ help="resume file: skip injection points already completed and "
159
+ "merge the findings recorded there (written atomically)")
160
+ scan.add_argument("--no-profile", dest="no_profile", action="store_true",
161
+ help="skip filter-fingerprinting probes (fewer requests, no mutation bypass)")
162
+ scan.add_argument("--mutations", type=int, default=3, metavar="N",
163
+ help="filter-bypass mutations tried per payload (default 3, 0 disables)")
164
+
165
+ ev = p.add_argument_group("evasion and discovery")
166
+ ev.add_argument("--waf", dest="waf", action="store_true", default=True,
167
+ help="fingerprint the WAF in front of the target and route payloads "
168
+ "around it (default on; --no-waf disables)")
169
+ ev.add_argument("--no-waf", dest="no_waf", action="store_true",
170
+ help="skip WAF fingerprinting and evasion")
171
+ ev.add_argument("--evade", dest="evade", action="store_true", default=True,
172
+ help="use vendor-specific obfuscation when a blocking WAF is detected "
173
+ "(default on)")
174
+ ev.add_argument("--no-evade", dest="no_evade", action="store_true",
175
+ help="detect the WAF but keep payloads unchanged")
176
+ ev.add_argument("--brute", action="store_true",
177
+ help="character-level filter brute force: when every crafted payload "
178
+ "fails on a reflecting point, map the characters that survive "
179
+ "and synthesise a payload from them (bounded by --brute-budget)")
180
+ ev.add_argument("--brute-budget", type=int, default=40, metavar="N",
181
+ help="request budget for --brute across the whole scan (default 40)")
182
+ ev.add_argument("--evasion-budget", type=int, default=240, metavar="N",
183
+ help="cap on WAF-evasion variants added across the whole scan "
184
+ "(default 240; every point gets its own share, so one hostile "
185
+ "point cannot starve the rest)")
186
+ ev.add_argument("--osv", action="store_true",
187
+ help="ask osv.dev for advisories on every identified library version "
188
+ "(off by default: it is an outbound call to a third party, "
189
+ "capped at 12 lookups)")
190
+ ev.add_argument("--discover-params", action="store_true",
191
+ help="probe undocumented parameter names on each target and test the "
192
+ "ones that change the response")
193
+ ev.add_argument("--fuzz", action="store_true",
194
+ help="fuzz parameters for reflection/filter behaviour and report "
195
+ "raw, encoded, stripped and template-evaluated results")
196
+ ev.add_argument("--fuzz-budget", type=int, default=200, metavar="N",
197
+ help="request budget for --fuzz (default 200)")
198
+ ev.add_argument("--js-libs", dest="js_libs", action="store_true", default=True,
199
+ help="fingerprint outdated JavaScript libraries found while crawling "
200
+ "and list the CVEs they are known for (default on)")
201
+ ev.add_argument("--no-js-libs", dest="no_js_libs", action="store_true",
202
+ help="skip JavaScript library fingerprinting")
203
+
204
+ br = p.add_argument_group("verification")
205
+ br.add_argument("--browser", dest="browser", action="store_true", default=None,
206
+ help="confirm execution in a headless Chromium (default: auto)")
207
+ br.add_argument("--no-browser", dest="no_browser", action="store_true",
208
+ help="disable headless browser confirmation")
209
+ br.add_argument("--dom", dest="dom", action="store_true", default=None,
210
+ help="force DOM XSS analysis (requires a browser)")
211
+ br.add_argument("--no-dom", dest="no_dom", action="store_true",
212
+ help="skip DOM XSS analysis")
213
+ br.add_argument("--dom-flows", type=int, default=15, metavar="N",
214
+ help="cap on DOM flows proven in the browser (default 15)")
215
+ br.add_argument("--stored", dest="stored", action="store_true", default=False,
216
+ help="plant payloads in forms and prove stored XSS (writes data)")
217
+ br.add_argument("--no-stored", dest="no_stored", action="store_true",
218
+ help="never plant stored payloads (overrides --autonomous)")
219
+ br.add_argument("--stored-max-forms", type=int, default=20, metavar="N",
220
+ help="cap on forms used for stored-XSS planting (default 20)")
221
+ br.add_argument("--stored-json", action="append", default=[], metavar="URL",
222
+ help="JSON write endpoint to plant stored payloads in (repeatable)")
223
+ br.add_argument("--stored-json-field", default="comment", metavar="NAME",
224
+ help="JSON property that carries the payload (default comment)")
225
+ br.add_argument("--viewer-url", action="append", default=[], metavar="URL",
226
+ help="page that renders stored content, e.g. a moderation queue or "
227
+ "admin inbox (repeatable; needed to observe blind stored XSS)")
228
+ br.add_argument("--callback", nargs="?", const=0, type=int, default=None,
229
+ metavar="PORT",
230
+ help="start a loopback callback listener for blind XSS proof")
231
+ br.add_argument("--callback-bind", default="127.0.0.1", metavar="ADDR",
232
+ help="address the callback listener binds to (default 127.0.0.1; use "
233
+ "0.0.0.0 to accept beacons from another host on the network)")
234
+ br.add_argument("--callback-url", default="", metavar="URL",
235
+ help="public URL to embed in beacons when the listener is reached "
236
+ "through a tunnel or port-forward, e.g. https://abc.ngrok.app")
237
+ br.add_argument("--capture-cookies", dest="capture_cookies", action="store_true",
238
+ default=False,
239
+ help="let the callback beacon send document.cookie (off by default: "
240
+ "an OOB hit already proves execution)")
241
+ br.add_argument("--headless", choices=["new", "old"], default="new",
242
+ help="headless mode for Chrome (default new)")
243
+ br.add_argument("--verify", dest="verify", action="store_true", default=False,
244
+ help="exploit stage: replay each finding with a weaponised payload and "
245
+ "measure what the script can reach (cookies, anti-CSRF token, "
246
+ "same-origin reads, callback) instead of only proving execution")
247
+ br.add_argument("--no-verify", dest="no_verify", action="store_true",
248
+ help="skip the exploit stage (overrides --autonomous)")
249
+ br.add_argument("--verify-max", type=int, default=10, metavar="N",
250
+ help="cap on findings replayed by --verify (default 10)")
251
+
252
+ auth = p.add_argument_group("authentication")
253
+ auth.add_argument("--login-url", metavar="URL",
254
+ help="sign in through this page's form before scanning")
255
+ auth.add_argument("--login-user", metavar="USER", help="username for --login-url")
256
+ auth.add_argument("--login-pass", metavar="PASS", help="password for --login-url")
257
+ auth.add_argument("--login-user-field", default="", metavar="NAME",
258
+ help="username field name (auto-detected by default)")
259
+ auth.add_argument("--login-pass-field", default="", metavar="NAME",
260
+ help="password field name (auto-detected by default)")
261
+ auth.add_argument("--login-data", action="append", default=[], metavar="K=V",
262
+ help="extra login form field, e.g. csrf_token=... or remember=1")
263
+ auth.add_argument("--login-check", metavar="URL",
264
+ help="URL that must stop redirecting to login once authenticated")
265
+ auth.add_argument("--cookie-jar", metavar="FILE",
266
+ help="preload cookies from a Netscape cookies.txt file")
267
+ auth.add_argument("--save-cookies", metavar="FILE",
268
+ help="write the final cookie jar (sensitive: live session secrets)")
269
+ auth.add_argument("--no-csrf-refresh", dest="csrf_refresh", action="store_false",
270
+ default=True,
271
+ help="do not re-read anti-CSRF tokens before each submission")
272
+
273
+ out = p.add_argument_group("output")
274
+ out.add_argument("-o", "--output", help="write JSON results to this file")
275
+ out.add_argument("--html", help="write an HTML report to this file")
276
+ out.add_argument("--markdown", "--md", dest="markdown", help="write a Markdown report")
277
+ out.add_argument("--screenshots", action="store_true",
278
+ help="save a PNG screenshot for every browser-confirmed finding")
279
+ out.add_argument("--output-dir", default="xssmap-out",
280
+ help="directory for default report files (default xssmap-out)")
281
+ out.add_argument("--sarif", help="write a SARIF 2.1.0 report (CI integrations)")
282
+ out.add_argument("--evidence", dest="evidence_dir", metavar="DIR",
283
+ help="write one evidence file per finding into DIR")
284
+ out.add_argument("--quiet", "-q", action="store_true", help="only findings")
285
+ out.add_argument("--verbose", "-v", action="store_true", help="show every request")
286
+ out.add_argument("--no-color", action="store_true", help="disable ANSI colours")
287
+ out.add_argument("--fail-on-findings", action="store_true",
288
+ help="exit with status 1 when something is found (CI mode)")
289
+ out.add_argument("--list-payloads", action="store_true", help="print the payload catalogue")
290
+ out.add_argument("--version", action="version", version=f"xssmap {VERSION}")
291
+ return p
292
+
293
+
294
+ # What --autonomous turns on. Values are only applied when the user did not
295
+ # pass the flag themselves, so "--autonomous --max-pages 50" still honours 50.
296
+ AUTONOMOUS_DEFAULTS: dict[str, object] = {
297
+ "crawl_depth": 3,
298
+ "max_pages": 400,
299
+ "max_points": 3000,
300
+ "max_minutes": 30.0,
301
+ "subdomains": True,
302
+ "common_paths": True,
303
+ "forms": True,
304
+ "stored": True,
305
+ "headers_points": True,
306
+ "dom": True,
307
+ "browser": True,
308
+ "verify": True,
309
+ "screenshots": True,
310
+ "waf": True,
311
+ "evade": True,
312
+ "brute": True,
313
+ "discover_params": True,
314
+ "js_libs": True,
315
+ }
316
+
317
+ # dest -> the flag that switches the same feature off. An explicit off switch
318
+ # must survive the preset.
319
+ _NEGATED = {
320
+ "browser": "no_browser",
321
+ "verify": "no_verify",
322
+ "dom": "no_dom",
323
+ "crawl": "no_crawl",
324
+ "forms": "no_forms",
325
+ "stored": "no_stored",
326
+ "waf": "no_waf",
327
+ "evade": "no_evade",
328
+ "js_libs": "no_js_libs",
329
+ }
330
+
331
+
332
+ def explicit_dests(parser: argparse.ArgumentParser, argv: list[str]) -> set[str]:
333
+ """Return the option dests the user actually typed.
334
+
335
+ argparse does not record whether a value came from the command line or a
336
+ default, so the preset reads the argument vector instead.
337
+ """
338
+ known: dict[str, str] = {}
339
+ for action in parser._actions:
340
+ for opt in action.option_strings:
341
+ known[opt] = action.dest
342
+ explicit: set[str] = set()
343
+ for token in argv:
344
+ if not token.startswith("-"):
345
+ continue
346
+ dest = known.get(token.split("=", 1)[0])
347
+ if dest:
348
+ explicit.add(dest)
349
+ return explicit
350
+
351
+
352
+ def option_flags(parser: argparse.ArgumentParser) -> dict[str, str]:
353
+ """Map option dests back to the flag a user would recognise."""
354
+ return {action.dest: action.option_strings[0]
355
+ for action in parser._actions if action.option_strings}
356
+
357
+
358
+ def apply_autonomous(args: argparse.Namespace, explicit: set[str]) -> list[str]:
359
+ """Apply the autonomous defaults, keeping every explicit choice."""
360
+ applied: list[str] = []
361
+ for dest, value in AUTONOMOUS_DEFAULTS.items():
362
+ if dest in explicit:
363
+ continue
364
+ off = _NEGATED.get(dest)
365
+ if off and off in explicit:
366
+ continue
367
+ if getattr(args, dest, None) == value:
368
+ continue
369
+ setattr(args, dest, value)
370
+ applied.append(dest)
371
+ return applied
372
+
373
+
374
+ def finalize_args(args: argparse.Namespace) -> None:
375
+ """Collapse paired flags into one truth for the rest of the program."""
376
+ if getattr(args, "no_forms", False):
377
+ args.forms = False
378
+ if getattr(args, "no_stored", False):
379
+ args.stored = False
380
+ if getattr(args, "no_verify", False):
381
+ args.verify = False
382
+ if getattr(args, "no_waf", False):
383
+ args.waf = False
384
+ if getattr(args, "no_evade", False):
385
+ args.evade = False
386
+ if getattr(args, "no_js_libs", False):
387
+ args.js_libs = False
388
+ if args.no_crawl:
389
+ args.crawl = False
390
+ elif args.crawl is None:
391
+ args.crawl = True
392
+
393
+
394
+ def read_wordlist(path: str) -> list[str]:
395
+ """Read extra DNS labels, one per line. Blank lines and # comments skipped."""
396
+ words: list[str] = []
397
+ with open(path, encoding="utf-8", errors="replace") as fh:
398
+ for line in fh:
399
+ word = line.strip().lower().strip(".")
400
+ if not word or word.startswith("#"):
401
+ continue
402
+ if not subs.LABEL_RE.match(word):
403
+ continue
404
+ if word not in words:
405
+ words.append(word)
406
+ return words
407
+
408
+
409
+ def probe_base(http: HTTP, host: str, port: int | None, headers,
410
+ log: Console, announce: bool = True) -> str | None:
411
+ """Find a working scheme for a bare host, https first."""
412
+ netloc = f"{host}:{port}" if port else host
413
+ for scheme in ("https", "http"):
414
+ url = f"{scheme}://{netloc}"
415
+ try:
416
+ resp = http.get(url + "/", headers=headers)
417
+ except Exception as exc:
418
+ (log.info if announce else log.debug)(f" {url}: {str(exc)[:80]}")
419
+ continue
420
+ (log.ok if announce else log.debug)(f" {url}: HTTP {resp.status}")
421
+ return url
422
+ return None
423
+
424
+
425
+ def domain_host(value: str) -> tuple[str, int | None]:
426
+ """Split --domain into (host, port), rejecting paths and queries."""
427
+ host = subs.normalize_domain(value)
428
+ parts = urllib.parse.urlsplit(value if "://" in value else "//" + value)
429
+ try:
430
+ port = parts.port
431
+ except ValueError as exc:
432
+ raise subs.DiscoveryError(f"invalid port in {value!r}") from exc
433
+ return host, port
434
+
435
+
436
+ def ct_fetcher(http: HTTP, headers):
437
+ """Wrap the client so certificate-source failures raise instead of returning ""."""
438
+ def fetch(url: str) -> str:
439
+ resp = http.get(url, headers=headers)
440
+ if resp.status >= 400:
441
+ host = urllib.parse.urlsplit(url).hostname or "certificate source"
442
+ raise RuntimeError(f"{host} returned HTTP {resp.status}")
443
+ return resp.text or ""
444
+ return fetch
445
+
446
+
447
+ UA_POOL = [
448
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) "
449
+ "Chrome/124.0.0.0 Safari/537.36",
450
+ "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) "
451
+ "Version/17.4 Safari/605.1.15",
452
+ "Mozilla/5.0 (X11; Linux x86_64; rv:125.0) Gecko/20100101 Firefox/125.0",
453
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:124.0) Gecko/20100101 Firefox/124.0",
454
+ ]
455
+
456
+
457
+ def parse_headers(raw_headers: list[str], cookie: str | None, ua: str | None,
458
+ random_agent: bool) -> list[tuple[str, str]]:
459
+ headers: list[tuple[str, str]] = []
460
+ for raw in raw_headers:
461
+ if ":" not in raw:
462
+ raise SystemExit(f"[-] bad header (expected 'Name: value'): {raw}")
463
+ name, value = raw.split(":", 1)
464
+ headers.append((name.strip(), value.strip()))
465
+ if cookie:
466
+ # --cookie seeds the cookie jar (host scoped, refreshed by Set-Cookie)
467
+ # instead of pinning one stale header onto every request.
468
+ headers = [(k, v) for k, v in headers if k.lower() != "cookie"]
469
+ if ua:
470
+ headers.append(("User-Agent", ua))
471
+ elif random_agent:
472
+ headers.append(("User-Agent", random.choice(UA_POOL)))
473
+ return headers
474
+
475
+
476
+ def load_targets(args) -> list[str]:
477
+ targets: list[str] = []
478
+ if args.url:
479
+ targets.append(args.url)
480
+ if args.urls:
481
+ with open(args.urls, encoding="utf-8", errors="replace") as fh:
482
+ for line in fh:
483
+ line = line.strip()
484
+ if line and not line.startswith("#"):
485
+ targets.append(line)
486
+ out = []
487
+ for t in targets:
488
+ if not re.match(r"^https?://", t, re.I):
489
+ t = "https://" + t
490
+ out.append(normalize_url(t) if "?" in t else t.rstrip("/"))
491
+ return out
492
+
493
+
494
+ def csrf_fetcher_factory(http: HTTP, headers, log):
495
+ def fetch(url: str) -> dict[str, str]:
496
+ resp = http.get(url, headers=headers)
497
+ if not resp.is_html:
498
+ return {}
499
+ from .htmlparse import parse_page
500
+ page = parse_page(resp.url, resp.text)
501
+ tokens = {}
502
+ for form in page.forms:
503
+ for name, value, typ in form.params:
504
+ if typ == "hidden" and re.search(r"(csrf|token|nonce|authenticity|_wpnonce)", name, re.I):
505
+ tokens[name] = value
506
+ if not tokens:
507
+ m = re.search(r"""(?i)name=["'](csrf[^"']*|_token|authenticity_token)["']\s+value=["']([^"']+)""",
508
+ resp.text)
509
+ if m:
510
+ tokens[m.group(1)] = m.group(2)
511
+ return tokens
512
+ return fetch
513
+
514
+
515
+ def print_payload_catalogue(log: Console):
516
+ payloads = build_payload_set()
517
+ log.banner(f"payload catalogue ({len(payloads)} payloads)")
518
+ by_ctx: dict[str, list] = {}
519
+ for p in payloads:
520
+ by_ctx.setdefault(p.context, []).append(p)
521
+ for ctx in sorted(by_ctx):
522
+ print(f"\n {ctx}")
523
+ for p in by_ctx[ctx]:
524
+ flags = []
525
+ if p.interaction:
526
+ flags.append("interaction")
527
+ if p.danger != "low":
528
+ flags.append(p.danger)
529
+ print(f" - {p.name:<22} {p.template}")
530
+ if flags:
531
+ print(f" {', '.join(flags)}")
532
+ print(f"\n contexts: {', '.join(sorted(by_ctx))}\n")
533
+
534
+
535
+ def main(argv=None) -> int:
536
+ parser = build_parser()
537
+ args = parser.parse_args(argv)
538
+ colour = not args.no_color and (sys.stdout.isatty() or os.name == "nt")
539
+ log = Console(quiet=args.quiet, color=colour, verbose=args.verbose)
540
+ explicit = explicit_dests(parser, list(sys.argv[1:] if argv is None else argv))
541
+
542
+ if args.list_payloads:
543
+ print_payload_catalogue(log)
544
+ return 0
545
+
546
+ if args.autonomous:
547
+ applied = apply_autonomous(args, explicit)
548
+ if applied:
549
+ log.action("autonomous: enabled " + ", ".join(
550
+ f"{dest}={AUTONOMOUS_DEFAULTS[dest]}" for dest in applied))
551
+ flags = option_flags(parser)
552
+ kept = (explicit & set(AUTONOMOUS_DEFAULTS)) | {
553
+ off for off in _NEGATED.values() if off in explicit}
554
+ if kept:
555
+ log.info("autonomous: kept your explicit " + ", ".join(
556
+ sorted(flags.get(dest, dest) for dest in kept)))
557
+ if not args.no_stored and not args.no_forms:
558
+ log.warn("autonomous submits forms and plants stored payloads (writes data); "
559
+ "pass --no-forms / --no-stored to keep the target read-only")
560
+ finalize_args(args)
561
+
562
+ if args.domain and (args.url or args.urls):
563
+ log.error("use either --domain or -u/-m, not both")
564
+ return 2
565
+
566
+ headers = parse_headers(args.header, args.cookie, args.user_agent, args.random_agent)
567
+ throttle = Throttle(delay=args.delay, max_workers=args.threads)
568
+ http = HTTP(
569
+ timeout=args.timeout, retries=args.retries, proxy=args.proxy,
570
+ verify=not args.insecure, user_agent=args.user_agent or "xssmap/" + VERSION,
571
+ throttle=throttle, debug=args.verbose,
572
+ )
573
+ if args.user_agent or args.random_agent:
574
+ http.extra_headers = {}
575
+
576
+ if args.domain:
577
+ try:
578
+ host, port = domain_host(args.domain)
579
+ except (subs.DiscoveryError, ValueError) as exc:
580
+ log.error(f"--domain: {exc}")
581
+ return 2
582
+ base = probe_base(http, host, port, headers, log)
583
+ if not base:
584
+ log.error(f"--domain {args.domain}: no HTTP endpoint answered on {host}")
585
+ return 2
586
+ targets = [base]
587
+ if args.crawl:
588
+ args.subdomains = True
589
+ else:
590
+ log.warn("--domain without crawling only tests the root URL; drop --no-crawl "
591
+ "to sweep the domain")
592
+ else:
593
+ targets = load_targets(args)
594
+ if not targets:
595
+ log.error("no target: use -u URL, --domain DOMAIN or -m FILE")
596
+ return 2
597
+
598
+ extra_words: list[str] | None = None
599
+ if args.subdomain_wordlist:
600
+ try:
601
+ extra_words = read_wordlist(args.subdomain_wordlist)
602
+ except OSError as exc:
603
+ log.error(f"could not read --subdomain-wordlist: {exc}")
604
+ return 2
605
+ extra_words = list(dict.fromkeys(subs.WORDLIST + extra_words))
606
+ log.info(f"subdomain wordlist: {len(extra_words)} label(s) after merging "
607
+ f"the built-in list")
608
+
609
+ suffix_table = None
610
+ if args.public_suffix_list:
611
+ try:
612
+ suffix_table = subs.load_suffix_file(args.public_suffix_list)
613
+ except subs.DiscoveryError as exc:
614
+ log.error(str(exc))
615
+ return 2
616
+ log.info(f"public suffix list: {len(suffix_table)} rule(s) loaded")
617
+
618
+ if not args.quiet:
619
+ log.splash(VERSION, f"{len(targets)} target(s) | level {args.level} "
620
+ f"risk {args.risk}")
621
+ browser_enabled = (not args.no_browser) if args.browser is None else bool(args.browser)
622
+ if args.no_browser:
623
+ browser_enabled = False
624
+ browser = BrowserVerifier(enabled=browser_enabled, log=log, headless=args.headless,
625
+ proxy=args.proxy)
626
+
627
+ # ---- authenticated session -------------------------------------
628
+ jar = CookieJar()
629
+ for target in targets:
630
+ if args.cookie:
631
+ jar.add_raw(target, args.cookie)
632
+ http.jar = jar
633
+ login_summary = ""
634
+ if args.cookie_jar:
635
+ try:
636
+ seeded = jar.load_netscape(args.cookie_jar)
637
+ log.info(f"cookie jar: {seeded} cookie(s) loaded from {args.cookie_jar}")
638
+ except OSError as exc:
639
+ log.error(f"could not read --cookie-jar {args.cookie_jar}: {exc}")
640
+ return 2
641
+ session = None
642
+ if args.login_url:
643
+ if not (args.login_user and args.login_pass):
644
+ log.error("--login-url also needs --login-user and --login-pass")
645
+ return 2
646
+ extra = dict(item.split("=", 1) for item in args.login_data if "=" in item)
647
+ session = Session(http, log=log)
648
+ log.action(f"signing in at {args.login_url}")
649
+ result = session.login(args.login_url, args.login_user, args.login_pass,
650
+ user_field=args.login_user_field,
651
+ pass_field=args.login_pass_field, extra=extra)
652
+ login_summary = result.describe()
653
+ if result.ok:
654
+ log.ok(login_summary)
655
+ log.info(f"cookie jar: {jar.describe()}")
656
+ browser.set_cookies(jar.cdp_cookies())
657
+ if args.login_check:
658
+ try:
659
+ check = http.get(args.login_check, allow_redirects=True)
660
+ from .htmlparse import parse_page as _parse_page
661
+ forms_there = _parse_page(check.url, check.text or "").forms
662
+ still_login = any(is_login_form(f) for f in forms_there)
663
+ except Exception as exc:
664
+ log.warn(f"--login-check could not be fetched: {str(exc)[:120]}")
665
+ else:
666
+ if still_login:
667
+ log.warn(f"--login-check {check.url} still shows a login form; "
668
+ "the session may not be valid")
669
+ result.ok = False
670
+ result.confident = True
671
+ login_summary += "; login-check still shows the login form"
672
+ else:
673
+ log.ok(f"--login-check {check.url} is reachable while signed in")
674
+ else:
675
+ for note in result.notes:
676
+ log.debug(f" login: {note}")
677
+ log.error(login_summary)
678
+ if result.confident:
679
+ log.error("refusing to scan with an unauthenticated session "
680
+ "(drop --login-url to scan anonymously)")
681
+ return 2
682
+ log.warn("continuing although authentication could not be confirmed")
683
+
684
+ dom_enabled = bool(args.dom) or (not args.no_dom and not args.no_browser)
685
+ dom_enabled = dom_enabled and browser.available
686
+ screenshot_dir = os.path.join(args.output_dir, "evidence") if args.screenshots else None
687
+
688
+ callback = None
689
+ if args.callback is not None:
690
+ callback = CallbackListener(host=args.callback_bind, port=args.callback, log=log,
691
+ capture_cookies=args.capture_cookies,
692
+ public_url=args.callback_url)
693
+ try:
694
+ callback.start()
695
+ log.ok(f"callback listener: {callback.url} (blind XSS proof)")
696
+ except OSError as exc:
697
+ log.error(f"could not start the callback listener: {exc}")
698
+ callback = None
699
+
700
+ started = dt.datetime.now()
701
+ resume = stateio.load_state(args.state) if args.state else stateio.empty_state()
702
+ if resume.get("error"):
703
+ log.warn(f"ignoring --state: {resume['error']}")
704
+ done_keys = set(resume["done"])
705
+ all_findings = list(resume["findings"])
706
+ all_leads = list(resume["leads"])
707
+ if done_keys or all_findings or all_leads:
708
+ log.info(f"resume: {len(done_keys)} completed point(s), "
709
+ f"{len(all_findings)} confirmed and {len(all_leads)} lead finding(s) "
710
+ f"carried over from {args.state}")
711
+ crawl_stats = {}
712
+ points_total = 0
713
+ reflected_total = 0
714
+ mxss_total = 0
715
+ charset_total = 0
716
+ dom_total = 0
717
+ stored_total = 0
718
+ resumed_total = 0
719
+ tokens_total = 0
720
+ json_total = 0
721
+ waf_variants_total = 0
722
+ brute_probes_total = 0
723
+ brute_reports: list[dict] = []
724
+ discoveries: list[dict] = []
725
+ libs_found: list = []
726
+ waf_results: dict[str, wafmod.WAFDetection] = {}
727
+ evasion_notes: dict[str, str] = {}
728
+ fuzz_summary = None
729
+ fuzz_result = None
730
+ interrupted = False
731
+ page_urls: list[str] = []
732
+
733
+ deadline = time.monotonic() + args.max_minutes * 60 if args.max_minutes else None
734
+ # A pending request must not outlive the budget it was started under.
735
+ http.set_deadline(deadline)
736
+ budget_hit = False
737
+
738
+ for target in targets:
739
+ if deadline is not None and time.monotonic() > deadline:
740
+ budget_hit = True
741
+ log.warn(f"time budget of {args.max_minutes:g} min reached; "
742
+ "skipping the remaining target(s)")
743
+ break
744
+ log.banner(f"target: {target}")
745
+
746
+ do_crawl = bool(args.crawl)
747
+ seeds = [target]
748
+ sub_info = None
749
+ scope_mode = args.scope
750
+ if args.subdomains and do_crawl:
751
+ base_host = subs.subdomain_base(target, args.subdomain_base, suffix_table)
752
+ sources = "ct (crt.sh, certspotter, hackertarget)"
753
+ log.action(f"discovering subdomains of {base_host} "
754
+ f"({sources + ' + dns' if args.subdomain_brute else 'passive ' + sources})")
755
+ sub_info = subs.discover(
756
+ base_host, fetch=ct_fetcher(http, headers), log=log,
757
+ brute=args.subdomain_brute, wordlist=extra_words,
758
+ max_hosts=args.max_hosts,
759
+ concurrency=min(max(args.threads, 2), 12),
760
+ )
761
+ if sub_info.providers:
762
+ log.debug(" ct source yields: " + ", ".join(
763
+ f"{name}={count}" for name, count in sub_info.providers.items()))
764
+ for host in sub_info.hosts:
765
+ if host == base_host:
766
+ continue
767
+ url = probe_base(http, host, None, headers, log, announce=False)
768
+ if url:
769
+ seeds.append(url)
770
+ log.info(f" + {url}")
771
+ else:
772
+ log.debug(f" - {host}: no HTTP(S) response")
773
+ if len(seeds) > 1 and scope_mode == "host":
774
+ if "scope" in explicit:
775
+ log.warn("--scope host keeps the discovered host(s) out of this crawl; "
776
+ "drop --scope host to include them")
777
+ seeds = [target]
778
+ else:
779
+ scope_mode = "subdomain"
780
+ log.info("scope widened to subdomain for the discovered host(s)")
781
+ elif args.subdomains and not do_crawl:
782
+ log.warn("--subdomains needs crawling; --no-crawl disables discovery")
783
+
784
+ scope = Scope(target, scope_mode)
785
+ log.info(f"scope: {scope.describe()}")
786
+
787
+ param_urls: list[str] = []
788
+ forms: list[Form] = []
789
+ js_resources: list[tuple[str, str, list[str]]] = []
790
+ crawled_pages = 0
791
+
792
+ if do_crawl:
793
+ hosts_note = f", {len(seeds)} host(s)" if len(seeds) > 1 else ""
794
+ log.action(f"crawling (depth {args.crawl_depth}, max {args.max_pages} pages, "
795
+ f"{args.threads} threads{hosts_note})")
796
+ crawler = Crawler(
797
+ http, scope, log,
798
+ max_depth=args.crawl_depth, max_pages=args.max_pages,
799
+ concurrency=args.threads, exclude=args.exclude, include=args.include,
800
+ crawl_js=not args.no_js, crawl_forms=True, ajax=not args.no_js,
801
+ respect_robots=args.robots, headers=headers,
802
+ )
803
+ crawl_result = crawler.run(seeds)
804
+ crawled_pages = len(crawl_result.pages)
805
+ param_urls = list(crawl_result.param_urls)
806
+ forms = crawl_result.forms
807
+ js_resources = [(info.url, info.body, info.pages)
808
+ for info in crawl_result.js_files.values()]
809
+ page_urls = list(crawl_result.pages)
810
+ crawl_stats = {
811
+ "pages": crawled_pages,
812
+ "seeds": len(seeds),
813
+ "hosts_crawled": len({urllib.parse.urlsplit(u).hostname
814
+ for u in crawl_result.pages}),
815
+ "subdomains_discovered": len(sub_info.hosts) if sub_info else 0,
816
+ "parameterised_urls": len(param_urls),
817
+ "forms": len(forms),
818
+ "js_files": len(crawl_result.js_files),
819
+ "external_hosts": len(crawl_result.external_hosts),
820
+ "errors": len(crawl_result.errors),
821
+ }
822
+ log.ok(f"crawl finished: {crawled_pages} page(s), {len(param_urls)} parameterised URL(s), "
823
+ f"{len(forms)} form(s), {len(crawl_result.js_files)} JS file(s)")
824
+ if crawl_result.errors:
825
+ log.warn(f"{len(crawl_result.errors)} request(s) failed during crawl "
826
+ f"(first: {crawl_result.errors[0][1][:90]})")
827
+ else:
828
+ log.info("crawling disabled")
829
+
830
+ # make sure the seed URL itself is always tested
831
+ if "?" in target and target not in param_urls:
832
+ param_urls.insert(0, target)
833
+
834
+ # ---- passive fingerprints ----------------------------------
835
+ # Both run once per host and never change the proof standard: the WAF
836
+ # result only decides which payload variants are *offered*, and the
837
+ # library list is evidence, not a finding on its own.
838
+ host_key = urllib.parse.urlsplit(target).netloc.lower() or target
839
+ if args.waf and host_key not in waf_results:
840
+ log.action("probing for a web application firewall")
841
+ try:
842
+ waf_results[host_key] = wafmod.detect(http, target, headers, log=log)
843
+ except Exception as exc: # a fingerprint must never abort a scan
844
+ log.warn(f"WAF probe failed: {str(exc)[:120]}")
845
+ waf_results[host_key] = wafmod.WAFDetection(checked=True)
846
+ current = waf_results[host_key]
847
+ if current.detected:
848
+ log.warn(current.describe())
849
+ if current.evasive and args.evade:
850
+ log.info("evasion: " + ", ".join(current.strategies())
851
+ + f" (up to {wafmod.evasion_budget(current.confidence, current.blocking)} "
852
+ "extra variant(s) per point)")
853
+ else:
854
+ log.info(current.describe())
855
+ waf_result: wafmod.WAFDetection | None = waf_results.get(host_key)
856
+
857
+ if args.js_libs and js_resources:
858
+ log.action(f"fingerprinting {len(js_resources)} client-side script(s)")
859
+ try:
860
+ target_libs = jslibmod.scan(js_resources)
861
+ except Exception as exc:
862
+ log.warn(f"library fingerprinting failed: {str(exc)[:120]}")
863
+ target_libs = []
864
+ libs_found.extend(target_libs)
865
+ for lib in target_libs:
866
+ if lib.vulnerable:
867
+ log.warn(" outdated client library: " + lib.line())
868
+ else:
869
+ log.info(" client library: " + lib.line())
870
+ if target_libs:
871
+ lib_stats = jslibmod.summary(target_libs)
872
+ log.ok(f"client libraries: {lib_stats['detected']} identified, "
873
+ f"{lib_stats['outdated']} outdated")
874
+ if args.osv:
875
+ # The local table is a curated shortcut; OSV is current. Only
876
+ # the version is sent, never target headers or cookies.
877
+ log.action("querying osv.dev for these library versions")
878
+ try:
879
+ gained = jslibmod.enrich_osv(target_libs, http, log=log)
880
+ except Exception as exc:
881
+ gained = 0
882
+ log.debug(f" osv enrichment failed: {str(exc)[:80]}")
883
+ if gained:
884
+ log.ok(f"OSV added advisories for {gained} library(ies)")
885
+
886
+ if args.common_paths and do_crawl:
887
+ from .crawler import COMMON_PATHS
888
+ root = "{0.scheme}://{0.netloc}".format(urllib.parse.urlsplit(target))
889
+ log.action(f"probing {len(COMMON_PATHS)} common paths for parameterised endpoints")
890
+ for path in COMMON_PATHS[:40]:
891
+ try:
892
+ resp = http.get(root + path, headers=headers)
893
+ except Exception:
894
+ continue
895
+ if resp.status < 400 and resp.is_html:
896
+ from .htmlparse import parse_page
897
+ page = parse_page(resp.url, resp.text)
898
+ for form in page.forms:
899
+ forms.append(form)
900
+
901
+ if deadline is not None and time.monotonic() > deadline:
902
+ budget_hit = True
903
+ log.warn(f"time budget of {args.max_minutes:g} min reached; reporting what "
904
+ "has been tested so far")
905
+ break
906
+
907
+ only_params = [p.strip() for p in args.param.split(",")] if args.param else None
908
+
909
+ # ---- parameter discovery -----------------------------------
910
+ # A hidden parameter is only worth finding if the scanner then tests
911
+ # it, so discovered names are merged into a copy of the URL and that
912
+ # copy is queued for the new names only (no re-testing of the params
913
+ # the URL already had).
914
+ # A GET form is a parameterised URL that a link crawler cannot see: its
915
+ # field names are exactly what the handler reads, so queue the action
916
+ # with those names filled in. POST bodies are probed further below.
917
+ form_urls = 0
918
+ for form in forms:
919
+ if form.method.upper() != "GET" or not form.action:
920
+ continue
921
+ names = [n for n, _v, typ in form.params
922
+ if n and typ not in ("submit", "button", "file", "image", "reset")]
923
+ if not names:
924
+ continue
925
+ candidate = paramdisc.with_params(form.action, names)
926
+ if candidate not in param_urls:
927
+ param_urls.append(candidate)
928
+ form_urls += 1
929
+ if form_urls:
930
+ log.info(f"queued {form_urls} GET form action(s) as parameterised URL(s)")
931
+
932
+ # Names the application's own JavaScript uses: no extra request (the
933
+ # crawler already downloaded the files) and more accurate than a generic
934
+ # wordlist on renamed or localised parameters.
935
+ js_names = paramdisc.names_from_js(js_resources) if js_resources else []
936
+ if js_names:
937
+ log.info(f"client-side script references {len(js_names)} parameter name(s)")
938
+
939
+ if (args.discover_params or args.fuzz) and not param_urls:
940
+ log.warn("--discover-params/--fuzz probe query strings, but no parameterised "
941
+ "URL was found on this target, so those stages had nothing to do "
942
+ "(reach body sinks with --json-body/--data instead)")
943
+
944
+ extra_only: dict[str, list[str]] = {}
945
+ if args.discover_params and param_urls:
946
+ probe_urls = param_urls[:3]
947
+ log.action(f"probing {len(probe_urls)} URL(s) for undocumented parameters")
948
+ for url in probe_urls:
949
+ if deadline is not None and time.monotonic() > deadline:
950
+ budget_hit = True
951
+ log.warn("time budget reached during parameter discovery")
952
+ break
953
+ try:
954
+ # discovery details are reported below with the URL attached
955
+ found = paramdisc.discover(http, url, headers, wordlist=js_names)
956
+ except Exception as exc:
957
+ log.debug(f" discovery failed on {url}: {str(exc)[:90]}")
958
+ continue
959
+ if not found.found:
960
+ log.info(f" {url}: no undocumented parameter responded")
961
+ continue
962
+ names = [n for n in found.names()
963
+ if not only_params or n in only_params]
964
+ if not names:
965
+ log.info(f" {url}: discovered name(s) excluded by --param")
966
+ continue
967
+ augmented = paramdisc.with_params(url, names)
968
+ if augmented in extra_only:
969
+ extra_only[augmented].extend(n for n in names
970
+ if n not in extra_only[augmented])
971
+ else:
972
+ extra_only[augmented] = list(names)
973
+ param_urls.append(augmented)
974
+ discoveries.append(found.as_dict())
975
+ shown = ", ".join(names[:10]) + (" ..." if len(names) > 10 else "")
976
+ log.ok(f" {url}: {len(names)} hidden parameter(s) - {shown}")
977
+
978
+ # ---- body parameter discovery ------------------------------
979
+ # The query-string prober cannot see a JSON or form body, which is where
980
+ # most current APIs put their parameters. Discovered properties are
981
+ # merged into the body that the injection-point builder walks, so the
982
+ # names are tested by the normal engine rather than reported and dropped.
983
+ json_body = args.json_body
984
+ if args.discover_params and json_body:
985
+ log.action("probing the request body for undocumented properties")
986
+ try:
987
+ body_found = paramdisc.discover_body(
988
+ http, target, json_body, "json", headers, log=log, wordlist=js_names)
989
+ except Exception as exc:
990
+ body_found = None
991
+ log.warn(f"body discovery failed: {str(exc)[:120]}")
992
+ if body_found is not None and body_found.found:
993
+ names = [n for n in body_found.names()
994
+ if not only_params or n in only_params]
995
+ if names:
996
+ for name in names[:20]:
997
+ json_body = paramdisc.body_with(json_body, "json", name, "1")
998
+ discoveries.append(body_found.as_dict())
999
+ log.ok(f" {target}: {len(names)} hidden body property(ies) - "
1000
+ + ", ".join(names[:10]))
1001
+
1002
+ # ---- fuzzing -----------------------------------------------
1003
+ if args.fuzz and param_urls:
1004
+ fuzz_result = None
1005
+ fuzz_urls = param_urls[:10]
1006
+ log.action(f"fuzzing parameters on {len(fuzz_urls)} URL(s) "
1007
+ f"(budget {args.fuzz_budget} requests)")
1008
+ try:
1009
+ fuzz_result = fuzzmod.run(http, fuzz_urls, headers, log=log,
1010
+ max_requests=args.fuzz_budget)
1011
+ except Exception as exc:
1012
+ log.warn(f"fuzzing failed: {str(exc)[:120]}")
1013
+ if fuzz_result is not None:
1014
+ fuzz_summary = fuzzmod.summary(fuzz_result)
1015
+ if fuzz_summary["parameters_fuzzed"]:
1016
+ log.ok(f"fuzzing: {fuzz_summary['parameters_fuzzed']} parameter(s) probed, "
1017
+ f"{fuzz_summary['with_raw_reflection']} reflected raw, "
1018
+ f"{fuzz_summary['encoded_only']} encoding-escaped, "
1019
+ f"{fuzz_summary['template_evaluation']} template-evaluated")
1020
+ if fuzz_summary["truncated"]:
1021
+ log.warn("fuzzing stopped at the request budget; "
1022
+ "raise --fuzz-budget for full coverage")
1023
+
1024
+ # ---- injection points --------------------------------------
1025
+ log.action("building injection points")
1026
+ points = []
1027
+ for url in param_urls:
1028
+ if url in extra_only:
1029
+ points.extend(points_from_url(url, headers, args.param_value,
1030
+ extra_only[url]))
1031
+ continue
1032
+ points.extend(points_from_url(url, headers, args.param_value, only_params))
1033
+ for form in forms:
1034
+ if form.method == "POST" and not args.forms:
1035
+ continue
1036
+ fetcher = None
1037
+ if form.method == "POST" and args.csrf_refresh:
1038
+ fetch = csrf_fetcher_factory(http, headers, log)
1039
+ token_page_url = form.origin_url or form.action
1040
+ fetcher = (lambda f=fetch, u=token_page_url: f(u))
1041
+ points.extend(points_from_form(form, headers, fetcher, only_params))
1042
+
1043
+ if args.data or json_body:
1044
+ method = (args.method or "POST").upper()
1045
+ if json_body:
1046
+ points.extend(points_from_json(target, json_body.encode(), headers,
1047
+ only_params, method))
1048
+ else:
1049
+ pairs = parse_qs_ordered(args.data or "")
1050
+ synthetic = Form(
1051
+ action=target, method=method,
1052
+ enctype="application/x-www-form-urlencoded",
1053
+ params=[(k, v, "text") for k, v in pairs],
1054
+ origin_url=target,
1055
+ )
1056
+ fetcher = None
1057
+ if method == "POST" and args.csrf_refresh:
1058
+ fetch = csrf_fetcher_factory(http, headers, log)
1059
+ fetcher = (lambda f=fetch, u=target: f(u))
1060
+ points.extend(points_from_form(synthetic, headers, fetcher, only_params))
1061
+
1062
+ if args.headers_points:
1063
+ for hname in ("Referer", "User-Agent", "X-Forwarded-Host", "Origin"):
1064
+ points.append(HeaderPoint(target, hname, headers, "GET"))
1065
+ if args.cookie:
1066
+ for part in args.cookie.split(";"):
1067
+ if "=" in part:
1068
+ cname = part.split("=", 1)[0].strip()
1069
+ points.append(CookiePoint(target, cname, headers))
1070
+
1071
+ # de-duplicate points
1072
+ seen = set()
1073
+ uniq = []
1074
+ for p in points:
1075
+ form_obj = getattr(p, "form", None)
1076
+ where = getattr(p, "url", "") or (form_obj.action if form_obj else "")
1077
+ key = p.label() + "|" + where
1078
+ if key in seen:
1079
+ continue
1080
+ seen.add(key)
1081
+ uniq.append(p)
1082
+ points = uniq[: args.max_points]
1083
+ # Counted per point by the engine as it actually tests them, not from the
1084
+ # queue length: a run stopped by --max-minutes must not report the points
1085
+ # it never reached as "points tested".
1086
+ findings: list = []
1087
+ if not points:
1088
+ log.warn("no parameterised injection points found")
1089
+ if not (dom_enabled and js_resources) \
1090
+ and not (args.stored and (forms or args.stored_json)):
1091
+ continue
1092
+ else:
1093
+ log.info(f"{len(points)} injection point(s) queued")
1094
+ if args.verbose:
1095
+ for p in points[:40]:
1096
+ log.debug(f" - {p.label()}")
1097
+
1098
+ # ---- scan -----------------------------------------------
1099
+ log.action(f"scanning {len(points)} point(s) with {args.threads} thread(s)"
1100
+ + (f", delay {args.delay}s" if args.delay else ""))
1101
+ scanner = Scanner(
1102
+ http, level=args.level, risk=args.risk, browser=browser, log=log,
1103
+ headers=headers, params_override=args.param_value,
1104
+ profile_enabled=not args.no_profile, mutation_budget=args.mutations,
1105
+ skip_points=done_keys, deadline=deadline,
1106
+ waf_detection=waf_result, evasion=args.evade,
1107
+ waf_budget=args.evasion_budget,
1108
+ bruteforce=args.brute, brute_budget=args.brute_budget,
1109
+ )
1110
+ findings = scanner.scan_points(points, concurrency=args.threads)
1111
+ points_total += scanner.stats["points"]
1112
+ if scanner.budget_exhausted:
1113
+ # The engine already logged how much it managed to test.
1114
+ budget_hit = True
1115
+ reflected_total += scanner.stats["reflected_points"]
1116
+ mxss_total += scanner.stats.get("mxss_probes", 0)
1117
+ charset_total += scanner.stats.get("charset_probes", 0)
1118
+ waf_variants_total += scanner.stats.get("waf_variants", 0)
1119
+ learned = scanner.evasion_memory.describe()
1120
+ if learned:
1121
+ log.info(f"evasion learned from this target: {learned}")
1122
+ evasion_notes[host_key] = learned
1123
+ brute_probes_total += scanner.stats.get("brute_probes", 0)
1124
+ if scanner.brute_reports:
1125
+ brute_reports.extend(scanner.brute_reports)
1126
+ log.ok(f"brute force: learned the filter map for "
1127
+ f"{len(scanner.brute_reports)} point(s)")
1128
+ all_findings.extend(findings)
1129
+ all_leads.extend(scanner.leads)
1130
+ done_keys |= scanner.completed_points
1131
+ resumed_total += scanner.resumed_points
1132
+ if scanner.interrupted:
1133
+ interrupted = True
1134
+ log.warn("interrupted: writing a partial report from the results that "
1135
+ "completed before the stop")
1136
+ if browser.available and scanner.stats["verified"] == 0 and findings:
1137
+ log.info("browser verification ran but did not observe execution "
1138
+ "(CSP or an interaction requirement can cause this)")
1139
+
1140
+ if interrupted:
1141
+ break
1142
+
1143
+ # ---- DOM XSS ------------------------------------------------
1144
+ if dom_enabled and js_resources:
1145
+ log.action(f"tracing DOM sources and sinks in {len(js_resources)} script resource(s)")
1146
+ dom = DomScanner(browser=browser, log=log, max_flows=args.dom_flows,
1147
+ screenshot_dir=screenshot_dir, deadline=deadline)
1148
+ outcome = dom.scan(target, js_resources)
1149
+ if dom.budget_exhausted:
1150
+ budget_hit = True
1151
+ all_findings.extend(outcome["findings"])
1152
+ all_leads.extend(outcome["leads"])
1153
+ dom_total += len(outcome["findings"])
1154
+ if outcome["findings"]:
1155
+ log.ok(f"{len(outcome['findings'])} DOM XSS flow(s) proven in the browser")
1156
+ elif outcome["flows"]:
1157
+ log.info(f"{len(outcome['flows'])} DOM flow(s) analysed, none proven")
1158
+ if outcome["leads"] and args.verbose:
1159
+ for lead in outcome["leads"][:10]:
1160
+ log.debug(f" DOM lead: {lead.param} at {lead.url}")
1161
+
1162
+ # ---- stored / blind XSS -------------------------------------
1163
+ if deadline is not None and time.monotonic() > deadline:
1164
+ budget_hit = True
1165
+ log.warn(f"time budget of {args.max_minutes:g} min reached before the stored "
1166
+ "stage; reporting what has been tested so far")
1167
+ break
1168
+ if args.stored and (forms or args.stored_json):
1169
+ log.action(f"planting stored-XSS payloads in {len(forms)} form(s)"
1170
+ + (f" and {len(args.stored_json)} JSON endpoint(s)"
1171
+ if args.stored_json else "")
1172
+ + (f", callback {callback.url}" if callback else ""))
1173
+ store = StoredScanner(
1174
+ http, browser=browser, log=log, callback=callback,
1175
+ max_forms=args.stored_max_forms, screenshot_dir=screenshot_dir,
1176
+ json_endpoints=args.stored_json, json_field=args.stored_json_field,
1177
+ viewer_urls=args.viewer_url, deadline=deadline,
1178
+ )
1179
+ outcome = store.scan(target, forms, page_urls)
1180
+ if store.budget_exhausted:
1181
+ budget_hit = True
1182
+ all_findings.extend(outcome["findings"])
1183
+ all_leads.extend(outcome["leads"])
1184
+ stored_total += outcome["stats"]["verified"]
1185
+ st = outcome["stats"]
1186
+ tokens_total += st.get("tokens_refreshed", 0)
1187
+ json_total += st.get("json_submitted", 0)
1188
+ log.ok(f"stored: {st['markers']} marker(s) planted, {st['hits']} persisted, "
1189
+ f"{st['verified']} proven")
1190
+ if st.get("tokens_refreshed"):
1191
+ log.info(f"stored: {st['tokens_refreshed']} anti-CSRF token(s) refreshed "
1192
+ "before planting")
1193
+ if st.get("json_submitted"):
1194
+ log.info(f"stored: {st['json_submitted']} JSON endpoint(s) accepted the payload")
1195
+ if outcome["findings"]:
1196
+ log.warn(f"{len(outcome['findings'])} stored XSS flow(s) confirmed")
1197
+
1198
+ finished = dt.datetime.now()
1199
+ findings = rp.dedupe(all_findings)
1200
+
1201
+ # ---- exploit stage ---------------------------------------------
1202
+ # Detection says an input reaches an execution context; --verify replays the
1203
+ # exact request with a weaponised payload and measures what the script could
1204
+ # reach. It never upgrades a finding on the strength of a payload it only
1205
+ # sent, so a finding without an observation keeps saying so.
1206
+ verification = None
1207
+ if args.verify and findings:
1208
+ log.action(f"exploit stage: replaying up to {min(len(findings), args.verify_max)} "
1209
+ f"of {len(findings)} finding(s) with a weaponised payload")
1210
+ prover = ExploitProver(http=http, browser=browser, log=log, callback=callback,
1211
+ max_targets=args.verify_max, deadline=deadline,
1212
+ session=session)
1213
+ verification = prover.run(findings)
1214
+ vstats = verification["stats"]
1215
+ if vstats.get("proven"):
1216
+ log.ok(f"exploit: {vstats['proven']} finding(s) proven to reach "
1217
+ "cookies, tokens or same-origin data")
1218
+ if vstats.get("unproven") or vstats.get("not_tested"):
1219
+ log.warn(f"exploit: {vstats.get('unproven', 0)} unproven, "
1220
+ f"{vstats.get('not_tested', 0)} not tested")
1221
+ first = next((f for f in findings
1222
+ if (getattr(f, "exploit", None) or {}).get("reason")), None)
1223
+ if first is not None and not vstats.get("proven"):
1224
+ log.info(f"exploit: first reason - {first.exploit['reason'][:200]}")
1225
+ log.info("exploit: a finding that stays unproven is still a confirmed "
1226
+ "injection; the report says which capability was measured")
1227
+
1228
+ # ---- output ----------------------------------------------------
1229
+ print()
1230
+ log.banner("results")
1231
+ if not findings:
1232
+ log.ok("no cross-site scripting confirmed")
1233
+ if all_leads:
1234
+ log.info(f"{len(rp.dedupe(all_leads))} unconfirmed lead(s) - see the report's leads section")
1235
+ else:
1236
+ counts: dict[str, int] = {}
1237
+ for f in findings:
1238
+ sev = rp.severity_of(f)
1239
+ counts[sev] = counts.get(sev, 0) + 1
1240
+ summary = ", ".join(f"{counts[s]} {s}" for s in ("high", "medium", "low") if s in counts)
1241
+ log.warn(f"{len(findings)} finding(s): {summary}")
1242
+ for f in findings:
1243
+ log.found(f)
1244
+
1245
+ stats = {
1246
+ "points": points_total,
1247
+ "requests": http.stats["requests"],
1248
+ "reflected_points": reflected_total,
1249
+ "mxss_probes": mxss_total,
1250
+ "charset_probes": charset_total,
1251
+ "waf_variants": waf_variants_total,
1252
+ "brute_probes": brute_probes_total,
1253
+ "verified": browser.hits,
1254
+ "dom_flows": dom_total,
1255
+ "stored_flows": stored_total,
1256
+ "resumed_points": resumed_total,
1257
+ "rate_limits": http.stats.get("rate_limits", 0),
1258
+ "tokens_refreshed": tokens_total,
1259
+ "json_submitted": json_total,
1260
+ "callback_hits": len(callback.hits) if callback else 0,
1261
+ "errors": http.stats["errors"],
1262
+ "bytes": http.stats["bytes"],
1263
+ }
1264
+ meta = rp.build_meta(
1265
+ targets=targets, started=started, finished=finished,
1266
+ stats={k: v for k, v in stats.items() if v is not None},
1267
+ crawl_stats=crawl_stats,
1268
+ browser_note=browser.describe(),
1269
+ command=" ".join(shlex.quote(a) for a in sys.argv),
1270
+ )
1271
+ if interrupted:
1272
+ meta["interrupted"] = True
1273
+ if budget_hit:
1274
+ meta["partial"] = f"time budget of {args.max_minutes:g} min reached"
1275
+ if verification is not None:
1276
+ meta["verification"] = verification["stats"]
1277
+ if args.autonomous:
1278
+ meta["autonomous"] = True
1279
+ if waf_results:
1280
+ meta["waf"] = [dict(detection.as_dict(), target=host)
1281
+ for host, detection in waf_results.items()]
1282
+ meta["waf_note"] = "; ".join(detection.describe()
1283
+ for detection in waf_results.values())
1284
+ if evasion_notes:
1285
+ meta["evasion_learned"] = evasion_notes
1286
+ if libs_found:
1287
+ uniq_libs: dict[tuple[str, str], jslibmod.Library] = {}
1288
+ for lib in libs_found:
1289
+ uniq_libs.setdefault((lib.name, lib.version), lib)
1290
+ lib_list = list(uniq_libs.values())
1291
+ meta["js_libraries"] = [lib.as_dict() for lib in lib_list]
1292
+ meta["js_library_summary"] = {
1293
+ k: v for k, v in jslibmod.summary(lib_list).items() if k != "libraries"}
1294
+ if discoveries:
1295
+ meta["discovered_parameters"] = discoveries
1296
+ if fuzz_summary is not None:
1297
+ meta["fuzzing"] = fuzz_summary
1298
+ meta["fuzzed_parameters"] = (fuzz_result or {}).get("params", [])
1299
+ if brute_reports:
1300
+ # A hostile target can reflect hundreds of points; the report stays
1301
+ # readable and the JSON records how many entries were dropped.
1302
+ meta["brute_force"] = brute_reports[:80]
1303
+ if len(brute_reports) > 80:
1304
+ meta["brute_force_truncated"] = len(brute_reports) - 80
1305
+ if login_summary:
1306
+ meta["authentication"] = {"login_url": args.login_url,
1307
+ "result": login_summary,
1308
+ "cookies": jar.names()}
1309
+ if all_leads:
1310
+ lead_rows = rp.dedupe(all_leads)
1311
+ meta["leads"] = [
1312
+ {"url": f.url, "param": f.param, "context": f.context,
1313
+ "location": f.location, "confidence": f.confidence, "notes": f.notes,
1314
+ "kind": (f.filter_profile or {}).get("lead_kind", "")}
1315
+ for f in lead_rows[:200]
1316
+ ]
1317
+ if len(lead_rows) > 200:
1318
+ meta["leads_truncated"] = True
1319
+
1320
+ written = []
1321
+ output_dir = args.output_dir
1322
+ stamp = finished.strftime("%Y%m%d-%H%M%S")
1323
+ json_path = args.output or os.path.join(output_dir, f"xssmap-{stamp}.json")
1324
+ html_path = args.html or os.path.join(output_dir, f"xssmap-{stamp}.html")
1325
+ md_path = args.markdown or os.path.join(output_dir, f"xssmap-{stamp}.md")
1326
+ sarif_path = args.sarif or os.path.join(output_dir, f"xssmap-{stamp}.sarif")
1327
+ try:
1328
+ written.append(rp.write_json(json_path, findings, meta))
1329
+ written.append(rp.write_html(html_path, findings, meta))
1330
+ written.append(rp.write_markdown(md_path, findings, meta))
1331
+ written.append(sarif.write_sarif(sarif_path, findings, meta))
1332
+ if args.evidence_dir or args.screenshots:
1333
+ evidence_dir = args.evidence_dir or os.path.join(output_dir, "evidence")
1334
+ sarif.write_evidence(findings, evidence_dir)
1335
+ if args.screenshots:
1336
+ sarif.capture_screenshots(browser, findings, evidence_dir)
1337
+ except OSError as exc:
1338
+ log.error(f"could not write report: {exc}")
1339
+
1340
+ if written and not args.quiet:
1341
+ print()
1342
+ log.info(f"{http.stats['requests']} request(s), "
1343
+ f"{http.stats['bytes'] / 1024:.0f} KB transferred, "
1344
+ f"{meta['duration_s']}s")
1345
+ for path in written:
1346
+ log.info(f"report: {path}")
1347
+ if args.state:
1348
+ try:
1349
+ stateio.save_state(args.state, targets, done_keys, findings, rp.dedupe(all_leads))
1350
+ log.info(f"state: {len(done_keys)} completed point(s) saved to {args.state}")
1351
+ except OSError as exc:
1352
+ log.error(f"could not write --state: {exc}")
1353
+ if args.save_cookies:
1354
+ try:
1355
+ jar.save_netscape(args.save_cookies)
1356
+ log.info(f"cookies written to {args.save_cookies} (sensitive: live secrets)")
1357
+ except OSError as exc:
1358
+ log.error(f"could not write --save-cookies: {exc}")
1359
+ if callback is not None:
1360
+ callback.stop()
1361
+ browser.cleanup()
1362
+
1363
+ if interrupted:
1364
+ return 130
1365
+ if args.fail_on_findings and findings:
1366
+ return 1
1367
+ return 0
1368
+
1369
+
1370
+ if __name__ == "__main__":
1371
+ try:
1372
+ sys.exit(main())
1373
+ except KeyboardInterrupt:
1374
+ print("\n[-] interrupted")
1375
+ sys.exit(130)