XMLThreatProtection policy

What

Address XML vulnerabilities and minimize attacks on your API. Optionally, detect XML payload attacks based on configured limits. Screen against XML threats using the following approaches:

  • Validate messages against an XML schema (.xsd)
  • Evaluate message content for specific blacklisted keywords or patterns
  • Detect corrupt or malformed messages before those messages are parsed

Watch a short video on threat protection

Video: Watch a short video on threat protection policies from the Four-minute Videos for Developers (4MV4D) series.

Element reference

The element reference describes the elements and attributes of the XMLThreatProtection policy.

<XMLThreatProtection async="false" continueOnError="false" enabled="true" name="XML-Threat-Protection-1">
   <DisplayName>XML Threat Protection 1</DisplayName>
   <NameLimits>
      <Element>10</Element>
      <Attribute>10</Attribute>
      <NamespacePrefix>10</NamespacePrefix>
      <ProcessingInstructionTarget>10</ProcessingInstructionTarget>
   </NameLimits>
   <Source>request</Source>
   <StructureLimits>
      <NodeDepth>5</NodeDepth>
      <AttributeCountPerElement>2</AttributeCountPerElement>
      <NamespaceCountPerElement>3</NamespaceCountPerElement>
      <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
   </StructureLimits>
   <ValueLimits>
      <Text>15</Text>
      <Attribute>10</Attribute>
      <NamespaceURI>10</NamespaceURI>
      <Comment>10</Comment>
      <ProcessingInstructionData>10</ProcessingInstructionData>
   </ValueLimits> 
</XMLThreatProtection>

<XMLThreatProtection> attributes

<XMLThreatProtection async="false" continueOnError="false" enabled="true" name="XML-Threat-Protection-1"> 

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default:

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence: Optional
Type: String

<NameLimits> element

Specifies character limits to be checked and enforced by the policy.

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>
Default: N/A
Presence: Optional
Type: N/A

<NameLimits>/<Element> element

Specifies a limit on the maximum number of characters permitted in any element name in the XML document.

For example, consider the following XML:

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>

When analyzing the XML above, the <Element> element value in the policy snippet below will validate that element names (book , title, author, and year) do not exceed 10 characters.

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type: Integer

<NameLimits>/<Attribute> element

Specifies a limit on the maximum number of characters permitted in any attribute name in the XML document.

For example, consider the following XML:

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>

When analyzing the XML above, the <Attribute> element value in the policy snippet below will validate that attribute name category does not exceed 10 characters.

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type: Integer

<NameLimits>/<NamespacePrefix> element

Specifies a limit on the maximum number of characters permitted in the namespace prefix in the XML document.

For example, consider the following XML:

<ns1:myelem xmlns:ns1="http://ns1.com"/>

When analyzing the XML above, the <NamespacePrefix> element value in the policy snippet below will validate that the namespace prefix ns1 does not exceed 10 characters.

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type: Integer

<NameLimits>/<ProcessingInstructionTarget> element

Specifies a limit on the maximum number of characters permitted in the target of any processing instructions in the XML document.

For example, consider the following XML:

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

When analyzing the XML above, the <ProcessingInstructionTarget> element value in the policy snippet below will validate that the processing instruction target xml-stylesheet does not exceed 10 characters.

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type: Integer

<Source> element

Message to be screened for XML payload attacks. This is most commonly set to request, as you will typically need to validate inbound requests from client apps. When set to message, this element will automatically evaluate the request message when attached to the request flow and the response message when attached to the response flow.

<Source>request</Source>
Default: request
Presence: Optional
Type:

String.

Select from request, response, or message.

<StructuralLimits> element

Specifies structural limits to be checked and enforced by the policy.

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>
Default: N/A
Presence: Optional
Type: N/A

<StructuralLimits>/<NodeDepth> element

Specifies the maximum node depth allowed in the XML.

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type:

Integer

<StructuralLimits>/<AttributeCountPerElement> element

Specifies the maximum number of attributes allowed for any element.

