--- name: XSS Detection slug: cross-site-scripting-detection category: Quality description: "Detect Cross-Site Scripting vulnerabilities in a codebase using a three-phase approach: recon for sink sites, batched taint tracing, and result merging. Use when auditing code for XSS bugs." github: "https://github.com/utkusen/sast-skills/tree/main/sast-files/.agents/skills/sast-xss" stars: 1231 forks: 60 install: "git clone https://github.com/utkusen/sast-skills" added: 2026-07-20T06:49:13.351Z last_synced: 2026-07-29T06:37:20.458Z canonical_url: "https://dirskills.com/skills/cross-site-scripting-detection" --- # XSS Detection Detect Cross-Site Scripting vulnerabilities in a codebase using a three-phase approach: recon for sink sites, batched taint tracing, and result merging. Use when auditing code for XSS bugs. **Install:** `git clone https://github.com/utkusen/sast-skills` ## README # Cross-Site Scripting (XSS) Detection You are performing a focused security assessment to find Cross-Site Scripting vulnerabilities in a codebase. This skill uses a three-phase approach with subagents: **recon** (find sink sites), **batched verify** (trace taint for parallel batches of up to 3 sinks each), and **merge** (consolidate batch results into one report). **Prerequisites**: `sast/architecture.md` must exist. Run the analysis skill first if it doesn't. --- ## What is XSS XSS occurs when user-supplied input is incorporated into a web page's HTML, JavaScript, or DOM without proper escaping or sanitization. This allows attackers to inject and execute arbitrary scripts in victims' browsers, leading to session hijacking, credential theft, defacement, and malware distribution. The core pattern: *unescaped, unsanitized user input reaches an HTML/JS output sink.* ### XSS Types - **Reflected XSS**: User input is immediately echoed back in the HTTP response (e.g., a search term rendered directly into the page HTML). - **Stored XSS**: User input is saved to persistent storage (database, file) and later rendered in HTML for other users. - **DOM-based XSS**: Client-side JavaScript reads from an attacker-controlled source (`location.search`, `location.hash`, `document.cookie`) and writes to a dangerous DOM sink (`innerHTML`, `eval`, `document.write`) without server involvement. ### What XSS IS **Server-side HTML sinks** — rendering user data into HTML responses without escaping: - Python/Jinja2: `{{ var | safe }}`, `{% autoescape off %}...{{ var }}...{% endautoescape %}` - Python/Django: `mark_safe(var)`, `format_html(...)` with `%s` and unescaped input, `{{ var | safe }}` in templates - Python/Flask: `Markup(var)`, `render_template_string(f"...{var}...")` - PHP: `echo $var`, `print $var`, `` without `htmlspecialchars()` - Ruby/Rails: `raw(var)`, `var.html_safe`, `<%= raw var %>`, `content_tag` with `.html_safe` - Java/JSP: `<%= var %>`, `${var}` without `` or `fn:escapeXml()` - Java/Thymeleaf: `th:utext="${var}"` (unescaped), `[(${var})]` - Go/html-template misuse: using `template.HTML(var)`, `template.JS(var)`, `template.URL(var)` to bypass auto-escaping - C#/Razor: `@Html.Raw(var)`, `MvcHtmlString.Create(var)` - Node.js/EJS: `<%- var %>` (unescaped), vs `<%= var %>` (safe) - Node.js/Handlebars: `{{{ var }}}` (triple-brace, unescaped) - Node.js/Pug: `!{var}` (unescaped) - Express: `res.send("..." + var + "...")`, `res.write("

" + var + "

