JSONThreatProtection 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

結果

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

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

時，這項政策才會執行

影片：觀看這部短片，進一步瞭解 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，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 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>
預設值： 要求
外觀狀態： 選用
類型：

字串。

有效值：request、response 或 message。

<StringValueLength> 元素

指定字串值的長度上限。

<StringValueLength>500</StringValueLength>
預設值： 如果您未指定此元素，或指定負整數，系統就不會強制執行限制。
外觀狀態： 選用
類型： 整數

錯誤參考資料

時，這項政策才會執行。

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「 政策錯誤的相關資訊」和「 處理錯誤」。

執行階段錯誤

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

錯誤代碼 HTTP 狀態 原因 修正
steps.jsonthreatprotection.ExecutionFailed 500 JSONThreatProtection 政策可能會擲回多種不同類型的 ExecutionFailed 錯誤。大多數這類錯誤都是在政策中設定的特定門檻值超出時發生。這些錯誤類型包括：物件項目名稱長度、物件項目數量、陣列元素數量、容器深度、字串字串值長度。如果酬載包含無效的 JSON 物件，也會發生這個錯誤。
steps.jsonthreatprotection.SourceUnavailable 500 如果 <Source> 元素中指定的 message 變數為下列任一情況，就會發生這個錯誤：
  • 超出範圍 (無法在執行政策的特定流程中使用)
  • 不是有效值 request、response 或 message 中的其中一個
steps.jsonthreatprotection.NonMessageVariable 500 如果 <Source> 元素設為非 message 類型的變數，就會發生這個錯誤。

部署錯誤

無

錯誤變數

系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「關於政策錯誤的相關資訊」。

變數 地點 範例
fault.name="fault_name" fault_name 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。 fault.name Matches "SourceUnavailable"
jsonattack.policy_name.failed policy_name 是擲回錯誤的政策的使用者指定名稱。 jsonattack.JTP-SecureRequest.failed = true

錯誤回應範例

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

錯誤規則範例

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

結構定義

使用須知

與以 XML 為基礎的服務一樣，支援 JavaScript 物件表示法 (JSON) 的 API 也容易遭到內容層級攻擊。簡單的 JSON 攻擊會嘗試使用會讓 JSON 剖析器不堪負荷的結構，藉此讓服務當機，並誘發應用程式層級的拒絕服務攻擊。所有設定皆為選用設定，應調整為針對潛在的安全漏洞，最佳化您的服務需求。

相關主題

JSONtoXML 政策

XMLThreatProtection 政策

RegularExpressionProtection 政策