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> 元素值會驗證元素名稱 (booktitleauthoryear) 不超過 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> 元素值會驗證 booktitleauthoryear 元素是否具備超過 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> 元素值會驗證 e1e2 元素分別未包含超過 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 XMLErik 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,讓系統等於無限制。
所在地: 選用
類型:

整數

錯誤參考資料

本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

執行政策時,可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因 修正
steps.xmlthreatprotection.ExecutionFailed 500 XMLThreatProtection 政策可能會擲回多種不同類型的 ExecutionFailed 錯誤。 這類錯誤大多發生在政策中設定的特定門檻。這類錯誤包括:元素名稱長度子項數量節點深度屬性計數屬性名稱長度等。如要查看完整清單,請參閱「XMLThreatProtection 政策執行階段錯誤疑難排解」主題。
steps.xmlthreatprotection.InvalidXMLPayload 500 如果 XMLThreatProtection 政策的 <Source> 元素指定的輸入訊息酬載不是有效的 XML 文件,就會發生這個錯誤。
steps.xmlthreatprotection.SourceUnavailable 500 如果 <Source> 元素中指定的 message 變數是下列任一,就會發生這個錯誤:
  • 超出範圍 (不適用於執行政策的特定流程)
  • 不是有效的值 requestresponsemessage
steps.xmlthreatprotection.NonMessageVariable 500 如果 <Source> 元素設為不屬於 message 類型的變數,就會發生這個錯誤。

附註:

  • 錯誤名稱「ExecutionFailed」是預設的錯誤名稱,無論偵測到的錯誤類型為何,系統都會傳回這個名稱。不過,您可以設定機構層級屬性,以變更這項預設值。設定這個屬性後,錯誤名稱將反映實際錯誤。例如「TextExceeded」或「AttrValueExceeded」。詳情請參閱「使用注意事項」一節。
  • 預設狀態為 500 HTTP。不過,您可將機構層級屬性,將要求流程錯誤的 HTTP 狀態變更為 400。詳情請參閱「使用注意事項」一節。

部署錯誤

無。

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

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

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

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

相關主題

JSON 威脅防護政策

規則運算式保護政策