您正在查看 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 |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<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>/<命名空間 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>
預設: | 申請。 |
所在地: | 選用 |
類型: |
字串。 請選取「 |
<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>/<命名空間 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 政策執行階段錯誤疑難排解」主題。 | build |
steps.xmlthreatprotection.InvalidXMLPayload |
500 |
如果 XMLThreatProtection 政策的 <Source> 元素指定的輸入訊息酬載不是有效的 XML 文件,就會發生這個錯誤。 |
build |
steps.xmlthreatprotection.SourceUnavailable |
500 |
如果 <Source> 元素中指定的 message 變數是下列任一,就會發生這個錯誤:
|
build |
steps.xmlthreatprotection.NonMessageVariable |
500 |
如果 <Source> 元素設為不屬於 message 類型的變數,就會發生這個錯誤。 |
build |
附註:
- 錯誤名稱「ExecutionFailed」是預設的錯誤名稱,無論偵測到的錯誤類型為何,系統都會傳回這個名稱。不過,您可以設定機構層級屬性,以變更這項預設值。設定這個屬性後,錯誤名稱將反映實際錯誤。例如「TextExceeded」或「AttrValueExceeded」。詳情請參閱「使用注意事項」一節。
- 預設狀態為 500 HTTP。不過,您可將機構層級屬性,將要求流程錯誤的 HTTP 狀態變更為 400。詳情請參閱「使用注意事項」一節。
部署錯誤
無。
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。
錯誤回應範例
{ "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 支援團隊聯絡才能設定機構資源。