xml-threat-protection.md

description
This page provides the technical details of the XML Threat Protection policy

XML Threat Protection

Overview

You can use the xml-threat-protection policy to validate an XML request body by applying limits on XML structures such as elements, entities, attributes and string values. When an invalid request is detected (meaning the limit is reached), the request will be considered a threat and rejected with a 400 BAD REQUEST.

Functional and implementation information for the xml-threat-protection policy is organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to v2 APIs and v4 HTTP proxy APIs. It cannot be applied to v4 message APIs or v4 TCP proxy APIs. {% endhint %}

{% tabs %} {% tab title="HTTP proxy API example" %} Sample policy configuration:

{
        "name" : "XML Threat Protection",
        "enabled" : true,
        "policy" : "xml-threat-protection",
        "configuration" : {
          "maxDepth" : 90,
          "maxChildrenPerElement" : 90,
          "maxEntities" : 90,
          "maxAttributesPerElement" : 90,
          "allowExternalEntities" : false,
          "maxElements" : 900,
          "maxEntityDepth" : 90,
          "maxAttributeValueLength" : 90,
          "maxTextValueLength" : 90,
          "maxLength" : 900
        }
}

{% endtab %} {% endtabs %}

Configuration

Phases

The phases checked below are supported by the xml-threat-protection policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	false	onRequest	false
onResponse	false	onResponse	false
onRequestContent	true	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

The xml-threat-protection policy can be configured with the following options:

Property	Required	Description	Type	Default
maxElements	false	Maximum number of elements allowed in an XML document. Example: <root><a>1</a>2<b></b></root> has 3 elements.	integer (-1 to specify no limit)	1000
maxDepth	false	Maximum depth of XML structure. Example: <root><a><b>1</b></a></root> has a depth of 2.	integer (-1 to specify no limit)	100
maxLength	false	Maximum number of characters allowed for the whole XML document.	integer (-1 to specify no limit)	1000
maxAttributesPerElement	false	Maximum number of attributes allowed for single XML element.	integer (-1 to specify no limit)	100
maxAttributeValueLength	false	Maximum length of individual attribute values.	integer (-1 to specify no limit)	100
maxChildrenPerElement	false	Maximum number of child elements for a given element. Example: <code><root><a><b>1</b><c>2</c></a></root></code> a element has 2 children.	integer (-1 to specify no limit)	100
maxTextValueLength	false	Maximum length of individual text value.	integer (-1 to specify no limit)	100
maxEntities	false	Maximum number of entity expansions allowed. XML entities are a type of macro and vulnerable to entity expansion attacks (for more information on XML entity expansion attacks, see Billion laughs attack).	integer (-1 to specify no limit)	100
maxEntityDepth	false	Maximum depth of nested entity expansions allowed.	integer (-1 to specify no limit)	100
allowExternalEntities	false	Whether to allow inclusion of external entities. WARNING: Since XML can be vulnerable to XXE injection, only enable this feature if you can really trust your consumers.	boolean	false

Compatibility matrix

The following is the compatibility matrix for APIM and the xml-threat-protection policy:

Plugin Version	Supported APIM versions
1.x	All

Errors

HTTP status code	Message
400 Bad Request	Invalid xml structure Maximum xml elements exceeded Maximum xml depth exceeded Maximum xml length exceeded Maximum attributes per element exceeded Maximum attribute value length exceeded Maximum children per element exceeded Maximum text value length exceeded Maximum xml entities exceeded Maximum xml entity depth exceeded External entity is used when prohibited

You can use the response template feature to override the default response provided by the policy. These templates must be defined at the API level (see the API Console Response Templates option in the API Proxy menu).

The error keys sent by this policy are as follows:

Key	Parameters
XML_THREAT_DETECTED	-
XML_THREAT_MAX_DEPTH	-
XML_THREAT_MAX_LENGTH	-
XML_THREAT_MAX_ATTRIBUTES	-
XML_THREAT_MAX_ATTRIBUTE_VALUE_LENGTH	-
XML_MAX_CHILD_ELEMENTS	-
XML_THREAT_MAX_TEXT_VALUE_LENGTH	-
XML_THREAT_MAX_ENTITIES	-
XML_THREAT_MAX_ENTITY_DEPTH	-
XML_THREAT_EXTERNAL_ENTITY_FORBIDDEN	-

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-xml-threat-protection/blob/master/CHANGELOG.md" %}