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 的默认值，系统会将其视为无限制。
状态： 可选
类型：

整数

错误参考信息

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

运行时错误

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

故障代码 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> 元素设置为非消息类型的变量，则会发生此错误。

注意：

  • 错误名称 ExecutionFailed 是默认错误名称，无论检测到何种错误类型，都将返回此错误；但是，可以通过设置组织级属性来更改此默认值。设置此属性后，错误名称将反映实际错误。例如，“TextExceeded”或“AttrValueExceeded”。如需了解详情，请参阅使用说明。
  • 500 HTTP 状态是默认值；但是，您可以通过设置组织级属性将 HTTP 状态更改为 400（对于请求流故障）。如需了解详情，请参阅使用说明。

部署错误

无。

故障变量

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

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

错误响应示例

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

架构

使用说明

任何接收在线数据的服务器都会受到攻击，无论恶意还是无意。某些攻击会构建可能损害后端系统的无效文档，以利用 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 威胁防范政策

正则表达式保护政策