XMLThreatProtection 政策

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

查看 Apigee Edge 說明文件。

結果

解決 API 上的 XML 安全漏洞並盡可能降低攻擊的威脅。您也可以選擇根據設定的限制偵測 XML 酬載攻擊。使用下列方法防範 XML 威脅：

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

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

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

觀看威脅防護簡介短片

影片：觀看「開發人員的 4 分鐘影片」系列中的短片，瞭解威脅防護政策。

元素參考資料

元素參考資料說明 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 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
continueOnError	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。 將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
enabled	設為 true 即可強制執行政策。 設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
async	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

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

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

錯誤參考資料

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

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

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

結構定義

範例：如要查看最新結構定義，請參閱 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 威脅防護政策

規則運算式保護政策