XMLThreatProtection 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

優勢

解決 API 上的 XML 安全漏洞並盡量減少攻擊。或者，您也可以根據設定的限制偵測 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> 元素，在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

 不適用 需要
continueOnError

如果設為 false，即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true，即可在政策失敗後繼續執行資料流。

 false 選用
enabled

如要強制執行政策，請設為 true。

設為 false 即可停用這項政策。即使政策仍附加在流程中，系統也不會強制執行政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

除了 name 屬性外，您還可以使用不同的自然語言名稱，在管理 UI Proxy 編輯器中為政策加上標籤。

<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>/<命名空間 Prefix> 元素

指定 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>
預設： 申請。
所在地： 選用
類型：

字串。

請選取「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>/<命名空間 URI> 元素

指定 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，則重要資訊：根據預設，如果訊息未超過 JSON 或 XML 威脅防護政策，Edge 會擲回 HTTP 500 內部伺服器錯誤狀態碼和 ExecutionFailed 錯誤代碼。您可以使用新的機構層級資源變更這項錯誤行為。將機構屬性 features.isPolicyHttpStatusEnabled 設為 true 時，會發生下列行為：

  • 要求：在任何要求流程中附加威脅防護政策後，無效訊息會傳回 400 錯誤要求狀態碼，以及對應的政策錯誤代碼 (而非單純的「ExecutionFailed」)。
  • 回應：如果您已將威脅防護政策附加至任何回應流程，無效訊息仍會傳回 500 Internal Server Error 狀態碼，並且擲回相對應的政策錯誤代碼 (而非單純的「ExecutionFailed」)。

Cloud 客戶必須與 Apigee Edge 支援團隊聯絡才能設定機構資源。

相關主題

JSON 威脅防護政策

規則運算式保護政策