https://github.com/jamestoohey/csprefabricate
Generate a valid CSP with TypeScript.
https://github.com/jamestoohey/csprefabricate
contentsecuritypolicy csp security typescript web-security xss-protection
Last synced: 4 months ago
JSON representation
Generate a valid CSP with TypeScript.
- Host: GitHub
- URL: https://github.com/jamestoohey/csprefabricate
- Owner: JamesToohey
- License: mit
- Created: 2024-12-11T23:25:33.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-16T23:05:43.000Z (5 months ago)
- Last Synced: 2026-01-17T11:27:55.265Z (5 months ago)
- Topics: contentsecuritypolicy, csp, security, typescript, web-security, xss-protection
- Language: TypeScript
- Homepage:
- Size: 2.75 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# csprefabricate
**Generate a valid CSP with TypeScript.**
Content Security Policies (CSPs) are cumbersome strings that are frustrating to work with:
- Fickle syntax
- Duplication when multiple TLDs are required
- Easy to allow insecure configuration
This project aims to make creating useful and secure CSPs a more pleasant experience.
Currently `csprefabricate`:
- Validates directive names
- Supports providing a list of TLDs for a given domain name
- Provides warnings for insecure or incomplete CSP configurations, with options to disable specific warnings
## Common CSP Issues
By default, `csprefabricate` will warn you about common CSP issues, such as:
- Overly permissive sources (e.g. using `*`)
- Missing recommended directives (i.e. `object-src`, `base-uri`, `form-action`)
- Use of `'unsafe-inline'` in `script-src`, even if nonces or hashes are present
- Missing nonces or hashes when using `'unsafe-inline'` in `script-src`
- Allowing `data:` in `img-src` or `media-src`
You can control which warnings are shown by passing an optional `WarningOptions` object to the `create` function:
```typescript
import {
create,
Directive,
ContentSecurityPolicy,
WarningOptions,
} from "csprefabricate";
const csp: ContentSecurityPolicy = {
[Directive.SCRIPT_SRC]: ["*"],
[Directive.IMG_SRC]: ["data:"],
};
// Disable all warnings
const warningOptions: WarningOptions = {
overlyPermissive: false,
missingDirectives: false,
unsafeInline: false,
missingNonceOrHash: false,
dataUri: false,
};
create(csp, warningOptions);
```
You can selectively enable or disable specific warnings as needed.
## Real World Examples
### Example 1: Basic Strict Policy
```typescript
import {create, Directive, ContentSecurityPolicy} from "csprefabricate";
const csp: ContentSecurityPolicy = {
[Directive.DEFAULT_SRC]: ["'self'"],
[Directive.SCRIPT_SRC]: ["'self'"],
[Directive.STYLE_SRC]: ["'self'"],
[Directive.IMG_SRC]: ["'self'"],
[Directive.OBJECT_SRC]: ["'none'"],
[Directive.BASE_URI]: ["'self'"],
[Directive.FORM_ACTION]: ["'self'"],
};
const cspString = create(csp);
// "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self';"
```
### Example 2: Allowing Google Analytics
```typescript
import {create, Directive, ContentSecurityPolicy} from "csprefabricate";
const csp: ContentSecurityPolicy = {
[Directive.DEFAULT_SRC]: ["'self'"],
[Directive.SCRIPT_SRC]: ["'self'", "*.googletagmanager.com"],
[Directive.STYLE_SRC]: ["'self'"],
[Directive.IMG_SRC]: [
"'self'",
"https://*.google-analytics.com",
"https://*.googletagmanager.com",
],
[Directive.OBJECT_SRC]: ["'none'"],
[Directive.BASE_URI]: ["'self'"],
[Directive.FORM_ACTION]: ["'self'"],
[Directive.CONNECT_SRC]: [
"'self'",
"https://*.google-analytics.com",
"https://*.analytics.google.com",
"https://*.googletagmanager.com",
],
};
const cspString = create(csp);
// "default-src 'self'; script-src 'self' *.googletagmanager.com; style-src 'self'; img-src 'self' https://*.google-analytics.com https://*.googletagmanager.com; object-src 'none'; base-uri 'self'; form-action 'self'; connect-src 'self' https://*.google-analytics.com https://*.analytics.google.com https://*.googletagmanager.com;"
```
### Example 3: Using TLD Expansion for Multiple Domains
```typescript
import {create, Directive, ContentSecurityPolicy} from "csprefabricate";
const csp: ContentSecurityPolicy = {
[Directive.IMG_SRC]: ["self", {"*.example": [".com", ".co.uk", ".net"]}],
};
const cspString = create(csp);
// "img-src 'self' *.example.com *.example.co.uk *.example.net;"
```
## Baseline Recommended CSPs
You can quickly generate a recommended Content Security Policy for common use cases using built-in baselines.
Available Baselines:
- BASELINE_STRICT_CSP
- GOOGLE_ANALYTICS_CSP
- GOOGLE_ANALYTICS_WITH_SIGNALS_CSP
### Google Analytics Baseline CSP
Allow Google Analytics and Tag Manager:
```typescript
import {create, Baseline} from "csprefabricate";
const cspString = create(Baseline.GOOGLE_ANALYTICS_CSP);
```