# Content Security Policy

> Design and deploy Content-Security-Policy (CSP) to prevent XSS attacks and unauthorized resource loading.

- Skill: `sethdford/content-security-policy` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sethdford/content-security-policy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sethdford/content-security-policy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: sethdford (https://skillmd.com/u/sethdford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sethdford/content-security-policy

---


# Content-Security-Policy

Design and deploy CSP to prevent XSS and unauthorized resource loading.

## Context

You are a senior security engineer implementing CSP for $ARGUMENTS. CSP is the browser's defense against XSS by controlling which scripts, styles, and resources can load. A well-designed CSP blocks inline scripts and restricts external resources to trusted domains, making XSS significantly harder to exploit.

## Domain Context

- **CSP Directives**: `default-src`, `script-src`, `style-src`, `img-src`, `font-src`, `connect-src`, `frame-src`, `form-action`, `base-uri`
- **Values**: `'self'` (same origin), `'none'` (block all), domain whitelist, nonces (random tokens per request), hashes (SHA-256)
- **Violation Reporting**: `report-uri` or `report-to` for CSP violations; use to detect XSS attempts and policy issues
- **Browser Support**: Widely supported in modern browsers; older browsers ignore CSP (graceful degradation)

## Instructions

1. **Start with Report-Only Mode**:
   - Deploy CSP with `Content-Security-Policy-Report-Only` header first
   - Set `report-uri` to collect violations
   - Monitor for 1-2 weeks; fix legitimate violations (misconfigured resources)
   - Then enforce with `Content-Security-Policy` header (report-only + enforcement can coexist)

2. **Design Base Policy**:
   - `default-src 'self'` — allow same-origin resources by default
   - `script-src 'self'` — allow same-origin scripts only (no inline scripts)
   - `style-src 'self'` — allow same-origin styles only (no inline styles)
   - `img-src 'self' data: https:` — allow same-origin, data URIs, and HTTPS images
   - `font-src 'self'` — allow same-origin fonts only
   - `connect-src 'self'` — allow same-origin API calls only

3. **Allow Trusted External Resources**:
   - If you need external CDNs: `script-src 'self' cdn.jsdelivr.net`
   - If you need Google Fonts: `font-src 'self' fonts.googleapis.com; style-src 'self' fonts.googleapis.com`
   - Always prefer HTTPS for external resources
   - Whitelist specific subdomains, not entire domains (e.g., `trusted-cdn.com` not `*.example.com`)

4. **Secure Inline Scripts & Styles**:
   - **Option 1 (Nonces)**: Generate random nonce per request; include in `<script nonce="abc123">` and CSP header
     - `script-src 'nonce-abc123'` — only that script with matching nonce executes
   - **Option 2 (Hashes)**: Hash inline content; include in CSP header
     - `script-src 'sha256-hash'` — only scripts matching hash execute
   - **Option 3 (Refactor)**: Move inline scripts to external files (best practice)
   - Never use `'unsafe-inline'` or `'unsafe-eval'` unless absolutely necessary (defeats XSS protection)

5. **Monitor & Iterate**:
   - Review CSP violations in logs; identify patterns (third-party analytics, ads, etc.)
   - Add trusted domains as needed, but conservatively
   - Tighten policy over time (remove unnecessary directives)
   - Test CSP in different browsers (Chrome, Firefox, Safari, Edge)
   - Document policy rationale for future maintainers

## Anti-Patterns

- Setting `default-src *` or overly permissive policies; **this provides no protection against XSS**
- Using `'unsafe-inline'` to fix CSP violations; **refactor code instead; inline scripts defeat CSP's purpose**
- Not using nonces/hashes; **without them, you must rely on domain whitelisting, which is fragile**
- Ignoring CSP violation reports; **violations indicate XSS attempts or misconfigured resources**
- Setting CSP on sensitive endpoints only; **apply consistently across entire application**

## Further Reading

- Content-Security-Policy Spec: https://w3c.github.io/webappsec-csp/
- OWASP CSP Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html
- MDN CSP Guide: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
- CSP Violations Handling: https://developer.mozilla.org/en-US/docs/Web/API/SecurityPolicyViolationEvent