用 Go 优雅地清理 HTML 并抵御 XSS——Bluemonday

1、背景与动机

只要你的服务接收并回显用户生成内容（UGC）——论坛帖子、评论、富文本邮件正文、Markdown 等——就必须考虑 XSS（Cross‑Site Scripting）攻击风险。浏览器在解析 HTML 时会执行脚本；如果不做清理，恶意用户可插入 <script>、onerror 等内容窃取 Cookie 或劫持会话。

Bluemonday 的使命就是 “先 allowlist，后输出”：只留下安全允许的元素与属性，其余一律剥离，保证最终字符串对浏览器“无害”。

2、XSS 攻击原理与防线简述

攻击类型	触发机理	常见载体
反射型	恶意片段拼进 URL，服务器原样输出	搜索框、重定向链接
存储型	恶意脚本写入数据库，其他用户浏览时触发	论坛帖子、评论
DOM 型	前端 JS 对外部数据拼接 innerHTML	JSONP、模板拼接

综合防御思路

1. 输入校验：长度、格式、白名单字符集。
2. 输出编码/清理：HTMLEscape、CSP、Bluemonday 等。
3. 最小权限：Cookie HttpOnly/SameSite、前后端分离降低风险。

3、认识 Bluemonday

3.1 主要特性

• 纯 Go 实现；零 CGo 依赖，可用在任意平台。
• 基于允许列表（Allowlist）；默认拒绝一切未知元素，安全系数高。
• 多种预置策略：StrictPolicy、UGCPolicy、NewPolicy() 自定义。
• 线程安全：Policy 对象是只读，可被多个 goroutine 并发复用。
• 支持 string/[]byte/io.Reader 三种输入形式，便于流式处理。citeturn0search1

3.2 安装与版本管理

go get github.com/microcosm-cc/bluemonday@latest

Bluemonday 发布节奏相对稳定，建议在 go.mod 中锁定次版本号（v1.x.y）以避免潜在破坏性变更。

4、快速上手：StrictPolicy 一键剥离标签

最“硬核”的策略就是全部移除标签，仅保留文本：

policy := bluemonday.StrictPolicy()
clean  := policy.Sanitize(`<p>Hello <strong>世界</strong>！<script>alert(1)</script></p>`)
// clean == "Hello 世界！"

该策略实现了 “硬删除脚本 + 去掉所有属性” 的极致安全；在 Markdown‑>HTML 渲染前做一次清理，可有效杀死脚本注入。citeturn0search0

5 、进阶使用：UGCPolicy 与自定义策略

5.1 UGCPolicy——保留安全富文本

StrictPolicy 虽安全，却也太“干净”。当你需要 保留 <a>、<em>、<ul> 等常用排版元素 时，可以使用官方预设的 UGCPolicy()：

p   := bluemonday.UGCPolicy()
out := p.Sanitize(`<a href="http://evil.com" onclick="steal()">点我</a>`)
fmt.Println(out)
// <a href="http://evil.com" rel="nofollow">点我</a>

重点：

• 允许 <a>、自动加 rel="nofollow"。
• 过滤一切 JS‑相关属性（onclick, onerror 等）。
• 自动修正不完整/畸形标签，防跳脱闭合漏洞。citeturn0search2

5.2 手写自定义 Policy

如果业务场景需要 保留特定 CSS class、data-* 自定义属性，可通过 NewPolicy() 自定义：

p := bluemonday.NewPolicy()// 允许 block/inline 常用元素
p.AllowElements("p", "ul", "li", "strong", "em")// 允许 <a>，但仅开放 href=https://* 并加 rel="noopener"
p.AllowAttrs("href").Matching(bluemonday.UrlRegexp).OnElements("a")
p.RequireNoFollowOnLinks(false)
p.AddTargetBlankToFullyQualifiedLinks(true)// 允许 <span class="highlight">
p.AllowAttrs("class").Matching(regexp.MustCompile(`^(highlight)$`)).OnElements("span")// …更多颗粒度设置

Bluemonday 的 API 链式可读性高；官方文档中每个 Allow* 方法都带示例，可参考并组合。

6、性能、并发与内存开销

• 并发安全：Policy 初始化后为只读结构体，可在全局变量缓存并被 goroutine 复用。
• 基于标准库 html Tokenizer：解析成本≈ O(n)，常规博文（~5 KB）清理耗时 < 100 µs。
• 零分配策略：SanitizeBytes 复用切片，避免多余 copy。

性能调优要点：

1. 单例化 Policy，避免每次请求都 NewPolicy()。
2. 对高并发流量可用 sync.Pool 复用临时缓冲区，减轻 GC 压力。

7、与 Gin 集成的落地示例

// middleware/htmlsan.go
var htmlPolicy = bluemonday.UGCPolicy()func SanitizeHTML() gin.HandlerFunc {return func(c *gin.Context) {if c.Request.Method == http.MethodPost || c.Request.Method == http.MethodPut {// 读 bodyraw, _ := io.ReadAll(c.Request.Body)clean := htmlPolicy.SanitizeBytes(raw)// 重写 body 并继续链路c.Request.Body = io.NopCloser(bytes.NewReader(clean))c.Request.ContentLength = int64(len(clean))}c.Next()}
}

注册：

r := gin.Default()
r.Use(middleware.SanitizeHTML())

• 适用于 富文本编辑器上传、评论接口 等写操作。
• 若上传为 JSON，可在绑定结构体前使用 json.Decoder + htmlPolicy.Sanitize() 逐字段过滤。

8、单元测试与安全基线

func TestStripXSS(t *testing.T) {cases := []struct{in, out string}{{`<img src=x onerror=alert(1)>`, ``},{`<a href="javascript:alert(1)">x</a>`, `<a rel="nofollow">x</a>`},}p := bluemonday.UGCPolicy()for _, c := range cases {if got := p.Sanitize(c.in); got != c.out {t.Errorf("want %q, got %q", c.out, got)}}
}

• 建议将常见 XSS Payload 集合（OWASP Cheat Sheet）纳入回归测试。
• 关注安全通报：例如 Go‑2022‑0588 提及自定义策略允许 style 时可能触发 CSS XSS，应尽量避免。

9、常见陷阱 & 优化建议

场景	潜在风险	建议
盲目 AllowElements("style")	CSS 注入绕过	使用 CSP 并限制 style
文件上传富文本嵌入 <img src="data:…">	内嵌恶意 SVG	限制 src 协议为 https
前端再拼接 innerHTML += …	DOM XSS	前端使用 textContent 或框架安全输出
大文件批量清理	内存飙升	使用 SanitizeReader 流式处理

10、 结语

Bluemonday 把复杂的 XSS 防御落地成本降到了“引一个包 + 三行代码”。
然而安全永远不是“一招鲜”：

• 输入校验、输出清理、浏览器 CSP 缺一不可。
• 单元测试 & 安全扫描 持续跟进新 Payload。
• 合理选择 StrictPolicy / UGCPolicy / 自定义混合策略，平衡 用户体验 与 安全强度。

把好内容入口关，让你的 Go Web 服务拥有“消毒后”的纯净输入！