feat: Add cspReport utility to generate CSP reports and recommendations

.changeset/csp-report.md

@@ -0,0 +1,7 @@
+---
+"@cronn/playwright-utils": minor
+---
+
+Add `cspReport` to evaluate a `Content-Security-Policy` header against recommended directives and render the result as a Markdown report for file snapshots.
+
+Add `getCspHeader` to extract the `Content-Security-Policy` header from a page response, falling back to an empty string.

data/test/validation/csp-report/does_not_require_base_directives_if_both_variants_are_defined.md

@@ -0,0 +1,22 @@
+# CSP Report
+
+## Detected Directives
+
+| Directive                   | Value               |
+| --------------------------- | ------------------- |
+| `upgrade-insecure-requests` | _none_              |
+| `trusted-types`             | `angular`           |
+| `require-trusted-types-for` | `'script'`          |
+| `default-src`               | `'self'`            |
+| `script-src-elem`           | `'nonce-[NONCE_0]'` |
+| `script-src-attr`           | `'none'`            |
+| `style-src-elem`            | `'nonce-[NONCE_1]'` |
+| `style-src-attr`            | `'none'`            |
+| `object-src`                | `'none'`            |
+| `base-uri`                  | `'none'`            |
+| `form-action`               | `'self'`            |
+| `frame-ancestors`           | `'none'`            |
+
+## Recommendations
+
+None

data/test/validation/csp-report/evaluates_missing_directives_using_their_fallback.md

@@ -0,0 +1,20 @@
+# CSP Report
+
+## Detected Directives
+
+| Directive                   | Value               |
+| --------------------------- | ------------------- |
+| `upgrade-insecure-requests` | _none_              |
+| `trusted-types`             | `angular`           |
+| `require-trusted-types-for` | `'script'`          |
+| `default-src`               | `'self'`            |
+| `script-src`                | `'nonce-[NONCE_0]'` |
+| `object-src`                | `'none'`            |
+| `base-uri`                  | `'none'`            |
+| `form-action`               | `'self'`            |
+| `frame-ancestors`           | `'none'`            |
+
+## Recommendations
+
+- `style-src`: Add a nonce source
+- `style-src`: Remove `'self'` (inherited from `default-src`)

data/test/validation/csp-report/recommends_adding_a_nonce_source.md

@@ -0,0 +1,20 @@
+# CSP Report
+
+## Detected Directives
+
+| Directive                   | Value               |
+| --------------------------- | ------------------- |
+| `upgrade-insecure-requests` | _none_              |
+| `trusted-types`             | `angular`           |
+| `require-trusted-types-for` | `'script'`          |
+| `default-src`               | `'self'`            |
+| `script-src`                | `'strict-dynamic'`  |
+| `style-src`                 | `'nonce-[NONCE_0]'` |
+| `object-src`                | `'none'`            |
+| `base-uri`                  | `'none'`            |
+| `form-action`               | `'self'`            |
+| `frame-ancestors`           | `'none'`            |
+
+## Recommendations
+
+- `script-src`: Add a nonce source

data/test/validation/csp-report/recommends_adding_missing_sources.md

@@ -0,0 +1,26 @@
+# CSP Report
+
+## Detected Directives
+
+| Directive                   | Value                        |
+| --------------------------- | ---------------------------- |
+| `upgrade-insecure-requests` | _none_                       |
+| `trusted-types`             | `angular`                    |
+| `require-trusted-types-for` | `'script'`                   |
+| `default-src`               | `'self'`                     |
+| `script-src`                | `'nonce-[NONCE_0]'`          |
+| `style-src`                 | `'nonce-[NONCE_1]'`          |
+| `img-src`                   | `https://images.example.com` |
+| `object-src`                | `https://cdn.example.com`    |
+| `base-uri`                  | `'none'`                     |
+| `form-action`               | `https://api.example.com`    |
+| `frame-ancestors`           | `'none'`                     |
+
+## Recommendations
+
+- `img-src`: Add `'self' data:`
+- `img-src`: Remove `https://images.example.com`
+- `object-src`: Add `'none'`
+- `object-src`: Remove `https://cdn.example.com`
+- `form-action`: Add `'self'`
+- `form-action`: Remove `https://api.example.com`

data/test/validation/csp-report/recommends_all_directives_for_an_empty_header.md

@@ -0,0 +1,21 @@
+# CSP Report
+
+## Detected Directives
+
+None
+
+## Recommendations
+
+- `upgrade-insecure-requests`: Missing, add `upgrade-insecure-requests`
+- `trusted-types`: Missing, add `trusted-types`
+- `require-trusted-types-for`: Missing, add `require-trusted-types-for 'script'`
+- `default-src`: Missing, add `default-src 'self'`
+- `script-src`: Missing, add `script-src 'nonce-[RANDOM]'`
+- `style-src`: Missing, add `style-src 'nonce-[RANDOM]'`
+- `img-src`: Missing, add `img-src 'self' data:`
+- `font-src`: Missing, add `font-src 'self'`
+- `connect-src`: Missing, add `connect-src 'self'`
+- `object-src`: Missing, add `object-src 'none'`
+- `base-uri`: Missing, add `base-uri 'self'`
+- `form-action`: Missing, add `form-action 'self'`
+- `frame-ancestors`: Missing, add `frame-ancestors 'none'`

