@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/auditing-cors-policy/references/PLAYBOOK.md

@@ -0,0 +1,220 @@
+# CORS Remediation Playbook
+
+## Pattern 1 — Replace reflection with allow-list
+
+### nginx
+
+```nginx
+map $http_origin $cors_origin {
+    default "";
+    "~^https://app\.example\.com$" "$http_origin";
+    "~^https://admin\.example\.com$" "$http_origin";
+}
+
+server {
+    location /api/ {
+        add_header Access-Control-Allow-Origin $cors_origin always;
+        add_header Access-Control-Allow-Credentials true always;
+        add_header Vary Origin always;
+        if ($request_method = OPTIONS) {
+            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE" always;
+            add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
+            add_header Access-Control-Max-Age 3600 always;
+            return 204;
+        }
+    }
+}
+```
+
+The `map` directive evaluates each allowed origin pattern. If none match, `$cors_origin` is empty and the Allow-Origin header is sent empty (browser rejects, request blocked).
+
+### Express (Node.js)
+
+```js
+const cors = require('cors');
+app.use('/api', cors({
+    origin: ['https://app.example.com', 'https://admin.example.com'],
+    credentials: true,
+    methods: ['GET', 'POST', 'PUT', 'DELETE'],
+    allowedHeaders: ['Authorization', 'Content-Type'],
+    maxAge: 3600,
+}));
+```
+
+The `cors` middleware sets `Vary: Origin` automatically; the `origin` array does exact-match against the request Origin.
+
+### Spring (Java)
+
+```java
+@Configuration
+public class WebConfig implements WebMvcConfigurer {
+    @Override
+    public void addCorsMappings(CorsRegistry registry) {
+        registry.addMapping("/api/**")
+            .allowedOrigins("https://app.example.com", "https://admin.example.com")
+            .allowedMethods("GET", "POST", "PUT", "DELETE")
+            .allowedHeaders("Authorization", "Content-Type")
+            .allowCredentials(true)
+            .maxAge(3600);
+    }
+}
+```
+
+### FastAPI (Python)
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://app.example.com", "https://admin.example.com"],
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE"],
+    allow_headers=["Authorization", "Content-Type"],
+    max_age=3600,
+)
+```
+
+### Rails 7
+
+```ruby
+# config/initializers/cors.rb
+Rails.application.config.middleware.insert_before 0, Rack::Cors do
+    allow do
+        origins 'app.example.com', 'admin.example.com'  # exact list
+        resource '/api/*',
+            headers: :any,
+            methods: [:get, :post, :put, :delete],
+            credentials: true,
+            max_age: 3600
+    end
+end
+```
+
+## Pattern 2 — Fix subdomain pattern matching
+
+### Wrong (JavaScript)
+
+```js
+if (origin.endsWith('.example.com')) { allow(origin); }
+```
+
+Matches `evil.example.com.attacker.com`.
+
+### Right (JavaScript)
+
+```js
+const url = new URL(origin);
+const trustedHosts = ['example.com'];
+if (
+    trustedHosts.includes(url.hostname) ||
+    trustedHosts.some(h => url.hostname.endsWith('.' + h))
+) {
+    allow(origin);
+}
+```
+
+The `new URL()` parse + `hostname` extraction + leading-dot check eliminates the suffix-string bypass.
+
+### Right (Python)
+
+```python
+from urllib.parse import urlparse
+
+TRUSTED_HOSTS = {'example.com'}
+
+def is_origin_allowed(origin: str) -> bool:
+    try:
+        hostname = urlparse(origin).hostname
+    except Exception:
+        return False
+    if hostname in TRUSTED_HOSTS:
+        return True
+    return any(hostname.endswith('.' + h) for h in TRUSTED_HOSTS)
+```
+
+## Pattern 3 — Remove Allow-Origin:null trust
+
+If your allow-list contains the string `'null'`, remove it. There's no legitimate cross-origin sender of Origin:null worth trusting.
+
+Edge case: if you have a legitimate use case for sandboxed-iframe access to a specific endpoint, design around it explicitly (e.g., a separate auth-token-in-URL flow); do not extend CORS trust to Origin:null.
+
+## Pattern 4 — Always set Vary:Origin when per-origin
+
+### nginx (global for /api/)
+
+```nginx
+location /api/ {
+    add_header Vary Origin always;
+}
+```
+
+### Caddy
+
+```caddy
+example.com {
+    header /api/* Vary Origin
+}
+```
+
+### CDN-level (CloudFlare Workers, Fastly VCL)
+
+Inject `Vary: Origin` on every response from your origin behind the CDN. Configure the CDN to respect Vary on cache lookups.
+
+## Pattern 5 — Cap preflight cache at 24h or less
+
+Browsers cap at 7200s anyway, so setting it to 3600 is the practical move:
+
+```
+Access-Control-Max-Age: 3600
+```
+
+Anything higher confuses the next engineer reading the config.
+
+## Pattern 6 — Restrict Allow-Methods
+
+Replace `Access-Control-Allow-Methods: *` with the explicit list of methods your endpoint actually serves:
+
+```
+Access-Control-Allow-Methods: GET, POST, PUT, DELETE
+```
+
+## Pattern 7 — Disable Allow-Credentials if not needed
+
+If your endpoint doesn't need to read user cookies cross-origin (most public APIs don't — they use Authorization: Bearer instead), drop `Access-Control-Allow-Credentials: true` entirely. This eliminates the entire credential-theft attack surface.
+
+For bearer-token APIs:
+
+```
+Access-Control-Allow-Origin: *
+# (no Allow-Credentials — bearer tokens come in Authorization header, not cookies)
+```
+
+The wildcard is safe here because the browser won't attach cookies; the only way to authenticate is the bearer token, which the cross-origin JS already had to obtain.
+
+## CI integration
+
+```yaml
+- name: CORS audit on changed endpoints
+  run: |
+    for ENDPOINT in $(./scripts/list-changed-endpoints.sh); do
+      python3 plugins/security/penetration-tester/skills/auditing-cors-policy/scripts/audit_cors.py \
+          "$ENDPOINT" --authorized --min-severity high --format jsonl >> cors-audit.jsonl
+    done
+- run: |
+    if [ -s cors-audit.jsonl ] && jq -s 'any(.severity == "critical" or .severity == "high")' cors-audit.jsonl | grep -q true; then
+      echo "::error::CORS audit found high/critical findings"
+      exit 1
+    fi
+```
+
+## Verification after remediation
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/auditing-cors-policy/scripts/audit_cors.py \
+    https://api.example.com/endpoint \
+    --authorized \
+    --min-severity high
+```
+
+Expected: exit code 0, only INFO-level finding "No CORS misconfiguration detected".

package/skills/auditing-cors-policy/references/THEORY.md

@@ -0,0 +1,142 @@
+# CORS Theory
+
+## What CORS actually does
+
+By default, a browser running JavaScript on `https://app.example.com`
+cannot read responses from `https://api.different.com` — the Same-
+Origin Policy blocks the read. CORS is the controlled relaxation: the
+target server says "yes, this specific origin can read my responses,
+and here are the conditions."
+
+The browser enforces; the server announces. Two header categories:
+
+- **Response headers** (server → browser): `Access-Control-Allow-
+  Origin`, `-Credentials`, `-Methods`, `-Headers`, `-Max-Age`, `-Expose-
+  Headers`.
+- **Request headers** (browser → server): `Origin` (auto-set),
+  `Access-Control-Request-Method`, `-Request-Headers` (preflight only).
+
+The browser sends `Origin` on every cross-origin request. If the
+response doesn't allow that origin, the browser hides the response
+from JavaScript (but the request still hit the server — caveat
+explains the CSRF angle below).
+
+For "non-simple" requests (anything other than GET/HEAD/POST with
+limited content types, or with custom headers), browsers send an
+`OPTIONS` preflight first. The server's preflight response declares
+allowed methods + headers + cache duration. If preflight passes, the
+real request proceeds.
+
+## Why reflection is dangerous
+
+The "easy" fix when a CORS bug ticket lands: read the incoming Origin
+header and echo it into Allow-Origin. The request from
+`https://api.partner.com` works; the request from
+`https://my-frontend.com` works; QA closes the ticket.
+
+The problem: requests from `https://attacker.example.com` ALSO work.
+If the endpoint serves authenticated content and `Allow-Credentials:
+true` is set, the browser sends the user's cookies on the cross-origin
+request AND lets the attacker's JavaScript read the response. Full
+session-theft via a malicious page the victim visits while logged in.
+
+The fix is not "validate the Origin format" — it's "allow-list a
+specific set of trusted origins server-side, check exact equality
+against that allow-list, return the matched origin or refuse."
+
+## The credentials + wildcard combination
+
+The Fetch standard makes this combo illegal — browsers reject the
+response. Server is asserting Allow-Origin:* AND Allow-Credentials:
+true; browser sees both, refuses to expose the response to JavaScript.
+
+So why is this a CRITICAL finding? Because the server-side intent is
+wrong. A future server-config change could replace * with reflection,
+or a future browser bug could relax the rule. The combination signals
+the developer didn't understand the model — and that misunderstanding
+will recur in the next CORS-related change.
+
+## Subdomain-pattern bypass
+
+A common shorthand: "trust any subdomain of example.com." The naive
+implementation in JavaScript / config:
+
+```js
+if (origin.endsWith('.example.com')) { allow(origin); }
+```
+
+This matches `evil.example.com.attacker.com` because `.endsWith()` on
+a string just checks the suffix — it doesn't parse the URL into host
+parts. The attacker registers `attacker.com`, sets up DNS for
+`*.example.com.attacker.com`, and gets a wildcard CORS pass.
+
+The fix: parse the Origin as a URL, extract `hostname`, then check
+either exact equality or proper subdomain logic
+(`hostname === 'example.com' || hostname.endsWith('.example.com')`
+— note the second form checks the leading dot, which the buggy form
+omits).
+
+## Origin: null
+
+Three places this comes from:
+
+1. Sandboxed iframes — `<iframe sandbox>` sends Origin:null.
+2. `data:` URLs — pages loaded from data URLs send Origin:null.
+3. `file:` URLs — local file pages send Origin:null.
+
+If your server trusts Origin:null, any page that ends up in a
+sandboxed iframe can read your cross-origin responses. Attackers
+embed your target site in a sandboxed iframe on attacker.com, the
+browser sends Origin:null, your server returns Allow-Origin:null,
+attacker reads the response.
+
+Never trust Origin:null. There is no legitimate cross-origin use case
+that needs it.
+
+## Vary:Origin and CDN cache poisoning
+
+If your CORS response is per-origin (Allow-Origin varies based on the
+Origin header), the cache layer must vary on Origin too. Otherwise:
+
+1. User from `https://trusted.com` requests `/api/profile`. Server
+   responds `Allow-Origin: https://trusted.com`. CDN caches the response.
+2. Attacker from `https://attacker.com` requests `/api/profile`. CDN
+   returns the cached response, including `Allow-Origin: https://trusted.com`.
+3. Attacker's request still doesn't satisfy the Allow-Origin match
+   (browser checks), so no read happens — BUT the cache is now
+   serving a different origin's CORS headers to attacker, which
+   becomes a poisoning vector for downstream attacks.
+
+The fix: `Vary: Origin` on every CORS-varying response. Every modern
+framework's CORS middleware does this; hand-rolled CORS configs
+forget it.
+
+## Preflight cache duration
+
+`Access-Control-Max-Age` controls how long the browser caches the
+preflight response. Higher = fewer round trips (perf gain) but
+slower CORS-policy revocation (if you change the allow-list, browsers
+won't re-preflight until cache expires).
+
+Chrome and Firefox cap at 7200s (2h) regardless of what the server
+says, so values above 7200s don't actually help. Setting it explicitly
+to 86400s (24h) or higher is a misunderstanding rather than a security
+issue — flagged LOW for awareness.
+
+## CORS does NOT prevent CSRF
+
+This trips up developers. CORS controls JavaScript's ability to READ
+responses cross-origin. The cross-origin REQUEST is still sent
+(cookies, headers, everything). If your server changes state based on
+the request alone (POST that updates a record without reading the
+response), CORS doesn't help.
+
+Pair CORS audit with CSRF audit (skill #13 in another plugin —
+`csrf-protection-validator`) for full coverage.
+
+## Primary sources
+
+- [Fetch Standard — CORS protocol](https://fetch.spec.whatwg.org/#cors-protocol)
+- [MDN — Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+- [OWASP A05:2021 Security Misconfiguration](https://owasp.org/Top10/A05_2021-Security_Misconfiguration/)
+- [CWE-942 Permissive Cross-domain Policy with Untrusted Domains](https://cwe.mitre.org/data/definitions/942.html)