Stats
Actions
Tags
From cors-audit
This skill performs a comprehensive CORS (Cross-Origin Resource Sharing) audit on web projects. It should be used when diagnosing CORS errors, setting up CORS for new projects, reviewing CORS configuration after deployment issues, or validating that CORS is handled correctly across all layers (gateway, backend, frontend). Covers standard frontend-backend setups, micro-app architectures (Qiankun, single-spa), and multi-origin dynamic-origin scenarios.
How this skill is triggered — by the user, by Claude, or both
Slash command
/cors-audit:cors-auditThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Perform a systematic CORS configuration audit across all layers of a web project. Identify misconfigurations, redundant headers, and security issues before they cause production problems.
Perform a systematic CORS configuration audit across all layers of a web project. Identify misconfigurations, redundant headers, and security issues before they cause production problems.
Match user's language: Respond in the same language the user uses.
scripts/validate_cors.py — Automated CORS validator (Python stdlib, no dependencies)references/cors_checklist.md — Detailed per-item audit checklist with pass/fail criteriareferences/architecture_patterns.md — CORS strategy for each architecture type with configuration examplesreferences/script_reference.md — Full script subcommands, options, and usage examplesBefore starting, run the preflight check:
python scripts/validate_cors.py preflight
Check-Fix table:
| Check | Fix |
|---|---|
| Python < 3.7 | Install Python 3.7+ (brew install python3 / apt install python3) |
| Python not found | Install Python (brew install python3 / apt install python3 / winget install Python.Python.3) |
When live endpoints are unreachable (network failures, firewall, VPN required):
| Situation | Strategy |
|---|---|
| Live endpoint unreachable | Skip Phases 3/5 live validation; rely on static config analysis only |
| Some endpoints reachable, some not | Validate reachable endpoints; report unreachable ones as "skipped — not reachable" |
| No network access at all | Run static-only audit (Phases 1, 2, 4 config review); note that live validation was skipped in the report |
Always inform the user which validations were skipped and why. Static config analysis alone can still catch the majority of CORS issues (duplicate headers, wildcard+credentials, missing OPTIONS handlers).
Print this checklist at the start and update it as each phase completes:
Progress:
- [ ] Phase 1: Architecture Discovery
- [ ] Phase 2: Config Collection & Static Validation
- [ ] Phase 3: Single-Layer Rule Verification
- [ ] Phase 4: Best Practices Validation
- [ ] Phase 5: Environment-Specific Validation
- [ ] Phase 6: Report Findings
Determine the project's architecture type before examining configuration:
references/architecture_patterns.md:
Collect CORS config from every layer. For each, document: where headers are set, Allow-Origin value, Allow-Credentials flag, OPTIONS handling.
| Layer | What to check |
|---|---|
| Gateway/Proxy | Config file (Caddyfile, nginx.conf) — CORS headers, OPTIONS handling |
| Backend | CORS middleware config — origin lists, regex patterns, credential flags |
| Frontend | API base URL — same-origin, relative path, or cross-origin absolute URL? |
| Environment vars | Different CORS settings per environment (dev/staging/production)? |
Run static validation on each config file found:
python scripts/validate_cors.py validate --config path/to/Caddyfile
The #1 CORS best practice: CORS headers must be set by exactly ONE layer. Duplicate headers are the most common CORS bug.
header_down -Access-Control-Allow-Origin; Nginx: proxy_hide_header)Verify on live endpoints (most reliable — catches headers from any layer):
python scripts/validate_cors.py validate --url https://your-api.com/health --origin https://your-frontend.com
Reference references/cors_checklist.md for the full per-item checklist. Key areas:
* with credentials; prefer specific origins in production; dynamic reflection for multiple originsMax-AgeAllow-Credentials: true requires specific origin (not *)Allow-Headers and Allow-Methods must cover all frontend usageRun live validation on production endpoints — see references/script_reference.md for batch and micro-app testing examples.
Produce a summary table and classify issues:
* with credentials, missing CORS entirelyMax-Age, overly broad Allow-HeadersGenerate a JSON report: see references/script_reference.md for output format options (--format, --output, --limit).
Exit codes reflect script execution status, not audit severity. Finding severity is in the JSON summary field.
| Symptom | Likely Cause | Fix |
|---|---|---|
"multiple values *, https://x.com" | Two layers both add Origin header | Apply single-layer rule (Phase 3) |
| "No Access-Control-Allow-Origin header" | CORS not configured for this origin | Add origin to allowlist |
| Preflight blocked by CORS | OPTIONS not handled | Add OPTIONS handler returning 204 |
Request to localhost from production | Frontend API URL not set for prod | Set API base URL to gateway domain |
| 404 on API when embedded as micro-app | Relative path resolves to host domain | Use absolute URL to gateway |
| Works standalone, fails when embedded | Origin is host domain, not app domain | Allow host domain in CORS config |
| Server-to-server calls unaffected | CORS is browser-only | Investigate auth/network issues instead |
npx claudepluginhub psylch/cors-audit-skill --plugin cors-auditValidates CORS configurations in web apps/APIs for security misconfigurations like wildcard origins, origin reflection, permissive methods/headers.
Verifies CORS policy enforcement by testing origin reflection, null origin, subdomain bypass, wildcard-with-credentials, and preflight correctness using targeted curl and browser tests.
Audits PHP CORS configurations for security issues like wildcard origins, credentials with wildcards, dynamic origin reflection, missing preflight handling, and overly permissive policies.