Send Docs Feedback

JSON Threat Protection policy

What

Minimizes the risk posed by content-level attacks by enabling you to specify limits on various JSON structures, such as arrays and strings.

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Element reference

The element reference describes the elements and attributes of the JSONThreatProtection policy.

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

<JSONThreatProtection> attributes

<JSONThreatProtection async="false" continueOnError="false" enabled="true" name="JSON-Threat-Protection-1"> 

The following attributes are common to all policy parent elements.

Attribute Description Default Presence
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

Note: This attribute does not make the policy execute asynchronously.

When set to true, policy execution is offloaded to a different thread, leaving the main thread free to handle additional requests. When the offline processing is complete, the main thread comes back and finishes handling the message flow. In some cases, setting async to true improves API proxy performance. However, overusing async can hurt performance with too much thread switching.

To use asynchronous behavior in API proxies, see JavaScript callouts.

false Optional

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default:

N/A

If you omit this element, the the value of the policy's name attribute is used.

Presence: Optional
Type: String

 

<ArrayElementCount> element

Specifies the maximum number of elements allowed in an array.

<ArrayElementCount>20</ArrayElementCount>
Default: If you do not specify this element, or if you specify a negative integer, the system does not enforce a limit.
Presence: Optional
Type: Integer

<ContainerDepth> element

Specifies the maximum allowed containment depth, where the containers are objects or arrays. For example, an array containing an object which contains an object would result in a containment depth of 3.

<ContainerDepth>10</ContainerDepth>
Default: If you do not specify this element, or if you specify a negative integer, the system does not enforce any limit.
Presence: Optional
Type: Integer

<ObjectEntryCount> element

Specifies the maximum number of entries allowed in an object.

<ObjectEntryCount>15</ObjectEntryCount>
Default: If you do not specify this element, or if you specify a negative integer, the system does not enforce any limit.
Presence: Optional
Type: Integer

<ObjectEntryNameLength> element

Specifies the maximum string length allowed for a property name within an object.

<ObjectEntryNameLength>50</ObjectEntryNameLength>
Default: If you do not specify this element, or if you specify a negative integer, the system does not enforce a limit.
Presence: Optional
Type: Integer

<Source> element

Message to be screened for JSON payload attacks. This is most commonly set to request, as you will typically need to validate inbound requests from client apps. When set to message, this element will automatically evaluate the request message when attached to the request flow and the response message when attached to the response flow.

<Source>request</Source>
Default: request
Presence: Optional
Type:

String.

Valid values: request, response, or message.

<StringValueLength> element

Specifies the maximum length allowed for a string value.

<StringValueLength>500</StringValueLength>
Default: If you do not specify this element, or if you specify a negative integer, the system does not enforce a limit.
Presence: Optional
Type: Integer

Error codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The JSONThreatProtection Policy types defines the following error codes:

Error Code Message
ExceededContainerDepth JSONThreatProtection[{0}]: Exceeded container depth at line {1}
ExceededObjectEntryCount JSONThreatProtection[{0}]: Exceeded object entry count at line {1}
ExceededArrayElementCount JSONThreatProtection[{0}]: Exceeded array element count at line {1}
ExceededObjectEntryNameLength JSONThreatProtection[{0}]: Exceeded object entry name length at line {1}
ExceededStringValueLength JSONThreatProtection[{0}]: Exceeded string value length at line {1}
SourceUnavailable JSONThreatProtection[{0}]:: Source {1} is not available
NonMessageVariable JSONThreatProtection[{0}]: Variable {1} does not resolve to a Message
ExecutionFailed JSONThreatProtection[{0}]: Execution failed. reason: {1}

Schemas

See our GitHub repository samples for the most recent schemas.

Usage notes

Like XML-based services, APIs that support JavaScript object notation (JSON) are vulnerable to content-level attacks. Simple JSON attacks attempt to use structures that overwhelm JSON parsers to crash a service and induce application-level denial-of-service attacks. All settings are optional and should be tuned to optimize your service requirements against potential vulnerabilities.

Threat protection error configuration

By default, Edge throws an HTTP 500 Internal Server Error status code and an ExecutionFailed error if a message doesn't make it past a JSON or XML Threat Protection policy. You can change that error behavior with a new organization-level property. When setting org property features.isPolicyHttpStatusEnabled to true, the following behavior occurs:

  • Request: With a threat protection policy attached to any request flow, invalid messages return a 400 status code, along with a corresponding policy error message.
  • Response: With a threat protection policy attached to any response flow, invalid messages still return a 500 status code, and one of the corresponding policy error messages is thrown (rather than just ExecutionFailed).

Cloud customers must contact Apigee Support to set the organization property.

Private Cloud customers can set the property with an API call like the following.

When doing a PUT to update organization properties, be sure to include all existing properties in the call to prevent wiping them out.

curl -u email:password -X POST -H "Content-type:application/xml" http://host:8080/v1/o/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Environments/>
    <Properties>
        <Property name="features.isPolicyHttpStatusEnabled">true</Property>
        ...
    </Properties>
</Organization>"

Related topics

JSON to XML policy

XML Threat Protection policy

Regular Expression Protection policy

 

Help or comments?