XMLThreatProtection 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

解决 XML 漏洞并最大限度地减少对您的 API 的攻击。（可选）根据配置的限制检测 XML 载荷攻击。使用以下方法对 XML 威胁进行筛查：

  • 根据 XML 架构 (.xsd) 验证消息
  • 评估要排除的特定关键字或模式的消息内容
  • 在解析消息前检测已损坏或格式错误的消息

元素参考

元素参考描述了 XMLThreatProtection 政策的元素和属性。

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

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

下表介绍了所有政策父元素通用的特性：

属性 说明 默认 状态
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必填
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true，即使在政策失败后，仍可以继续执行流。

 false 可选
enabled

设置为 true 可强制执行政策。

设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。

 是 可选
async

此特性已弃用。

 false 已弃用

<DisplayName> 元素

除了用于 name 属性之外，还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素，则会使用政策的 name 属性的值。
状态 可选
类型 字符串

<NameLimits> 元素

指定政策要检查和强制执行的字符数限制。

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>
默认： 不适用
状态： 可选
类型： 无

<NameLimits>/<Element> 元素

指定 XML 文档中任何元素名称允许的最大字符数。

例如，考虑以下 XML：

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

分析上述 XML 时，以下政策代码段中的 <Element> 元素值将验证元素名称（book、title、author 和 year)）未超过 10 个字符。

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型： 整数

<NameLimits>/<Attribute> 元素

指定 XML 文档中任何属性名称允许的最大字符数。

例如，考虑以下 XML：

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

分析上述 XML 时，以下政策代码段中的 <Attribute> 元素值将验证属性名称 category 未超过 10 个字符。

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型： 整数

<NameLimits>/<NamespacePrefix> 元素

指定 XML 文档中命名空间前缀允许的最大字符数。

例如，考虑以下 XML：

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

分析上述 XML 时，以下政策代码段中的 <NamespacePrefix> 元素值将验证命名空间前缀 ns1 未超过 10 个字符。

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型： 整数

<NameLimits>/<ProcessingInstructionTarget> 元素

指定 XML 文件中任何处理指令目标允许的最大字符数。

例如，考虑以下 XML：

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

分析上述 XML 时，以下政策代码段中的 <ProcessingInstructionTarget> 元素值将验证处理指令目标 xml-stylesheet 未超过 10 个字符。

<NameLimits>
   <Element>10</Element>
   <Attribute>10</Attribute>
   <NamespacePrefix>10</NamespacePrefix>
   <ProcessingInstructionTarget>10</ProcessingInstructionTarget>     
</NameLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型： 整数

<Source> 元素

要针对 XML 载荷攻击筛查的消息。这最常设置为 request，因为您通常需要验证来自客户端应用的入站请求。设置为 message 时，此元素将在附加到请求流时自动评估请求消息，并在附加到响应流时自动评估响应消息。

<Source>request</Source>
默认： 请求
状态： 可选
类型：

String。

从 request、response 或 message 中选择。

<StructuralLimits> 元素

指定政策要检查和强制执行的结构限制。

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>
默认： 不适用
状态： 可选
类型： 无

<StructuralLimits>/<NodeDepth> 元素

指定 XML 中允许的最大节点深度。

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型：

整数

<StructuralLimits>/<AttributeCountPerElement> 元素

指定任何元素允许的最大属性数。

例如，考虑以下 XML：

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>
在分析上述 XML 时，以下政策代码段中的 <AttributeCountPerElement> 元素值将验证元素 book、title、author 和 year 都未超过 2 个属性。请注意，用于定义命名空间的属性不计算在内。 
<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型：

整数

<StructuralLimits>/<NameSpaceCountPerElement> 元素

指定任何元素允许的最大命名空间定义数。

例如，考虑以下 XML：

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

在分析上述 XML 时，以下政策代码段中的 <NamespaceCountPerElement> 元素值将验证 e1 和 e2 元素均未超过 2 个命名空间定义。在本例中，<e1> 具有 0 个命名空间定义，而 <e2> 具有 2 个命名空间定义：xmlns="http://apigee.com" 和 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>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型：

整数

<StructuralLimits>/<ChildCount> 元素

指定任何元素允许的最大子元素数。

<StructureLimits>
   <NodeDepth>5</NodeDepth>
   <AttributeCountPerElement>2</AttributeCountPerElement>
   <NamespaceCountPerElement>3</NamespaceCountPerElement>
   <ChildCount includeComment="true" includeElement="true" includeProcessingInstruction="true" includeText="true">3</ChildCount>
</StructureLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型：

整数

特性

属性 默认 状态
includeComment 是 可选
includeElement 是 可选
includeProcessingInstructions 是 可选
includeText 是 可选

<ValueLimits> 元素

指定政策要检查和强制执行的值的字符数限制。

