Class XSS


  • public class XSS
    extends Object
    the static access for the Sling XSSAPI / XSSFilter - wraps the Sling XSS services
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected XSS()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static @NotNull org.apache.sling.xss.XSSAPI api()  
      static boolean check​(org.apache.sling.xss.ProtectionContext context, String src)
      Indicates whether or not a given source string contains XSS policy violations.
      static @Nullable String encodeForCSSString​(@Nullable String source)
      Encodes a source string for writing to CSS string content.
      static @Nullable String encodeForHTML​(@Nullable String source)
      Encodes a source string for HTML element content.
      static @Nullable String encodeForHTMLAttr​(@Nullable String source)
      Encodes a source string for writing to an HTML attribute value.
      static @Nullable String encodeForJSString​(@Nullable String source)
      Encodes a source string for writing to JavaScript string content.
      static @Nullable String encodeForXML​(@Nullable String source)
      Encodes a source string for XML element content.
      static @Nullable String encodeForXMLAttr​(@Nullable String source)
      Encodes a source string for writing to an XML attribute value.
      static @NotNull org.apache.sling.xss.XSSFilter filter()  
      static String filter​(String src)
      Prevents the given source string from containing XSS stuff.
      static String[] filter​(String[] src)
      Prevents the given source strings from containing XSS stuff.
      static String filter​(String contextName, String src)
      Protects the given source string from containing XSS stuff.
      static String filter​(org.apache.sling.xss.ProtectionContext context, String src)
      Protects the given source string from containing XSS stuff.
      static @NotNull String filterHTML​(@Nullable String source)
      Filters potentially user-contributed HTML to meet the AntiSamy policy rules currently in effect for HTML output (see the XSSFilter service for details).
      static @Nullable String getValidCSSColor​(@Nullable String color, @Nullable String defaultColor)
      Validate a CSS color value.
      static @Nullable String getValidDimension​(@Nullable String dimension, @Nullable String defaultValue)
      Validate a string which should contain a dimension, returning a default value if the source is empty, can't be parsed, or contains XSS risks.
      static @Nullable Double getValidDouble​(@Nullable String source, double defaultValue)
      Validate a string which should contain an double, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.
      static @NotNull String getValidHref​(@Nullable String url)
      Sanitizes a URL for writing as an HTML href or src attribute value.
      static @Nullable Integer getValidInteger​(@Nullable String integer, int defaultValue)
      Validate a string which should contain an integer, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.
      static String getValidJSON​(@Nullable String json, @Nullable String defaultJson)
      Validate a JSON string
      static @Nullable String getValidJSToken​(@Nullable String token, @Nullable String defaultValue)
      Validate a Javascript token.
      static @Nullable Long getValidLong​(@Nullable String source, long defaultValue)
      Validate a string which should contain a long, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.
      static String getValidMultiLineComment​(@Nullable String comment, @Nullable String defaultComment)
      Validate multi-line comment to be used inside a <script>...</script> or <style>...</style> block.
      static @Nullable String getValidStyleToken​(@Nullable String token, @Nullable String defaultValue)
      Validate a style/CSS token.
      static String getValidXML​(@Nullable String xml, @Nullable String defaultXml)
      Validate an XML string
      static boolean isValidHref​(String url)
      Checks if the given URL is valid to be used for the href attribute in a a tag.
    • Field Detail

      • XSSAPI_HANDLE

        protected static ServiceHandle<org.apache.sling.xss.XSSAPI> XSSAPI_HANDLE
      • XSSFilter_HANDLE

        protected static ServiceHandle<org.apache.sling.xss.XSSFilter> XSSFilter_HANDLE
    • Constructor Detail

      • XSS

        protected XSS()
    • Method Detail

      • api

        @NotNull
        public static @NotNull org.apache.sling.xss.XSSAPI api()
      • filter

        @NotNull
        public static @NotNull org.apache.sling.xss.XSSFilter filter()
      • getValidInteger

        @Nullable
        public static @Nullable Integer getValidInteger​(@Nullable
                                                        @Nullable String integer,
                                                        int defaultValue)
        Validate a string which should contain an integer, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.
        Parameters:
        integer - the source integer
        defaultValue - a default value if the source can't be used, is null or an empty string
        Returns:
        a sanitized integer
      • getValidLong

        @Nullable
        public static @Nullable Long getValidLong​(@Nullable
                                                  @Nullable String source,
                                                  long defaultValue)
        Validate a string which should contain a long, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.
        Parameters:
        source - the source long
        defaultValue - a default value if the source can't be used, is null or an empty string
        Returns:
        a sanitized integer
      • getValidDouble

        @Nullable
        public static @Nullable Double getValidDouble​(@Nullable
                                                      @Nullable String source,
                                                      double defaultValue)
        Validate a string which should contain an double, returning a default value if the source is null, empty, can't be parsed, or contains XSS risks.
        Parameters:
        source - the source double
        defaultValue - a default value if the source can't be used, is null or an empty string
        Returns:
        a sanitized double
      • getValidDimension

        @Nullable
        public static @Nullable String getValidDimension​(@Nullable
                                                         @Nullable String dimension,
                                                         @Nullable
                                                         @Nullable String defaultValue)
        Validate a string which should contain a dimension, returning a default value if the source is empty, can't be parsed, or contains XSS risks. Allows integer dimensions and the keyword "auto".
        Parameters:
        dimension - the source dimension
        defaultValue - a default value if the source can't be used, is null or an empty string
        Returns:
        a sanitized dimension
      • getValidHref

        @NotNull
        public static @NotNull String getValidHref​(@Nullable
                                                   @Nullable String url)
        Sanitizes a URL for writing as an HTML href or src attribute value.
        Parameters:
        url - the source URL
        Returns:
        a sanitized URL (possibly empty)
      • getValidJSToken

        @Nullable
        public static @Nullable String getValidJSToken​(@Nullable
                                                       @Nullable String token,
                                                       @Nullable
                                                       @Nullable String defaultValue)
        Validate a Javascript token. The value must be either a single identifier, a literal number, or a literal string.
        Parameters:
        token - the source token
        defaultValue - a default value to use if the source is null, an empty string, or doesn't meet validity constraints.
        Returns:
        a string containing a single identifier, a literal number, or a literal string token
      • getValidStyleToken

        @Nullable
        public static @Nullable String getValidStyleToken​(@Nullable
                                                          @Nullable String token,
                                                          @Nullable
                                                          @Nullable String defaultValue)
        Validate a style/CSS token. Valid CSS tokens are specified at http://www.w3.org/TR/css3-syntax/
        Parameters:
        token - the source token
        defaultValue - a default value to use if the source is null, an empty string, or doesn't meet validity constraints.
        Returns:
        a string containing sanitized style token
      • getValidCSSColor

        @Nullable
        public static @Nullable String getValidCSSColor​(@Nullable
                                                        @Nullable String color,
                                                        @Nullable
                                                        @Nullable String defaultColor)
        Validate a CSS color value. Color values as specified at http://www.w3.org/TR/css3-color/#colorunits are safe and definitively allowed. Vulnerable constructs will be disallowed. Currently known vulnerable constructs include url(...), expression(...), and anything with a semicolon.
        Parameters:
        color - the color value to be used.
        defaultColor - a default value to use if the input color value is null, an empty string, doesn't meet validity constraints.
        Returns:
        a string a css color value.
      • getValidMultiLineComment

        public static String getValidMultiLineComment​(@Nullable
                                                      @Nullable String comment,
                                                      @Nullable
                                                      @Nullable String defaultComment)
        Validate multi-line comment to be used inside a <script>...</script> or <style>...</style> block. Multi-line comment end block is disallowed.
        Parameters:
        comment - the comment to be used
        defaultComment - a default value to use if the comment is null or not valid.
        Returns:
        a valid multi-line comment
      • getValidJSON

        public static String getValidJSON​(@Nullable
                                          @Nullable String json,
                                          @Nullable
                                          @Nullable String defaultJson)
        Validate a JSON string
        Parameters:
        json - the JSON string to validate
        defaultJson - the default value to use if json is null or not valid
        Returns:
        a valid JSON string
      • getValidXML

        public static String getValidXML​(@Nullable
                                         @Nullable String xml,
                                         @Nullable
                                         @Nullable String defaultXml)
        Validate an XML string
        Parameters:
        xml - the XML string to validate
        defaultXml - the default value to use if xml is null or not valid
        Returns:
        a valid XML string
      • encodeForHTML

        @Nullable
        public static @Nullable String encodeForHTML​(@Nullable
                                                     @Nullable String source)
        Encodes a source string for HTML element content. DO NOT USE FOR WRITING ATTRIBUTE VALUES!
        Parameters:
        source - the input to encode
        Returns:
        an encoded version of the source
      • encodeForHTMLAttr

        @Nullable
        public static @Nullable String encodeForHTMLAttr​(@Nullable
                                                         @Nullable String source)
        Encodes a source string for writing to an HTML attribute value. DO NOT USE FOR ACTIONABLE ATTRIBUTES (href, src, event handlers); YOU MUST USE A VALIDATOR FOR THOSE!
        Parameters:
        source - the input to encode
        Returns:
        an encoded version of the source
      • encodeForXML

        @Nullable
        public static @Nullable String encodeForXML​(@Nullable
                                                    @Nullable String source)
        Encodes a source string for XML element content. DO NOT USE FOR WRITING ATTRIBUTE VALUES!
        Parameters:
        source - the input to encode
        Returns:
        an encoded version of the source
      • encodeForXMLAttr

        @Nullable
        public static @Nullable String encodeForXMLAttr​(@Nullable
                                                        @Nullable String source)
        Encodes a source string for writing to an XML attribute value.
        Parameters:
        source - the input to encode
        Returns:
        an encoded version of the source
      • encodeForJSString

        @Nullable
        public static @Nullable String encodeForJSString​(@Nullable
                                                         @Nullable String source)
        Encodes a source string for writing to JavaScript string content. DO NOT USE FOR WRITING TO ARBITRARY JAVASCRIPT; YOU MUST USE A VALIDATOR FOR THAT. (Encoding only ensures that the source material cannot break out of its context.)
        Parameters:
        source - the input to encode
        Returns:
        an encoded version of the source
      • encodeForCSSString

        @Nullable
        public static @Nullable String encodeForCSSString​(@Nullable
                                                          @Nullable String source)
        Encodes a source string for writing to CSS string content. DO NOT USE FOR WRITING OUT ARBITRARY CSS TOKENS; YOU MUST USE A VALIDATOR FOR THAT! (Encoding only ensures the source string cannot break out of its context.)
        Parameters:
        source - the input to encode
        Returns:
        an encoded version of the source
      • filterHTML

        @NotNull
        public static @NotNull String filterHTML​(@Nullable
                                                 @Nullable String source)
        Filters potentially user-contributed HTML to meet the AntiSamy policy rules currently in effect for HTML output (see the XSSFilter service for details).
        Parameters:
        source - a string containing the source HTML
        Returns:
        a string containing the sanitized HTML which may be an empty string if source is null or empty
      • check

        public static boolean check​(org.apache.sling.xss.ProtectionContext context,
                                    String src)
        Indicates whether or not a given source string contains XSS policy violations.
        Parameters:
        context - context to use for checking
        src - source string
        Returns:
        true if the source is violation-free
        Throws:
        NullPointerException - if context is null
      • filter

        public static String filter​(String src)
        Prevents the given source string from containing XSS stuff.

        The default protection context is used for checking.

        Parameters:
        src - source string
        Returns:
        string that does not contain XSS stuff
      • filter

        public static String[] filter​(String[] src)
        Prevents the given source strings from containing XSS stuff.

        The default protection context is used for checking.

        Parameters:
        src - array of source strings
        Returns:
        array of strings that does not contain XSS stuff
      • filter

        public static String filter​(String contextName,
                                    String src)
        Protects the given source string from containing XSS stuff.
        Parameters:
        context - context to use for checking
        src - source string
        Returns:
        string that does not contain XSS stuff
        Throws:
        NullPointerException - if context is null
      • filter

        public static String filter​(org.apache.sling.xss.ProtectionContext context,
                                    String src)
        Protects the given source string from containing XSS stuff.
        Parameters:
        context - context to use for checking
        src - source string
        Returns:
        string that does not contain XSS stuff
        Throws:
        NullPointerException - if context is null
      • isValidHref

        public static boolean isValidHref​(String url)
        Checks if the given URL is valid to be used for the href attribute in a a tag.

        The default protection context is used for checking.

        Parameters:
        url - the URL that should be validated
        Returns:
        true if the URL is violation-free