diff --git a/Makefile b/Makefile index b15dc74..b5903a2 100644 --- a/Makefile +++ b/Makefile @@ -25,7 +25,7 @@ build: @go build vet: - @go vet *.go + @go vet lint: @golint *.go diff --git a/doc.go b/doc.go index 71dab60..ba2d775 100644 --- a/doc.go +++ b/doc.go @@ -28,10 +28,10 @@ // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. /* -Package bluemonday provides a way of describing a whitelist of HTML elements +Package bluemonday provides a way of describing an allowlist of HTML elements and attributes as a policy, and for that policy to be applied to untrusted strings from users that may contain markup. All elements and attributes not on -the whitelist will be stripped. +the allowlist will be stripped. The default bluemonday.UGCPolicy().Sanitize() turns this: @@ -84,21 +84,21 @@ bluemonday is heavily inspired by both the OWASP Java HTML Sanitizer We ship two default policies, one is bluemonday.StrictPolicy() and can be thought of as equivalent to stripping all HTML elements and their attributes as -it has nothing on its whitelist. +it has nothing on its allowlist. The other is bluemonday.UGCPolicy() and allows a broad selection of HTML elements and attributes that are safe for user generated content. Note that -this policy does not whitelist iframes, object, embed, styles, script, etc. +this policy does not allow iframes, object, embed, styles, script, etc. The essence of building a policy is to determine which HTML elements and attributes are considered safe for your scenario. OWASP provide an XSS prevention cheat sheet ( https://www.google.com/search?q=xss+prevention+cheat+sheet ) to help explain the risks, but essentially: - 1. Avoid whitelisting anything other than plain HTML elements - 2. Avoid whitelisting `script`, `style`, `iframe`, `object`, `embed`, `base` + 1. Avoid allowing anything other than plain HTML elements + 2. Avoid allowing `script`, `style`, `iframe`, `object`, `embed`, `base` elements - 3. Avoid whitelisting anything other than plain HTML elements with simple + 3. Avoid allowing anything other than plain HTML elements with simple values that you can match to a regexp */ package bluemonday diff --git a/example_test.go b/example_test.go index fc279df..8fc2a2f 100644 --- a/example_test.go +++ b/example_test.go @@ -89,7 +89,7 @@ func Example() { // schema relative URLs (i.e. `href="//www.google.com"` is schema relative). p.AllowRelativeURLs(true) - // If you have enabled parseable URLs then you can whitelist the schemas + // If you have enabled parseable URLs then you can allow the schemas // that are permitted. Bear in mind that allowing relative URLs in the above // option allows for blank schemas. p.AllowURLSchemes("mailto", "http", "https") @@ -102,7 +102,7 @@ func Example() { p.RequireNoFollowOnLinks(true) // We provide a convenience function that applies all of the above, but you - // will still need to whitelist the linkable elements: + // will still need to allow the linkable elements: p = bluemonday.NewPolicy() p.AllowStandardURLs() p.AllowAttrs("cite").OnElements("blockquote") @@ -121,7 +121,7 @@ func Example() { } func ExampleNewPolicy() { - // NewPolicy is a blank policy and we need to explicitly whitelist anything + // NewPolicy is a blank policy and we need to explicitly allow anything // that we wish to allow through p := bluemonday.NewPolicy() @@ -178,7 +178,7 @@ func ExamplePolicy_AllowAttrs() { p := bluemonday.NewPolicy() // Allow the 'title' attribute on every HTML element that has been - // whitelisted + // allowed p.AllowAttrs("title").Matching(bluemonday.Paragraph).Globally() // Allow the 'abbr' attribute on only the 'td' and 'th' elements. @@ -205,7 +205,7 @@ func ExamplePolicy_AllowStyles() { p.AllowStyles("text-decoration").MatchingEnum("underline", "line-through", "none").OnElements("span") // Allow the 'color' property with valid RGB(A) hex values only - // on every HTML element that has been whitelisted + // on every HTML element that has been allowed p.AllowStyles("color").Matching(regexp.MustCompile("(?i)^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$")).Globally() // Default handler diff --git a/helpers.go b/helpers.go index 089fe9d..776a4a6 100644 --- a/helpers.go +++ b/helpers.go @@ -141,7 +141,7 @@ func (p *Policy) AllowStandardURLs() { } // AllowStandardAttributes will enable "id", "title" and the language specific -// attributes "dir" and "lang" on all elements that are whitelisted +// attributes "dir" and "lang" on all elements that are allowed func (p *Policy) AllowStandardAttributes() { // "dir" "lang" are permitted as both language attributes affect charsets // and direction of text. diff --git a/policy.go b/policy.go index 6a942c8..602a203 100644 --- a/policy.go +++ b/policy.go @@ -39,7 +39,7 @@ import ( "github.com/microcosm-cc/bluemonday/css" ) -// Policy encapsulates the whitelist of HTML elements and attributes that will +// Policy encapsulates the allowlist of HTML elements and attributes that will // be applied to the sanitised HTML. // // You should use bluemonday.NewPolicy() to create a blank policy as the @@ -192,9 +192,9 @@ func (p *Policy) init() { } } -// NewPolicy returns a blank policy with nothing whitelisted or permitted. This +// NewPolicy returns a blank policy with nothing allowed or permitted. This // is the recommended way to start building a policy and you should now use -// AllowAttrs() and/or AllowElements() to construct the whitelist of HTML +// AllowAttrs() and/or AllowElements() to construct the allowlist of HTML // elements and attributes. func NewPolicy() *Policy { @@ -208,7 +208,7 @@ func NewPolicy() *Policy { // AllowAttrs takes a range of HTML attribute names and returns an // attribute policy builder that allows you to specify the pattern and scope of -// the whitelisted attribute. +// the allowed attribute. // // The attribute policy is only added to the core policy when either Globally() // or OnElements(...) are called. @@ -373,7 +373,7 @@ func (abp *attrPolicyBuilder) Globally() *Policy { // AllowStyles takes a range of CSS property names and returns a // style policy builder that allows you to specify the pattern and scope of -// the whitelisted property. +// the allowed property. // // The style policy is only added to the core policy when either Globally() // or OnElements(...) are called. @@ -501,7 +501,7 @@ func (spb *stylePolicyBuilder) Globally() *Policy { return spb.p } -// AllowElements will append HTML elements to the whitelist without applying an +// AllowElements will append HTML elements to the allowlist without applying an // attribute policy to those elements (the elements are permitted // sans-attributes) func (p *Policy) AllowElements(names ...string) *Policy { @@ -518,6 +518,8 @@ func (p *Policy) AllowElements(names ...string) *Policy { return p } +// AllowElementsMatching will append HTML elements to the allowlist if they +// match a regexp. func (p *Policy) AllowElementsMatching(regex *regexp.Regexp) *Policy { p.init() if _, ok := p.elsMatchingAndAttrs[regex]; !ok { @@ -628,7 +630,7 @@ func (p *Policy) AllowRelativeURLs(require bool) *Policy { return p } -// AllowURLSchemes will append URL schemes to the whitelist +// AllowURLSchemes will append URL schemes to the allowlist // Example: p.AllowURLSchemes("mailto", "http", "https") func (p *Policy) AllowURLSchemes(schemes ...string) *Policy { p.init() @@ -646,7 +648,7 @@ func (p *Policy) AllowURLSchemes(schemes ...string) *Policy { } // AllowURLSchemeWithCustomPolicy will append URL schemes with -// a custom URL policy to the whitelist. +// a custom URL policy to the allowlist. // Only the URLs with matching schema and urlPolicy(url) // returning true will be allowed. func (p *Policy) AllowURLSchemeWithCustomPolicy( @@ -666,7 +668,7 @@ func (p *Policy) AllowURLSchemeWithCustomPolicy( } // AddSpaceWhenStrippingTag states whether to add a single space " " when -// removing tags that are not whitelisted by the policy. +// removing tags that are not allowed by the policy. // // This is useful if you expect to strip tags in dense markup and may lose the // value of whitespace. diff --git a/sanitize.go b/sanitize.go index 0ecc871..9bb87a6 100644 --- a/sanitize.go +++ b/sanitize.go @@ -52,7 +52,7 @@ var ( ) // Sanitize takes a string that contains a HTML fragment or document and applies -// the given policy whitelist. +// the given policy allowlist. // // It returns a HTML string that has been sanitized by the policy or an empty // string if an error has occurred (most likely as a consequence of extremely @@ -66,7 +66,7 @@ func (p *Policy) Sanitize(s string) string { } // SanitizeBytes takes a []byte that contains a HTML fragment or document and applies -// the given policy whitelist. +// the given policy allowlist. // // It returns a []byte containing the HTML that has been sanitized by the policy // or an empty []byte if an error has occurred (most likely as a consequence of @@ -80,7 +80,7 @@ func (p *Policy) SanitizeBytes(b []byte) []byte { } // SanitizeReader takes an io.Reader that contains a HTML fragment or document -// and applies the given policy whitelist. +// and applies the given policy allowlist. // // It returns a bytes.Buffer containing the HTML that has been sanitized by the // policy. Errors during sanitization will merely return an empty result. @@ -88,8 +88,8 @@ func (p *Policy) SanitizeReader(r io.Reader) *bytes.Buffer { return p.sanitizeWithBuff(r) } -// SanitizeReaderWriter takes an io.Reader that contains a HTML fragment or document -// and applies the given policy whitelist and writes to the provided writer returning +// SanitizeReaderToWriter takes an io.Reader that contains a HTML fragment or document +// and applies the given policy allowlist and writes to the provided writer returning // an error if there is one. func (p *Policy) SanitizeReaderToWriter(r io.Reader, w io.Writer) error { return p.sanitize(r, w) @@ -259,11 +259,6 @@ func (p *Policy) sanitizeWithBuff(r io.Reader) *bytes.Buffer { return &buff } -type stringWriterWriter interface { - io.Writer - io.StringWriter -} - type asStringWriter struct { io.Writer } @@ -530,7 +525,7 @@ func (p *Policy) sanitizeAttrs( } // Builds a new attribute slice based on the whether the attribute has been - // whitelisted explicitly or globally. + // allowed explicitly or globally. cleanAttrs := []html.Attribute{} attrsLoop: for _, htmlAttr := range attrs { diff --git a/stringwriterwriter_go1.12.go b/stringwriterwriter_go1.12.go new file mode 100644 index 0000000..afa011e --- /dev/null +++ b/stringwriterwriter_go1.12.go @@ -0,0 +1,10 @@ +// +build go1.12 + +package bluemonday + +import "io" + +type stringWriterWriter interface { + io.Writer + io.StringWriter +} diff --git a/stringwriterwriter_ltgo1.12.go b/stringwriterwriter_ltgo1.12.go new file mode 100644 index 0000000..9bc6747 --- /dev/null +++ b/stringwriterwriter_ltgo1.12.go @@ -0,0 +1,14 @@ +// +build go1.1,!go1.12 + +package bluemonday + +import "io" + +type stringWriterWriter interface { + io.Writer + StringWriter +} + +type StringWriter interface { + WriteString(s string) (n int, err error) +}