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

XMLThreatProtection 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

解決 XML 安全漏洞，盡可能降低 API 遭受攻擊的風險。您可以選擇根據設定的限制偵測 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` 屬性值。
存在必要性	選用
類型	字串

不適用

如果省略這個元素，系統會使用政策的 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 屬性不超過 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 命名空間定義不超過 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	是	選用
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.

時，這項政策才會執行。

本節說明這項政策觸發錯誤時，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>

結構定義

使用須知

任何接收線上資料的伺服器都可能遭到攻擊，無論攻擊者是否蓄意為之。部分攻擊會利用 XML 的彈性，建構可能會危害後端系統的無效文件。損毀或極為複雜的 XML 文件可能會導致伺服器分配的記憶體超過可用容量，並綁定 CPU 和記憶體資源，導致剖析器停止運作，並通常會停用訊息處理作業，並造成應用程式層級的拒絕服務攻擊。

威脅防護錯誤設定

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

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

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

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 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

結果

觀看威脅防護簡短影片

元素參照

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

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

使用須知

威脅防護錯誤設定

相關主題

XMLThreatProtection 政策