This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The XMLThreatProtection policy lets you address XML vulnerabilities and minimize attacks on your API. You can also use the policy to detect XML payload attacks based on configured limits. Screen against XML threats using the following approaches:

• Detect corrupt or malformed messages before those messages are parsed
• Evaluate message content for specific keywords or patterns to exclude

This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.

Element reference

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

<XMLThreatProtectionasync="false"continueOnError="false"enabled="true"name="XML-Threat-Protection-1"><DisplayName>XMLThreatProtection1</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><ChildCountincludeComment="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:

<DisplayName> element

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

<DisplayName>Policy Display Name</DisplayName>

<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>

<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, andyear) do not exceed10 characters.

<NameLimits><Element>10</Element><Attribute>10</Attribute><NamespacePrefix>10</NamespacePrefix><ProcessingInstructionTarget>10</ProcessingInstructionTarget></NameLimits>

<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 namecategory does not exceed10 characters.

<NameLimits><Element>10</Element><Attribute>10</Attribute><NamespacePrefix>10</NamespacePrefix><ProcessingInstructionTarget>10</ProcessingInstructionTarget></NameLimits>

<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:myelemxmlns:ns1="http://ns1.com"/>

When analyzing the XML above, the<NamespacePrefix> element value in the policy snippet below will validate that the namespace prefixns1 does not exceed10 characters.

<NameLimits><Element>10</Element><Attribute>10</Attribute><NamespacePrefix>10</NamespacePrefix><ProcessingInstructionTarget>10</ProcessingInstructionTarget></NameLimits>

<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-stylesheettype="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 targetxml-stylesheet does not exceed10 characters.

<NameLimits><Element>10</Element><Attribute>10</Attribute><NamespacePrefix>10</NamespacePrefix><ProcessingInstructionTarget>10</ProcessingInstructionTarget></NameLimits>

<Source> element

Message to be screened for XML payload attacks. This is most commonly set torequest, as you will typically need to validate inbound requests from client apps. When set tomessage, 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>

<StructuralLimits> element

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

<StructureLimits><NodeDepth>5</NodeDepth><AttributeCountPerElement>2</AttributeCountPerElement><NamespaceCountPerElement>3</NamespaceCountPerElement><ChildCountincludeComment="true"includeElement="true"includeProcessingInstruction="true"includeText="true">3</ChildCount></StructureLimits>

<StructuralLimits>/<NodeDepth> element

Specifies the maximum node depth allowed in the XML.

<StructureLimits><NodeDepth>5</NodeDepth><AttributeCountPerElement>2</AttributeCountPerElement><NamespaceCountPerElement>3</NamespaceCountPerElement><ChildCountincludeComment="true"includeElement="true"includeProcessingInstruction="true"includeText="true">3</ChildCount></StructureLimits>

<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>

<StructureLimits><NodeDepth>5</NodeDepth><AttributeCountPerElement>2</AttributeCountPerElement><NamespaceCountPerElement>3</NamespaceCountPerElement><ChildCountincludeComment="true"includeElement="true"includeProcessingInstruction="true"includeText="true">3</ChildCount></StructureLimits>

<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 elementse1 ande2 do not have more than2 namespace definitions each. In this case,<e1> has 0 namespace definitions and<e2> has 2 namespace definitions:xmlns="http://apigee.com" andxmlns:yahoo="http://yahoo.com".

<StructureLimits><NodeDepth>5</NodeDepth><AttributeCountPerElement>2</AttributeCountPerElement><NamespaceCountPerElement>3</NamespaceCountPerElement><ChildCountincludeComment="true"includeElement="true"includeProcessingInstruction="true"includeText="true">3</ChildCount></StructureLimits>

<StructuralLimits>/<ChildCount> element

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

<StructureLimits><NodeDepth>5</NodeDepth><AttributeCountPerElement>2</AttributeCountPerElement><NamespaceCountPerElement>3</NamespaceCountPerElement><ChildCountincludeComment="true"includeElement="true"includeProcessingInstruction="true"includeText="true">3</ChildCount></StructureLimits>

Attributes

<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>

<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>

<ValueLimits><Text>15</Text><Attribute>10</Attribute><NamespaceURI>10</NamespaceURI><Comment>10</Comment><ProcessingInstructionData>10</ProcessingInstructionData></ValueLimits>

<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>

<ValueLimits><Text>15</Text><Attribute>10</Attribute><NamespaceURI>10</NamespaceURI><Comment>10</Comment><ProcessingInstructionData>10</ProcessingInstructionData></ValueLimits>

<ValueLimits>/<NamespaceURI> element

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

For example, consider the following XML:

<ns1:myelemxmlns:ns1="http://ns1.com"/>

<ValueLimits><Text>15</Text><Attribute>10</Attribute><NamespaceURI>10</NamespaceURI><Comment>10</Comment><ProcessingInstructionData>10</ProcessingInstructionData></ValueLimits>

<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>

<ValueLimits><Text>15</Text><Attribute>10</Attribute><NamespaceURI>10</NamespaceURI><Comment>10</Comment><ProcessingInstructionData>10</ProcessingInstructionData></ValueLimits>

<ValueLimits>/<ProcessingInstructionData> element

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

For example, consider the following XML:

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

<ValueLimits><Text>15</Text><Attribute>10</Attribute><NamespaceURI>10</NamespaceURI><Comment>10</Comment><ProcessingInstructionData>10</ProcessingInstructionData></ValueLimits>

Error reference

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

Runtime errors

These errors can occur when the policy executes.

Deployment errors

None.

Fault variables

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

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"    }  }}

<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>

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, Apigee 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 propertyfeatures.isPolicyHttpStatusEnabled to true, the following behavior occurs:

• Request: With a threat protection policy attached to any request flow, invalid messages return a400 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 a500 Internal Server Error status code, and one of the corresponding policy error codes is thrown (rather than just ExecutionFailed).

Cloud customers must contactGoogle Cloud Customer Care to set the organization property.

curl-uemail:password-XPOST-H"Content-type:application/xml"http://host:8080/v1/o/myorg -d \"<Organization type="trial" name="MyOrganization">    <Environments/>    <Properties>        <Property name="features.isPolicyHttpStatusEnabled">true</Property>        ...    </Properties></Organization>"

JSON Threat Protection policy

Regular Expression Protection policy