Gonzo17/nuxt-csp-report
GitHub: Gonzo17/nuxt-csp-report
一个 Nuxt 模块，用于收集、规范化和持久化内容安全策略（CSP）报告以辅助安全分析。
Stars: 18 | Forks: 0
# nuxt-csp-report
[][npm-version-href]
[][npm-downloads-href]
[][license-href]
[][nuxt-href]
[](https://nuxt.care/?search=nuxt-csp-report)
一个用于收集、规范化和持久化内容安全策略（CSP）报告的 Nuxt 模块。
**兼容性：** Nuxt 3（3.12.0 及以上版本）和 Nuxt 4。
[✨ Release Notes](/CHANGELOG.md)
## 什么是 CSP 和 CSP 报告？
CSP 是一种 HTTP 响应头，用于控制文档允许加载哪些资源。例如，设置 `Content-Security-Policy: script-src example.com;` 将阻止任何脚本标签从 `example.com` 之外的源加载。任何违规行为都会在浏览器控制台中被记录。此外，还可以在 CSP 头中设置一个报告端点，浏览器会将 CSP 报告发送至此。
一旦你决定使用 CSP 来保护你的网站，你很可能希望在生产环境中分析 CSP 头部是否配置正确。这在加载更多外部资源时可能会变得棘手。尤其是动态加载的脚本（例如根据你的国家或你的同意状态），对每个用户来说可能并不相同。这就是 CSP 报告发挥作用的地方，因为它们展示了用户在浏览器中实际遇到的 CSP 违规情况。
## 功能特性
- 📋 注册一个用于 CSP 报告的 POST 端点
- 📡 为 `report-to` 支持添加 `Reporting-Endpoints` 响应头
- 🔄 同时支持旧版 `report-uri` 和 `report-to` 格式的报告
- ✅ 使用 Zod 验证并规范化报告
- 💾 通过 unstorage 持久化报告
- 📝 完整的 TypeScript 支持并导出正确的类型
## 快速开始
将模块安装到你的 Nuxt 应用中：
```
npm install nuxt-csp-report
```
将其添加到 `nuxt.config.ts`：
```
export default defineNuxtConfig({
modules: ['nuxt-csp-report'],
cspReport: {
// Module options
},
})
```
## 示例
* 最小起步示例：[](https://stackblitz.com/github/Gonzo17/nuxt-csp-report/tree/main/examples/minimal?file=nuxt.config.ts)
* 源码示例：[examples/minimal/nuxt.config.ts](examples/minimal/nuxt.config.ts) 和 [examples/minimal/app.vue](examples/minimal/app.vue)。
* StackBlitz 在 iframe 中运行；示例 CSP 允许 `frame-ancestors` 针对 `*.stackblitz.io`、`*.webcontainer.io` 和 `*.local-credentialless.webcontainer.io`。
* 开发用 Playground：[playground/nuxt.config.ts](playground/nuxt.config.ts)，使用 nuxt-security 默认配置并启用额外日志。
## 用法
该模块开箱即用，默认配置即可满足大多数需求。
在大多数使用场景中，简单的日志记录已经足够。如果你希望分析 CSP 报告，可以使用 `storage` 选项将报告持久化到 KV 存储中。
### nuxt-security
内容安全策略通过特定头部设置。你可以通过 Nuxt/Nitro 自行处理，但我强烈推荐使用 [nuxt-security](https://github.com/Baroshem/nuxt-security)。
以下是如何结合使用这两个模块的最小示例：
```
export default defineNuxtConfig({
modules: ['nuxt-security', 'nuxt-csp-report'],
security: {
headers: {
contentSecurityPolicy: {
'report-uri': '/api/csp-report',
// your CSP headers
},
},
},
})
```
### 进阶：访问报告
根据你的使用场景，你可能希望访问 CSP 报告。你可以使用 `useStorage` 来实现：
```
export default defineNuxtConfig({
modules: ['nuxt-csp-report'],
cspReport: {
storage: {
driver: {
name: 'redis',
options: {
// Your redis configuration
}
}
},
},
})
```
```
import { type NormalizedCspReport } from 'nuxt-csp-report'
const storage = useStorage
('csp-report-storage')
```
## 选项
### endpoint
* 类型：`string`
* 默认值：`/api/csp-report`
* 描述：可选。CSP 报告端点的路径。
### reportingEndpointsHeader
* 类型：`boolean`
* 默认值：`false`
* 描述：可选。将 `Reporting-Endpoints` 响应头添加到你的 HTML 响应中，使用 `'csp-endpoint'` 作为键，`endpoint` 配置值作为值。如果希望在 CSP 配置中使用 `report-to csp-endpoint`，此头部是必需的。
### console
* 类型：`'summary' | 'full' | false`
* 默认值：`'summary'`
* 描述：可选。将报告记录到服务器控制台。`'full'` 将打印 `NormalizedCspReport` 对象。
### storage
* 类型：参见下方字段。
* 描述：可选。使用 `unstorage` 设置存储，这是 Nitro 和 Nuxt 的一部分。
### storage.driver
* 类型：`BuiltinDriverOptions`
* 描述：定义来自 `unstorage` 的驱动。你可以使用与 Nuxt 相同的表示法和驱动：
* https://nuxt.com/docs/4.x/directory-structure/server#server-storage
* https://nitro.build/guide/storage
* https://unstorage.unjs.io/drivers
### storage.keyPrefix
* 类型：`string`
* 默认值：`csp-report`
* 描述：可选。存储报告时的键前缀。
标签：CSP, CSP 报告分析, HTTP 安全头, Nuxt 3, Nuxt 4, Nuxt 模块, SEO 安全, TypeScript, Unstorage, Web 安全, Zod 验证, 人工智能安全, 内容安全策略, 前端安全, 合规性, 安全报告, 安全插件, 安全标准, 报告端点, 持久化存储, 日志收集, 自动化攻击, 规则仓库, 跨域报告