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 服務擁有“消毒后”的純凈輸入！