")` **Client-side DOM sinks** — JavaScript writing user-controlled data to the DOM unsafely: - `element.innerHTML = var` - `element.outerHTML = var` - `document.write(var)`, `document.writeln(var)` - `element.insertAdjacentHTML('beforeend', var)` - jQuery: `$(element).html(var)`, `$(element).append(var)` (when var contains HTML), `$('
' + var + '
')` - React: `dangerouslySetInnerHTML={{ __html: var }}` - Angular: `[innerHTML]="var"`, `bypassSecurityTrustHtml(var)`, `bypassSecurityTrustScript(var)`, `bypassSecurityTrustUrl(var)` - Vue: `v-html="var"` **JavaScript execution sinks** — user-controlled data evaluated as code: - `eval(var)` - `setTimeout(var, delay)` / `setInterval(var, delay)` when `var` is a string - `new Function(var)()` - `element.setAttribute('onclick', var)`, `element.setAttribute('href', 'javascript:' + var)` - `location.href = var`, `location.replace(var)`, `location.assign(var)` (when var is user-controlled and can be `javascript:...`) - `element.src = var`, `element.action = var` (script injection via `javascript:` URIs) - `scriptElement.text = var`, `scriptElement.textContent = var` **DOM-based sources** — attacker-controlled inputs read by client-side JavaScript: - `location.search` (URL query string) - `location.hash` (URL fragment) - `location.href` - `document.referrer` - `document.URL`, `document.documentURI` - `document.cookie` - `postMessage` event data (`event.data`) - `window.name` - `localStorage.getItem(...)`, `sessionStorage.getItem(...)` (if populated from URL or postMessage) ### What XSS is NOT Do not flag these as XSS: - **CSRF**: Forging requests on behalf of a user — a separate vulnerability class - **SQLi via XSS**: Injecting SQL through an XSS vector — the SQL injection itself is the primary finding - **Clickjacking**: Embedding pages in iframes — different vulnerability class - **Header injection**: Injecting newlines into HTTP response headers — separate class (HTTP Response Splitting) - **Safe template output**: Auto-escaped `{{ var }}` in Jinja2/Django/Twig/Blade/Handlebars double-brace syntax with auto-escaping on — these are safe - **`textContent` / `innerText`**: These write plain text only; no HTML parsing occurs — safe ### Patterns That Prevent XSS When you see these patterns, the code is likely **not vulnerable**: **1. Context-aware auto-escaping (most template engines default)** ``` # Jinja2 / Django (auto-escape on by default) {{ var }} # HTML-escaped → safe # EJS <%= var %> # HTML-escaped → safe # Handlebars {{ var }} # HTML-escaped → safe # Pug = var # HTML-escaped → safe # Thymeleaf th:text="${var}" # HTML-escaped → safe # Razor (C#) @var # HTML-encoded → safe ``` **2. Explicit escaping before output** ```php // PHP echo htmlspecialchars($var, ENT_QUOTES, 'UTF-8'); ``` ```ruby # Rails <%= h(var) %> <%= ERB::Util.html_escape(var) %> ``` ```java // JSP with JSTL // or fn:escapeXml() ${fn:escapeXml(var)} ``` ```go // html/template — auto-escapes by context (HTML, JS, URL, CSS) {{.Var}} // safe inside html/template ``` **3. DOM manipulation using safe properties** ```javascript element.textContent = userInput; // plain text, no HTML parsing — safe element.innerText = userInput; // plain text — safe ``` **4. Sanitization with an allowlisted HTML library** ```javascript // DOMPurify element.innerHTML = DOMPurify.sanitize(userInput); // sanitize-html with strict config const clean = sanitizeHtml(userInput, { allowedTags: [], allowedAttributes: {} }); ``` **5. React / Angular / Vue auto-escaping** ```jsx // React JSX — auto-escaped return
{userInput}
; ``` ```html
{{ userInput }}
{{ userInput }}
``` --- ## Vulnerable vs. Secure Examples ### Python — Flask / Jinja2 ```python # VULNERABLE: Markup() bypasses Jinja2 auto-escaping @app.route('/greet') def greet(): name = request.args.get('name', '') return render_template_string(f"

Hello, {name}!

") # raw f-string, no template escaping # VULNERABLE: mark_safe equivalent @app.route('/profile') def profile(): bio = request.args.get('bio', '') return render_template('profile.html', bio=Markup(bio)) # Markup() marks it as safe, bypassing escaping # SECURE: use template with auto-escaping (never pass Markup around user input) @app.route('/greet') def greet(): name = request.args.get('name', '') return render_template('greet.html', name=name) # template: {{ name }} — auto-escaped ``` ### Python — Django ```python # VULNERABLE: mark_safe() with user input def user_bio(request): bio = request.GET.get('bio', '') safe_bio = mark_safe(bio) # user input bypasses Django's auto-escaping return render(request, 'bio.html', {'bio': safe_bio}) # SECURE: pass raw string; template handles escaping def user_bio(request): bio = request.GET.get('bio', '') return render(request, 'bio.html', {'bio': bio}) # template: {{ bio }} — auto-escaped ``` ### PHP ```php // VULNERABLE: echo without escaping function showUsername($username) { echo "

