Sanitize output

REST API output sanitization removes or encodes data returned by requests, thus reducing security risks. Output sanitization is enabled by default. You can disable it or configure the feature using site parameters.

You can configure HTML sanitization for the values of fields of various entities in the ALM project customization interface. You can select:

  • Do nothing - return the value as it is stored in the database.
  • Text encoding - values are HTML encoded. Used especially with text fields.
  • HTML sanitization - value is sanitized according to a predefined whitelist for allowed HTML content in the following manner:

Data to be sanitized must be inside the <html> and <body> tags of a valid HTML document. Otherwise, a tag might be sanitized even though it is allowed by the whitelist.

If data cannot be stored as a valid HTML document, you can prevent unwanted sanitizing by configuring the specific field for no sanitation. Consider the security implications before doing this.

HTML sanitization

There is a default HTML sanitization whitelist. You can override the defaults by configuring HTML sanitization at the level of protocols, tags, and attributes using a custom HTML sanitizer whitelist. See Output sanitization whitelist.

The tags and attributes specified in the whitelist are returned without change.

Tags that are not in the whitelist are HTML encoded. For example, if tag <abc> is in the field value, but tag abc is not in the whitelist, the returned value is &lt;abc&gt;.

Attributes not in the whitelist are removed, even if they are attributes of a tag that is in the whitelist. For example:
The field value contains <img src="http://mypage.com/1.jpg" onClick="alert('a');" />. The img tag and the src attribute of img are in the whitelist, but the onClick attribute is not. onClick is stripped and the return value is <img src="http://mypage.com/1.jpg" />.

Attributes that reference a protocol that is not in the whitelist are removed, even if the attributes and tag are in the whitelist. For example:
The field value contains <img src="ftp://mypage.com/1.jpg" />. The img tag and the src attribute of img are in the whitelist, but the ftp protocol is not. src is stripped and the return value is <img />.

The default whitelist allows <img src=””…/> http / https protocols. For more strict sanitization, provide a custom whitelist.

Output sanitization whitelist

To specify which tags, attributes, and protocols are returned as-is when using HTML sanitization, create a custom whitelist file named sanitizer-whitelist.xml. Place the file in directory: %ALM_INSTALL_DIR%/Micro Focus/ALM/webapps/qcbin/WEB-INF/classes/. On Windows platforms the default path is C:\ProgramData\Micro Focus\ALM\webapps\qcbin\WEB-INF\classes\. On Linux platforms the default path is /var/opt/Micro Focus/ALM/webapps/qcbin/WEB-INF/classes/. The whitelist takes effect when the ALM service is restarted.

In a cluster environment, put the whitelist on each node.

The whitelist contains three collections.

  • The tags collection contains the tags that are returned unchanged. The contents of the element for a tag may change if there are attributes or protocols that are not themselves whitelisted.
  • The attributes collection contains lists of the attributes allowed for each specified tag.
  • The protocols collection contains lists of the protocols allowed for each specified tag-attribute pair. 
<root>
    <tags>
        <!--
           Collection of tags not changed by sanitizer. Content of elements may still be changed
           if contained attributes and protocols are not whitelisted.
           Tags not in this collection are HTML encoded so they are rendered by browser as plain text.
        -->
        <tag>html</tag>
        <tag>head</tag>
        <tag>meta</tag>
        <tag>body</tag>
        <tag>a</tag>
        <tag>b</tag>
    </tags>
    <attributes>
        <!--
            Collection of attributes not removed by sanitizer if they are used in the specified tag.
            For example, in this definition, in a "meta" element, only the attributes
            "http-equiv" and "content" are allowed.
               Input: <meta content="INDEX,NOFOLLOW" name="my_meta"/>
               Output: <meta content="INDEX,NOFOLLOW" />

           Attributes defined for the special tag ":all" are allowed for any tag in the "tags" collection.
        -->
        <attribute tag=":all">
            <value>style</value>
            <value>class</value>
            <value>align</value>
        </attribute>
        <attribute tag="meta">
            <value>http-equiv</value>
            <value>content</value>
        </attribute>
    </attributes>
    <protocols>
        <!--
            Collection of protocols not removed by sanitizer if they are used
            in the specified attribute and tag.
           For example, in this definition, in the "src" attribute of an "img" element,
           only "http" and  "https" are allowed.
               Input: <img src="http://somewebsite.com/a.png" />
               Output: <img src="http://somewebsite.com/a.png" />

               Input: <img src="ftp://somewebsite.com/a.png" />
               Output: <img />
        -->
        <protocol tag="img" attribute="src">
            <value>http</value>
            <value>https</value>
        </protocol>
        <protocol tag="a" attribute="href">
            <value>http</value>
            <value>https</value>
            <value>mailto</value>
        </protocol>
    </protocols>
</root>
				
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="root" type="rootType"/>
    <xs:complexType name="tagsType">
        <xs:sequence>
            <xs:element type="xs:string" name="tag" maxOccurs="unbounded" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="protocolType">
        <xs:sequence>
            <xs:element type="xs:string" name="value" maxOccurs="unbounded" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute type="xs:string" name="tag" use="required"/>
        <xs:attribute type="xs:string" name="attribute" use="required"/>
    </xs:complexType>
    <xs:complexType name="rootType">
        <xs:sequence>
            <xs:element type="tagsType" name="tags"/>
            <xs:element type="attributesType" name="attributes"/>
            <xs:element type="protocolsType" name="protocols"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="attributesType">
        <xs:sequence>
            <xs:element type="attributeType" name="attribute" maxOccurs="unbounded" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="attributeType">
        <xs:sequence>
            <xs:element type="xs:string" name="value" maxOccurs="unbounded" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute type="xs:string" name="tag" use="required"/>
    </xs:complexType>
    <xs:complexType name="protocolsType">
        <xs:sequence>
            <xs:element type="protocolType" name="protocol" maxOccurs="unbounded" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
</xs:schema>