@sun-asterisk/sunlint 1.3.26 → 1.3.27

package/rules/security/S022_escape_output_context/README.md

@@ -0,0 +1,254 @@
+# S022 - Escape Data Properly Based on Output Context
+
+## Overview
+
+**Rule ID:** S022
+**Category:** Security
+**Severity:** Error
+**OWASP:** A03:2021 – Injection (XSS)
+**CWE:** CWE-79 - Improper Neutralization of Input During Web Page Generation
+
+## Description
+
+This rule ensures that all data output to different contexts (HTML, JavaScript, URL, CSS, attributes) is properly escaped or sanitized to prevent Cross-Site Scripting (XSS) attacks. Different output contexts require different escaping mechanisms.
+
+XSS vulnerabilities occur when untrusted data is included in a web page without proper validation or escaping, allowing attackers to inject malicious scripts that execute in victims' browsers.
+
+## Why This Matters
+
+### Security Impact
+
+- **Data Theft**: Attackers can steal sensitive information (cookies, session tokens, credentials)
+- **Account Hijacking**: Session tokens can be stolen for account takeover
+- **Malware Distribution**: Inject scripts that download malware
+- **Defacement**: Modify page content to damage reputation
+- **Phishing**: Redirect users to malicious sites
+
+### Context-Specific Escaping
+
+Different contexts require different escaping methods:
+
+1. **HTML Context**: `<div>{data}</div>` → Escape `<`, `>`, `&`, `"`, `'`
+2. **JavaScript Context**: `<script>var x = '{data}'</script>` → JSON encoding
+3. **URL Context**: `<a href="{data}">` → URL encoding + validation
+4. **CSS Context**: `<style>{data}</style>` → CSS escaping
+5. **Attribute Context**: `<div title="{data}">` → Attribute escaping
+
+## What It Detects
+
+### 1. HTML Context Violations
+
+```javascript
+// ❌ BAD: Unsafe innerHTML with user input
+element.innerHTML = req.query.name;
+element.outerHTML = userInput;
+document.write(req.body.content);
+
+// ❌ BAD: React dangerouslySetInnerHTML without sanitization
+<div dangerouslySetInnerHTML={{__html: userInput}} />
+
+// ❌ BAD: Vue v-html without sanitization
+<div v-html="userInput"></div>
+
+// ✅ GOOD: Use textContent for plain text
+element.textContent = req.query.name;
+
+// ✅ GOOD: Sanitize HTML with DOMPurify
+element.innerHTML = DOMPurify.sanitize(userInput);
+
+// ✅ GOOD: React with sanitization
+<div dangerouslySetInnerHTML={{__html: DOMPurify.sanitize(userInput)}} />
+
+// ✅ GOOD: Vue with v-text
+<div v-text="userInput"></div>
+```
+
+### 2. JavaScript Context Violations
+
+```javascript
+// ❌ BAD: eval with user input
+eval(req.query.code);
+new Function(userInput)();
+setTimeout(req.body.script, 1000);
+
+// ❌ BAD: Even dynamic eval is dangerous
+const code = getCodeFromSomewhere();
+eval(code);
+
+// ✅ GOOD: Never use eval - use JSON.parse for data
+const data = JSON.parse(jsonString);
+
+// ✅ GOOD: Use safe alternatives
+const func = functionMap[safeKey];
+func();
+```
+
+### 3. URL Context Violations
+
+```javascript
+// ❌ BAD: Unvalidated URL redirect (Open Redirect)
+window.location = req.query.redirect;
+location.href = userInput;
+window.open(req.query.url);
+
+// ✅ GOOD: Validate URLs against whitelist
+const allowedHosts = ['example.com', 'trusted.com'];
+const url = new URL(req.query.redirect);
+if (allowedHosts.includes(url.hostname)) {
+  window.location = url.href;
+}
+
+// ✅ GOOD: Use relative URLs only
+if (redirectUrl.startsWith('/')) {
+  window.location = redirectUrl;
+}
+```
+
+### 4. Event Handler Violations
+
+```javascript
+// ❌ BAD: Dynamic event handler with user input
+element.setAttribute('onclick', userInput);
+element.setAttribute('onerror', req.query.handler);
+
+// ✅ GOOD: Use addEventListener
+element.addEventListener('click', function() {
+  // Safe handler logic
+});
+
+// ✅ GOOD: Use data attributes
+element.dataset.action = userInput;
+```
+
+## Framework-Specific Guidance
+
+### React
+
+```javascript
+// ❌ Avoid dangerouslySetInnerHTML
+<div dangerouslySetInnerHTML={{__html: userInput}} />
+
+// ✅ Use children or textContent
+<div>{userInput}</div>
+
+// ✅ If HTML is needed, sanitize it
+import DOMPurify from 'dompurify';
+<div dangerouslySetInnerHTML={{__html: DOMPurify.sanitize(html)}} />
+```
+
+### Vue
+
+```javascript
+// ❌ Avoid v-html with user input
+<div v-html="userInput"></div>
+
+// ✅ Use interpolation or v-text
+<div>{{ userInput }}</div>
+<div v-text="userInput"></div>
+
+// ✅ If HTML is needed, sanitize it
+<div v-html="$sanitize(html)"></div>
+```
+
+### Angular
+
+```javascript
+// ❌ Avoid [innerHTML] with user input
+<div [innerHTML]="userInput"></div>
+
+// ✅ Use interpolation
+<div>{{ userInput }}</div>
+
+// ✅ Use DomSanitizer if HTML is needed
+import { DomSanitizer } from '@angular/platform-browser';
+this.safeHtml = this.sanitizer.sanitize(SecurityContext.HTML, html);
+```
+
+## Recommended Sanitization Libraries
+
+1. **DOMPurify** (Browser & Node.js)
+   ```javascript
+   import DOMPurify from 'dompurify';
+   const clean = DOMPurify.sanitize(dirty);
+   ```
+
+2. **xss** (Node.js)
+   ```javascript
+   const xss = require('xss');
+   const clean = xss(dirty);
+   ```
+
+3. **validator.js** (Node.js)
+   ```javascript
+   const validator = require('validator');
+   const escaped = validator.escape(input);
+   ```
+
+## Safe Alternatives
+
+| Unsafe Method | Safe Alternative |
+|--------------|------------------|
+| `innerHTML` | `textContent` or `innerText` |
+| `outerHTML` | `textContent` |
+| `document.write()` | DOM manipulation methods |
+| `eval()` | `JSON.parse()` |
+| `setTimeout(string)` | `setTimeout(function)` |
+| `dangerouslySetInnerHTML` | React children or DOMPurify |
+| `v-html` | `v-text` or sanitization |
+
+## How to Fix
+
+1. **Identify the Context**: Determine where the data will be output (HTML, JS, URL, etc.)
+2. **Choose Appropriate Method**:
+   - HTML: Use `textContent` or sanitize with DOMPurify
+   - JavaScript: Avoid dynamic code execution
+   - URL: Validate and whitelist
+3. **Apply Escaping/Sanitization**: Use context-appropriate escaping
+4. **Test**: Verify XSS payloads don't execute
+
+## Testing
+
+Create test files with common XSS payloads:
+
+```javascript
+const testPayloads = [
+  '<script>alert("XSS")</script>',
+  '<img src=x onerror=alert("XSS")>',
+  'javascript:alert("XSS")',
+  '<svg onload=alert("XSS")>',
+  '"><script>alert("XSS")</script>',
+];
+
+// Test that these are properly escaped/sanitized
+testPayloads.forEach(payload => {
+  const result = sanitize(payload);
+  assert(!result.includes('<script'));
+});
+```
+
+## References
+
+- [OWASP XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
+- [OWASP DOM XSS Prevention](https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html)
+- [DOMPurify Documentation](https://github.com/cure53/DOMPurify)
+- [CWE-79: Improper Neutralization of Input](https://cwe.mitre.org/data/definitions/79.html)
+
+## Configuration
+
+This rule can be configured in `.sunlint.json`:
+
+```json
+{
+  "rules": {
+    "S022": {
+      "enabled": true,
+      "severity": "error",
+      "contexts": {
+        "html": { "severity": "error" },
+        "javascript": { "severity": "error" },
+        "url": { "severity": "warning" }
+      }
+    }
+  }
+}
+```