Criterio RegularExpressionProtection

Policy estensibile

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio RegularExpressionProtection estrae informazioni da un messaggio (ad esempio, percorso URI, parametro di query, intestazione, parametro del modulo, variabile, payload XML o payload JSON) e confronta il valore con espressioni regolari progettate per identificare le minacce. Se il confronto con un'espressione regolare restituisce true, la norma genera un errore.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Esempi

GitHub

L'esempio regex-protection su GitHub mostra come intercettare potenziali attacchi di SQL injection emessi tramite un parametro di query che potrebbe contenere codice dannoso in un tag <script>. L'esempio illustra anche una buona pratica di impostazione di uno stato di errore 400 generico per impedire agli hacker di ottenere informazioni utili dalla risposta.

Protezione dagli attacchi di inclusione JavaScript

<RegularExpressionProtection name="JsonPathRegExProtection">
    <Source>request</Source>
    <JSONPayload escapeSlashCharacter="true">
       <JSONPath>
          <Expression>$</Expression>
          <Pattern><![CDATA[ <\s*script\b[^>]*>[^<]+<\s*\/\s*script\s*> ]]></Pattern>
       </JSONPath>
    </JSONPayload>
 </RegularExpressionProtection>

L'esempio precedente illustra come utilizzare il criterio RegularExpressionProtection per valutare i payload JSON per gli attacchi di inclusione JavaScript. In particolare, i contenuti estratti da <JSONPath>/<Expression> vengono valutati in base all'espressione regolare in <JSONPath>/<Pattern>.

Se l'espressione regolare in <JSONPath>/<Pattern> include caratteri riservati XML (", &, ', < o >), devi racchiuderla in una sezione CDATA (dati di tipo carattere), come mostrato nell'esempio precedente, o codificare in XML i caratteri riservati: ad esempio, sostituendo < con &lt; e > con &gt;.

Inoltre, se l'espressione regolare include barre (/), devi aggiungervi un carattere di escape impostando l'attributo <JSONPayload> escapeSlashCharacter su true.

Corrispondenza senza distinzione tra maiuscole e minuscole

Un caso d'uso comune è quello di eseguire la corrispondenza senza fare distinzione tra maiuscole e minuscole. Ecco un esempio di come puoi ottenere questo risultato in un'espressione regolare utilizzando il costrutto (?i). In questo esempio, ad esempio, DELETE, delete e Delete restituiranno true.

<Pattern>[\s]*(?i)((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b))</Pattern>

Controlli dei parametri del modulo

<RegularExpressionProtection name="REP-Formparam">
  <Source>request</Source>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <FormParam name="firstname">
    <Pattern><![CDATA[[-+=$%&]]]></Pattern>
  </FormParam>
  <FormParam name="lastname">
    <Pattern><![CDATA[[-+=$%&]]]></Pattern>
  </FormParam>
</RegularExpressionProtection>

Questa configurazione dei criteri RegularExpressionProtection valuterà i parametri del modulo per la presenza di caratteri speciali, all'interno del set [-+=$%&]. Questo criterio ha effetto solo quando l'intestazione Content-Type nella richiesta è application/x-www-form-urlencoded. La configurazione dei criteri utilizza una sezione CDATA (dati di tipo carattere) per racchiudere le espressioni regolari, a causa della presenza del carattere &, che è speciale in XML.


Informazioni sul criterio di protezione delle espressioni regolari

Apigee ti consente di configurare espressioni regolari che possono essere valutate rispetto al traffico API in fase di runtime per identificare minacce comuni a livello di contenuti che seguono determinati pattern.

Un'espressione regolare, o regex in breve, è un insieme di stringhe che specificano un pattern in una stringa. Le espressioni regolari consentono di valutare i pattern dei contenuti in modo programmatico. Le espressioni regolari possono essere utilizzate, ad esempio, per valutare un indirizzo email per assicurarsi che sia strutturato correttamente. Per saperne di più, consulta Espressioni regolari nei tutorial di Java.

L'utilizzo più comune di RegularExpressionProtection è la valutazione dei payload JSON e XML per contenuti dannosi.

Nessuna espressione regolare può eliminare tutti gli attacchi basati sui contenuti e devono essere combinati più meccanismi per consentire la difesa in profondità. Questa sezione descrive alcuni pattern consigliati per l'esclusione dei contenuti.

Pattern di esclusione di esempio

Le espressioni regolari devono essere codificate in XML nel file di configurazione XML del criterio. Vedi anche Antipattern: utilizzare quantificatori greedy nel criterio RegularExpressionProtection.

