satteri-sanitize
satteri-sanitize
Sätteri HAST plugin that sanitizes HTML in Markdown, a port of
rehype-sanitize.
Why you need it
Sätteri passes raw HTML through unparsed. This Markdown:
<script>alert(1)</script>
[click](javascript:alert(1))
renders as exactly that: a live script tag and a javascript: link. If any part of your Markdown
comes from somewhere you do not fully control, comments, user profiles, a CMS, a pull request
description, the content of a repo you did not write, it is an XSS vector.
import { markdownToHtml } from "satteri";
import { satteriSanitize } from "satteri-sanitize";
const { html } = markdownToHtml(untrusted, { hastPlugins: [satteriSanitize()] });
Run it last, after any plugin that generates HTML, so it sees their output too.
Install
npm install satteri-sanitize
Use with Astro 7
// astro.config.mjs
import { defineConfig } from "astro/config";
import { satteri } from "@astrojs/markdown-satteri";
import { satteriSanitize } from "satteri-sanitize";
export default defineConfig({
markdown: {
processor: satteri({
hastPlugins: [satteriSanitize()],
}),
},
});
Astro appends its own plugins after yours, so put this last in your list to cover as much as
possible. Note it cannot see Astro’s syntax highlighter output, which runs first.
What it does
- Elements: an allowlist ported from
hast-util-sanitize’sdefaultSchema(GitHub’s rules).
Anything else is unwrapped: the tags go, the text stays. script: removed along with its text content, including when that content arrives as a
separate node.- Attributes: allowlisted per element. Every
on*handler is refused unconditionally. - URLs:
href,src,citeandlongdescare checked against a protocol allowlist. The check
decodes character entities, strips control characters and ignores case, soJaVaScRiPt:,
javascript:andjava<tab>script:are all caught. Relative, anchor and protocol-relative
URLs are allowed. - Markdown-generated links and images are protocol-checked too, not just raw HTML.
- Comments are removed.
idandnameget auser-content-prefix to prevent DOM clobbering.
API
satteriSanitize(options?)
| Option | Type | Default |
|---|---|---|
tagNames |
string[] |
GitHub’s element allowlist |
attributes |
Record<string, string[]> |
merged over the default per-element allowlist |
protocols |
Record<string, string[]> |
merged over the default URL allowlist |
clobberPrefix |
string |
"user-content-" |
satteriSanitize({
tagNames: ["p", "a", "strong"],
attributes: { a: ["href", "target"] },
protocols: { href: ["https"] },
});
Differences from rehype-sanitize
These are deliberate. Where they diverge, this plugin is the stricter of the two.
- Token-level, not tree-level.
rehype-sanitizeruns on a parsed tree. Sätteri hands plugins raw
HTML as strings, so this filters tokens instead. Output is not byte-identical; the guarantee is
that no disallowed element, attribute or protocol survives. on*attributes are refused even if you allowlist them.rehype-sanitizetrusts its
allowlist. This will not hand you a footgun.inputis not allowed in raw HTML. Sätteri emits task-list checkboxes as real elements, so
they are unaffected; a raw<input>is only ever a form control.- No
requiredschema field.rehype-sanitizecan force attributes onto elements. Not
implemented. - Unclosed
<script>recovers at the next block element, matching parse5, rather than consuming
the rest of the document. - An element inside a script region survives as an empty element. Its text is dropped and its
URLs are protocol-checked, so it is inert, but the tag itself remains.
Reporting a vulnerability
If you find an input that produces executable output, please report it privately via
GitHub security advisories
rather than a public issue.
Licence
MIT © Ashish Vaghela