Welcome, " . $username . "

"; } // SECURE: htmlspecialchars function showUsername($username) { echo "

Welcome, " . htmlspecialchars($username, ENT_QUOTES, 'UTF-8') . "

"; } ``` ### Node.js — Express (string concatenation) ```javascript // VULNERABLE: user input concatenated into HTML response app.get('/search', (req, res) => { const query = req.query.q; res.send(`

Results for: ${query}

`); }); // SECURE: use a template engine with auto-escaping, or escape manually const escapeHtml = require('escape-html'); app.get('/search', (req, res) => { const query = req.query.q; res.send(`

Results for: ${escapeHtml(query)}

`); }); ``` ### Node.js / EJS ```html
<%- userInput %>
<%= userInput %>
``` ### Node.js / Handlebars ```html
{{{ userInput }}}
{{ userInput }}
``` ### JavaScript — DOM Sinks ```javascript // VULNERABLE: innerHTML with URL fragment const name = location.hash.substring(1); document.getElementById('greeting').innerHTML = 'Hello, ' + name; // SECURE: textContent const name = location.hash.substring(1); document.getElementById('greeting').textContent = 'Hello, ' + name; ``` ```javascript // VULNERABLE: eval with postMessage data window.addEventListener('message', (event) => { eval(event.data); }); // SECURE: parse and validate; never eval postMessage data window.addEventListener('message', (event) => { const data = JSON.parse(event.data); // handle data safely }); ``` ### React ```jsx // VULNERABLE: dangerouslySetInnerHTML with user input function Comment({ content }) { return
; } // SECURE: render as text (auto-escaped by React) function Comment({ content }) { return
{content}
; } ``` ### Angular ```typescript // VULNERABLE: bypassing Angular's DomSanitizer constructor(private sanitizer: DomSanitizer) {} getUserHtml(input: string): SafeHtml { return this.sanitizer.bypassSecurityTrustHtml(input); // unsafe if input is user-controlled } ``` ```html
{{ userInput }}
``` ### Ruby on Rails ```erb <%# VULNERABLE: raw() or html_safe with user input %> <%= raw(@user.bio) %> <%= @user.bio.html_safe %> <%# SECURE: default ERB escaping %> <%= @user.bio %> ``` ### Java — JSP ```jsp <%-- VULNERABLE: scriptlet echo --%>

Hello, <%= request.getParameter("name") %>

<%-- VULNERABLE: EL without c:out --%>

Hello, ${param.name}

<%-- SECURE: c:out escaping --%>

Hello,

``` ### Go — html/template vs. text/template ```go // VULNERABLE: using text/template (no HTML escaping) import "text/template" tmpl := template.Must(template.New("").Parse("

Hello, {{.Name}}!

")) tmpl.Execute(w, data) // VULNERABLE: using template.HTML() cast to bypass escaping import "html/template" name := template.HTML(r.URL.Query().Get("name")) // bypasses auto-escaping // SECURE: html/template with plain string value import "html/template" tmpl := template.Must(template.New("").Parse("

Hello, {{.Name}}!