data/test/validation/csp-report/recommends_fixing_weak_directive_variants.md

@@ -0,0 +1,31 @@
+# CSP Report
+
+## Detected Directives
+
+| Directive                   | Value                                     |
+| --------------------------- | ----------------------------------------- |
+| `upgrade-insecure-requests` | _none_                                    |
+| `trusted-types`             | `angular`                                 |
+| `require-trusted-types-for` | `'script'`                                |
+| `default-src`               | `'self'`                                  |
+| `script-src`                | `'nonce-[NONCE_0]'`                       |
+| `script-src-elem`           | `'unsafe-inline' https://cdn.example.com` |
+| `script-src-attr`           | `'unsafe-inline'`                         |
+| `style-src`                 | `'nonce-[NONCE_1]'`                       |
+| `style-src-elem`            | `'nonce-[NONCE_1]' 'unsafe-inline'`       |
+| `style-src-attr`            | `'unsafe-hashes'`                         |
+| `object-src`                | `'none'`                                  |
+| `base-uri`                  | `'none'`                                  |
+| `form-action`               | `'self'`                                  |
+| `frame-ancestors`           | `'none'`                                  |
+
+## Recommendations
+
+- `script-src-elem`: Add a nonce source
+- `script-src-elem`: Remove `'unsafe-inline'`
+- `script-src-elem`: Remove `https://cdn.example.com`
+- `script-src-attr`: Add `'none'`
+- `script-src-attr`: Remove `'unsafe-inline'`
+- `style-src-elem`: Remove `'unsafe-inline'`
+- `style-src-attr`: Add `'none'`
+- `style-src-attr`: Remove `'unsafe-hashes'`

data/test/validation/csp-report/recommends_nothing_for_a_strict_policy.md

@@ -0,0 +1,20 @@
+# CSP Report
+
+## Detected Directives
+
+| Directive                   | Value               |
+| --------------------------- | ------------------- |
+| `upgrade-insecure-requests` | _none_              |
+| `trusted-types`             | `angular`           |
+| `require-trusted-types-for` | `'script'`          |
+| `default-src`               | `'self'`            |
+| `script-src`                | `'nonce-[NONCE_0]'` |
+| `style-src`                 | `'nonce-[NONCE_1]'` |
+| `object-src`                | `'none'`            |
+| `base-uri`                  | `'none'`            |
+| `form-action`               | `'self'`            |
+| `frame-ancestors`           | `'none'`            |
+
+## Recommendations
+
+None

data/test/validation/csp-report/recommends_nothing_for_strict_directive_variants.md

@@ -0,0 +1,24 @@
+# CSP Report
+
+## Detected Directives
+
+| Directive                   | Value               |
+| --------------------------- | ------------------- |
+| `upgrade-insecure-requests` | _none_              |
+| `trusted-types`             | `angular`           |
+| `require-trusted-types-for` | `'script'`          |
+| `default-src`               | `'self'`            |
+| `script-src`                | `'nonce-[NONCE_0]'` |
+| `script-src-elem`           | `'nonce-[NONCE_0]'` |
+| `script-src-attr`           | `'none'`            |
+| `style-src`                 | `'nonce-[NONCE_1]'` |
+| `style-src-elem`            | `'nonce-[NONCE_1]'` |
+| `style-src-attr`            | `'none'`            |
+| `object-src`                | `'none'`            |
+| `base-uri`                  | `'none'`            |
+| `form-action`               | `'self'`            |
+| `frame-ancestors`           | `'none'`            |
+
+## Recommendations
+
+None

data/test/validation/csp-report/recommends_removing_extra_sources.md

@@ -0,0 +1,23 @@
+# CSP Report
+
+## Detected Directives
+
+| Directive                   | Value                                                        |
+| --------------------------- | ------------------------------------------------------------ |
+| `upgrade-insecure-requests` | _none_                                                       |
+| `trusted-types`             | `angular`                                                    |
+| `require-trusted-types-for` | `'script'`                                                   |
+| `default-src`               | `'self'`                                                     |
+| `script-src`                | `'nonce-[NONCE_0]' 'strict-dynamic' https://cdn.example.com` |
+| `style-src`                 | `'nonce-[NONCE_1]' 'unsafe-inline'`                          |
+| `img-src`                   | `'self' data: https://images.example.com`                    |
+| `object-src`                | `'none'`                                                     |
+| `base-uri`                  | `'none'`                                                     |
+| `form-action`               | `'self'`                                                     |
+| `frame-ancestors`           | `'none'`                                                     |
+
+## Recommendations
+
+- `script-src`: Remove `https://cdn.example.com`
+- `style-src`: Remove `'unsafe-inline'`
+- `img-src`: Remove `https://images.example.com`

