XMLThreatProtection 政策

可擴充的政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

XMLThreatProtection 政策可協助您解決 XML 安全漏洞，並盡可能降低 API 遭受攻擊的威脅。您也可以使用這項政策，根據設定的限制偵測 XML 酬載攻擊。使用下列方法防範 XML 威脅：

• 在剖析郵件前，偵測損毀或格式錯誤的郵件
• 評估訊息內容是否含有要排除的特定關鍵字或模式

注意：只有在要求或回應標頭的 Content-Type 設為 application/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: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	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>

預設值：	要求
外觀狀態：	選用
類型：	字串。 選取 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，這相當於沒有限制。
外觀狀態：	選用
類型：	整數

錯誤參考資料

注意：只有在要求或回應標頭的 Content-Type 設為 application/xml. 時，這項政策才會執行。

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼	HTTP 狀態	原因	修正
steps.xmlthreatprotection.ExecutionFailed	500	XMLThreatProtection 政策可能會擲回多種不同類型的 ExecutionFailed 錯誤。大多數這類錯誤都是在政策中設定的特定門檻值超出時發生。這些錯誤類型包括：元素名稱長度、子項數量、節點深度、屬性數量、屬性名稱長度，以及其他許多類型。如需完整清單，請參閱「XMLThreatProtection 政策執行階段錯誤疑難排解」主題。
steps.xmlthreatprotection.InvalidXMLPayload	500	如果 XMLThreatProtection 政策的 <Source> 元素指定的輸入訊息酬載不是有效的 XML 文件，就會發生這項錯誤。
steps.xmlthreatprotection.SourceUnavailable	500	如果 <Source> 元素中指定的 message 變數為下列任一情況，就會發生這個錯誤： 超出範圍 (無法在執行政策的特定流程中使用) 不是有效值 request、response 或 message 中的其中一個
steps.xmlthreatprotection.NonMessageVariable	500	如果 <Source> 元素設為非 message 類型的變數，就會發生這個錯誤。

部署錯誤

無

錯誤變數

這些變數會在發生執行階段錯誤時設定。詳情請參閱「關於政策錯誤的相關資訊」。

變數	地點	範例
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 和記憶體資源耗盡、剖析器停止運作，以及一般訊息處理作業遭到停用，進而造成應用程式層級的阻斷服務攻擊。

威脅保護措施錯誤設定

為這項政策建立 FaultRule 時的重要資訊：根據預設，如果訊息無法通過 JSON 或 XML 威脅防護政策，Apigee 會擲回 HTTP 500 內部伺服器錯誤狀態碼和 ExecutionFailed 錯誤代碼。您可以透過新的機構層級屬性變更這項錯誤行為。將機構屬性 features.isPolicyHttpStatusEnabled 設為 true 時，會發生下列行為：

• 要求：如果任何要求流程附加了威脅防護政策，無效訊息會傳回 400 Bad Request 狀態碼，以及相應的政策錯誤代碼 (而非僅傳回 ExecutionFailed)。
• 回應：如果任何回應流程附加了威脅防護政策，無效訊息仍會傳回 500 Internal Server Error 狀態碼，並擲回其中一個對應的政策錯誤代碼 (而非僅擲回 ExecutionFailed)。

Cloud 客戶必須與 Google Cloud Customer Care 聯絡，才能設定機構資源屬性。

警告：使用 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 威脅防護政策

規則運算式保護政策