Nome Espressione regolare
SQL injection
[\s]*((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b))
Iniezione di Server Side Include
<!--#(include|exec|echo|config|printenv)\s+.*

Codificato in XML:

&lt;!--#(include|exec|echo|config|printenv)\s+.*
XPath Abbreviated Syntax Injection
(/(@?[\w_?\w:\*]+(\[[^]]+\])*)?)+
Iniezione di sintassi espansa XPath
/?(ancestor(-or-self)?|descendant(-or-self)?|following(-sibling))
JavaScript Injection
<\s*script\b[^>]*>[^<]+<\s*/\s*script\s*>

Codificato in XML:

&lt;\s*script\b[^&gt;]*&gt;[^&lt;]+&lt;\s*/\s*script\s*&gt;

Impostare l'intestazione Content-Type in una richiesta con un payload XML o JSON

Il payload del criterio di protezione delle espressioni regolari può includere i seguenti elementi:

  • Elemento <XMLPayload>: specifica che le informazioni devono essere estratte da un payload XML e valutate in base all'espressione regolare fornita.

    Se utilizzi <XMLPayload> nel criterio, l'intestazione Content-Type della richiesta deve essere un tipo di contenuto XML, ad esempio application/xml o text/xml.

  • Elemento <JSONPayload>: specifica che le informazioni devono essere estratte da un payload JSON e valutate in base all'espressione regolare fornita.

    Se utilizzi <JSONPayload> nella policy, l'intestazione Content-Type della richiesta deve essere un tipo di contenuto JSON come application/json.

In genere, si progetta un'API per accettare XML o JSON. Tuttavia, potrebbe verificarsi uno scenario in cui l'API ha accettato entrambi. Potresti quindi definire una policy di protezione delle espressioni regolari che utilizza sia gli elementi <XMLPayload> che <JSONPayload>. Per una richiesta specifica, verrà applicato un solo elemento in base al valore dell'intestazione Content-Type.

Riferimento elemento

Il riferimento all'elemento descrive gli elementi e gli attributi del criterio RegularExpressionProtection.

<RegularExpressionProtection async="false" continueOnError="false" enabled="true" name="Regular-Expression-Protection-1">
   <DisplayName>Regular Expression Protection 1</DisplayName>
   <Source>response</Source>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <URIPath>
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </URIPath>
   <QueryParam name="a-query-param">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </QueryParam>
   <Header name="a-header">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </Header>
   <FormParam name="a-form-param">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </FormParam>
   <Variable name="request.content">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </Variable>
   <XMLPayload>
     <Namespaces>
       <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     </Namespaces>
     <XPath>
       <Expression>/apigee:Greeting/apigee:User</Expression>
       <Type>string</Type>
       <Pattern>REGEX PATTERN</Pattern>
       <Pattern>REGEX PATTERN</Pattern>
     </XPath>
   </XMLPayload>
   <JSONPayload>
     <JSONPath>
       <Expression>$.store.book[*].author</Expression>
       <Pattern>REGEX PATTERN</Pattern>
       <Pattern>REGEX PATTERN</Pattern>
     </JSONPath>
    </JSONPayload>
</RegularExpressionProtection>

<RegularExpressionProtection> attributi

<RegularExpressionProtection async="false" continueOnError="false" enabled="true" name="Regular-Expression-Protection-1">

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

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. See also:

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

This attribute is deprecated.

false Deprecated

<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 value of the policy's name attribute is used.

Presence Optional
Type String

Elemento <Source>

Indica il messaggio da cui devono essere estratte le informazioni.

Se l'elemento <Source> viene omesso, il valore predefinito è message. Ad esempio: <Source>message</Source>. Se impostato su message, il criterio utilizza il messaggio di richiesta come origine quando è collegato a un flusso di richieste. Allo stesso modo, la policy utilizza il messaggio di risposta quando è collegata a un flusso di risposta.

Se il messaggio di origine non può essere risolto o se viene risolto in un tipo non di messaggio, il criterio restituisce un errore.

<Source>response</Source>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: Stringa

Elemento <IgnoreUnresolvedVariables>

Determina se il criterio restituisce un errore quando rileva una variabile non risolvibile.

Se è impostato su false (valore predefinito), il criterio restituisce un errore quando viene rilevata una variabile non risolvibile. Se impostato su true, la variabile non risolta viene trattata come stringa vuota (Null).

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
Valore predefinito: falso
Presenza: Facoltativo
Tipo: Booleano

Elemento <URIPath>