For example, consider the following XML:

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>
When analyzing the XML above, the <AttributeCountPerElement> element value in the policy snippet below will validate that the elements book, title, author, and year do not have more than 2 attributes each. Note that attributes used for defining namespaces are not counted.
<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type:

Integer

<StructuralLimits>/<NameSpaceCountPerElement> element

Specifies the maximum number of namespace definitions allowed for any element.

For example, consider the following XML:

<e1 attr1="val1" attr2="val2">
    <e2 xmlns="http://apigee.com" xmlns:yahoo="http://yahoo.com" one="1" yahoo:two="2"/>
</e1>

When analyzing the XML above, the <NamespaceCountPerElement> element value in the policy snippet below will validate that the elements e1 and e2 do not have more than 2 namespace definitions each. In this case, <e1> has 0 namespace definitions and <e2> has 2 namespace definitions: xmlns="http://apigee.com" and xmlns:yahoo="http://yahoo.com".

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type:

Integer

<StructuralLimits>/<ChildCount> element

Specifies the maximum number of child elements allowed for any element.

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type:

Integer

Attributes

Attribute Default Presence
includeComment true Optional
includeElement true Optional
includeProcessingInstructions true Optional
includeText true Optional

<ValueLimits> element

Specifies character limits for values to be checked and enforced by the policy.

<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
Default: N/A
Presence: Optional
Type:

N/A

<ValueLimits>/<Text> element

Specifies a character limit for any text nodes present in the XML document.

For example, consider the following XML:

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>
When analyzing the XML above, the <Text> element value in the policy snippet below will validate that the element text values Learning XML, Erik T. Ray, and 2003 do not exceed 15 characters each.
<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type:

Integer

<ValueLimits>/<Attribute> element

Specifies a character limit for any attribute values present in the XML document.

For example, consider the following XML:

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>
When analyzing the XML above, the <Attribute> element value in the policy snippet below will validate that the attribute value WEB does not exceed 10 characters.
<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type:

Integer

<ValueLimits>/<NamespaceURI> element

Specifies a character limit for any namespace URIs present in the XML document.

For example, consider the following XML:

<ns1:myelem xmlns:ns1="http://ns1.com"/>
When analyzing the XML above, the <NamespaceURI> element value in the policy snippet below will validate that the namespace URI value http://ns1.com does not exceed 10 characters.
<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type:

Integer

<ValueLimits>/<Comment> element

Specifies a character limit for any comments present in the XML document.

For example, consider the following XML:

<book category="WEB">
   <!-- This is a comment -->
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>
When analyzing the XML above, the <Comment> element value in the policy snippet below will validate that the comment text This is a comment does not exceed 10 characters.
<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type:

Integer

<ValueLimits>/<ProcessingInstructionData> element

Specifies a character limit for any processing instruction text present in the XML document.

For example, consider the following XML:

<?xml-stylesheet type="text/xsl" href="style.xsl"?>
When analyzing the XML above, the <ProcessingInstructionData> element value in the policy snippet below will validate that the processing instruction text type="text/xsl" href="style.xsl" does not exceed 10 characters.
<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
Default: If you do not specify a limit, the system applies a default value of -1, which the system equates to no limit.
Presence: Optional
Type:

Integer

Error reference

Errors returned from Edge policies follow a consistent format as described in the Error code reference.

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

