Nooshu/CSP-Playground

# CSP 练习场 一个基于浏览器的工具，用于构建 [内容安全策略](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) (CSP) 头部。启用指令，选择常见关键字，添加自定义源 URL，查看实时安全评分，并复制生成的策略或现成的代码片段到你的 Web 服务器。 该应用完全在浏览器中运行以进行策略编辑。**从 URL 导入**使用小型的服务端查找（开发中使用 Vite middleware，生产中使用 [Cloudflare Pages Functions](https://developers.cloudflare.com/pages/functions/)），以便你可以从 HTTP 头部或 HTML meta 标签中获取现有策略。**粘贴头部或策略**完全在浏览器中运行——粘贴完整的响应头部块或单行 `Content-Security-Policy` 即可提取并导入 CSP。 ## 目的 内容安全策略 (CSP) 是防御跨站脚本攻击 (XSS) 和相关注入攻击最有效的方法之一，但其语法很容易写错。CSP Playground 通过以下方式降低了编写正确策略的门槛： - 将每个标准指令映射到易于访问的表单控件 - 解释 sandbox 标志并链接到 MDN 文档 - 生成 nonce、style 属性哈希和服务器配置代码片段 - 启发式地为你的策略评分并提出具体的改进建议 如果某个网站还没有 CSP，导入器会链接到 [why-csp.html](why-csp.html)——这是一份关于为什么以及如何采用该策略的简短指南。 ## 功能 ### 策略编辑器 - 基于表单的编辑器，支持**所有标准 CSP 指令**，按类别分组： - Fetch (`default-src`, `script-src`, `style-src`, …) - Document (`base-uri`, `sandbox`, …) - Navigation (`form-action`, `frame-ancestors`, …) - Reporting (`report-uri`, `report-to`, …) - 其他 (`upgrade-insecure-requests`, Trusted Types, …) - 独立启用/禁用每个指令 - **关键字下拉菜单**，提供常用值 (`'self'`, `'none'`, `'unsafe-inline'`, `'strict-dynamic'`, schemes 等) - 每个指令支持多个自定义源输入，并提供添加/删除控件 - **Sandbox 指令** — 每个 sandbox 标志都有对应的复选框列表，每个都带有一个 **?** 帮助图标，在悬停/聚焦时显示描述 - **Trusted Types** 指令带有适当的单值或多值控件 - 每个指令名称旁边都有 **MDN 文档链接** ### 导入现有策略 从在线 URL 或粘贴的文本将现有的 CSP 导入到构建器中： - **从 URL 导入** — 输入网站 URL 并从以下位置获取其 CSP： - `Content-Security-Policy` / `Content-Security-Policy-Report-Only` 响应头部 - HTML 中的 `` 标签 - **粘贴头部或策略** — 直接粘贴到表单中（无需服务端查找）： - 完整的 HTTP 响应头部；将自动提取 `Content-Security-Policy` - 单独的一行 `Content-Security-Policy:` 头部信息 - 根据解析出的策略自动填充构建器表单 - **验证 CSP** 检查格式并提出更正建议（适用于 URL 和粘贴导入） - 未找到策略时的优雅处理（提供指向 why-CSP 指南的链接） ### Nonce 和哈希助手 - **Script/style nonce 助手**（作用于 `script-src`, `script-src-elem`, `style-src`, `style-src-elem`）： - 生成**示例**加密随机 nonce，并为内联或外部脚本/样式表生成匹配的 HTML 代码片段 - 将 `'nonce-…'` 添加到指令中 - **生产环境注意事项：** 在生产环境中，必须在服务器上为**每个 HTTP 响应生成新的 nonce**，并将相同的值注入到你的 CSP 头部和 HTML 中——切勿重复使用从此工具复制的固定 nonce - **Style 属性哈希助手**（作用于 `style-src-attr`）： - 通过 Web Crypto 对确切的 `style="…"` 属性值进行 SHA-256 哈希计算 - 在需要时添加 `'sha256-…'` 和 `'unsafe-hashes'` - 复制带有已计算哈希属性的示例元素 ### 实时输出和导出 - 实时预览**策略值**和完整的 **HTTP 头部行** - 切换**强制执行 (enforce)** 与 **Content-Security-Policy-Report-Only** 以实现安全部署 - 一键复制策略值、头部或 Web 服务器代码片段 - 导出适用于 **Apache**、**Nginx**、**Caddy**、**LiteSpeed**、**Microsoft IIS**、**Traefik** 和 **Envoy** 的代码片段 - 带有 MDN 安全 CSP 实施指南链接的部署免责声明 ### 安全评分 - 实时**字母等级**（差 → 优秀）及数字得分 - 影响得分下降或提升的因素明细 - **可操作的建议**及预计的得分加成 - 点击建议可滚动到表单中的相关指令 - 评分中反映了 Report-only 模式（不会拦截违规行为） ### 无障碍设计 - 语义化 HTML、标签、焦点样式以及用于动态更新的 `aria-live` 区域 - 支持键盘访问的控件和工具提示 ## 技术栈 | 层级 | 选择 | |-------|--------| | UI | TypeScript, 原生 DOM (无框架) | | Bundler | [Vite](https://vite.dev/) | | Package manager | [Yarn v1](https://classic.yarnpkg.com/) (`yarn.lock` 是权威配置) | | Tests | [Vitest](https://vitest.dev/) + jsdom, v8 coverage | | Deployment | 在 [Cloudflare Pages](https://pages.cloudflare.com/) 上的静态 `dist/` + Pages Functions | ## 入门指南 ### 前置条件 - [Node.js](https://nodejs.org/) 18+ (`.nvmrc` 将本地开发环境固定为 Node 20) - [Yarn](https://yarnpkg.com/) 1.x ### 安装 ``` yarn install ``` ### 开发 ``` yarn dev ``` 打开 [http://localhost:5173](http://localhost:5173)。URL 导入通过 Vite middleware shim 实现——日常的 UI 开发不需要 Wrangler。 ### 构建 ``` yarn build ``` 静态文件将输出到 `dist/`。使用以下命令预览生产构建： ``` yarn preview ``` ### 测试 ``` yarn test # Run once yarn test:watch # Watch mode yarn test:coverage # Coverage with thresholds (100% lines/statements/functions, 95% branches) ``` ### 依赖完整性 直接依赖**被固定在精确的版本**。在任何依赖更新后，当所有更改完成时，运行**一次**验证： ``` yarn verify:deps ``` 完整的依赖策略请参阅 [AGENTS.md](AGENTS.md)。 ## 用法 1. 可选择在顶部使用**导入现有策略**——从 URL 获取，或粘贴响应头部 / `Content-Security-Policy` 头部行——然后点击 **Import CSP**。 2. 使用复选框启用指令（例如 `default-src`）。 3. 从下拉菜单中添加关键字或输入自定义源（例如 `https://cdn.example.com`）。 4. 在需要安全允许内联内容的地方使用 nonce 或 style-hash 助手。 5. 查看**安全评分**面板，如有帮助，请应用相关建议。 6. 在输出面板中查看生成的策略。 7. 复制策略、完整的头部或 Web 服务器配置代码片段。 切换 **Content-Security-Policy-Report-Only** 以在强制执行前生成用于测试的 report-only 头部。 ## 项目布局 ``` src/csp/ Policy parsing, building, scoring, keywords, hashes, server exports src/ui/ Form components, output panel, security score, helpers src/api/ Client fetch wrapper for CSP lookup server/ Shared lookup logic + Vite dev middleware functions/api/ Cloudflare Pages Function (production API) tests/ Vitest unit and integration tests public/data/ Sandbox flag descriptions (loaded for tooltips) ``` ## 部署到 Cloudflare Pages 生产环境中的 URL 导入使用 [Cloudflare Pages Functions](https://developers.cloudflare.com/pages/functions/)。位于 [`functions/api/csp-lookup.ts`](functions/api/csp-lookup.ts) 的函数在 Cloudflare 的边缘节点上暴露了 `POST /api/csp-lookup` 接口——与本地开发的契约相同。 ### Dashboard 设置 1. 将此仓库连接到 Cloudflare Pages。 2. **构建命令：** `yarn build` 3. **构建输出目录：** `dist` 4. **根目录 / 路径：** 留空（仓库根目录） Cloudflare 会从 `wrangler.toml` 读取 `pages_build_output_dir`，并将 `functions/` 与静态资源一起部署。不需要部署命令或单独的 Worker。 ### 本地 Pages 预览 在本地测试静态资源和 Pages Function： ``` yarn pages:dev ``` ### CLI 部署 ``` yarn pages:deploy ``` 需要 [Wrangler](https://developers.cloudflare.com/workers/wrangler/) 身份验证 (`wrangler login`)。 ## 贡献 / AI 代理 - [AGENTS.md](AGENTS.md) — 编码代理规范 (也可作为 `AGENT.md` 使用) - `.cursor/rules/` — 用于依赖固定和项目上下文的 Cursor 专用规则 - `src/`, `server/`, 和 `functions/` 中导出 API 的 TSDoc 注释 ## 许可证 [MIT](LICENSE)

标签：Syscall, Web开发, 内容安全策略, 前端工具, 浏览器端应用, 自动化攻击, 规则仓库