Criterio RegularExpressionProtection

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

Estrae informazioni da un messaggio (ad esempio, percorso URI, parametro di query, intestazione, parametro modulo, variabile, payload XML o payload JSON) e valuta i contenuti a fronte di espressioni regolari predefinite. Se una qualsiasi espressione regolare specificata restituisce true, il messaggio viene considerato una minaccia e il criterio genera un errore.

Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Video

Guarda il seguente video per ulteriori informazioni sulle norme relative alla protezione delle espressioni regolari.

Video Descrizione
Protezione dagli attacchi SQL injection Proteggiti dagli attacchi SQL injection utilizzando il criterio di protezione delle espressioni regolari nell'interfaccia utente di Apigee.

Esempi

GitHub

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

JavaScript include la protezione dagli attacchi

<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 riportato sopra illustra come utilizzare il criterio RegularExpressionProtection per valutare i payload JSON per gli attacchi che includono JavaScript. Nello specifico, 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 a XML (", &, ', < o >), devi includerla in una sezione sso (dati sui caratteri), come mostrato nell'esempio sopra, oppure eseguire la codifica XML dei caratteri riservati, ad esempio sostituendo < con &lt; e > con &gt;.

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

Corrispondenza senza distinzione tra maiuscole e minuscole

È un caso d'uso comune eseguire corrispondenze senza distinzione tra maiuscole e minuscole. Ecco un esempio di come puoi farlo in un'espressione regolare utilizzando il costrutto (?i). In questo esempio, ad esempio, DELETE, delete e Delete restituiscono true.

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

Controlli dei parametri di 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 del criterio RegularExpressionProtection valuterà i parametri del modulo per la presenza di caratteri speciali di chat, all'interno del set [-+=$%&]. Questo criterio avrà effetto soltanto se l'intestazione content-type nella richiesta è application/x-www-form-urlencoded. La configurazione dei criteri utilizza una sezione port (dati sui caratteri) per mandare a capo le espressioni regolari grazie alla presenza del carattere &, che è speciale nel linguaggio XML.


Informazioni sul criterio di protezione delle espressioni regolari

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

Un'espressione regolare, o regex, è un insieme di stringhe che specificano un pattern in una stringa. Le espressioni regolari consentono ai contenuti di essere valutati in modo programmatico per trovare pattern. Le espressioni regolari possono essere utilizzate, ad esempio, per valutare un indirizzo email e assicurarsi che sia strutturato correttamente. Per ulteriori informazioni, consulta la sezione Espressioni regolari nei tutorial Java.

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

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

Esempi di pattern di esclusione

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

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

XML codificato:

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

XML codificato:

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

Imposta 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, come 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> nel criterio, l'intestazione Content-Type della richiesta deve essere un tipo di contenuto JSON come application/json.

Solitamente si progetta un'API in modo che accetti XML o JSON. Tuttavia, potrebbe esserci uno scenario in cui l'API accettava entrambe. Puoi quindi definire un criterio di Protezione delle espressioni regolari che utilizza entrambi gli elementi <XMLPayload> e <JSONPayload>. In base al valore dell'intestazione Content-Type, verrà applicato un solo elemento a una richiesta specifica.

Riferimento elemento

Il riferimento agli elementi 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>

Attributi <RegularExpressionProtection>

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

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo Descrizione Predefinito Presenza
name

Il nome interno della norma. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

N/A Obbligatorio
continueOnError

Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio. Vedi anche:

false Facoltativo
enabled

Imposta il criterio su true per applicare il criterio.

Impostala su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.

true Facoltativo
async

Questo attributo è obsoleto.

false Deprecata

Elemento <DisplayName>

Utilizzalo in aggiunta all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>
Predefinito

N/A

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.

Presenza Facoltativo
Tipo Stringa

Elemento <Source>

Indica il messaggio da cui è necessario estrarre le informazioni.

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

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

<Source>response</Source>
Predefinita: N/A
Presenza: Facoltativo
Tipo: Stringa

Elemento <IgnoraUnresolvedVariables>

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

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

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
Predefinita: false
Presenza: Facoltativo
Tipo: Booleano

Elemento <URIPath>

Specifica che le informazioni devono essere estratte dal percorso dell'URI della richiesta e valutate in base alle espressioni regolari fornite. Devi fornire almeno un elemento <Pattern> che specifichi un modello di espressione regolare di cui trovare una corrispondenza.

<URIPath>
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</URIPath>
Predefinita: N/A
Presenza: Facoltativo
Tipo: N/A

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 modello di espressione regolare di cui trovare una corrispondenza.

<QueryParam name="a-query-param">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</QueryParam>
Predefinita: N/A
Presenza: Facoltativo
Tipo: N/A

Attributi

Attributo Descrizione Predefinito Presenza
comune Nome del parametro di query della richiesta da cui deve essere estratta le informazioni per la valutazione in base alle espressioni regolari fornite. N/A Obbligatorio

Elemento <Header>

Specifica che le informazioni devono essere estratte dalle intestazioni della richiesta e della risposta e valutate in base alle espressioni regolari fornite. Devi fornire almeno un elemento <Pattern> che specifichi un modello di espressione regolare di cui trovare una corrispondenza.

<Header name="a-header">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</Header>
Predefinita: N/A
Presenza: Facoltativo
Tipo: N/A

Attributi

Attributo Descrizione Predefinito Presenza
comune

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

N/A 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 modello di espressione regolare di cui trovare una corrispondenza.

<FormParam name="a-form-param">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</FormParam>
Predefinita: N/A
Presenza: Facoltativo
Tipo: N/A

Attributi

Attributo Descrizione Predefinito Presenza
comune

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

N/A 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>
Predefinita: N/A
Presenza: Facoltativo
Tipo: N/A

Attributi

Attributo Descrizione Predefinito Presenza
comune

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

N/A 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>
Predefinita: N/A
Presenza: Facoltativo
Tipo: N/A

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>
Predefinita: N/A
Presenza: Facoltativo
Tipo: Stringa

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

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

Attributi

Attributo Descrizione Predefinito Presenza
prefisso

Fornisce un prefisso per qualificare un determinato spazio dei nomi.

N/A 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>
Predefinita: N/A
Presenza: Facoltativo
Tipo: N/A

Elemento <XMLPayload>/<XPath>/<Expression>

Specifica l'espressione XPath definita per la variabile. Sono supportate solo le espressioni XPath 1.0. Ad esempio, <Expression>/company/employee[@age>=$request.header.age]</Expression> estrae i dettagli per i dipendenti la cui età è superiore 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>
Predefinita: N/A
Presenza: Facoltativo
Tipo: Stringa

Elemento <XMLPayload>/<XPath>/<Type>

Specifica il tipo di dati di output desiderato.

Di solito si usa "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 su tutti gli elementi. Se specifichi "string" come Type, Apigee costringerà il risultato di questa query a una singola stringa; sarà il valore di uno degli attributi su uno degli elementi nel documento XML, ma quale attributo e quale elemento non sono definiti. Apigee eseguirà quindi la corrispondenza del pattern con il valore di quel singolo attributo. Probabilmente non è quello che volevi.

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

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

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

Elemento <XMLPayload>/<XPath>/<Pattern>

Definisce il modello di espressione regolare. Se un'espressione regolare nell'elemento <Pattern> include caratteri riservati a 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>
Predefinita: N/A
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>
Predefinita: N/A
Presenza: Facoltativo
Tipo: N/A

Attributi

Attributo Descrizione Predefinito Presenza
escapeSlashCharacter

Imposta su true per eseguire l'escape dei caratteri 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>
Predefinita: N/A
Presenza: Facoltativo
Tipo: Stringa

Elemento <JSONPayload>/<JSONPath>/<Pattern>

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

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

Messaggi di errore

Questa sezione descrive i codici e i messaggi restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per la gestione degli errori. Per acquisire un errore e generare un errore personalizzato, imposta l'attributo continueOnError="true" nell'elemento principale del criterio. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore Messaggio
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}

Errori di deployment

Codice di errore Messaggio Correggi
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}

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella precedente. fault.name Matches "ThreatDetected"
regularexpressionprotection.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. regularexpressionprotection.Regular-Expressions-Protection-1.failed = true

Schema

Argomenti correlati

Criteri di JSON Threat Protection

Criterio di protezione dalle minacce XML