本頁面由 Cloud Translation API 翻譯而成。

XMLThreatProtection 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。資訊

結果

解決 API 上的 XML 安全漏洞並盡可能減少攻擊。選擇性偵測 XML 酬載依據設定的限制來發動攻擊使用下列功能來防範 XML 威脅方法：

注意：這項政策只會在 Content-Type 的要求或回應標頭設為 application/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>` 元素，為政策加上標籤：管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。	不適用	必填
`continueOnError`	如果設為「`false`」，系統會在政策失敗時傳回錯誤。這是可預期的情況大多數政策的行為如果設為 `true`，即使政策已發生，流程執行作業仍會繼續執行失敗。	false	選用
`enabled`	如要強制執行政策，請設為 `true`。設為 `false` 即可停用政策。這項政策不會仍會強制執行政策。	true	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName>元素

除 name 屬性外，一併使用管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>

預設

預設	不適用如果省略這個元素，政策的 `name` 屬性值會是
存在必要性	選用
類型	字串

不適用

如果省略這個元素，政策的 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-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> 沒有命名空間定義，以及 <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.

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 Edge 所設定的錯誤變數。請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則，處理錯誤詳情請參閱這篇文章瞭解政策錯誤和處理方式發生錯誤

執行階段錯誤

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

錯誤程式碼	HTTP 狀態	原因
`steps.xmlthreatprotection.ExecutionFailed`	500	XMLThreatProtection 政策可能會擲回許多不同類型的 Execution 失敗錯誤。這類錯誤大多會在超過政策中設定的特定門檻時發生。這些錯誤類型包括：元素名稱長度子項數量、節點深度屬性計數、屬性名稱長度以及其他許多工具如要查看完整清單，請參閱「排解 XMLThreatProtection 政策執行階段錯誤疑難排解」主題。
`steps.xmlthreatprotection.InvalidXMLPayload`	500	如果 XMLThreatProtection 政策的 `<Source>` 元素指定的輸入訊息酬載不是有效的 XML 文件，就會發生這個錯誤。
`steps.xmlthreatprotection.SourceUnavailable`	500	如果系統傳回這個錯誤，表示 message `<Source>` 元素中指定的變數為以下任一種形式：範圍外 (不適用於執行政策的特定流程) 不是有效的值 `request`、`response`、或 `message`
`steps.xmlthreatprotection.NonMessageVariable`	500	如果 `<Source>` 元素設為變數，非類型訊息。

注意：

錯誤名稱「 ExecutionFailed」是預設錯誤名稱。不論偵測到的錯誤類型；但只要設定一個機構層級資源設定這個屬性後，錯誤名稱將反映實際的錯誤。例如「TextExceeded」或「AttrValueExceeded」請參閱「使用注意事項」詳細資料。
預設值為 500 HTTP 狀態。但可以將 HTTP 狀態來要求流程錯誤。請參閱「使用注意事項」詳細資料。

部署錯誤

無。

錯誤變數

系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知政策錯誤。

變數	地點	範例
`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>

結構定義

使用須知

所有收到線上資料的伺服器都會遭受攻擊 (無論是惡意或非蓄意)。有些攻擊會建構含有基本特性的無效文件，藉此利用 XML 的靈活性後端系統可能遭到破壞毀損或極為複雜的 XML 文件會導致伺服器分配比可用的記憶體更多，導致佔用大量 CPU 和記憶體資源會造成剖析器異常終止，並通常會停用訊息處理功能及建立應用程式層級阻斷服務攻擊

威脅防護錯誤設定

如果您為這項政策建立 FaultRules，重要資訊如下： 預設，Edge 會擲回 HTTP 500 內部伺服器錯誤狀態碼與 ExecutionFailed 錯誤程式碼。您可以而是用新的機構層級資源引發錯誤行為設定機構時將 features.isPolicyHttpStatusEnabled 屬性設為 true，則在以下行為發生：

要求：附加威脅防護政策到任何要求流程時，無效的訊息會傳回 400 Bad Request 狀態碼，以及相應的政策錯誤 (不只是執行失敗)。
回應：在任何回應流程中附加威脅防護政策，無效的訊息系統仍然會傳回 500 內部伺服器錯誤狀態碼，且系統會擲回相對應的政策錯誤代碼 (而非只是執行失敗)。

雲端客戶必須聯絡 Apigee Edge 支援以設定

Private Cloud：私有雲客戶可以透過 API 呼叫來設定屬性，例如追蹤。

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

XMLThreatProtection 政策

結果

元素參照

&lt;XMLThreatProtection&gt;屬性

&lt;DisplayName&gt;元素

&lt;NameLimits&gt;元素

&lt;NameLimits&gt;/&lt;Element&gt;元素

&lt;NameLimits&gt;/&lt;Attribute&gt;元素

&lt;NameLimits&gt;/&lt;NamespacePrefix&gt;元素

&lt;NameLimits&gt;/&lt;ProcessingInstructionTarget&gt;元素

&lt;Source&gt;元素

&lt;StructuralLimits&gt;元素

&lt;StructuralLimits&gt;/&lt;NodeDepth&gt;元素

&lt;StructuralLimits&gt;/&lt;AttributeCountPerElement&gt;元素

&lt;StructuralLimits&gt;/&lt;NameSpaceCountPerElement&gt;元素

&lt;StructuralLimits&gt;/&lt;ChildCount&gt; 元素

屬性

&lt;ValueLimits&gt;元素

&lt;ValueLimits&gt;/&lt;Text&gt;元素

&lt;ValueLimits&gt;/&lt;Attribute&gt;元素

&lt;ValueLimits&gt;/&lt;NamespaceURI&gt;元素

&lt;ValueLimits&gt;/&lt;Comment&gt;元素

&lt;ValueLimits&gt;/&lt;ProcessingInstructionData&gt;元素

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

使用須知

威脅防護錯誤設定

相關主題

<XMLThreatProtection>屬性

<DisplayName>元素

<NameLimits>元素

<NameLimits>/<Element>元素

<NameLimits>/<Attribute>元素

<NameLimits>/<NamespacePrefix>元素

<NameLimits>/<ProcessingInstructionTarget>元素

<Source>元素

<StructuralLimits>元素

<StructuralLimits>/<NodeDepth>元素

<StructuralLimits>/<AttributeCountPerElement>元素

<StructuralLimits>/<NameSpaceCountPerElement>元素

<StructuralLimits>/<ChildCount> 元素

<ValueLimits>元素

<ValueLimits>/<Text>元素

<ValueLimits>/<Attribute>元素

<ValueLimits>/<NamespaceURI>元素

<ValueLimits>/<Comment>元素

<ValueLimits>/<ProcessingInstructionData>元素