")) tmpl.Execute(w, data) // .Name is a plain string — auto-escaped ``` --- ## Execution This skill runs in three phases using subagents. Pass the contents of `sast/architecture.md` to all subagents as context. ### Phase 1: Find XSS Sink Sites Launch a subagent with the following instructions: > **Goal**: Find every location in the codebase where data is rendered into HTML, JavaScript, or the DOM in a way that could allow script injection — any unescaped or explicitly-marked-safe output, any dangerous DOM property assignment, any JavaScript execution sink. Write results to `sast/xss-recon.md`. > > **Context**: You will be given the project's architecture summary. Use it to understand the frontend stack, template engines, server-side rendering frameworks, and any client-side JavaScript patterns. > > **What to search for — vulnerable sink patterns**: > > Flag ANY dynamic variable passed to a dangerous output sink. You are not yet checking whether the variable is user-controlled — that is Phase 2's job. > > **1. Server-side template unescaped output**: > - Jinja2/Django: `{{ var | safe }}`, `{% autoescape off %}`, `Markup(var)`, `mark_safe(var)`, `format_html(...)` with direct user-controlled format args > - EJS: `<%- var %>` > - Handlebars/Mustache: `{{{ var }}}` > - Pug: `!{var}` > - Thymeleaf: `th:utext="${var}"`, `[(${var})]` > - Twig: `{{ var | raw }}` > - Blade (Laravel): `{!! $var !!}` > - Rails ERB: `raw(var)`, `var.html_safe`, `<%= raw var %>` > - PHP: `echo $var`, `print $var`, `` without `htmlspecialchars()` > - Go: `template.HTML(var)`, `template.JS(var)`, `template.URL(var)`, usage of `text/template` for HTML output > - C#/Razor: `@Html.Raw(var)`, `MvcHtmlString.Create(var)` > > **2. Direct HTML string construction in server-side code**: > - String concatenation or interpolation building an HTML response: `res.send("

" + var + "

")`, `f"

{var}

