XMLThreatProtection 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

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

• 评估要排除的特定关键字或模式的消息内容
• 在解析消息前检测已损坏或格式错误的消息

注意：仅当请求或响应标头的 Content-Type 设置为 application/xml. 时，此政策才会执行

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

观看有关威胁防范的短视频

视频：观看面向开发者的四分钟视频 (4MV4D) 系列中关于威胁防范政策的短视频。

元素参考

元素参考描述了 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，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障	false	可选
enabled	设置为 true 可强制执行政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	true	可选
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 的默认值，系统会将其视为无限制。
状态：	可选
类型：	整数

错误参考信息

注意：仅当将请求或响应标头的 Content-Type 设置为 application/xml. 时，此政策才会执行

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码	HTTP 状态	原因	修复
steps.xmlthreatprotection.ExecutionFailed	500	XMLThreatProtection 政策可能会抛出许多不同类型的 ExecutionFailed 错误。其中大多数错误会在超出政策中设置的特定阈值时发生。这些类型的错误包括：元素名称长度、子级计数、节点深度、属性计数、属性名称长度，等等。您可以在 XMLThreatProtection 政策运行时错误问题排查主题中查看完整列表。
steps.xmlthreatprotection.InvalidXMLPayload	500	如果 XMLThreatProtection 政策的 <Source> 元素指定的输入消息载荷不是有效的 XML 文档，就会出现此错误。
steps.xmlthreatprotection.SourceUnavailable	500	如果在 <Source> 元素中指定的消息变量为以下任意一项，就会出现此错误： 超出范围（在执行政策的特定流中不可用） 不是 request、response 或 message 有效值之一
steps.xmlthreatprotection.NonMessageVariable	500	如果将 <Source> 元素设置为非消息类型的变量，则会发生此错误。

部署错误

无。

故障变量

发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量	地点	示例
fault.name="fault_name"	fault_name 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	fault.name Matches "SourceUnavailable"
xmlattack.policy_name.failed	policy_name 是抛出故障的政策的用户指定名称。	xmlattack.XPT-SecureRequest.failed = true

错误响应示例

注意：处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

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

架构

示例：查看我们的 GitHub 代码库示例，了解最新架构。

使用说明

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

威胁防范错误配置

您要为此政策创建故障规则时的重要信息：默认情况下，如果消息未通过 JSON 或 XML 威胁防范限制，Apigee 会抛出 HTTP 500 内部服务器错误状态代码和 ExecutionFailed 错误代码。您可以使用新的组织级属性更改错误行为。将组织属性 features.isPolicyHttpStatusEnabled 设置为 true 时，将发生以下行为：

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

Cloud 客户必须联系 Apigee 支持来设置组织属性。

警告：在执行 PUT 以更新组织属性时，务必在调用中包含所有现有属性，以防擦除这些属性。

curl -u email:password -X POST -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 威胁防范政策

正则表达式保护政策