—Rate this article—
 

XML Threat Protection policy

 XML Threat Protection policy

About | Element reference | Error codes | Schemas | Usage notes | Related topics

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

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

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"> 
Attribute Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

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

N/A Required

<DisplayName> element

A natural-language name that labels the policy in the management UI proxy editor. If omitted, the policy name attribute is used.

<DisplayName>Custom label used in UI</DisplayName>
Default: Policy name attribute value.
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 codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The XMLThreatProtection Policy type defines the following error codes:

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

Schemas

See our GitHub repository samples for the most recent 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.

Related topics

JSON Threat Protection policy

Regular Expression Protection policy

 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)