Specifica che le informazioni devono essere estratte dal percorso URI della richiesta e valutate in base alle espressioni regolari fornite. Devi fornire almeno un elemento <Pattern> che specifichi un pattern di espressione regolare da abbinare.

<URIPath>
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</URIPath>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: N/D

Elemento <QueryParam>

Specifica che le informazioni devono essere estratte dal parametro di query della richiesta e valutate in base alle espressioni regolari fornite. Devi fornire almeno un elemento <Pattern> che specifichi un pattern di espressione regolare da abbinare.

<QueryParam name="a-query-param">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</QueryParam>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: N/D

Attributi

Attributo Descrizione Predefinito Presenza
nome Nome del parametro di query della richiesta da cui devono essere estratte le informazioni per la valutazione rispetto alle espressioni regolari fornite. N/D Obbligatorio

Elemento <Header>

Specifica che le informazioni devono essere estratte dalle intestazioni di richiesta e risposta e valutate in base alle espressioni regolari fornite. Devi fornire almeno un elemento <Pattern> che specifichi un pattern di espressione regolare da abbinare.

<Header name="a-header">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</Header>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: N/D

Attributi

Attributo Descrizione Predefinito Presenza
nome

Nome dell'intestazione della richiesta e della risposta da cui devono essere estratte le informazioni per la valutazione rispetto alle espressioni regolari fornite.

N/D Obbligatorio

Elemento <FormParam>

Specifica che le informazioni devono essere estratte dal parametro del modulo di richiesta e valutate in base alle espressioni regolari fornite. Devi fornire almeno un elemento <Pattern> che specifichi un pattern di espressione regolare da abbinare.

<FormParam name="a-form-param">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</FormParam>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: N/D

Attributi

Attributo Descrizione Predefinito Presenza
nome

Nome del parametro del modulo di richiesta da cui devono essere estratte le informazioni per la valutazione in base alle espressioni regolari fornite.

N/D Obbligatorio

Elemento <Variable>

Specifica che le informazioni devono essere estratte dalla variabile specificata e valutate in base alle espressioni regolari fornite.

<Variable name="request.content">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</Variable>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: N/D

Attributi

Attributo Descrizione Predefinito Presenza
nome

Nome della variabile da cui devono essere estratte le informazioni per la valutazione rispetto alle espressioni regolari fornite.

N/D Obbligatorio

Elemento <XMLPayload>

Specifica che le informazioni devono essere estratte da un payload XML e valutate in base alle espressioni regolari fornite.

<XMLPayload>
   <Namespaces>
      <Namespace prefix="apigee">http://www.apigee.com</Namespace>
   </Namespaces>
   <XPath>
      <Expression>/apigee:Greeting/apigee:User</Expression>
      <Type>string</Type>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </XPath>
</XMLPayload>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: N/D

Elemento <XMLPayload>/<Namespaces>

Specifica gli spazi dei nomi da utilizzare nella valutazione XPath.

<XMLPayload>
   <Namespaces>
      <Namespace prefix="apigee">http://www.apigee.com</Namespace>
   </Namespaces>
   <XPath>
      <Expression>/apigee:Greeting/apigee:User</Expression>
      <Type>string</Type>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </XPath>
</XMLPayload>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: Stringa

Elemento <XMLPayload>/<Namespaces>/<Namespace>

Specifica ogni spazio dei nomi da utilizzare nella valutazione XPath.
<Namespaces>
   <Namespace prefix="apigee">http://www.apigee.com</Namespace>
</Namespaces>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: Stringa

Attributi

Attributo Descrizione Predefinito Presenza
prefisso

Fornisce un prefisso per qualificare un determinato spazio dei nomi.

N/D Obbligatorio

Elemento <XMLPayload>/<XPath>

Specifica l'XPath da valutare.
<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: N/D

<XMLPayload>/<XPath>/<Expression> element

Specifica l'espressione XPath definita per la variabile. Sono supportate solo espressioni XPath 1.0. Ad esempio, <Expression>/company/employee[@age>=$request.header.age]</Expression> estrae i dettagli dei dipendenti la cui età è maggiore o uguale al valore specificato in request.header.age.
<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: Stringa

<XMLPayload>/<XPath>/<Type> elemento

Specifica il tipo di dati di output desiderato.

Di solito utilizzerai "string" o "nodeset". Utilizza "stringa" se hai la certezza che la query XPath restituirà al massimo un valore o se vuoi controllare al massimo un valore. Se la query XPath può restituire più valori, specifica "nodeset" per controllare tutti i valori.

