Merge pull request #5 from yangyin5127/yy/2025/feat-css-filter

feat: add css filter

Author: yangyin5127

README.en.md

@@ -200,7 +200,28 @@ options.SingleQuotedAttributeValue = true
 // <a href='#'>Hello</a>
 ```
 
+### Customize CSS filter
 
+If you allow the attribute style, the value will be processed by [cssfilter](github.com/yangyin5127/go-xss/cssfilter) module. The cssfilter module includes a default css whitelist. You can specify the options for cssfilter module like this:
+
+
+```
+// When enabled, the content of style attribute will be filtered to prevent XSS attacks via CSS.
+options.EnableCssFilter = true
+// enable div tag's style attribute
+options.WhiteList["div"] = []string{"style"}
+
+
+options.CssFilterOption = xss.NewCssFilterOption()
+options.CssFilterOption.WhiteList = ....
+// 	OnAttr func(name, value string, options StyleAttrOption) *string
+options.CssFilterOption.OnAttr = ....
+//  OnIgnoreAttr func(name, value string, options StyleAttrOption) *string
+options.CssFilterOption.OnIgnoreAttr = ....
+```
+
+
+more details see: github.com/yangyin5127/go-xss/cssfilter
 
 ### Quick Start
 

README.md

@@ -201,7 +201,28 @@ options.SingleQuotedAttributeValue = true
 
 ### 自定义 CSS 过滤器
 
-TODO
+通过 `EnableCssFilter` 来启用 [CSS过滤器](github.com/yangyin5127/go-xss/cssfilter)，启用后会对 style 属性中的内容进行过滤，防止通过 CSS 进行 XSS 攻击
+
+
+```golang
+
+# 例子
+// 允许css filter
+options.EnableCssFilter = true
+// 开启标签style属性白名单,默认style禁止
+options.WhiteList["div"] = []string{"style"}
+
+options.CssFilterOption = xss.NewCssFilterOption()
+options.CssFilterOption.WhiteList = ....
+// 	OnAttr func(name, value string, options StyleAttrOption) *string
+options.CssFilterOption.OnAttr = ....
+//  OnIgnoreAttr func(name, value string, options StyleAttrOption) *string
+options.CssFilterOption.OnIgnoreAttr = ....
+
+
+```
+more details see: github.com/yangyin5127/go-xss/cssfilter/css_option.go
+
 
 ## 快捷配置
 

cssfilter/css_option.go

@@ -0,0 +1,26 @@
+package cssfilter
+
+import "testing"
+
+func TestSafeAttrValue(t *testing.T) {
+	sourceName := "href"
+	sourceValue := "javascript:alert(1);"
+	result := SafeAttrValue(sourceName, sourceValue)
+	if result != "" {
+		t.Errorf("TestSafeAttrValue err %v", result)
+	}
+
+	sourceName = "src"
+	sourceValue = "javascript:alert(1);"
+	result = SafeAttrValue(sourceName, sourceValue)
+	if result != "" {
+		t.Errorf("TestSafeAttrValue err %v", result)
+	}
+
+	sourceName = "style"
+	sourceValue = "background-image: url(javascript:alert(1));"
+	result = SafeAttrValue(sourceName, sourceValue)
+	if result != "" {
+		t.Errorf("TestSafeAttrValue err %v", result)
+	}
+}

cssfilter/css_option_test.go

@@ -0,0 +1,103 @@
+package cssfilter
+
+// 等价 JS isNull：nil → true
+func isNull(v interface{}) bool {
+	return v == nil
+}
+
+// ---------- FilterCSS 核心 ----------
+
+type FilterCSS struct {
+	Options CssOption
+}
+
+// 新建 FilterCSS（浅拷贝 semantics）
+func NewFilterCSS(opt *CssOption) *FilterCSS {
+	var cfg CssOption
+	if opt != nil {
+		cfg = *opt
+	}
+
+	// 白名单为空时，默认空 map
+	if cfg.WhiteList == nil {
+		cfg.WhiteList = DefaultCssWhiteList
+	}
+
+	// 默认回调
+	if cfg.OnAttr == nil {
+		cfg.OnAttr = func(name, value string, opts StyleAttrOption) *string {
+			return nil
+		}
+	}
+	if cfg.OnIgnoreAttr == nil {
+		cfg.OnIgnoreAttr = func(name, value string, opts StyleAttrOption) *string {
+			return nil
+		}
+	}
+	if cfg.SafeAttrValue == nil {
+		cfg.SafeAttrValue = SafeAttrValue
+	}
+
+	return &FilterCSS{Options: cfg}
+}
+
+func (fc *FilterCSS) Process(css string) string {
+	if css == "" {
+		return ""
+	}
+
+	opts := fc.Options
+	white := opts.WhiteList
+	onAttr := opts.OnAttr
+	onIgnore := opts.OnIgnoreAttr
+	safeAttrValue := opts.SafeAttrValue
+
+	result := ParseStyle(css, func(sourcePos, position int, name, value, source string) string {
+
+		// ---- whitelist check ----
+		check, exists := white[name]
+		isWhite := false
+		if exists {
+			if check.Allow {
+				isWhite = true
+			} else if check.Func != nil {
+				isWhite = check.Func(value)
+			} else if check.Reg != nil {
+				isWhite = check.Reg.MatchString(value)
+			}
+		}
+
+		// ---- safeAttrValue ----
+		value = safeAttrValue(name, value)
+		if value == "" {
+			return ""
+		}
+
+		optsObj := StyleAttrOption{
+			Position:       position,
+			SourcePosition: sourcePos,
+			Source:         source,
+			IsWhite:        isWhite,
+		}
+
+		if isWhite && onAttr != nil {
+			// onAttr 可返回 nil → 默认 name:value
+			ret := onAttr(name, value, optsObj)
+
+			if ret == nil {
+				return name + ":" + value
+			}
+			return *ret
+		}
+
+		// not whitelisted
+		ret := onIgnore(name, value, optsObj)
+		if ret != nil {
+			return *ret
+		}
+
+		return ""
+	})
+
+	return result
+}

cssfilter/filter.go

@@ -0,0 +1,102 @@
+package cssfilter
+
+import (
+	"testing"
+)
+
+func eq(t *testing.T, got, want string) {
+	t.Helper()
+	if got != want {
+		t.Fatalf("expected `%s`, got `%s`", want, got)
+	}
+}
+
+func ok(t *testing.T, condition bool, msg string) {
+	t.Helper()
+	if !condition {
+		t.Fatal(msg)
+	}
+}
+
+func TestFilterCSS_Normal(t *testing.T) {
+	fc := NewFilterCSS(nil)
+
+	result := fc.Process("00xx; position: fixed; width:100px; height:  200px")
+	eq(t, result, "width:100px; height:200px;")
+
+	fc = NewFilterCSS(&CssOption{
+		OnAttr: func(name, value string, opts StyleAttrOption) *string {
+			ok(t, opts.IsWhite, "expected IsWhite true")
+			if name == "width" {
+				eq(t, value, "100px")
+			} else if name == "height" {
+				eq(t, value, "200px")
+			} else {
+				t.Fatalf("bad attr name `%s`", name)
+			}
+			return nil
+		},
+		OnIgnoreAttr: func(name, value string, opts StyleAttrOption) *string {
+			ok(t, !opts.IsWhite, "expected IsWhite false")
+			if name == "position" {
+				eq(t, value, "fixed")
+			} else {
+				t.Fatalf("bad attr name `%s`", name)
+			}
+			return nil
+		},
+	})
+
+	result = fc.Process("position: fixed; width:100px; height:  200px")
+	eq(t, result, "width:100px; height:200px;")
+}
+
+func TestFilterCSS_OnAttrReturnNewSource(t *testing.T) {
+	fc := NewFilterCSS(&CssOption{
+		OnAttr: func(name, value string, opts StyleAttrOption) *string {
+			ok(t, opts.IsWhite, "expected IsWhite true")
+			ret := name + ": " + value
+			return &ret
+		},
+	})
+
+	result := fc.Process("position: fixed; width:100px; height:  200px")
+	eq(t, result, "width: 100px; height: 200px;")
+}
+
+func TestFilterCSS_OnIgnoreAttrReturnNewSource(t *testing.T) {
+	fc := NewFilterCSS(&CssOption{
+		OnIgnoreAttr: func(name, value string, opts StyleAttrOption) *string {
+			ok(t, !opts.IsWhite, "expected IsWhite false")
+			if name == "position" {
+				ret := "x-" + name + ":" + value
+				return &ret
+			}
+			return nil
+		},
+	})
+
+	result := fc.Process("position: fixed; width:100px; height:  200px")
+	eq(t, result, "x-position:fixed; width:100px; height:200px;")
+}
+
+func TestFilterCSS_SafeAttrValue(t *testing.T) {
+	fc := NewFilterCSS(nil)
+
+	tests := []struct {
+		input  string
+		expect string
+	}{
+		{"background: url(javascript:alert(/xss/)); height: 400px;", "height:400px;"},
+		{"background: url( javascript : alert(/xss/)); height: 400px;", "height:400px;"},
+		{"background: url ( javascript :alert(/xss/)); height: 400px;", "height:400px;"},
+		{"background: url (\" javascript :alert(/xss/)\"); height: 400px;", "height:400px;"},
+		{"background: url ( javascript : \"alert(/xss/) \"); height: 400px;", "height:400px;"},
+		{"background: url ( java script : alert(/xss/)); height: 400px;", "background:url ( java script : alert(/xss/)); height:400px;"},
+	}
+
+	for _, test := range tests {
+		result := fc.Process(test.input)
+		eq(t, result, test.expect)
+	}
+}

cssfilter/filter_test.go

@@ -0,0 +1,77 @@
+package cssfilter
+
+import (
+	"strings"
+	"unicode"
+)
+
+type OnAttrFunc func(sourcePosition int, position int, name string, value string, source string) string
+
+func trimRight(s string) string {
+	return strings.TrimRightFunc(s, unicode.IsSpace)
+}
+
+func trim(s string) string {
+	return strings.TrimSpace(s)
+}
+
+func ParseStyle(css string, onAttr OnAttrFunc) string {
+	css = trimRight(css)
+	if !strings.HasSuffix(css, ";") {
+		css += ";"
+	}
+
+	cssLen := len(css)
+	isParenthesisOpen := false
+	lastPos := 0
+	i := 0
+	retCSS := strings.Builder{}
+
+	addNewAttr := func() {
+		if !isParenthesisOpen {
+			source := trim(css[lastPos:i])
+			j := strings.Index(source, ":")
+			if j != -1 {
+				name := trim(source[:j])
+				value := trim(source[j+1:])
+				if name != "" {
+					ret := onAttr(lastPos, retCSS.Len(), name, value, source)
+					if ret != "" {
+						retCSS.WriteString(ret)
+						retCSS.WriteString("; ")
+					}
+				}
+			}
+		}
+		lastPos = i + 1
+	}
+
+	for i < cssLen {
+		c := css[i]
+
+		// 注释 /* ... */
+		if c == '/' && i+1 < cssLen && css[i+1] == '*' {
+			j := strings.Index(css[i+2:], "*/")
+			if j == -1 {
+				break
+			}
+			i = i + 2 + j + 1
+			lastPos = i + 1
+			isParenthesisOpen = false
+		} else if c == '(' {
+			isParenthesisOpen = true
+		} else if c == ')' {
+			isParenthesisOpen = false
+		} else if c == ';' {
+			if !isParenthesisOpen {
+				addNewAttr()
+			}
+		} else if c == '\n' {
+			addNewAttr()
+		}
+
+		i++
+	}
+
+	return trim(retCSS.String())
+}