November 19, 2026
The API Docs Page That Ran My JavaScript: Stored XSS in vitepress-openapi
How I found, proved, reported and then tried to break the fix for GHSA-2527-wvp8-x7r8
By Jegann
10 min read
By Jeg4nX19
There's a special kind of code nobody looks at twice: the part that makes documentation look nice.
It doesn't handle passwords or move money. It takes some Markdown and turns it into pretty HTML. What could go wrong?
This post covers a stored cross-site scripting (XSS) bug I found in vitepress-openapi, a library that turns OpenAPI specs into documentation pages inside VitePress sites. It gets about 42,000 downloads a week. Any description field in the spec could run JavaScript in the browser of everyone who opened the docs.
The maintainer fixed it the next day, published an advisory crediting me (GHSA-2527-wvp8-x7r8), and then asked me to try to break the fix. That last part was the most fun I've had all month.
Here's the whole thing: how I picked the target, how I traced the bug, how I proved it, how I reported it, and how I attacked the patch.
TL;DR
- Package:
vitepress-openapi(npm) - Affected:
< 0.2.16 - Fixed: 0.2.16
- Bug: OpenAPI
descriptionfields were rendered as Markdown with raw HTML allowed, then written to the page withinnerHTML. There was no sanitizer. - Impact: stored XSS on any docs site that renders a spec it doesn't fully control
- Severity: Moderate, CVSS 3.1 6.1 (
AV:N/AC:L/PR:N/UI:R/S:U/C:L/I:L/A:N), CWE-79 - Advisory: GHSA-2527-wvp8-x7r8, published and crediting me. A CVE has been requested but isn't assigned yet, so I'm not claiming one.
If you use vitepress-openapi, update to 0.2.16 or later.
Step 0: Why I was looking at documentation renderers
I'd been working through a family of bugs in API documentation tools. It started with a published advisory for @orpc/openapi (CVE-2026-33331), where spec data went into the page without escaping. I'd already found the same kind of mistake in a couple of Swagger UI wrappers.
But I'd run out of wrappers. The rest either loaded the spec from a URL or escaped properly, and I was reading the same safe code over and over.
So I changed the question. Instead of "who pastes the spec into a script tag?" I asked:
Who takes Markdown from the spec, turns it into HTML, and puts that HTML on the page without cleaning it?
Why Markdown is the interesting part
OpenAPI lets you write description fields in Markdown. Documentation renderers convert that Markdown to HTML so it looks nice.
The most popular Markdown library in JavaScript, markdown-it, has an option called html: true. When it's on, any raw HTML in the input passes through untouched. So <img src=x onerror=alert(1)> comes out the other side as a real image tag with a real event handler.
markdown-it's own security docs say it plainly: if you turn on html: true and the input isn't trusted, you need a separate sanitizer.
That gave me a simple three-part search for every doc renderer:
# 1. Is raw HTML enabled?
grep -rnE "html:\s*true" src/
# 2. Where does the HTML go into the page?
grep -rnE "v-html|innerHTML|set:html|dangerouslySetInnerHTML|\{@html" src/
# 3. Is there a sanitizer anywhere?
grep -E "dompurify|sanitize-html|\"xss\"" package.json# 1. Is raw HTML enabled?
grep -rnE "html:\s*true" src/
# 2. Where does the HTML go into the page?
grep -rnE "v-html|innerHTML|set:html|dangerouslySetInnerHTML|\{@html" src/
# 3. Is there a sanitizer anywhere?
grep -E "dompurify|sanitize-html|\"xss\"" package.jsonA match on 1, a match on 2 and nothing on 3 means it's time to read closely.
vitepress-openapi matched on all three.
Step 1: Following the data from spec to page
I traced the path from the spec to the browser one file at a time.
1a. The Markdown engine (src/composables/useMarkdown.ts)
let md = markdownit({
html: true, // raw HTML in the input passes through as-is
breaks: true,
})
function render(content: string) {
return md.render(content || '')
}let md = markdownit({
html: true, // raw HTML in the input passes through as-is
breaks: true,
})
function render(content: string) {
return md.render(content || '')
}Raw HTML is on, and render() returns whatever came in, now as HTML.
1b. The component that shows descriptions (src/components/Common/OAMarkdown.vue)
<template>
<div
v-hydratable-html="render(props.content)"
:class="cn('OAMarkdown oa-doc', props.class)"
/>
</template><template>
<div
v-hydratable-html="render(props.content)"
:class="cn('OAMarkdown oa-doc', props.class)"
/>
</template>The result of render() goes into something called v-hydratable-html. That isn't a built-in Vue directive, so I needed to see what it does.
1c. The custom directive (src/lib/utils/vHydratableHtml.ts)
export const vHydratableHtml = {
getSSRProps: ({ value }) => ({ innerHTML: value }), // server-side render
beforeMount(el, { value }) { writeHtml(el, value) }, // client
updated(el, { value }) { writeHtml(el, value) }, // client, on change
}
function writeHtml(el, html) {
el.innerHTML = html
}export const vHydratableHtml = {
getSSRProps: ({ value }) => ({ innerHTML: value }), // server-side render
beforeMount(el, { value }) { writeHtml(el, value) }, // client
updated(el, { value }) { writeHtml(el, value) }, // client, on change
}
function writeHtml(el, html) {
el.innerHTML = html
}So it's v-html under a different name. It sets innerHTML on the server (so the HTML is baked into the generated page) and on the client (when the page loads or changes).
1d. Is there a sanitizer anywhere?
I checked package.json. The runtime dependencies were:
@lucide/vue, @vueuse/core, class-variance-authority, clsx,
markdown-it-link-attributes, reka-ui@lucide/vue, @vueuse/core, class-variance-authority, clsx,
markdown-it-link-attributes, reka-uiNo DOMPurify, no sanitize-html, no xss. I also grepped the source for any hand-written cleaning (replace(, escape, sanitize) near the Markdown code. Nothing.
The full chain is:
OpenAPI description -> markdown-it (html: true) -> v-hydratable-html -> innerHTMLOpenAPI description -> markdown-it (html: true) -> v-hydratable-html -> innerHTMLwith nothing in between.
Step 2: How much of the spec reaches this?
One vulnerable field is a bug. Many vulnerable fields means anyone using the library is affected. I grepped for every place OAMarkdown gets its content:
grep -rn "OAMarkdown" src/components | grep -v "^src/components/Common/OAMarkdown.vue"grep -rn "OAMarkdown" src/components | grep -v "^src/components/Common/OAMarkdown.vue"Eight different spec fields fed into it:
info.description(OAInfoContent.vue)- operation
description(OAOperationContent.vue) - parameter
description(OAParameter.vue) - response
description(OAResponse.vue) - security scheme
description(OASecurityContent.vue) - schema property
description(OASchemaUI.vue) - example
description(OASchemaTabs.vue) - tag / path-group
description(OAPathsGroup.vue)
Any one of those containing HTML would do it.
Why "stored" XSS
VitePress builds pages ahead of time. The server-side render step (getSSRProps: innerHTML) means the payload gets written into the static HTML files that are deployed. Every visitor gets it. No special link is needed. They just open the docs.
Step 3: Who is actually at risk?
I always write this part honestly, because overselling is the quickest way to lose a maintainer's trust.
If you only render a spec your own team wrote by hand, the risk is low. You'd be attacking yourself.
But documentation renderers are commonly used in setups where the spec is not fully trusted:
- API portals and catalogs that render specs from partners, customers or other teams.
- Build pipelines that download the spec from an upstream URL. If that upstream spec gets compromised, the attacker's script ends up on your docs site.
- Specs generated from other data, where
descriptiontext comes from code comments, a database or user content.
In all of these, the library promises to display the spec as documentation. A description field shouldn't be able to take over the page. That's the same reasoning behind other accepted advisories in this family (fumadocs, zudoku, docusaurus-openapi-docs, oRPC).
Step 4: Proving it with the real library, not a copy
The rule I follow: never prove a library bug with your own reimplementation. If I copy the code into my own test, the maintainer can reasonably say "that isn't how our code runs." So I installed the real published package in an empty folder:
mkdir poc && cd poc && npm init -y
npm i vitepress-openapi@0.2.15 vue@3 @vue/server-renderer@3mkdir poc && cd poc && npm init -y
npm i vitepress-openapi@0.2.15 vue@3 @vue/server-renderer@3Then I imported the real OAMarkdown component and server-rendered it with a payload as the description:
// poc-ssr.mjs
import { createSSRApp, h } from 'vue'
import { renderToString } from '@vue/server-renderer'
import { OAMarkdown } from 'vitepress-openapi/vue'
// the value of an OpenAPI `description` field
const payload = `Normal text. <img src=x onerror="document.title='PWNED-XSS'">`
const app = createSSRApp({ render: () => h(OAMarkdown, { content: payload }) })
console.log(await renderToString(app))// poc-ssr.mjs
import { createSSRApp, h } from 'vue'
import { renderToString } from '@vue/server-renderer'
import { OAMarkdown } from 'vitepress-openapi/vue'
// the value of an OpenAPI `description` field
const payload = `Normal text. <img src=x onerror="document.title='PWNED-XSS'">`
const app = createSSRApp({ render: () => h(OAMarkdown, { content: payload }) })
console.log(await renderToString(app))That proves the payload comes out unescaped. But showing up in the output isn't the same as running, so step two was a real browser. I wrapped the output in a page whose title was SAFE-ORIGINAL-TITLE, opened it in headless Chromium, and dumped the live DOM:
chromium --headless --no-sandbox --dump-dom file://$PWD/served-page.html \
| grep -E '<title>|onerror'chromium --headless --no-sandbox --dump-dom file://$PWD/served-page.html \
| grep -E '<title>|onerror'
The title changed from SAFE-ORIGINAL-TITLE to PWNED-XSS. The onerror handler ran. A real attacker would steal tokens or show a fake login form instead of changing the title.
All of this happened on my own machine. No live websites, no other people's data.
Step 5: Reporting it
Finding the right channel
The repo's Security โ Advisories page had no "Report a vulnerability" button, so private vulnerability reporting (PVR) was off.
I'd been here before. On an earlier report I opened a public GitHub issue asking a maintainer to turn on PVR, and then nothing happened for weeks. The repo was eventually archived.
The maintainer, Enzo Notario, had a public email address on his GitHub profile and was clearly active (he'd pushed code that day). So I sent a private email with a complete, self-contained report.
What went into the report
- Summary: a few sentences anyone can understand.
- Root cause: the three files above, with exact paths and code.
- Reachability: the eight-field list.
- Threat model: when it matters and when it doesn't.
- PoC: the script, the output, the Chromium proof, and copy-paste steps to reproduce from scratch.
- Severity: CVSS 3.1 6.1 Moderate, CWE-79.
- Fix options: set
html: false; or sanitize the output ofrender()with DOMPurify, sanitize-html or js-xss; or allow raw HTML only behind a documented opt-in. - Credit request: Jeg4nX19, plus a request to publish an advisory and a CVE.
The goal of a report is that the maintainer can understand it in two minutes and reproduce it in five.
Step 6: The fix arrived the next day
Enzo replied quickly and shipped vitepress-openapi 0.2.16:
- added the
xss(js-xss) sanitizer, on by default, for all Markdown-rendered HTML, - added a
markdown.sanitizeoption for people who really need raw HTML and accept the risk, - escaped the operation-link
href, method and title as well, - turned on private vulnerability reporting for the repo,
- published GHSA-2527-wvp8-x7r8 crediting me, and requested a CVE through GitHub.
Then he asked me to check the fix.
Step 7: Trying to break the fix
A maintainer asking you to attack their patch is the best kind of invitation. I used the same setup (real package, now 0.2.16, real OAMarkdown, server render, then a real browser) and went through three rounds.
Round 1: the classics
<img src=x onerror=...>became<img src="x">(handler removed)<svg onload=...>was removed<script>...</script>was removed<iframe srcdoc=...>was removed<details open ontoggle=...>became<details open>- mixed case like
<IMG OnErRoR=...>was also cleaned
Normal formatting like **bold**, <b> and <code> still worked, so the fix didn't break legitimate content either.
Round 2: sneaky URLs
javascript:links with tabs, newlines, leading spaces, null bytes,:entities and mixed case: thehrefwas emptiedvbscript:anddata:text/htmllinks: shown as plain text<img src=javascript:...>:srcemptiedstyle="background:url(javascript:...)": style removed<form action=javascript:...>: action removed
Round 3: mutation XSS (the hard one)
Some payloads look harmless to a sanitizer working on a string, then change shape when the browser parses them. This is called mutation XSS (mXSS), and it has beaten real sanitizers before.
I tried 13 mXSS vectors: <math>/<mtext>/<mglyph> namespace confusion, <noscript> and <template> context breaks, annotation-xml encoding="text/html", <svg><foreignObject>, <xmp>, <title> and <style> breakouts, and more.
For each one I didn't trust the string output. I rendered it with the real component, set the result as innerHTML in real Chromium, and planted a canary (window.__x) that would flip if any JavaScript ran.
The result
About 38 payloads, 0 bypasses.
I also grepped the whole 0.2.16 source for any other place raw HTML reaches the page. There were only two:
- the Markdown path, which is now sanitized, and the sanitizer wraps the final output, so it also covers link plugins and user-added Markdown plugins;
- the Shiki code highlighter, which escapes code before turning it into HTML.
Two payloads were flagged as "dangerous" by my quick regex, and I checked both:
- a
[x](javascript:...)link that rendered as plain visible text, not a real link; - an SVG inside an
<img src="data:...">, which is inert, because browsers don't run scripts in SVGs loaded through<img>.
Both were false positives. I wrote them down as false positives rather than claiming a bypass I didn't have. Claiming "I bypassed your fix" when you haven't is a great way to lose a maintainer's trust permanently.
I told Enzo the fix holds.
What I took away from this one
- Custom directives deserve a second look.
v-hydratable-htmlsounds fancy. It'sinnerHTML. html: truewithout a sanitizer is a red flag in anything that renders content you don't fully control.- Count the reachable fields. Eight sinks make a stronger report than one.
- Prove it with the real package, then prove it runs in a real browser.
- Be honest about who's affected. "Low risk if you write your own spec" belongs in the report.
- When there's no private reporting, a polite private email works.
- If the maintainer asks you to test the fix, do it properly, and report false positives as false positives.
- An advisory isn't a CVE. I have a published, credited GHSA. When the CVE number shows up, I'll update this post.
For maintainers of Markdown or doc renderers
- If you render Markdown from content you don't fully control, use
html: false, or sanitize the final HTML (DOMPurify, sanitize-html or js-xss). - Sanitize the final output, after every plugin has run, not just the raw input.
- Make "allow raw HTML" an explicit opt-in, and document the risk.
- Treat the OpenAPI spec as untrusted input.
- Turn on GitHub private vulnerability reporting.
Thanks
Big thanks to Enzo Notario for a fast, thorough fix, for publishing the advisory with credit, for turning on private reporting, and for inviting me to test the patch. That's how disclosure is supposed to go.
โ Jeg4nX19
References
- Advisory: GHSA-2527-wvp8-x7r8
- Package: vitepress-openapi on npm (fixed in 0.2.16)
- Repository: https://github.com/enzonotario/vitepress-openapi
- markdown-it security notes: https://github.com/markdown-it/markdown-it/blob/master/docs/security.md
Tags: Bug Bounty, XSS, Cybersecurity, Open Source, Vue