csp-html-linter

1.0.13 verified Fri May 01 auth: no javascript

A tool to lint HTML files for potential Content Security Policy (CSP) violations, targeting inline styles, inline JavaScript, style tags without nonce, and script tags without nonce. Current stable version is 1.0.13. It is designed to be used as a build step to catch violations early. Differentiators: simple CLI and programmatic API, zero dependencies, returns violations as array or detailed objects with location info. Offers a narrow but focused set of checks, suitable for integration into CI pipelines.

Common errors

error TypeError: cspHtmlLinter.parse is not a function ↓

cause Using default import with ESM syntax instead of require().

fix

Change import to require: const cspHtmlLinter = require('csp-html-linter');

error Mismatched quotes or missing glob pattern ↓

cause CLI --include argument is missing or not properly quoted.

fix

Use --include with double quotes around the glob, e.g., --include "src/**/*.html"

error TypeError: Cannot read property 'message' of undefined ↓

cause Assuming includeLocationInfo returns object with message property without checking if location info is enabled.

fix

When includeLocationInfo is false, each violation is a string, not an object. Check your options or handle both types.

Warnings

gotcha ESM imports are not supported; only CommonJS require() works. Using import will result in a runtime error. ↓

fix Use const cspHtmlLinter = require('csp-html-linter'); or use dynamic import() if your environment supports it.

gotcha CLI requires --include argument with a glob string; passing a file path directly does nothing. ↓

fix Always use --include with a glob, e.g., --include "src/**/*.html".

gotcha The parse() method returns an array of strings by default, but when includeLocationInfo is true, it returns an array of objects with message and location. Mixing these return types can break downstream code expecting strings. ↓

fix Check the options.includeLocationInfo value or use a type guard to handle both cases.

gotcha All options default to false; if you intend to allow something, you must explicitly set it to true. This can lead to unexpected violations if options are omitted. ↓

fix Always explicitly set all options you care about to avoid false positives.

Install

npm install csp-html-linter

yarn add csp-html-linter

pnpm add csp-html-linter

Imports

cspHtmlLinter
wrong
```
import cspHtmlLinter from 'csp-html-linter';
```
correct
```
const cspHtmlLinter = require('csp-html-linter');
```
Package exposes a CommonJS module. ES module imports are not supported; only require() works. TypeScript types are shipped but usage requires @types/node or similar.
parse
wrong
```
cspHtmlLinter.default.parse(code, options);
```
correct
```
cspHtmlLinter.parse(code, options);
```
The main export is an object with a parse method. No default export. Always use require() and call parse directly on the required object.
csp-html-linter CLI
wrong
```
npx csp-html-linter src/**/*.html
```
correct
```
csp-html-linter --include "src/**/*.html" --verbose
```
The CLI requires the --include argument as a glob string. It does not accept file paths directly. Use --include with quotes around the glob.

Quickstart

Shows programmatic usage with parse() and options, including location info.

// Install: npm install csp-html-linter --save-dev

const cspHtmlLinter = require('csp-html-linter');

const htmlCode = `
<div style="color:red;">Text</div>
<script>alert('xss')</script>
<a href="javascript:void(0)">click</a>
`;

const violations = cspHtmlLinter.parse(htmlCode, { includeLocationInfo: true });
console.log('Violations:', violations);
// Example output:
// Violations: [
//   { message: 'Inline styles are not allowed', location: { startLine: 2, startCol: 5, ... } },
//   { message: 'Script tags without nonce are not allowed', location: { startLine: 3, startCol: 1, ... } },
//   { message: 'Inline JavaScript is not allowed', location: { startLine: 4, startCol: 9, ... } }
// ]