Questa pagina si applica a Apigee e Apigee ibrido.
Visualizza la documentazione di
Apigee Edge.
Cosa
Estrae informazioni da un messaggio (ad esempio, URI Path, Query Param, Header, Form Param, Variable, XML Payload o JSON Payload) e valuta i contenuti in base a espressioni regolari predefinite. Se 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 per l'utilizzo, consulta la pagina Tipi di criteri.
Video
Guarda il seguente video per scoprire di più sulle norme relative alla protezione dalle espressioni regolari.
Video | Descrizione |
---|---|
Protezione dagli attacchi SQL injection | Proteggiti dagli attacchi di SQL injection utilizzando il criterio di protezione dalle espressioni regolari nella UI di Apigee. |
Esempi
GitHub
L'esempio di protezione regex su GitHub illustra come intrappolare potenziali attacchi di SQL injection inviati tramite un parametro di query che potrebbe contenere codice dannoso in un tag <script>
.
L'esempio illustra anche una buona pratica per impostare uno stato di errore 400 generico 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 JavaScript che include gli attacchi. 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 in formato XML
(", &, ', < o >), devi includerla in una sezione CDATA (dati di carattere), come mostrato
nell'esempio sopra, oppure codifica in XML i caratteri riservati, ad esempio sostituendo <
con <
e >
con >
.
Inoltre, se l'espressione regolare include barre (/), devi eseguirne il escape impostando l'attributo <JSONPayload>
escapeSlashCharacter
su true
.
Corrispondenza senza distinzione tra maiuscole e minuscole
In genere, le corrispondenze senza distinzione tra maiuscole e minuscole sono molto comuni. Ecco un esempio di come puoi farlo in un'espressione regolare utilizzando il costrutto (?i)
. In questo
esempio, ad esempio, DELETE
, delete
e Delete
avranno
il valore 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 del criterio RegularExpressionProtection valuterà i parametri del modulo
per la presenza di chatacter speciali, all'interno del valore [-+=$%&]
impostato.
Questo criterio avrà effetto solo se l'intestazione content-type nella richiesta
è application/x-www-form-urlencoded
. La configurazione dei criteri utilizza una sezione CDATA (dati di carattere) per eseguire il wrapping delle espressioni regolari, a causa della presenza del carattere &, speciale in XML.
Informazioni sul criterio di protezione dalle espressioni regolari
Apigee ti consente di configurare espressioni regolari che possono essere valutate in base al traffico API in fase di runtime per identificare le minacce comuni a livello di contenuto che seguono determinati pattern.
Un'espressione regolare, o in breve regex, è un insieme di stringhe che specificano un pattern in una stringa. Le espressioni regolari consentono di valutare in modo programmatico i contenuti per rilevare i pattern. È possibile utilizzare espressioni regolari, ad esempio, per valutare un indirizzo email e verificare che sia strutturato correttamente. Per ulteriori informazioni, consulta la sezione sulle espressioni regolari nei tutorial Java.
L'uso più comune di RegularExpressionProtection è la valutazione dei payload JSON e XML per rilevare contenuti dannosi.
Nessuna espressione regolare è in grado di eliminare tutti gli attacchi basati sui contenuti ed è necessario combinare più meccanismi per consentire la 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 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)) |
Iniezione di inclusione lato server |
<!--#(include|exec|echo|config|printenv)\s+.* Codifica XML: <!--#(include|exec|echo|config|printenv)\s+.* |
Inserimento della sintassi abbreviata di XPath |
(/(@?[\w_?\w:\*]+(\[[^]]+\])*)?)+ |
aggiunta della sintassi espansa di XPath |
/?(ancestor(-or-self)?|descendant(-or-self)?|following(-sibling)) |
aggiunta JavaScript |
<\s*script\b[^>]*>[^<]+<\s*/\s*script\s*> Codifica XML: <\s*script\b[^>]*>[^<]+<\s*/\s*script\s*> |
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'intestazioneContent-Type
della richiesta deve essere un tipo di contenuto XML, comeapplication/xml
otext/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'intestazioneContent-Type
della richiesta deve essere un tipo di contenuto JSON, comeapplication/json
.
In genere, progetti un'API in modo che accetti i formati XML o JSON. Tuttavia, in uno scenario in cui l'API potrebbe accettare entrambe le cose. Puoi quindi definire un criterio di protezione dalle espressioni regolari che utilizza entrambi gli elementi <XMLPayload>
e <JSONPayload>
.
Viene applicato un solo elemento a una richiesta specifica in base al valore
dell'intestazione Content-Type
.
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 Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
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 |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <Source>
Indica il messaggio da cui è necessario estrarre 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 della richiesta come origine quando è collegato a un flusso di richiesta. Allo stesso modo, il criterio utilizza il messaggio di risposta quando allegato a un flusso di risposta.
Se il messaggio di origine non può essere risolto o se viene risolto in un tipo diverso da messaggio, il criterio restituisce un errore.
<Source>response</Source>
Predefinita: | N/A |
Presenza: | Facoltativo |
Tipo: | String |
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 impostato 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>
specificando un pattern di espressioni regolari da abbinare.
<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 di richiesta e valutate in base alle espressioni regolari fornite. Devi fornire almeno un
elemento <Pattern>
specificando un pattern di espressioni regolari da abbinare.
<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 | Predefinita | Presenza |
---|---|---|---|
nome | Nome del parametro di query della richiesta da cui è necessario estrarre le informazioni per la valutazione rispetto 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>
specificando un pattern di espressioni regolari da abbinare.
<Header name="a-header"> <Pattern>REGEX PATTERN</Pattern> <Pattern>REGEX PATTERN</Pattern> </Header>
Predefinita: | N/A |
Presenza: | Facoltativo |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinita | Presenza |
---|---|---|---|
nome |
Nome dell'intestazione della richiesta e della risposta da cui è necessario estrarre le informazioni per la valutazione rispetto alle espressioni regolari fornite. |
N/A | Obbligatorio |
Elemento <FormParam>
Specifica che le informazioni devono essere estratte dal parametro del modulo di richiesta ed è necessario valutarle in base alle espressioni regolari fornite. Devi fornire almeno un
elemento <Pattern>
specificando un pattern di espressioni regolari da abbinare.
<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 | Predefinita | Presenza |
---|---|---|---|
nome |
Nome del parametro del modulo di richiesta da cui è necessario estrarre le informazioni per la valutazione rispetto alle espressioni regolari fornite. |
N/A | Obbligatorio |
Elemento <Variabile>
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 | Predefinita | Presenza |
---|---|---|---|
nome |
Nome della variabile da cui devono essere estratte le informazioni per la valutazione rispetto 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 di 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: | String |
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: | String |
Attributi
Attributo | Descrizione | Predefinita | 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>/<Espressione>
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à è 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: | String |
Elemento <XMLPayload>/<XPath>/<Type>
Specifica il tipo di dati di output desiderato.
In genere utilizzerai "string" o "nodeset". Utilizza "string" se hai la certezza che la query xpath genererà al massimo un valore o se vuoi controllare al massimo un valore. Se la query xpath può restituire più valori, specifica "nodeset" per selezionare tutti i valori.
Considera ad esempio l'espressione XPath //*/@*
. Corrisponde a tutti gli attributi su tutti gli elementi. Se specifichi "stringa" come Type
, Apigee
costringerà il risultato di questa query in una singola stringa; sarà il valore di uno degli
attributi su uno degli elementi nel documento XML, ma quale attributo e quale elemento
non è definito. Apigee eseguirà quindi la corrispondenza dei pattern in base al valore di quel singolo
attributo. Probabilmente non è quello che vuoi.
Al contrario, se specifichi "nodeset" come Type
per quell'espressione XPath, Apigee
eseguirà la corrispondenza di pattern in base a ciascun valore degli attributi su ciascun 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: | String |
Valori validi: |
Una di queste parole chiave: |
Elemento <XMLPayload>/<XPath>/<Pattern>
Definisce il pattern dell'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: | String |
Elemento <JSONPayload>
Specifica che le informazioni devono essere estratte da un payload JSON ed essere 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 | Predefinita | Presenza |
---|---|---|---|
escapeSlashCharacter |
Imposta il valore |
true | Facoltativo |
Elemento <JSONPayload>/<JSONPath>/<Espressione>
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: | String |
Elemento <JSONPayload>/<JSONPath>/<Pattern>
Definisce il pattern dell'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: | String |
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} |
build |
DuplicatePrefix |
RegularExpressionProtection {0}: Duplicate prefix {1} |
build |
EmptyJSONPathExpression |
RegularExpressionProtection {0}: Empty JSONPath expression |
build |
EmptyXPathExpression |
RegularExpressionProtection {0}: Empty XPath expression |
build |
InvalidRegularExpression |
RegularExpressionProtection {0}: Invalid Regular Expression {1}, Context {2} |
build |
JSONPathCompilationFailed |
RegularExpressionProtection {0}: Failed to compile jsonpath {1}. Context {2} |
build |
NONEmptyPrefixMappedToEmptyURI |
RegularExpressionProtection {0}: Non-empty prefix {1} cannot be mapped to empty
uri |
build |
NoPatternsToEnforce |
RegularExpressionProtection {0}: No patterns to enforce in {1} |
build |
NothingToEnforce |
RegularExpressionProtection {0}: at least one of URIPath, QueryParam, Header,
FormParam, XMLPayload, JSONPayload is mandatory |
build |
XPathCompilationFailed |
RegularExpressionProtection {0}: Failed to compile xpath {1}. Context {2} |
build |
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 protezione dalle minacce per JSON
Criteri di XML Threat Protection