<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
默认： 不适用
状态： 可选
类型：

无

<ValueLimits>/<Text> 元素

指定 XML 文档中存在的任何文本节点的字符数限制。

例如，考虑以下 XML：

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>
分析上述 XML 时，以下政策代码段中的 <Text> 元素值将验证元素文本值 Learning XML、Erik T. Ray, 和 2003 未超过 15 个字符。 
<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型：

整数

<ValueLimits>/<Attribute> 元素

指定 XML 文档中存在的任何属性值的字符数限制。

例如，考虑以下 XML：

<book category="WEB">
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>
分析上述 XML 时，以下政策代码段中的 <Attribute> 元素值将验证属性值 WEB 未超过 10 个字符。 
<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型：

整数

<ValueLimits>/<NamespaceURI> 元素

指定 XML 文档中存在的任何命名空间 URI 的字符数限制。

例如，考虑以下 XML：

<ns1:myelem xmlns:ns1="http://ns1.com"/>
分析上述 XML 时，以下政策代码段中的 <NamespaceURI> 元素值将验证命名空间 URI 值 http://ns1.com 未超过 10 个字符。 
<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型：

整数

<ValueLimits>/<Comment> 元素

指定 XML 文档中存在的任何备注的字符数限制。

例如，考虑以下 XML：

<book category="WEB">
   <!-- This is a comment -->
   <title>Learning XML</title>
   <author>Erik T. Ray</author>
   <year>2003</year>
</book>
分析上述 XML 时，以下政策代码段中的 <Comment> 元素值将验证备注文本 This is a comment 未超过 10 个字符。 
<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型：

整数

<ValueLimits>/<ProcessingInstructionData> 元素

指定 XML 文档中存在的任何处理指令文本的字符数限制。

例如，考虑以下 XML：

<?xml-stylesheet type="text/xsl" href="style.xsl"?>
分析上述 XML 时，以下政策代码段中的 <ProcessingInstructionData> 元素值将验证处理指令文本 type="text/xsl" href="style.xsl" 未超过 10 个字符。 
<ValueLimits>
   <Text>15</Text>
   <Attribute>10</Attribute>
   <NamespaceURI>10</NamespaceURI>
   <Comment>10</Comment>
   <ProcessingInstructionData>10</ProcessingInstructionData>
</ValueLimits>
默认： 如果您未指定限制，系统会应用 -1 的默认值，系统会将其视为无限制。
状态： 可选
类型：

整数

错误参考信息

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 HTTP status Cause Fix
steps.xmlthreatprotection.ExecutionFailed 500 The XMLThreatProtection policy can throw many different types of ExecutionFailed errors. Most of these errors occur when a specific threshold set in the policy is exceeded. These types of errors include: element name length, child count, node depth, attribute count, attribute name length, and many others. You can see the complete list in the XMLThreatProtection policy runtime error troubleshooting topic.
steps.xmlthreatprotection.InvalidXMLPayload 500 This error occurs if the input message payload specified by the XMLThreatProtection policy's <Source> element is not a valid XML Document.
steps.xmlthreatprotection.SourceUnavailable 500 This error occurs if the message variable specified in the <Source> element is either:
  • Out of scope (not available in the specific flow where the policy is being executed)
  • Is not one of the valid values request, response, or message
steps.xmlthreatprotection.NonMessageVariable 500 This error occurs if the <Source> element is set to a variable which is not of type message.

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

架构

使用说明

任何接收在线数据的服务器都会受到攻击，无论恶意还是无意。某些攻击会构建可能损害后端系统的无效文档，以利用 XML 灵活性。损坏或极其复杂的 XML 文档可能会导致服务器分配多于可用内存的内存，消耗 CPU 和内存资源，导致解析器崩溃，而且通常会停用消息处理和创建应用级拒绝服务攻击。

威胁防范错误配置

如果您要为此政策创建 FaultRules ，请参考以下重要信息： 默认情况下，Edge 会抛出 HTTP 500 Internal Server Error 状态代码，以及一条 ExecutionFailed 错误 代码。您可以使用新的组织级属性更改错误行为。将组织属性 features.isPolicyHttpStatusEnabled 设置为 true 时，将发生以下行为：

  • 请求：将威胁防范政策附加到任何请求流后，无效消息将返回 400 请求有误状态代码，以及对应的政策错误代码（而不仅仅是 ExecutionFailed）。
  • 响应：将威胁防范政策附加到任何响应流后，无效消息仍会返回 500 内部服务器错误状态代码，并会抛出其中一个对应的政策错误代码（而不仅仅是 ExecutionFailed）。

Cloud 客户必须与 Apigee Edge 支持联系，以设置 组织属性。

<ph type="x-smartling-placeholder">

相关主题

JSON 威胁防范政策

正则表达式保护政策