bluemonday: github.com/microcosm-cc/bluemonday Index | Examples | Files

package bluemonday

import "github.com/microcosm-cc/bluemonday"

Package bluemonday provides a way of describing a whitelist 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 default bluemonday.UGCPolicy().Sanitize() turns this:

Hello <STYLE>.XSS{background-image:url("javascript:alert('XSS')");}</STYLE><A CLASS=XSS></A>World

Into the more harmless:

Hello World

And it turns this:

<a href="javascript:alert('XSS1')" onmouseover="alert('XSS2')">XSS<a>

Into this:

XSS

Whilst still allowing this:

<a href="http://www.google.com/">
  <img src="https://ssl.gstatic.com/accounts/ui/logo_2x.png"/>
</a>

To pass through mostly unaltered (it gained a rel="nofollow"):

<a href="http://www.google.com/" rel="nofollow">
  <img src="https://ssl.gstatic.com/accounts/ui/logo_2x.png"/>
</a>

The primary purpose of bluemonday is to take potentially unsafe user generated content (from things like Markdown, HTML WYSIWYG tools, etc) and make it safe for you to put on your website.

It protects sites against XSS (http://en.wikipedia.org/wiki/Cross-site_scripting) and other malicious content that a user interface may deliver. There are many vectors for an XSS attack (https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet) and the safest thing to do is to sanitize user input against a known safe list of HTML elements and attributes.

Note: You should always run bluemonday after any other processing.

If you use blackfriday (https://github.com/russross/blackfriday) or Pandoc (http://johnmacfarlane.net/pandoc/) then bluemonday should be run after these steps. This ensures that no insecure HTML is introduced later in your process.

bluemonday is heavily inspired by both the OWASP Java HTML Sanitizer (https://code.google.com/p/owasp-java-html-sanitizer/) and the HTML Purifier (http://htmlpurifier.org/).

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.

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.

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`
   elements
3. Avoid whitelisting anything other than plain HTML elements with simple
   values that you can match to a regexp

Copyright (c) 2019, David Kitchen <david@buro9.com>

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this

list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,

this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

* Neither the name of the organisation (Microcosm) nor the names of its

contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Code:

// Create a new policy
p := bluemonday.NewPolicy()

// Add elements to a policy without attributes
p.AllowElements("b", "strong")

// Add elements as a virtue of adding an attribute
p.AllowAttrs("nowrap").OnElements("td", "th")

// Attributes can either be added to all elements
p.AllowAttrs("dir").Globally()

//Or attributes can be added to specific elements
p.AllowAttrs("value").OnElements("li")

// It is ALWAYS recommended that an attribute be made to match a pattern
// XSS in HTML attributes is a very easy attack vector

// \p{L} matches unicode letters, \p{N} matches unicode numbers
p.AllowAttrs("title").Matching(regexp.MustCompile(`[\p{L}\p{N}\s\-_',:\[\]!\./\\\(\)&]*`)).Globally()

// You can stop at any time and call .Sanitize()

// Assumes that string htmlIn was passed in from a HTTP POST and contains
// untrusted user generated content
htmlIn := `untrusted user generated content <body onload="alert('XSS')">`
fmt.Println(p.Sanitize(htmlIn))

// And you can take any existing policy and extend it
p = bluemonday.UGCPolicy()
p.AllowElements("fieldset", "select", "option")

// Links are complex beasts and one of the biggest attack vectors for
// malicious content so we have included features specifically to help here.

// This is not recommended:
p = bluemonday.NewPolicy()
p.AllowAttrs("href").Matching(regexp.MustCompile(`(?i)mailto|https?`)).OnElements("a")

// The regexp is insufficient in this case to have prevented a malformed
// value doing something unexpected.

// This will ensure that URLs are not considered invalid by Go's net/url
// package.
p.RequireParseableURLs(true)

// If you have enabled parseable URLs then the following option will allow
// relative URLs. By default this is disabled and will prevent all local and
// 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
// that are permitted. Bear in mind that allowing relative URLs in the above
// option allows for blank schemas.
p.AllowURLSchemes("mailto", "http", "https")

// Regardless of whether you have enabled parseable URLs, you can force all
// URLs to have a rel="nofollow" attribute. This will be added if it does
// not exist.

// This applies to "a" "area" "link" elements that have a "href" attribute
p.RequireNoFollowOnLinks(true)

// We provide a convenience function that applies all of the above, but you
// will still need to whitelist the linkable elements:
p = bluemonday.NewPolicy()
p.AllowStandardURLs()
p.AllowAttrs("cite").OnElements("blockquote")
p.AllowAttrs("href").OnElements("a", "area")
p.AllowAttrs("src").OnElements("img")

// Policy Building Helpers

// If you've got this far and you're bored already, we also bundle some
// other convenience functions
p = bluemonday.NewPolicy()
p.AllowStandardAttributes()
p.AllowImages()
p.AllowLists()
p.AllowTables()

Index

Examples

Package Files

doc.go handlers.go helpers.go policies.go policy.go sanitize.go

Variables

var (
    // CellAlign handles the `align` attribute
    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td#attr-align
    CellAlign = regexp.MustCompile(`(?i)^(center|justify|left|right|char)$`)

    // CellVerticalAlign handles the `valign` attribute
    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td#attr-valign
    CellVerticalAlign = regexp.MustCompile(`(?i)^(baseline|bottom|middle|top)$`)

    // Direction handles the `dir` attribute
    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/bdo#attr-dir
    Direction = regexp.MustCompile(`(?i)^(rtl|ltr)$`)

    // ImageAlign handles the `align` attribute on the `image` tag
    // http://www.w3.org/MarkUp/Test/Img/imgtest.html
    ImageAlign = regexp.MustCompile(
        `(?i)^(left|right|top|texttop|middle|absmiddle|baseline|bottom|absbottom)$`,
    )

    // Integer describes whole positive integers (including 0) used in places
    // like td.colspan
    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td#attr-colspan
    Integer = regexp.MustCompile(`^[0-9]+$`)

    // ISO8601 according to the W3 group is only a subset of the ISO8601
    // standard: http://www.w3.org/TR/NOTE-datetime
    //
    // Used in places like time.datetime
    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time#attr-datetime
    //
    // Matches patterns:
    //  Year:
    //     YYYY (eg 1997)
    //  Year and month:
    //     YYYY-MM (eg 1997-07)
    //  Complete date:
    //     YYYY-MM-DD (eg 1997-07-16)
    //  Complete date plus hours and minutes:
    //     YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)
    //  Complete date plus hours, minutes and seconds:
    //     YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)
    //  Complete date plus hours, minutes, seconds and a decimal fraction of a
    //  second
    //      YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)
    ISO8601 = regexp.MustCompile(
        `^[0-9]{4}(-[0-9]{2}(-[0-9]{2}([ T][0-9]{2}(:[0-9]{2}){1,2}(.[0-9]{1,6})` +
            `?Z?([\+-][0-9]{2}:[0-9]{2})?)?)?)?$`,
    )

    // ListType encapsulates the common value as well as the latest spec
    // values for lists
    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol#attr-type
    ListType = regexp.MustCompile(`(?i)^(circle|disc|square|a|A|i|I|1)$`)

    // SpaceSeparatedTokens is used in places like `a.rel` and the common attribute
    // `class` which both contain space delimited lists of data tokens
    // http://www.w3.org/TR/html-markup/datatypes.html#common.data.tokens-def
    // Regexp: \p{L} matches unicode letters, \p{N} matches unicode numbers
    SpaceSeparatedTokens = regexp.MustCompile(`^([\s\p{L}\p{N}_-]+)$`)

    // Number is a double value used on HTML5 meter and progress elements
    // http://www.whatwg.org/specs/web-apps/current-work/multipage/the-button-element.html#the-meter-element
    Number = regexp.MustCompile(`^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?$`)

    // NumberOrPercent is used predominantly as units of measurement in width
    // and height attributes
    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-height
    NumberOrPercent = regexp.MustCompile(`^[0-9]+[%]?$`)

    // Paragraph of text in an attribute such as *.'title', img.alt, etc
    // https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes#attr-title
    // Note that we are not allowing chars that could close tags like '>'
    Paragraph = regexp.MustCompile(`^[\p{L}\p{N}\s\-_',\[\]!\./\\\(\)]*$`)
)

A selection of regular expressions that can be used as .Matching() rules on HTML attributes.

func AlignContentHandler Uses

func AlignContentHandler(value string) bool

func AlignItemsHandler Uses

func AlignItemsHandler(value string) bool

func AlignSelfHandler Uses

func AlignSelfHandler(value string) bool

func AllHandler Uses

func AllHandler(value string) bool

func AnimationDelayHandler Uses

func AnimationDelayHandler(value string) bool

func AnimationDirectionHandler Uses

func AnimationDirectionHandler(value string) bool

func AnimationDurationHandler Uses

func AnimationDurationHandler(value string) bool

func AnimationFillModeHandler Uses

func AnimationFillModeHandler(value string) bool

func AnimationHandler Uses

func AnimationHandler(value string) bool

func AnimationIterationCountHandler Uses

func AnimationIterationCountHandler(value string) bool

func AnimationNameHandler Uses

func AnimationNameHandler(value string) bool

func AnimationPlayStateHandler Uses

func AnimationPlayStateHandler(value string) bool

func BackfaceVisibilityHandler Uses

func BackfaceVisibilityHandler(value string) bool

func BackgroundAttachmentHandler Uses

func BackgroundAttachmentHandler(value string) bool

func BackgroundBlendModeHandler Uses

func BackgroundBlendModeHandler(value string) bool

func BackgroundClipHandler Uses

func BackgroundClipHandler(value string) bool

func BackgroundHandler Uses

func BackgroundHandler(value string) bool

func BackgroundOriginHandler Uses

func BackgroundOriginHandler(value string) bool

func BackgroundPositionHandler Uses

func BackgroundPositionHandler(value string) bool

func BackgroundRepeatHandler Uses

func BackgroundRepeatHandler(value string) bool

func BackgroundSizeHandler Uses

func BackgroundSizeHandler(value string) bool

func BaseHandler Uses

func BaseHandler(value string) bool

func BorderCollapseHandler Uses

func BorderCollapseHandler(value string) bool

func BorderHandler Uses

func BorderHandler(value string) bool

func BorderImageHandler Uses

func BorderImageHandler(value string) bool

func BorderImageOutsetHandler Uses

func BorderImageOutsetHandler(value string) bool

func BorderImageRepeatHandler Uses

func BorderImageRepeatHandler(value string) bool

func BorderImageSliceHandler Uses

func BorderImageSliceHandler(value string) bool

func BorderImageWidthHandler Uses

func BorderImageWidthHandler(value string) bool

func BorderRadiusHandler Uses

func BorderRadiusHandler(value string) bool

func BorderSideHandler Uses

func BorderSideHandler(value string) bool

func BorderSideRadiusHandler Uses

func BorderSideRadiusHandler(value string) bool

func BorderSideStyleHandler Uses

func BorderSideStyleHandler(value string) bool

func BorderSideWidthHandler Uses

func BorderSideWidthHandler(value string) bool

func BorderSpacingHandler Uses

func BorderSpacingHandler(value string) bool

func BorderStyleHandler Uses

func BorderStyleHandler(value string) bool

func BorderWidthHandler Uses

func BorderWidthHandler(value string) bool

func BoxDecorationBreakHandler Uses

func BoxDecorationBreakHandler(value string) bool

func BoxShadowHandler Uses

func BoxShadowHandler(value string) bool

func BoxSizingHandler Uses

func BoxSizingHandler(value string) bool

func BreakBeforeAfterHandler Uses

func BreakBeforeAfterHandler(value string) bool

func BreakInsideHandler Uses

func BreakInsideHandler(value string) bool

func CaptionSideHandler Uses

func CaptionSideHandler(value string) bool

func CaretColorHandler Uses

func CaretColorHandler(value string) bool

func ClearHandler Uses

func ClearHandler(value string) bool

func ClipHandler Uses

func ClipHandler(value string) bool

func ColorHandler Uses

func ColorHandler(value string) bool

func ColumnCountHandler Uses

func ColumnCountHandler(value string) bool

func ColumnFillHandler Uses

func ColumnFillHandler(value string) bool

func ColumnGapHandler Uses

func ColumnGapHandler(value string) bool

func ColumnRuleHandler Uses

func ColumnRuleHandler(value string) bool

func ColumnRuleWidthHandler Uses

func ColumnRuleWidthHandler(value string) bool

func ColumnSpanHandler Uses

func ColumnSpanHandler(value string) bool

func ColumnWidthHandler Uses

func ColumnWidthHandler(value string) bool

func ColumnsHandler Uses

func ColumnsHandler(value string) bool

func CursorHandler Uses

func CursorHandler(value string) bool

func DirectionHandler Uses

func DirectionHandler(value string) bool

func DisplayHandler Uses

func DisplayHandler(value string) bool

func EmptyCellsHandler Uses

func EmptyCellsHandler(value string) bool

func FilterHandler Uses

func FilterHandler(value string) bool

func FlexBasisHandler Uses

func FlexBasisHandler(value string) bool

func FlexDirectionHandler Uses

func FlexDirectionHandler(value string) bool

func FlexFlowHandler Uses

func FlexFlowHandler(value string) bool

func FlexGrowHandler Uses

func FlexGrowHandler(value string) bool

func FlexHandler Uses

func FlexHandler(value string) bool

func FlexWrapHandler Uses

func FlexWrapHandler(value string) bool

func FloatHandler Uses

func FloatHandler(value string) bool

func FontFamilyHandler Uses

func FontFamilyHandler(value string) bool

func FontHandler Uses

func FontHandler(value string) bool

func FontKerningHandler Uses

func FontKerningHandler(value string) bool

func FontLanguageOverrideHandler Uses

func FontLanguageOverrideHandler(value string) bool

func FontSizeAdjustHandler Uses

func FontSizeAdjustHandler(value string) bool

func FontSizeHandler Uses

func FontSizeHandler(value string) bool

func FontStretchHandler Uses

func FontStretchHandler(value string) bool

func FontStyleHandler Uses

func FontStyleHandler(value string) bool

func FontSynthesisHandler Uses

func FontSynthesisHandler(value string) bool

func FontVariantCapsHandler Uses

func FontVariantCapsHandler(value string) bool

func FontVariantHandler Uses

func FontVariantHandler(value string) bool

func FontVariantPositionHandler Uses

func FontVariantPositionHandler(value string) bool

func FontWeightHandler Uses

func FontWeightHandler(value string) bool

func GridAreaHandler Uses

func GridAreaHandler(value string) bool

func GridAutoColumnsHandler Uses

func GridAutoColumnsHandler(value string) bool

func GridAutoFlowHandler Uses

func GridAutoFlowHandler(value string) bool

func GridAxisStartEndHandler Uses

func GridAxisStartEndHandler(value string) bool

func GridColumnGapHandler Uses

func GridColumnGapHandler(value string) bool

func GridColumnHandler Uses

func GridColumnHandler(value string) bool

func GridGapHandler Uses

func GridGapHandler(value string) bool

func GridHandler Uses

func GridHandler(value string) bool

func GridRowHandler Uses

func GridRowHandler(value string) bool

func GridTemplateAreasHandler Uses

func GridTemplateAreasHandler(value string) bool

func GridTemplateColumnsHandler Uses

func GridTemplateColumnsHandler(value string) bool

func GridTemplateHandler Uses

func GridTemplateHandler(value string) bool

func GridTemplateRowsHandler Uses

func GridTemplateRowsHandler(value string) bool

func HangingPunctuationHandler Uses

func HangingPunctuationHandler(value string) bool

func HeightHandler Uses

func HeightHandler(value string) bool

func HyphensHandler Uses

func HyphensHandler(value string) bool

func ImageHandler Uses

func ImageHandler(value string) bool

func ImageRenderingHandler Uses

func ImageRenderingHandler(value string) bool

func IsolationHandler Uses

func IsolationHandler(value string) bool

func JustifyContentHandler Uses

func JustifyContentHandler(value string) bool

func LengthHandler Uses

func LengthHandler(value string) bool

func LetterSpacingHandler Uses

func LetterSpacingHandler(value string) bool

func LineBreakHandler Uses

func LineBreakHandler(value string) bool

func LineHeightHandler Uses

func LineHeightHandler(value string) bool

func ListStyleHandler Uses

func ListStyleHandler(value string) bool

func ListStylePositionHandler Uses

func ListStylePositionHandler(value string) bool

func ListStyleTypeHandler Uses

func ListStyleTypeHandler(value string) bool

func MarginHandler Uses

func MarginHandler(value string) bool

func MarginSideHandler Uses

func MarginSideHandler(value string) bool

func MaxHeightWidthHandler Uses

func MaxHeightWidthHandler(value string) bool

func MinHeightWidthHandler Uses

func MinHeightWidthHandler(value string) bool

func MixBlendModeHandler Uses

func MixBlendModeHandler(value string) bool

func ObjectFitHandler Uses

func ObjectFitHandler(value string) bool

func ObjectPositionHandler Uses

func ObjectPositionHandler(value string) bool

func OpacityHandler Uses

func OpacityHandler(value string) bool

func OrderHandler Uses

func OrderHandler(value string) bool

func OrphansHandler Uses

func OrphansHandler(value string) bool

func OutlineHandler Uses

func OutlineHandler(value string) bool

func OutlineOffsetHandler Uses

func OutlineOffsetHandler(value string) bool

func OutlineStyleHandler Uses

func OutlineStyleHandler(value string) bool

func OutlineWidthHandler Uses

func OutlineWidthHandler(value string) bool

func OverflowHandler Uses

func OverflowHandler(value string) bool

func OverflowWrapHandler Uses

func OverflowWrapHandler(value string) bool

func OverflowXYHandler Uses

func OverflowXYHandler(value string) bool

func PaddingHandler Uses

func PaddingHandler(value string) bool

func PaddingSideHandler Uses

func PaddingSideHandler(value string) bool

func PageBreakBeforeAfterHandler Uses

func PageBreakBeforeAfterHandler(value string) bool

func PageBreakInsideHandler Uses

func PageBreakInsideHandler(value string) bool

func PerspectiveHandler Uses

func PerspectiveHandler(value string) bool

func PerspectiveOriginHandler Uses

func PerspectiveOriginHandler(value string) bool

func PointerEventsHandler Uses

func PointerEventsHandler(value string) bool

func PositionHandler Uses

func PositionHandler(value string) bool

func QuotesHandler Uses

func QuotesHandler(value string) bool

func ResizeHandler Uses

func ResizeHandler(value string) bool

func ScrollBehaviorHandler Uses

func ScrollBehaviorHandler(value string) bool

func SideHandler Uses

func SideHandler(value string) bool

func TabSizeHandler Uses

func TabSizeHandler(value string) bool

func TableLayoutHandler Uses

func TableLayoutHandler(value string) bool

func TextAlignHandler Uses

func TextAlignHandler(value string) bool

func TextAlignLastHandler Uses

func TextAlignLastHandler(value string) bool

func TextCombineUprightHandler Uses

func TextCombineUprightHandler(value string) bool

func TextDecorationHandler Uses

func TextDecorationHandler(value string) bool

func TextDecorationLineHandler Uses

func TextDecorationLineHandler(value string) bool

func TextDecorationStyleHandler Uses

func TextDecorationStyleHandler(value string) bool

func TextIndentHandler Uses

func TextIndentHandler(value string) bool

func TextJustifyHandler Uses

func TextJustifyHandler(value string) bool

func TextOrientationHandler Uses

func TextOrientationHandler(value string) bool

func TextOverflowHandler Uses

func TextOverflowHandler(value string) bool

func TextShadowHandler Uses

func TextShadowHandler(value string) bool

func TextTransformHandler Uses

func TextTransformHandler(value string) bool

func TimingFunctionHandler Uses

func TimingFunctionHandler(value string) bool

func TransformHandler Uses

func TransformHandler(value string) bool

func TransformOriginHandler Uses

func TransformOriginHandler(value string) bool

func TransformStyleHandler Uses

func TransformStyleHandler(value string) bool

func TransitionDelayHandler Uses

func TransitionDelayHandler(value string) bool

func TransitionDurationHandler Uses

func TransitionDurationHandler(value string) bool

func TransitionHandler Uses

func TransitionHandler(value string) bool

func TransitionPropertyHandler Uses

func TransitionPropertyHandler(value string) bool

func UnicodeBidiHandler Uses

func UnicodeBidiHandler(value string) bool

func UserSelectHandler Uses

func UserSelectHandler(value string) bool

func VerticalAlignHandler Uses

func VerticalAlignHandler(value string) bool

func VisiblityHandler Uses

func VisiblityHandler(value string) bool

func WhiteSpaceHandler Uses

func WhiteSpaceHandler(value string) bool

func WidthHandler Uses

func WidthHandler(value string) bool

func WordBreakHandler Uses

func WordBreakHandler(value string) bool

func WordSpacingHandler Uses

func WordSpacingHandler(value string) bool

func WordWrapHandler Uses

func WordWrapHandler(value string) bool

func WritingModeHandler Uses

func WritingModeHandler(value string) bool

func ZIndexHandler Uses

func ZIndexHandler(value string) bool

type Policy Uses

type Policy struct {
    // contains filtered or unexported fields
}

Policy encapsulates the whitelist 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 unexported fields contain maps that need to be initialized.

func NewPolicy Uses

func NewPolicy() *Policy

NewPolicy returns a blank policy with nothing whitelisted 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 elements and attributes.

Code:

// NewPolicy is a blank policy and we need to explicitly whitelist anything
// that we wish to allow through
p := bluemonday.NewPolicy()

// We ensure any URLs are parseable and have rel="nofollow" where applicable
p.AllowStandardURLs()

// AllowStandardURLs already ensures that the href will be valid, and so we
// can skip the .Matching()
p.AllowAttrs("href").OnElements("a")

// We allow paragraphs too
p.AllowElements("p")

html := p.Sanitize(
    `<p><a onblur="alert(secret)" href="http://www.google.com">Google</a></p>`,
)

fmt.Println(html)

Output:

<p><a href="http://www.google.com" rel="nofollow">Google</a></p>

func StrictPolicy Uses

func StrictPolicy() *Policy

StrictPolicy returns an empty policy, which will effectively strip all HTML elements and their attributes from a document.

Code:

// StrictPolicy is equivalent to NewPolicy and as nothing else is declared
// we are stripping all elements (and their attributes)
p := bluemonday.StrictPolicy()

html := p.Sanitize(
    `Goodbye <a onblur="alert(secret)" href="http://en.wikipedia.org/wiki/Goodbye_Cruel_World_(Pink_Floyd_song)">Cruel</a> World`,
)

fmt.Println(html)

Output:

Goodbye Cruel World

func StripTagsPolicy Uses

func StripTagsPolicy() *Policy

StripTagsPolicy is DEPRECATED. Use StrictPolicy instead.

func UGCPolicy Uses

func UGCPolicy() *Policy

UGCPolicy returns a policy aimed at user generated content that is a result of HTML WYSIWYG tools and Markdown conversions.

This is expected to be a fairly rich document where as much markup as possible should be retained. Markdown permits raw HTML so we are basically providing a policy to sanitise HTML5 documents safely but with the least intrusion on the formatting expectations of the user.

Code:

// UGCPolicy is a convenience policy for user generated content.
p := bluemonday.UGCPolicy()

html := p.Sanitize(
    `<a onblur="alert(secret)" href="http://www.google.com">Google</a>`,
)

fmt.Println(html)

Output:

<a href="http://www.google.com" rel="nofollow">Google</a>

func (*Policy) AddSpaceWhenStrippingTag Uses

func (p *Policy) AddSpaceWhenStrippingTag(allow bool) *Policy

AddSpaceWhenStrippingTag states whether to add a single space " " when removing tags that are not whitelisted by the policy.

This is useful if you expect to strip tags in dense markup and may lose the value of whitespace.

For example: "<p>Hello</p><p>World</p>"" would be sanitized to "HelloWorld" with the default value of false, but you may wish to sanitize this to " Hello World " by setting AddSpaceWhenStrippingTag to true as this would retain the intent of the text.

func (p *Policy) AddTargetBlankToFullyQualifiedLinks(require bool) *Policy

AddTargetBlankToFullyQualifiedLinks will result in all a, area and link tags that point to a non-local destination (i.e. starts with a protocol and has a host) having a target="_blank" added to them if one does not already exist

Note: This requires p.RequireParseableURLs(true) and will enable it.

func (*Policy) AllowAttrs Uses

func (p *Policy) AllowAttrs(attrNames ...string) *attrPolicyBuilder

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 attribute policy is only added to the core policy when either Globally() or OnElements(...) are called.

Code:

p := bluemonday.NewPolicy()

// Allow the 'title' attribute on every HTML element that has been
// whitelisted
p.AllowAttrs("title").Matching(bluemonday.Paragraph).Globally()

// Allow the 'abbr' attribute on only the 'td' and 'th' elements.
p.AllowAttrs("abbr").Matching(bluemonday.Paragraph).OnElements("td", "th")

// Allow the 'colspan' and 'rowspan' attributes, matching a positive integer
// pattern, on only the 'td' and 'th' elements.
p.AllowAttrs("colspan", "rowspan").Matching(
    bluemonday.Integer,
).OnElements("td", "th")

func (*Policy) AllowDataAttributes Uses

func (p *Policy) AllowDataAttributes()

AllowDataAttributes whitelists all data attributes. We can't specify the name of each attribute exactly as they are customized.

NOTE: These values are not sanitized and applications that evaluate or process them without checking and verification of the input may be at risk if this option is enabled. This is a 'caveat emptor' option and the person enabling this option needs to fully understand the potential impact with regards to whatever application will be consuming the sanitized HTML afterwards, i.e. if you know you put a link in a data attribute and use that to automatically load some new window then you're giving the author of a HTML fragment the means to open a malicious destination automatically. Use with care!

func (*Policy) AllowDataURIImages Uses

func (p *Policy) AllowDataURIImages()

AllowDataURIImages permits the use of inline images defined in RFC2397 http://tools.ietf.org/html/rfc2397 http://en.wikipedia.org/wiki/Data_URI_scheme

Images must have a mimetype matching:

image/gif
image/jpeg
image/png
image/webp

NOTE: There is a potential security risk to allowing data URIs and you should only permit them on content you already trust. http://palizine.plynt.com/issues/2010Oct/bypass-xss-filters/ https://capec.mitre.org/data/definitions/244.html

func (*Policy) AllowElements Uses

func (p *Policy) AllowElements(names ...string) *Policy

AllowElements will append HTML elements to the whitelist without applying an attribute policy to those elements (the elements are permitted sans-attributes)

Code:

p := bluemonday.NewPolicy()

// Allow styling elements without attributes
p.AllowElements("br", "div", "hr", "p", "span")

func (*Policy) AllowElementsContent Uses

func (p *Policy) AllowElementsContent(names ...string) *Policy

AllowElementsContent marks the HTML elements whose content should be retained after removing the tag.

func (*Policy) AllowElementsMatching Uses

func (p *Policy) AllowElementsMatching(regex *regexp.Regexp) *Policy

func (*Policy) AllowImages Uses

func (p *Policy) AllowImages()

AllowImages enables the img element and some popular attributes. It will also ensure that URL values are parseable. This helper does not enable data URI images, for that you should also use the AllowDataURIImages() helper.

func (*Policy) AllowLists Uses

func (p *Policy) AllowLists()

AllowLists will enabled ordered and unordered lists, as well as definition lists

func (*Policy) AllowNoAttrs Uses

func (p *Policy) AllowNoAttrs() *attrPolicyBuilder

AllowNoAttrs says that attributes on element are optional.

The attribute policy is only added to the core policy when OnElements(...) are called.

func (*Policy) AllowRelativeURLs Uses

func (p *Policy) AllowRelativeURLs(require bool) *Policy

AllowRelativeURLs enables RequireParseableURLs and then permits URLs that are parseable, have no schema information and url.IsAbs() returns false This permits local URLs

func (*Policy) AllowStandardAttributes Uses

func (p *Policy) AllowStandardAttributes()

AllowStandardAttributes will enable "id", "title" and the language specific attributes "dir" and "lang" on all elements that are whitelisted

func (*Policy) AllowStandardURLs Uses

func (p *Policy) AllowStandardURLs()

AllowStandardURLs is a convenience function that will enable rel="nofollow" on "a", "area" and "link" (if you have allowed those elements) and will ensure that the URL values are parseable and either relative or belong to the "mailto", "http", or "https" schemes

func (*Policy) AllowStyles Uses

func (p *Policy) AllowStyles(propertyNames ...string) *stylePolicyBuilder

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 style policy is only added to the core policy when either Globally() or OnElements(...) are called.

Code:

p := bluemonday.NewPolicy()

// Allow only 'span' and 'p' elements
p.AllowElements("span", "p", "strong")

// Only allow 'style' attributes on 'span' and 'p' elements
p.AllowAttrs("style").OnElements("span", "p")

// Allow the 'text-decoration' property to be set to 'underline', 'line-through' or 'none'
// on 'span' elements only
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
p.AllowStyles("color").Matching(regexp.MustCompile("(?i)^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$")).Globally()

// Default handler
p.AllowStyles("background-origin").Globally()

// The span has an invalid 'color' which will be stripped along with other disallowed properties
html := p.Sanitize(
    `<p style="color:#f00;">
	<span style="text-decoration: underline; background-image: url(javascript:alert('XSS')); color: #f00ba; background-origin: invalidValue">
		Red underlined <strong style="text-decoration:none;">text</strong>
	</span>
</p>`,
)

fmt.Println(html)

Output:

<p style="color: #f00">
	<span style="text-decoration: underline">
		Red underlined <strong>text</strong>
	</span>
</p>

func (*Policy) AllowStyling Uses

func (p *Policy) AllowStyling()

AllowStyling presently enables the class attribute globally.

Note: When bluemonday ships a CSS parser and we can safely sanitise that, this will also allow sanitized styling of elements via the style attribute.

func (*Policy) AllowTables Uses

func (p *Policy) AllowTables()

AllowTables will enable a rich set of elements and attributes to describe HTML tables

func (*Policy) AllowURLSchemeWithCustomPolicy Uses

func (p *Policy) AllowURLSchemeWithCustomPolicy(
    scheme string,
    urlPolicy func(url *url.URL) (allowUrl bool),
) *Policy

AllowURLSchemeWithCustomPolicy will append URL schemes with a custom URL policy to the whitelist. Only the URLs with matching schema and urlPolicy(url) returning true will be allowed.

func (*Policy) AllowURLSchemes Uses

func (p *Policy) AllowURLSchemes(schemes ...string) *Policy

AllowURLSchemes will append URL schemes to the whitelist Example: p.AllowURLSchemes("mailto", "http", "https")

func (p *Policy) RequireNoFollowOnFullyQualifiedLinks(require bool) *Policy

RequireNoFollowOnFullyQualifiedLinks will result in all a, area, and link tags that point to a non-local destination (i.e. starts with a protocol and has a host) having a rel="nofollow" added to them if one does not already exist

Note: This requires p.RequireParseableURLs(true) and will enable it.

func (p *Policy) RequireNoFollowOnLinks(require bool) *Policy

RequireNoFollowOnLinks will result in all a, area, link tags having a rel="nofollow"added to them if one does not already exist

Note: This requires p.RequireParseableURLs(true) and will enable it.

func (p *Policy) RequireNoReferrerOnFullyQualifiedLinks(require bool) *Policy

RequireNoReferrerOnFullyQualifiedLinks will result in all a, area, and link tags that point to a non-local destination (i.e. starts with a protocol and has a host) having a rel="noreferrer" added to them if one does not already exist

Note: This requires p.RequireParseableURLs(true) and will enable it.

func (p *Policy) RequireNoReferrerOnLinks(require bool) *Policy

RequireNoReferrerOnLinks will result in all a, area, and link tags having a rel="noreferrrer" added to them if one does not already exist

Note: This requires p.RequireParseableURLs(true) and will enable it.

func (*Policy) RequireParseableURLs Uses

func (p *Policy) RequireParseableURLs(require bool) *Policy

RequireParseableURLs will result in all URLs requiring that they be parseable by "net/url" url.Parse() This applies to: - a.href - area.href - blockquote.cite - img.src - link.href - script.src

func (*Policy) Sanitize Uses

func (p *Policy) Sanitize(s string) string

Sanitize takes a string that contains a HTML fragment or document and applies the given policy whitelist.

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 malformed input)

Code:

// UGCPolicy is a convenience policy for user generated content.
p := bluemonday.UGCPolicy()

// string in, string out
html := p.Sanitize(`<a onblur="alert(secret)" href="http://www.google.com">Google</a>`)

fmt.Println(html)

Output:

<a href="http://www.google.com" rel="nofollow">Google</a>

func (*Policy) SanitizeBytes Uses

func (p *Policy) SanitizeBytes(b []byte) []byte

SanitizeBytes takes a []byte that contains a HTML fragment or document and applies the given policy whitelist.

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 extremely malformed input)

Code:

// UGCPolicy is a convenience policy for user generated content.
p := bluemonday.UGCPolicy()

// []byte in, []byte out
b := []byte(`<a onblur="alert(secret)" href="http://www.google.com">Google</a>`)
b = p.SanitizeBytes(b)

fmt.Println(string(b))

Output:

<a href="http://www.google.com" rel="nofollow">Google</a>

func (*Policy) SanitizeReader Uses

func (p *Policy) SanitizeReader(r io.Reader) *bytes.Buffer

SanitizeReader takes an io.Reader that contains a HTML fragment or document and applies the given policy whitelist.

It returns a bytes.Buffer containing the HTML that has been sanitized by the policy. Errors during sanitization will merely return an empty result.

Code:

// UGCPolicy is a convenience policy for user generated content.
p := bluemonday.UGCPolicy()

// io.Reader in, bytes.Buffer out
r := strings.NewReader(`<a onblur="alert(secret)" href="http://www.google.com">Google</a>`)
buf := p.SanitizeReader(r)

fmt.Println(buf.String())

Output:

<a href="http://www.google.com" rel="nofollow">Google</a>

func (*Policy) SkipElementsContent Uses

func (p *Policy) SkipElementsContent(names ...string) *Policy

SkipElementsContent adds the HTML elements whose tags is needed to be removed with its content.

Package bluemonday imports 9 packages (graph) and is imported by 462 packages. Updated 2019-11-19. Refresh now. Tools for package owners.