Règle JSONThreatProtection

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Quoi

Réduit le risque d'attaques au niveau du contenu en vous permettant de spécifier des limites sur différentes structures JSON, telles que des tableaux et des chaînes.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Remarque : Cette règle ne s'exécute que si le champ Content-Type de l'en-tête de la requête ou de la réponse est défini sur application/json.

Vidéo : Visionnez une courte vidéo pour savoir comment la règle JSONThreatProtection vous permet de sécuriser les API contre les attaques au niveau du contenu.

Vidéo : Visionnez cette courte vidéo sur la plate-forme de gestion d'API sur plusieurs clouds d'Apigee.

Documentation de référence des éléments

La documentation de référence des éléments décrit les éléments et les attributs de la règle de protection contre les menaces JSON.

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

Attributs <JSONThreatProtection>

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

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Attribut	Description	Par défaut	Presence
`name`	Nom interne de la règle. La valeur de l'attribut `name` peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément `<DisplayName>` pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.	N/A	Obligatoire
`continueOnError`	Définissez sur `false` pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur `true` pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également : Les règles d'erreur sont déclenchées UNIQUEMENT en état d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel	false	Facultatif
`enabled`	Définissez sur `true` pour appliquer la règle. Définissez sur `false` pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.	true	Facultatif
`async`	Cet attribut est obsolète.	false	Obsolète

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Par défaut

Par défaut	N/A Si vous omettez cet élément, la valeur de l'attribut `name` de la règle est utilisée.
Presence	Facultatif
Type	Chaîne

N/A

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.

Presence Facultatif

Type Chaîne

Élément <ArrayElementCount>

Indique le nombre maximal d'éléments autorisés dans un tableau.

<ArrayElementCount>20</ArrayElementCount>

Valeur par défaut :	Si vous ne spécifiez pas cet élément, ou si vous spécifiez un entier négatif, le système n'applique pas de limite.
Présence :	Facultatif
Type :	Entier

Élément <ContainerDepth>

Spécifie la profondeur maximale autorisée du conteneur (les conteneurs étant des objets ou des tableaux). Par exemple, un tableau contenant un objet contenant lui-même un objet donnerait une profondeur de conteneur de 3.

<ContainerDepth>10</ContainerDepth>

Valeur par défaut :	Si vous ne spécifiez pas cet élément ou si vous spécifiez un entier négatif, le système n'applique aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <ObjectEntryCount>

Spécifie le nombre maximal d'entrées autorisées dans un objet.

<ObjectEntryCount>15</ObjectEntryCount>

Valeur par défaut :	Si vous ne spécifiez pas cet élément ou si vous spécifiez un entier négatif, le système n'applique aucune limite.
Présence :	Facultatif
Type :	Entier

Élément <ObjectEntryNameLength>

Spécifie la longueur maximale de chaîne autorisée pour un nom de propriété dans un objet.

<ObjectEntryNameLength>50</ObjectEntryNameLength>

Valeur par défaut :	Si vous ne spécifiez pas cet élément, ou si vous spécifiez un entier négatif, le système n'applique pas de limite.
Présence :	Facultatif
Type :	Entier

Élément <Source>

Message à analyser pour rechercher des attaques de charge utile JSON. Ce paramètre est habituellement défini sur request, car vous devez généralement valider les requêtes entrantes provenant des applications clientes. Lorsque ce paramètre est défini sur message, cet élément évalue automatiquement le message de requête lorsqu'il est associé au flux de la requête et le message de réponse lorsqu'il est associé au flux de réponse.

<Source>request</Source>

Valeur par défaut :

requête

Présence :

Facultatif

Type :

Chaîne.

Valeurs valides : requête, réponse ou message.

Élément <StringValueLength>

Spécifie la longueur maximale autorisée pour une valeur de chaîne.

<StringValueLength>500</StringValueLength>

Valeur par défaut :	Si vous ne spécifiez pas cet élément, ou si vous spécifiez un entier négatif, le système n'applique pas de limite.
Présence :	Facultatif
Type :	Entier

Informations de référence sur les erreurs

Remarque : Cette règle ne s'exécute que si le champ Content-Type de la requête ou de l'en-tête de réponse est défini sur 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
`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>

Schémas

Remarques sur l'utilisation

Tout comme les services basés sur XML, les API compatibles avec la notation d'objet JavaScript (JSON) sont vulnérables aux attaques au niveau du contenu. Les attaques JSON simples tentent d'utiliser des structures qui surchargent les analyseurs JSON pour faire planter un service et provoquer des attaques par déni de service au niveau de l'application. Tous les paramètres sont facultatifs et doivent être réglés de façon à optimiser les exigences de votre service contre les failles potentielles.

Articles associés

Règle JSONtoXML

Règle XMLThreatProtection

Règle de protection contre les expressions régulières