* Fault code Fault string * HTTP status Cause
steps.xmlthreatprotection.AttrCountExceeded XMLThreatProtection stepDefinition {0}: Attribute count exceeded {1} 500 See fault string.
steps.xmlthreatprotection.AttrNameExceeded XMLThreatProtection stepDefinition {0}: Attribute name length exceeded {1} 500 See fault string.
steps.xmlthreatprotection.AttrValueExceeded XMLThreatProtection stepDefinition {0}: Attribute value length exceeded {1} 500 See fault string.
steps.xmlthreatprotection.ChildCountExceeded XMLThreatProtection stepDefinition {0}: Children count exceeded {1} 500 See fault string.
steps.xmlthreatprotection.CommentExceeded XMLThreatProtection stepDefinition {0}: Comment length exceeded {1} 500 See fault string.
steps.xmlthreatprotection.ElemNameExceeded XMLThreatProtection stepDefinition {0}: Element name length exceeded {1} 500 See fault string.
steps.xmlthreatprotection.ExecutionFailed XMLThreatProtection stepDefinition {0}: Execution failed. reason: {1} 500 See fault string.
steps.xmlthreatprotection.NodeDepthExceeded XMLThreatProtection stepDefinition {0}: Node depth exceeded {1} 500 See fault string.
steps.xmlthreatprotection.NonMessageVariable Variable {0} does not resolve to a Message 500 See fault string.
steps.xmlthreatprotection.NSCountExceeded XMLThreatProtection stepDefinition {0}: Namespace count exceeded {1} 500 See fault string.
steps.xmlthreatprotection.NSPrefixExceeded XMLThreatProtection stepDefinition {0}: Namespace prefix length exceeded {1} 500 See fault string.
steps.xmlthreatprotection.NSURIExceeded XMLThreatProtection stepDefinition {0}: Namespace uri length exceeded {1} 500 See fault string.
steps.xmlthreatprotection.PIDataExceeded XMLThreatProtection stepDefinition {0}: Processing Instruction data length exceeded {1} 500 See fault string.
steps.xmlthreatprotection.PITargetExceeded XMLThreatProtection stepDefinition {0}: Processing Instruction target length exceeded {1} 500 See fault string.
steps.xmlthreatprotection.SourceUnavailable XMLThreatProtection stepDefinition {0}: Source {1} is not available 500 See fault string.
steps.xmlthreatprotection.TextExceeded XMLThreatProtection stepDefinition {0}: Text length exceeded {1} 500 See fault string.

* Notes:

  • The error name ExecutionFailed is the default error name and will be returned regardless of the type of error detected; however, this default can be changed by setting an organization-level property. When this property is set, the error name will reflect the actual error. For example, "TextExceeded" or "AttrValueExceeded". See the Usage Notes for details.
  • The 500 HTTP status is the default; however, the HTTP Status can be changed to 400 for request flow faults by setting an organization-level property. See the Usage Notes for details.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "SourceUnavailable"
xmlattack.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. xmlattack.XPT-SecureRequest.failed = true

Example error response

{
  "fault": {
    "faultstring": "XMLThreatProtection[XPT-SecureRequest]: Execution failed. reason: XMLThreatProtection[XTP-SecureRequest]: Exceeded object entry name length at line 2",
    "detail": {
      "errorcode": "steps.xmlthreatprotection.ExecutionFailed"
    }
  }
}

Example fault rule

<FaultRule name="XML Threat Protection Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ExecutionFailed") </Condition>
    </Step>
    <Condition>(xmlattack.XPT-SecureRequest.failed = true) </Condition>
</FaultRule>

Schemas

Usage notes

Any server that receives online data is subject to attack, whether malicious or unintentional. Some attacks take advantage of the flexibility of XML by constructing invalid documents that have the potential to compromise back-end systems. Corrupt or extremely complex XML documents can cause servers to allocate more memory than is available, tying up CPU and memory resources, crashing parsers, and generally disabling message processing and creating application-level denial-of-service attacks.

Threat protection error configuration

Important information if you are creating FaultRules for this policy: By default, Edge throws an HTTP 500 Internal Server Error status code and an ExecutionFailed error code if a message doesn't make it past a JSON or XML Threat Protection policy. You can change that error behavior with a new organization-level property. When setting org property features.isPolicyHttpStatusEnabled to true, the following behavior occurs:

  • Request: With a threat protection policy attached to any request flow, invalid messages return a 400 Bad Request status code, along with a corresponding policy error code (rather than just ExecutionFailed).
  • Response: With a threat protection policy attached to any response flow, invalid messages still return a 500 Internal Server Error status code, and one of the corresponding policy error codes is thrown (rather than just ExecutionFailed).

Cloud customers must contact Apigee Support to set the organization property.

Related topics

JSON Threat Protection policy

Regular Expression Protection policy