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

下表介绍了所有政策父元素通用的特性：

属性 说明 默认 Presence
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必需
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅：

 false 可选
enabled

设置为 true 可强制执行政策。

设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。

 true 可选
async

此特性已弃用。

 false 已弃用

<DisplayName> 元素

用于在 name 属性之外在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素，则会使用政策的 name 属性的值。
Presence 可选
类型 字符串

<ArrayElementCount> 元素

指定数组中允许的最大元素数量。

<ArrayElementCount>20</ArrayElementCount>
默认： 如果您未指定此元素，或者指定负整数，系统不会强制执行限制。
状态： 可选
类型： 整数

<ContainerDepth> 元素

指定允许的最大包含深度，其中容器为对象或数组。例如，如果一个数组包含的一个对象还包含一个对象，则将导致包含深度为 3。

<ContainerDepth>10</ContainerDepth>
默认： 如果您未指定此元素，或者指定负整数，系统不会强制执行任何限制。
状态： 可选
类型： 整数

<ObjectEntryCount> 元素

指定对象中允许的最大条目数。

<ObjectEntryCount>15</ObjectEntryCount>
默认： 如果您未指定此元素，或者指定负整数，系统不会强制执行任何限制。
状态： 可选
类型： 整数

<ObjectEntryNameLength> 元素

指定对象中的属性名称允许的最大字符串长度。

<ObjectEntryNameLength>50</ObjectEntryNameLength>
默认： 如果您未指定此元素，或者指定负整数，系统不会强制执行限制。
状态： 可选
类型： 整数

<Source> 元素

要针对 JSON 载荷攻击筛查的消息。这最常设置为 request，因为您通常需要验证来自客户端应用的入站请求。设置为 message 时，此元素将在附加到请求流时自动评估请求消息，并在附加到响应流时自动评估响应消息。

<Source>request</Source>
默认： 请求
状态： 可选
类型：

String。

有效值：request、response 或 message。

<StringValueLength> 元素

指定字符串值允许的最大长度。

<StringValueLength>500</StringValueLength>
默认： 如果您未指定此元素，或者指定负整数，系统不会强制执行限制。
状态： 可选
类型： 整数

错误参考信息

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。 在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因 修复
steps.jsonthreatprotection.ExecutionFailed 500 JSONThreatProtection 政策可能会抛出许多不同类型的 ExecutionFailed 错误。其中大多数错误会在超出政策中设置的特定阈值时发生。这些类型的错误包括：对象条目名称长度、对象条目计数、数组元素计数、容器深度、字符串字符串值长度。当载荷包含无效的 JSON 对象时，也会发生此错误。
steps.jsonthreatprotection.SourceUnavailable 500 如果在 <Source> 元素中指定的消息变量为以下任意一项，就会出现此错误：
  • 超出范围（在执行政策的特定流中不可用）
  • 不是 request、response 或 message 有效值之一
steps.jsonthreatprotection.NonMessageVariable 500 如果将 <Source> 元素设置为非消息类型的变量，则会发生此错误。

部署错误

无。

故障变量

此政策触发错误时设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量 位置 示例
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 政策