Ad esempio, considera l'espressione XPath //*/@*. Corrisponde a tutti gli attributi di tutti gli elementi. Se specifichi "string" come Type, Apigee forzerà il risultato di questa query in una singola stringa, che sarà il valore di uno degli attributi di uno degli elementi del documento XML, ma non sono definiti l'attributo e l'elemento. Apigee eseguirà quindi la corrispondenza del pattern con il valore di un solo attributo. Probabilmente non è quello che vuoi.

Al contrario, se specifichi "nodeset" come Type per l'espressione XPath, Apigee esegue la corrispondenza del pattern con ciascuno dei valori degli attributi di ogni elemento del documento XML.

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>
Valore predefinito: string
Presenza: Facoltativo
Tipo: Stringa
Valori validi:

Una di queste parole chiave: string, boolean, int, long, float, double e nodeset.

<XMLPayload>/<XPath>/<Pattern> element

Definisce il pattern dell'espressione regolare. Se un'espressione regolare nell'elemento<Pattern> include caratteri riservati XML (", &, ', < o .), devi codificarla in XML prima di includerla.

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>
Valore predefinito: N/D
Presenza: Obbligatorio
Tipo: Stringa

Elemento <JSONPayload>

Specifica che le informazioni devono essere estratte da un payload JSON e valutate in base alle espressioni regolari fornite.

<JSONPayload>
   <JSONPath>
      <Expression>$.store.book[*].author</Expression>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </JSONPath>
</JSONPayload>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: N/D

Attributi

Attributo Descrizione Predefinito Presenza
escapeSlashCharacter

Imposta questo campo su true per eseguire l'escape di qualsiasi carattere barra (/) nelle espressioni regolari in <JSONPath>/<Pattern>.

true Facoltativo

Elemento <JSONPayload>/<JSONPath>/<Expression>

Specifica l'espressione JSONPath definita per la variabile.

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>
Valore predefinito: N/D
Presenza: Facoltativo
Tipo: Stringa

elemento <JSONPayload>/<JSONPath>/<Pattern>

Definisce il pattern dell'espressione regolare. Se un'espressione regolare nell'elemento <Pattern> include caratteri riservati XML (", &, ', < o .), devi codificarla in XML prima di includerla.

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>
Valore predefinito: N/D
Presenza: Obbligatorio
Tipo: Stringa

Messaggi di errore

This section describes the error codes and messages returned and fault variables set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. If you want to capture an error and raise your own custom error, set the continueOnError="true" attribute on the policy root element. 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.

Error Code Message
ExecutionFailed Failed to execute the RegularExpressionProtection StepDefinition {0}. Reason: {1}
InstantiationFailed Failed to instantiate the RegularExpressionProtection StepDefinition {0}
NonMessageVariable Variable {0} does not resolve to a Message
SourceMessageNotAvailable {0} message is not available for RegularExpressionProtection StepDefinition {1}
ThreatDetected Regular Expression Threat Detected in {0}: regex: {1} input: {2}
VariableResolutionFailed Failed to resolve variable {0}

Deployment errors

Error Code Message Fix
CannotBeConvertedToNodeset RegularExpressionProtection {0}: Result of xpath {1} cannot be converted to nodeset. Context {2}
DuplicatePrefix RegularExpressionProtection {0}: Duplicate prefix {1}
EmptyJSONPathExpression RegularExpressionProtection {0}: Empty JSONPath expression
EmptyXPathExpression RegularExpressionProtection {0}: Empty XPath expression
InvalidRegularExpression RegularExpressionProtection {0}: Invalid Regular Expression {1}, Context {2}
JSONPathCompilationFailed RegularExpressionProtection {0}: Failed to compile jsonpath {1}. Context {2}
NONEmptyPrefixMappedToEmptyURI RegularExpressionProtection {0}: Non-empty prefix {1} cannot be mapped to empty uri
NoPatternsToEnforce RegularExpressionProtection {0}: No patterns to enforce in {1}
NothingToEnforce RegularExpressionProtection {0}: at least one of URIPath, QueryParam, Header, FormParam, XMLPayload, JSONPayload is mandatory
XPathCompilationFailed RegularExpressionProtection {0}: Failed to compile xpath {1}. Context {2}

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 table above. fault.name Matches "ThreatDetected"
regularexpressionprotection.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. regularexpressionprotection.Regular-Expressions-Protection-1.failed = true

Schemi

Argomenti correlati

Policy di protezione dalle minacce JSON

Criterio di protezione dalle minacce XML