Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di
Apigee Edge.
Cosa
Estrae informazioni da un messaggio (ad esempio, percorso URI, parametro di query, intestazione, parametro del modulo, variabile, payload XML o payload JSON) e valuta i contenuti in base a espressioni regolari predefinite. Se una delle espressioni regolari specificate restituisce true, il messaggio viene considerato una minaccia e il criterio genera un errore.
Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di 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 saperne di più sulle norme relative alla protezione delle espressioni regolari.
Video | Descrizione |
---|---|
Protezione dagli attacchi di SQL injection | Proteggiti dagli attacchi SQL injection utilizzando il criterio di protezione delle espressioni regolari nell'interfaccia utente di Apigee. |
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 generico 400
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 mostra 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 carattere), come mostrato
nell'esempio precedente, o codificare in XML i caratteri riservati: ad esempio, sostituendo
<
con <
e >
con >
.
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 trovare corrispondenze senza fare distinzione tra maiuscole e minuscole. Ecco un esempio di come puoi
ottenere questo risultato in un'espressione regolare utilizzando la struttura (?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 avrà 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 escludere i 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: <!--#(include|exec|echo|config|printenv)\s+.* |
Iniezione di sintassi abbreviata XPath |
(/(@?[\w_?\w:\*]+(\[[^]]+\])*)?)+ |
Iniezione di sintassi estesa XPath |
/?(ancestor(-or-self)?|descendant(-or-self)?|following(-sibling)) |
JavaScript Injection |
<\s*script\b[^>]*>[^<]+<\s*/\s*script\s*> Codificato in XML: <\s*script\b[^>]*>[^<]+<\s*/\s*script\s*> |
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>
nelle norme, l'intestazioneContent-Type
della richiesta deve essere un tipo di contenuto XML, ad esempioapplication/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>
nella policy, l'intestazioneContent-Type
della richiesta deve essere un tipo di contenuti JSON comeapplication/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 un criterio 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">
La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:
Attributo | Descrizione | Predefinito | Presence |
---|---|---|---|
name |
Il nome interno del criterio. Il valore dell'attributo Se vuoi, utilizza l'elemento |
N/D | Obbligatorio |
continueOnError |
Imposta su Imposta su |
falso | Facoltativo |
enabled |
Imposta su Imposta su |
true | Facoltativo |
async |
Questo attributo è stato ritirato. |
falso | Deprecato |
Elemento <DisplayName>
Da utilizzare insieme 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/D Se ometti questo elemento, viene utilizzato il valore dell'attributo |
---|---|
Presence | Facoltativo |
Tipo | Stringa |
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 richiesta. Allo stesso modo, la norma 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>
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>
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>
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>
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>
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>
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 rispetto 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>
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>
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>
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>
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>
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>
Predefinito: | N/D |
Presenza: | Facoltativo |
Tipo: | Stringa |
<XMLPayload>/<XPath>/<Type> element
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 è definito quale attributo e quale elemento. Apigee eseguirà quindi la corrispondenza del pattern rispetto al 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>
Predefinito: | string |
Presenza: | Facoltativo |
Tipo: | Stringa |
Valori validi: |
Una di queste parole chiave: |
<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>
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>
Predefinito: | N/D |
Presenza: | Facoltativo |
Tipo: | N/D |
Attributi
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
escapeSlashCharacter |
Imposta su |
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>
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>
Predefinito: | N/D |
Presenza: | Obbligatorio |
Tipo: | Stringa |
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Se vuoi acquisire un errore e generare un errore personalizzato, imposta l'attributo continueOnError="true"
nell'elemento principale del criterio.
Per scoprire di più, consulta
Che cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi durante l'esecuzione del criterio.
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 ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella sopra. | 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 |
Schemi
Argomenti correlati
Policy di protezione dalle minacce JSON
Criterio di protezione dalle minacce XML