XMLThreatProtection 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

借助 XMLThreatProtection 政策,您可以解决 XML 漏洞并最大限度地减少对您的 API 的攻击。您还可以使用该政策根据配置的限制检测 XML 载荷攻击。使用以下方法对 XML 威胁进行筛查:

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

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

元素参考

元素参考描述了 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">

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

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

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails. See also:

false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

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

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence Optional
Type String

<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 true 可选
includeElement true 可选
includeProcessingInstructions true 可选
includeText true 可选

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

整数

错误参考信息

本部分介绍当此政策触发错误时返回的故障代码和错误消息,以及由 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

错误响应示例

{
  "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 和内存资源,导致解析器崩溃,而且通常会停用消息处理和创建应用级拒绝服务攻击。

威胁防范错误配置

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

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

Cloud 客户必须联系 Google Cloud Customer Care 才能设置组织属性。

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 威胁防范政策

正则表达式保护政策