@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/checking-http-security-headers/references/PLAYBOOK.md

@@ -0,0 +1,212 @@
+# HTTP Security Headers — Remediation Playbook
+
+## Baseline security-header bundle (every site)
+
+### nginx
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name example.com;
+
+    # HSTS — preload-eligible
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
+
+    # Clickjacking
+    add_header X-Frame-Options "DENY" always;
+
+    # MIME sniffing
+    add_header X-Content-Type-Options "nosniff" always;
+
+    # Referrer
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+    # Permissions baseline
+    add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), interest-cohort=()" always;
+
+    # CSP — start with report-only, tighten after collection
+    add_header Content-Security-Policy-Report-Only "default-src 'self'; report-uri /csp-report" always;
+
+    # Hide nginx version
+    server_tokens off;
+
+    # ... your location blocks ...
+}
+```
+
+The `always` flag is critical — without it nginx skips the headers on
+non-2xx responses, leaving error pages unprotected.
+
+### Caddy
+
+```caddy
+example.com {
+    header {
+        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+        X-Frame-Options "DENY"
+        X-Content-Type-Options "nosniff"
+        Referrer-Policy "strict-origin-when-cross-origin"
+        Permissions-Policy "camera=(), microphone=(), geolocation=(), interest-cohort=()"
+        Content-Security-Policy-Report-Only "default-src 'self'; report-uri /csp-report"
+        -Server
+    }
+}
+```
+
+### Apache (.htaccess or vhost)
+
+```apache
+<IfModule mod_headers.c>
+    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+    Header always set X-Frame-Options "DENY"
+    Header always set X-Content-Type-Options "nosniff"
+    Header always set Referrer-Policy "strict-origin-when-cross-origin"
+    Header always set Permissions-Policy "camera=(), microphone=(), geolocation=(), interest-cohort=()"
+    Header always set Content-Security-Policy-Report-Only "default-src 'self'; report-uri /csp-report"
+</IfModule>
+
+ServerTokens Prod
+ServerSignature Off
+```
+
+### Express (Node.js) via helmet
+
+```js
+const helmet = require('helmet');
+app.use(helmet({
+    contentSecurityPolicy: {
+        directives: {
+            defaultSrc: ["'self'"],
+            scriptSrc: ["'self'"],  // no unsafe-inline
+            styleSrc: ["'self'"],
+        },
+        reportOnly: true,
+    },
+    hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
+    referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+}));
+app.use((req, res, next) => {
+    res.setHeader('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), interest-cohort=()');
+    next();
+});
+```
+
+### FastAPI (Python)
+
+```python
+from starlette.middleware.base import BaseHTTPMiddleware
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request, call_next):
+        response = await call_next(request)
+        response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains; preload"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        response.headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=(), interest-cohort=()"
+        return response
+
+app.add_middleware(SecurityHeadersMiddleware)
+```
+
+### Rails
+
+```ruby
+# config/application.rb
+config.action_dispatch.default_headers.merge!(
+    'Strict-Transport-Security' => 'max-age=31536000; includeSubDomains; preload',
+    'X-Frame-Options' => 'DENY',
+    'X-Content-Type-Options' => 'nosniff',
+    'Referrer-Policy' => 'strict-origin-when-cross-origin',
+    'Permissions-Policy' => 'camera=(), microphone=(), geolocation=(), interest-cohort=()',
+)
+
+# config/initializers/content_security_policy.rb
+Rails.application.config.content_security_policy do |policy|
+    policy.default_src :self
+    policy.script_src  :self
+    policy.style_src   :self
+    policy.report_uri '/csp-report'
+end
+Rails.application.config.content_security_policy_report_only = true
+```
+
+## CSP rollout — report-only to enforce
+
+### Step 1 — report-only with violation endpoint
+
+Use the snippets above to ship `Content-Security-Policy-Report-Only`
+with a `report-uri`. Set up the endpoint to log violations:
+
+```python
+# FastAPI example
+@app.post("/csp-report")
+async def csp_report(request: Request):
+    body = await request.json()
+    logger.info("CSP violation", extra={"report": body})
+    return Response(status_code=204)
+```
+
+### Step 2 — collect for 2-4 weeks
+
+Group violations by `blocked-uri` and `violated-directive`. Categorize:
+
+- Legitimate inline scripts your own code includes → migrate to
+  external files or nonce-source.
+- Third-party widgets (analytics, chat, fonts) → add to allow-list.
+- Genuine injection attempts → keep blocked.
+
+### Step 3 — tighten policy and switch to enforcing
+
+```nginx
+add_header Content-Security-Policy "default-src 'self'; script-src 'self' https://cdn.example.com; style-src 'self' 'sha256-...'; report-uri /csp-report" always;
+```
+
+### Step 4 — monitor for regressions
+
+Keep the report-uri. Any new violation should trigger a follow-up.
+
+## HSTS preload submission checklist
+
+Before submitting at hstspreload.org:
+
+- [ ] HTTPS-only (HTTP → 301 redirect to HTTPS, not 302)
+- [ ] HSTS header on every HTTPS response
+- [ ] `max-age` ≥ 31536000
+- [ ] `includeSubDomains` directive present
+- [ ] `preload` directive present
+- [ ] All subdomains serve HTTPS (no http://subdomain.example.com)
+- [ ] No mixed content on any page
+
+Submit at https://hstspreload.org/. Approval takes 6-12 weeks; rejection
+is typically immediate.
+
+## CI integration
+
+```yaml
+- name: Security headers audit
+  run: |
+    python3 plugins/security/penetration-tester/skills/checking-http-security-headers/scripts/check_headers.py \
+        "${{ secrets.PROD_URL }}" \
+        --authorized \
+        --min-severity high \
+        --format json \
+        --output headers-audit.json
+- run: |
+    if jq 'any(.severity == "high" or .severity == "critical")' headers-audit.json | grep -q true; then
+      echo "::error::Security headers audit failed"
+      exit 1
+    fi
+```
+
+## Verification after remediation
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/checking-http-security-headers/scripts/check_headers.py \
+    https://example.com \
+    --authorized \
+    --min-severity medium
+```
+
+Expected: exit 0, no MEDIUM-or-higher findings. Cross-check with Mozilla
+Observatory (https://observatory.mozilla.org/) — target grade A+.

package/skills/checking-http-security-headers/references/THEORY.md

@@ -0,0 +1,137 @@
+# HTTP Security Headers — Theory
+
+## HSTS (Strict-Transport-Security)
+
+The first HTTPS visit is the soft spot. A network attacker sees the
+client typing `example.com` (HTTP-by-default) and rewrites the response
+to keep the conversation in cleartext (sslstrip pattern). HSTS closes
+this by pinning HTTPS: once the client has seen the header, it refuses
+to downgrade for the duration of `max-age`.
+
+For new clients (cache empty), HSTS doesn't help — the attacker still
+gets the first-visit window. The HSTS preload list closes that gap:
+sites on the list ship with browsers, so even first-visit users have
+HSTS pinned. Requirements for preload submission:
+
+- HTTPS only (no HTTP fallback)
+- `max-age` ≥ 31536000s (1 year)
+- `includeSubDomains` directive present
+- `preload` directive present
+- Manual submission at hstspreload.org
+
+Removal from the preload list takes 6–12 months (browsers ship the list
+in release binaries). Submit only when committed.
+
+## CSP (Content-Security-Policy)
+
+The browser-enforced rule set for what content the page can load and
+execute. The most effective single mitigation against XSS in the modern
+web stack — a CSP that blocks `'unsafe-inline'` and uses nonces or
+hashes for legitimate inline script means an injected `<script>alert(1)</script>` simply doesn't execute, even if the
+injection point exists.
+
+Rollout pattern:
+
+1. Start with `Content-Security-Policy-Report-Only` and a violation
+   endpoint (`report-uri /csp-report`).
+2. Collect violations for 2-4 weeks; categorize legitimate vs attack.
+3. Tighten the policy to permit the legitimate set; switch to
+   enforcing (`Content-Security-Policy` instead of report-only).
+4. Track violation rate; expect <1 / 10K page views in steady state.
+
+Common pitfalls:
+
+- `'unsafe-inline'` — the lazy default; defeats the XSS protection.
+  Replace inline handlers with addEventListener.
+- `'unsafe-eval'` — needed only by legacy build outputs; audit and
+  upgrade.
+- Over-broad `default-src` — `default-src *` defeats every directive
+  except those explicitly tighter.
+- Forgotten `frame-ancestors` — clickjacking opens if X-Frame-Options
+  is also missing.
+
+## X-Frame-Options vs CSP frame-ancestors
+
+X-Frame-Options is the legacy single-purpose header — DENY, SAMEORIGIN,
+or ALLOW-FROM. CSP `frame-ancestors` is the modern replacement with
+finer granularity. The browser respects both; if both present they
+both apply (most restrictive wins).
+
+For new sites, prefer `frame-ancestors`. For sites supporting older
+browsers (IE11 stragglers, embedded browsers in legacy mobile OSes),
+ship both.
+
+## X-Content-Type-Options: nosniff
+
+Without nosniff, the browser may "MIME-sniff" a response served as
+text/plain or application/octet-stream and decide it looks like HTML
+or JavaScript and execute it. The attack: upload a file with a .txt
+extension containing JavaScript; the server serves it as text/plain;
+the browser sniffs, sees `<script>`, executes.
+
+`nosniff` tells the browser to trust the Content-Type header. Combined
+with strict Content-Type values on user-uploaded content, this closes
+the class.
+
+## Referrer-Policy
+
+`Referer` (sic — the original spec misspelling persists) leaks the
+URL the user navigated from. Cross-origin, this is a privacy issue
+(internal URLs in your URL paths leak to wherever your users click
+links to). Within-origin it's useful for analytics.
+
+Modern recommendation: `strict-origin-when-cross-origin` — sends full
+URL same-origin, just the origin cross-origin. Strikes the right
+balance for most apps.
+
+`unsafe-url` sends everything to everyone. Don't.
+
+## Permissions-Policy
+
+Successor to Feature-Policy. Declares which device capabilities the
+page can request: camera, microphone, geolocation, USB, serial, idle-
+detection, etc. Default browser behavior is to PROMPT the user if the
+page asks; Permissions-Policy lets you assert "this page never asks"
+which is a defense-in-depth against compromised-page scenarios.
+
+Sensible baseline: `Permissions-Policy: camera=(), microphone=(),
+geolocation=(), interest-cohort=()`. `interest-cohort=()` opts out of
+FLoC / Topics API for users.
+
+## Server header version disclosure
+
+`Server: nginx/1.18.0` lets a scanner immediately enumerate every CVE
+affecting that nginx version. Information disclosure (CWE-200). Fix is
+trivial:
+
+- nginx: `server_tokens off;` → "nginx" without version
+- Apache: `ServerTokens Prod` → "Apache" without version
+- Caddy: doesn't disclose by default
+
+This isn't critical — sophisticated attackers fingerprint via response
+behavior, not headers. But it's free defense and audit-checkable.
+
+## Cache-Control on authenticated endpoints
+
+The trap: developer sets `Cache-Control: max-age=300` for performance.
+The endpoint serves authenticated content. A shared cache (corporate
+proxy, CDN edge) stores the response. The next request from a
+different user hits the cache and gets the first user's response.
+
+The fix is per-spec: `Cache-Control: private` (only the end-user's
+browser may cache) or `Cache-Control: no-store` (no caching anywhere).
+For authenticated APIs, `no-store` is the safer default; `private`
+allows browser-side caching which can leak in shared-device contexts.
+
+The pattern is so common that auditors call it out under CWE-525
+"Information Exposure Through Browser Caching".
+
+## Primary sources
+
+- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/)
+- [MDN — Strict-Transport-Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security)
+- [MDN — Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
+- [MDN — Permissions-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy)
+- [hstspreload.org](https://hstspreload.org/)
+- [Mozilla Observatory](https://observatory.mozilla.org/)
+- [W3C Permissions Policy](https://www.w3.org/TR/permissions-policy/)