JSONThreatProtection 政策

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

查看 Apigee Edge 說明文件。

結果

您可以針對各種 JSON 結構 (例如陣列和字串) 指定限制，盡量降低內容層級攻擊的風險。

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

注意：以下影片顯示 Apigee UI 中的傳統 Proxy 編輯器。Apigee 推出新版 Proxy 編輯器，設計與影片中顯示的傳統版不同。

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

影片：觀看短片，進一步瞭解 JSONThreatProtection 政策如何協助您防範內容層級的 API 攻擊。

影片：觀看這部短片，瞭解 Apigee 跨雲端 API 平台。

元素參考資料

元素參考資料說明 JSONThreatProtection 政策的元素和屬性。

<JSONThreatProtection async="false" continueOnError="false" enabled="true" name="JSON-Threat-Protection-1">
   <DisplayName>JSONThreatProtection 1</DisplayName>
   <ArrayElementCount>20</ArrayElementCount>
   <ContainerDepth>10</ContainerDepth>
   <ObjectEntryCount>15</ObjectEntryCount>
   <ObjectEntryNameLength>50</ObjectEntryNameLength>
   <Source>request</Source>
   <StringValueLength>500</StringValueLength>
</JSONThreatProtection>

<JSONThreatProtection> 屬性

<JSONThreatProtection async="false" continueOnError="false" enabled="true" name="JSON-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 屬性值。
存在必要性	選用
類型	字串

<ArrayElementCount> 元素

指定陣列中允許的元素數量上限。

<ArrayElementCount>20</ArrayElementCount>

預設值：	如未指定這個元素，或指定負整數，系統就不會強制執行限制。
外觀狀態：	選用
類型：	整數

<ContainerDepth> 元素

指定允許的最高容器深度，容器可以是物件或陣列。 舉例來說，如果陣列包含物件，而該物件又包含物件，則會產生 3 的包含深度。

<ContainerDepth>10</ContainerDepth>

預設值：	如未指定這個元素，或指定負整數，系統就不會強制執行任何限制。
外觀狀態：	選用
類型：	整數

<ObjectEntryCount> 元素

指定物件中允許的項目數量上限。

<ObjectEntryCount>15</ObjectEntryCount>

預設值：	如未指定這個元素，或指定負整數，系統就不會強制執行任何限制。
外觀狀態：	選用
類型：	整數

<ObjectEntryNameLength> 元素

指定物件中屬性名稱允許的字串長度上限。

<ObjectEntryNameLength>50</ObjectEntryNameLength>

預設值：	如未指定這個元素，或指定負整數，系統就不會強制執行限制。
外觀狀態：	選用
類型：	整數

<Source> 元素

要篩選 JSON 酬載攻擊的訊息。這項設定最常設為 request，因為您通常需要驗證來自用戶端應用程式的傳入要求。如果設為 message，這個元素會在附加至要求流程時自動評估要求訊息，並在附加至回應流程時評估回應訊息。

<Source>request</Source>

預設值：	要求
外觀狀態：	選用
類型：	字串。 有效值：要求、回應或訊息。

<StringValueLength> 元素

指定字串值的長度上限。

<StringValueLength>500</StringValueLength>

預設值：	如未指定這個元素，或指定負整數，系統就不會強制執行限制。
外觀狀態：	選用
類型：	整數

錯誤參考資料

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

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.jsonthreatprotection.ExecutionFailed	500	The JSONThreatProtection 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: object entry name length, object entry count, array element count, container depth, string string value length. This error also occurs when the payload contains an invalid JSON object.
steps.jsonthreatprotection.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.jsonthreatprotection.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 this policy triggers an error. 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"
jsonattack.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	jsonattack.JTP-SecureRequest.failed = true

Example error response

{
  "fault": {
    "faultstring": "JSONThreatProtection[JPT-SecureRequest]: Execution failed. reason: JSONThreatProtection[JTP-SecureRequest]: Exceeded object entry name length at line 2",
    "detail": {
      "errorcode": "steps.jsonthreatprotection.ExecutionFailed"
    }
  }
}

Example fault rule

<FaultRule name="JSONThreatProtection Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ExecutionFailed") </Condition>
    </Step>
    <Condition>(jsonattack.JPT-SecureRequest.failed = true) </Condition>
</FaultRule>

結構定義

範例：如要查看最新結構定義，請參閱 GitHub 存放區範例。

使用須知

與 XML 服務一樣，支援 JavaScript 物件表示法 (JSON) 的 API 也容易遭到內容層級攻擊。簡單的 JSON 攻擊會嘗試使用結構，讓 JSON 剖析器不堪負荷，導致服務當機，並引發應用程式層級的阻斷服務攻擊。所有設定都是選用項目，應根據服務需求調整，以防潛在的安全性漏洞。

相關主題

JSONtoXML 政策

XMLThreatProtection 政策

RegularExpressionProtection 政策