data/test/validation/csp-report/requires_base_directives_if_only_one_variant_is_defined.md

@@ -0,0 +1,21 @@
+# CSP Report
+
+## Detected Directives
+
+| Directive                   | Value               |
+| --------------------------- | ------------------- |
+| `upgrade-insecure-requests` | _none_              |
+| `trusted-types`             | `angular`           |
+| `require-trusted-types-for` | `'script'`          |
+| `default-src`               | `'self'`            |
+| `script-src-elem`           | `'nonce-[NONCE_0]'` |
+| `style-src`                 | `'nonce-[NONCE_1]'` |
+| `object-src`                | `'none'`            |
+| `base-uri`                  | `'none'`            |
+| `form-action`               | `'self'`            |
+| `frame-ancestors`           | `'none'`            |
+
+## Recommendations
+
+- `script-src`: Add a nonce source
+- `script-src`: Remove `'self'` (inherited from `default-src`)

docs/.vitepress/config.ts

@@ -63,6 +63,10 @@ export default defineConfig({
           { text: "CSP Violations", link: "/capturing/csp" },
         ],
       },
+      {
+        text: "Security",
+        items: [{ text: "CSP Report", link: "/security/csp-report" }],
+      },
       {
         text: "Snapshot Testing",
         items: [{ text: "Normalizers", link: "/snapshots/normalizers" }],

docs/src/security/csp-report.md

@@ -0,0 +1,52 @@
+# CSP Report
+
+A Content Security Policy is only effective if it is strict enough, and a weakened policy usually goes unnoticed because the application keeps working. `cspReport` evaluates a `Content-Security-Policy` header against a set of recommended directives and returns a Markdown report, which can be stored as a file snapshot to detect any change to the policy.
+
+## Usage
+
+```ts
+import { cspReport, getCspHeader } from "@cronn/playwright-utils";
+import { expect, test } from "@playwright/test";
+
+test("has a strict Content Security Policy", async ({ page }) => {
+  const response = await page.goto("/");
+  const cspHeader = await getCspHeader(response);
+
+  expect(cspReport(cspHeader)).toMatchTextFile({
+    fileExtension: "md",
+  });
+});
+```
+
+`getCspHeader` extracts the `Content-Security-Policy` header from a response. It accepts the nullable result of `page.goto()` and returns an empty string if the response or the header is missing, which `cspReport` reports as a policy without any directives.
+
+The report lists all directives of the header, followed by the recommendations for the policy:
+
+```md
+# CSP Report
+
+## Directives
+
+| Directive                   | Value               |
+| --------------------------- | ------------------- |
+| `upgrade-insecure-requests` | _none_              |
+| `trusted-types`             | `angular`           |
+| `require-trusted-types-for` | `'script'`          |
+| `default-src`               | `'self'`            |
+| `script-src`                | `'strict-dynamic'`  |
+| `style-src`                 | `'nonce-[NONCE_0]'` |
+| `object-src`                | `'none'`            |
+| `base-uri`                  | `'none'`            |
+| `form-action`               | `'self'`            |
+| `frame-ancestors`           | `'none'`            |
+
+## Recommendations
+
+- `script-src`: Add a nonce source
+```
+
+Nonces are generated per response, so they are masked as `[NONCE_0]`, `[NONCE_1]`, … to keep the report deterministic. The same nonce used by several directives is masked with the same index.
+
+A directive is considered compliant if it only contains recommended values or is set to `'none'`, so a stricter policy does not produce a recommendation. Extra sources which are not recommended are reported individually. If a directive contains none of the recommended values, the expected value is reported instead.
+
+If one of the fetch directives `script-src`, `style-src`, `img-src`, `font-src` or `connect-src` is missing, it is evaluated using `default-src`. Recommendations resulting from the fallback are marked as `(inherited from default-src)`.

package.json

@@ -51,6 +51,7 @@
     "version": "pnpm changeset version && pnpm turbo run format:fix"
   },
   "dependencies": {
+    "markdown-table": "^3.0.4",
     "package-directory": "^8.2.0"
   },
   "devDependencies": {

src/index.ts

@@ -34,6 +34,8 @@ export {
   type ResponseHandler,
 } from "./api/route-interceptor/response-handler";
 
+export { cspReport, getCspHeader } from "./security/csp-report";
+
 export { resolveFromPackageRoot } from "./file";
 
 export { formFiller, type FormFields } from "./page-object-model/form-filler";