"`, `"
" + var + "
"` > - `render_template_string(f"...{var}...")` in Flask > > **3. Client-side DOM sinks**: > - `element.innerHTML = var` > - `element.outerHTML = var` > - `document.write(var)`, `document.writeln(var)` > - `element.insertAdjacentHTML(position, var)` > - jQuery: `$(el).html(var)`, `$(el).append(var)`, `$('' + var + '')`, `$.parseHTML(var)` passed to DOM > - React: `dangerouslySetInnerHTML={{ __html: var }}` > - Angular: `[innerHTML]="var"`, `bypassSecurityTrustHtml(var)`, `bypassSecurityTrustScript(var)`, `bypassSecurityTrustUrl(var)`, `bypassSecurityTrustStyle(var)`, `bypassSecurityTrustResourceUrl(var)` > - Vue: `v-html="var"` > > **4. JavaScript execution sinks**: > - `eval(var)` > - `setTimeout(var, ...)` / `setInterval(var, ...)` where `var` is a string variable (not a function reference) > - `new Function(var)()` > - `scriptElement.text = var`, `scriptElement.textContent = var` > - `element.setAttribute('onclick', var)`, `element.setAttribute('href', 'javascript:' + var)`, and similar event-handler attribute assignments > - URL-based sinks where `javascript:` URIs could execute: `location.href = var`, `location.replace(var)`, `element.src = var`, `element.action = var` > > **5. DOM-based XSS patterns** — client-side code reading from attacker-controlled sources and passing to any sink above: > - Reading from: `location.search`, `location.hash`, `location.href`, `document.referrer`, `document.URL`, `document.cookie`, `window.name`, `postMessage` handler (`event.data`), `URLSearchParams` > - Then passing to an HTML or JS sink without escaping > > **What to skip** (these are safe output patterns — do not flag): > - Auto-escaped template output: `{{ var }}` in Jinja2 (auto-escape on), `<%= var %>` in EJS, `{{ var }}` in Handlebars double-brace, `@var` in Razor, `th:text` in Thymeleaf > - `element.textContent = var` and `element.innerText = var` — no HTML parsing, safe > - React JSX `{var}` — auto-escaped > - Angular `{{ var }}` interpolation — auto-escaped > - Vue `{{ var }}` interpolation — auto-escaped > - `DOMPurify.sanitize(var)` wrapping an innerHTML assignment — typically safe (verify config) > - `sanitize-html`, `xss`, or similar allowlist sanitizer library wrapping output > > **Output format** — write to `sast/xss-recon.md`: > > ```markdown > # XSS Recon: [Project Name] > > ## Summary > Found [N] locations where data is rendered into HTML/JS/DOM without guaranteed escaping. > > ## Sink Sites > > ### 1. [Descriptive name — e.g., "innerHTML assignment in search results handler"] > - **File**: `path/to/file.ext` (lines X-Y) > - **Function / endpoint / component**: [function name, route, or component] > - **Sink type**: [server-side template / HTML string concat / DOM innerHTML / eval / JS execution sink / DOM-based source-to-sink] > - **Sink call**: [the exact API or property used — e.g., `innerHTML`, `mark_safe()`, `<%- %>`] > - **Interpolated variable(s)**: `var_name` — [brief note, e.g., "unknown origin" or "looks like user profile field"] > - **XSS type**: [Reflected / Stored / DOM-based — best guess at this stage] > - **Code snippet**: > ``` > [the vulnerable sink code] > ``` > > [Repeat for each site] > ``` ### After Phase 1: Check for Candidates Before Proceeding After Phase 1 completes, read `sast/xss-recon.md`. If the recon found **zero sink sites** (the summary reports "Found 0" or the "Sink Sites" section is empty or absent), **skip Phase 2 and Phase 3 entirely**. Instead, write the following content to `sast/xss-results.md` and stop (you may delete `sast/xss-recon.md` after writing): ```markdown # XSS Analysis Results No vulnerabilities found. ``` Only proceed to Phase 2 if Phase 1 found at least one sink site. ### Phase 2: Verify — Trace User Input to Sinks (Batched) After Phase 1 completes, read `sast/xss-recon.md` and split the sink sites into **batches of up to 3 sink sites each**. Launch **one subagent per batch in parallel**. Each subagent traces taint only for its assigned sinks and writes results to its own batch file. **Batching procedure** (you, the orchestrator, do this — not a subagent): 1. Read `sast/xss-recon.md` and count the numbered sink sections (### 1., ### 2., etc.). 2. Divide them into batches of up to 3. For example, 8 sinks → 3 batches (1-3, 4-6, 7-8). 3. For each batch, extract the full text of those sink sections from the recon file. 4. Launch all batch subagents **in parallel**, passing each one only its assigned sinks. 5. Each subagent writes to `sast/xss-batch-N.md` where N is the 1-based batch number. 6. Identify the project's primary language/framework from `sast/architecture.md` and select **only the matching examples** from the "Vulnerable vs. Secure Examples" section above. For example, if the project uses React with an Express API, include the relevant Node.js and React examples. Include these selected examples in each subagent's instructions where indicated by `[TECH-STACK EXAMPLES]` below. Give each batch subagent the following instructions (substitute the batch-specific values): > **Goal**: For each assigned XSS sink site, determine whether a user-supplied value reaches the output variable. Write results to `sast/xss-batch-[N].md`. > > **Your assigned sink sites** (from the recon phase): > > [Paste the full text of the assigned sink sections here, preserving the original numbering] > > **Context**: You will be given the project's architecture summary. Use it to understand request entry points, data flows, middleware, and client-side data sources. > > **For each sink site, trace the interpolated variable(s) backwards to their origin**: > > **User-controlled sources to look for:** > > 1. **HTTP request sources** (server-side): > - Query parameters: `request.GET.get(...)`, `req.query.x`, `params[:x]`, `$_GET['x']`, `c.Query("x")`, `r.URL.Query().Get("x")` > - Path parameters: `request.path_params['id']`, `req.params.id`, `params[:id]`, `$_GET['id']` > - Request body / form fields: `request.POST.get(...)`, `req.body.x`, `request.form.get(...)`, `$_POST['x']` > - HTTP headers: `request.headers.get(...)`, `req.headers['x']`, `$_SERVER['HTTP_X_CUSTOM']` > - Cookies: `request.COOKIES.get(...)`, `req.cookies.x`, `$_COOKIE['x']` > - File upload filenames or content: `request.files['x'].filename` > > 2. **Attacker-controlled DOM sources** (client-side / DOM-based XSS): > - `location.search`, `location.hash`, `location.href`, `document.referrer`, `document.URL` > - `window.name`, `document.cookie` > - `postMessage` event: `window.addEventListener('message', (e) => { ... e.data ... })` > - `URLSearchParams` values derived from `location.search` > - `localStorage` / `sessionStorage` values written from URL or postMessage > > 3. **Stored (second-order) input** — the variable is read from persistent storage (database, file, cache), but the stored value or