JSONThreatProtection 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

您可以針對不同的 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 Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

<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>
預設: 如果您未指定這個元素,或指定了負整數,系統就不會強制執行限制。
所在地: 選用
類型: 整數

錯誤參考資料

本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

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

部署錯誤

無。

錯誤變數

系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「政策錯誤的注意事項」。

Variables 地點 範例
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 政策