Riferimento per il linguaggio delle regole personalizzate di Google Cloud Armor

Google Cloud Armor consente di definire regole prioritarie con condizioni di corrispondenza e azioni configurabili in un criterio di sicurezza. Viene applicata una regola, ovvero l'applicazione dell'azione configurata se è quella con la priorità più elevata le cui condizioni corrispondono agli attributi della richiesta in entrata.

Esistono due tipi di condizioni di corrispondenza:

Una condizione di corrispondenza di base contiene elenchi di indirizzi IP o intervalli di indirizzi IP.
Una condizione di corrispondenza avanzata contiene un'espressione con più sottoespressioni per trovare corrispondenze con una serie di attributi di una richiesta in arrivo.

Il linguaggio delle regole personalizzate viene utilizzato per scrivere le espressioni nelle condizioni di corrispondenza avanzate per le regole dei criteri di sicurezza. Il linguaggio delle regole personalizzate di Google Cloud Armor è un'estensione del CEL (Common Expression Language).

Un'espressione richiede due componenti:

Attributi che possono essere ispezionati nelle espressioni regola.
Operazioni che possono essere eseguite sugli attributi come parte di un'espressione.

Ad esempio, la seguente espressione utilizza gli attributi origin.ip e 9.9.9.0/24 nell'operazione inIpRange(). In questo caso, l'espressione restituisce true se origin.ip rientra nell'intervallo di indirizzi IP di 9.9.9.0/24.

inIpRange(origin.ip, '9.9.9.0/24')

Attributi

Gli attributi rappresentano le informazioni di una richiesta in entrata, come l'indirizzo IP di origine o il percorso dell'URL richiesto.

Campo	Tipo	Descrizione del campo
`origin.ip`	string	L'indirizzo IP di origine della richiesta.
`request.headers`	mappa	Mappa stringa-stringa delle intestazioni della richiesta HTTP. Se un'intestazione contiene più valori, il valore in questa mappa sarà una stringa separata da virgole di tutti i valori dell'intestazione. Le chiavi in questa mappa sono tutte in minuscolo. Per i controlli sono disponibili solo i primi 16 kB di ogni valore di intestazione. Qualsiasi valore di intestazione superiore a 16 kB viene troncato in base alle specifiche del bilanciatore del carico Google Cloud.
`request.method`	string	Il metodo di richiesta HTTP, ad esempio `GET` o `POST`.
`request.path`	string	Il percorso URL HTTP richiesto.
`request.scheme`	string	Lo schema URL HTTP, ad esempio `http` o `https`. I valori per questo attributo sono tutti minuscoli.
`request.query`	string	La query URL HTTP nel formato `name1=value&name2=value2`, come appare nella prima riga della richiesta HTTP. Non viene eseguita alcuna decodifica.
`origin.region_code`	string	Il codice paese Unicode associato all'IP di origine, ad esempio `US`. Se stai creando una regola o un'espressione che utilizza i codici paese o area geografica ISO 3166-1 alpha 2, Google Cloud Armor tratta ogni codice in modo indipendente. Le regole e le espressioni di Google Cloud Armor utilizzano esplicitamente tali codici per consentire o negare le richieste. Per ulteriori informazioni, consulta la sezione unicode_region_subtag nello standard tecnico Unicode.
`origin.asn`	integer	Il numero di sistema autonomo (ASN) associato all'indirizzo IP di origine. L'ASN univoco a livello globale è determinato in base all'operatore di rete che supporta i prefissi degli indirizzi IP che contengono l'indirizzo IP di origine.

Attributi reCAPTCHA Enterprise

Questa sezione elenca gli attributi applicabili solo ai token reCAPTCHA o ai cookie di esenzione reCAPTCHA. Una sottoespressione basata su questi attributi restituisce false se il token reCAPTCHA o il cookie di esenzione da valutare non è disponibile o non è valido (formato errato, non corrispondente o scaduto).

Attributi dei cookie di esenzione

Campo	Tipo	Descrizione del campo
`token.recaptcha_exemption.valid`	`bool`	La presenza di un cookie di esenzione reCAPTCHA valido.

Attributi action-token

Campo	Tipo	Descrizione del campo
`token.recaptcha_action.score`	`float`	Il punteggio di un token di azione reCAPTCHA. Un punteggio valido va da `0.0` a `1.0`, dove `0.0` è molto probabile che sia un utente illegittimo e `1.0` sia un utente legittimo.
`token.recaptcha_action.captcha_status`	`string`	Lo stato del captcha da un token di azione reCAPTCHA. Uno stato valido è `NONE`, `PASS` o `FAIL`, dove `NONE` si riferisce quando non ci sono verifiche durante la valutazione reCAPTCHA, in modo che il campo captcha non sia presente nel token action.
`token.recaptcha_action.action`	`string`	Il nome dell'azione (fino a 100 caratteri) da un token di azione reCAPTCHA. Vedi Nomi delle azioni.
`token.recaptcha_action.valid`	`bool`	La presenza di un token di azione reCAPTCHA valido.

Attributi token sessione

Campo	Tipo	Descrizione del campo
`token.recaptcha_session.score`	`float`	Il punteggio di un token di sessione reCAPTCHA. Un punteggio valido va da `0.0` a `1.0`, dove `0.0` è molto probabile che sia un utente illegittimo e `1.0` sia un utente legittimo.
`token.recaptcha_session.valid`	`bool`	La presenza di un token di sessione reCAPTCHA valido.

Suite operativa

Il seguente riferimento descrive gli operatori che puoi utilizzare con gli attributi (rappresentati da x, y e k) per definire le espressioni delle regole.

Espressioni	Descrizione
`x == "foo"`	Restituisce true se x è uguale al valore letterale di stringa costante specificato.
`x == R"fo'o"`	Restituisce true se x è uguale al valore letterale di stringa non elaborata fornita che non interpreta le sequenze di escape. I valori letterali di stringa non elaborata sono utili per esprimere stringhe che devono a loro volta utilizzare caratteri della sequenza di escape.
`x == y`	Restituisce true se x è uguale a y.
`x != y`	Restituisce true se x non è uguale a y.
`x + y`	Restituisce la stringa concatenata xy.
`x && y`	Restituisce true se x e y sono true.
`x \|\| y`	Restituisce true se x, y o entrambi sono true.
`!x`	Restituisce true se il valore booleano x è false o false se il valore booleano x è true.
`x.contains(y)`	Restituisce true se la stringa x contiene la sottostringa y.
`x.startsWith(y)`	Restituisce true se la stringa x inizia con la sottostringa y.
`x.endsWith(y)`	Restituisce true se la stringa x termina con la sottostringa y.
`x.matches(y)`	Restituisce true se la stringa x corrisponde al pattern RE2 specificato y. Il pattern RE2 viene compilato utilizzando l'opzione RE2::Latin1 che disabilita le funzionalità Unicode.
`inIpRange(x, y)`	Restituisce true se l'indirizzo IP x è contenuto nell'intervallo IP y. Le maschere della subnet per gli indirizzi IPv6 non possono essere maggiori di /64.
`x.lower()`	Restituisce il valore minuscolo della stringa x.
`x.upper()`	Restituisce il valore maiuscolo della stringa x.
`x.base64Decode()`	Restituisce il valore decodificato base64 di x; i caratteri `_ -` vengono prima sostituiti rispettivamente con `/ +`. Restituisce `""` (stringa vuota) se x non è un valore base64 valido.
`has(m['k'])`	Restituisce true se la chiave k è disponibile nella mappa m.
`m['k']`	Restituisce il valore nella chiave k nella mappa da stringa a stringa m se è disponibile k; in caso contrario, restituisce un errore. Si consiglia di verificare prima la disponibilità utilizzando `"has(m['k'])==true"`.
`int(x)`	Converte il risultato stringa di x in un tipo `int`. Può quindi essere utilizzato per effettuare un confronto con il numero intero utilizzando operatori aritmetici standard come > e <=. Funziona solo per i valori che si prevede siano interi.

Espressioni di esempio

Per ciascuna di queste espressioni, l'azione eseguita dipende dal fatto che l'espressione sia inclusa in una regola di negazione o in una regola di autorizzazione.

Consentire o negare l'accesso in base a un intervallo di indirizzi IP in IPv4 o IPv6

La seguente espressione corrisponde a richieste dall'intervallo di indirizzi IP di 9.9.9.0/24:
```
inIpRange(origin.ip, '9.9.9.0/24')
```
La seguente espressione corrisponde a richieste dall'intervallo di indirizzi IP di 2001:db8::/32:
```
inIpRange(origin.ip, '2001:db8::/32')
```

Consentire o negare il traffico con un cookie specifico

La seguente espressione corrisponde a richieste che hanno un cookie contenente 80=BLAH:
```
has(request.headers['cookie']) && request.headers['cookie'].contains('80=BLAH')
```

Consentire o negare il traffico con un'intestazione `referer` non vuota

La seguente espressione corrisponde a richieste con un'intestazione referer non vuota:
```
has(request.headers['referer']) && request.headers['referer'] != ""
```

Consentire o negare il traffico in base all'URL dell'host nell'intestazione

La seguente espressione corrisponde a richieste per un URL specifico:
```
request.headers['host'].lower().contains('test.example.com')
```

Consentire o negare il traffico da un'area geografica specifica

Se la tua applicazione web non è disponibile nell'area geografica AU, tutte le richieste da tale area geografica devono essere bloccate.

In una regola di negazione, utilizza la seguente espressione, che corrisponde alle richieste dall'area geografica AU:
```
origin.region_code == 'AU'
```

In alternativa, se l'applicazione web è disponibile solo nell'area geografica AU, le richieste da tutte le altre aree geografiche devono essere bloccate.

In una regola di negazione, utilizza la seguente espressione, che corrisponde alle richieste di tutte le aree geografiche diverse da AU:
```
origin.region_code != 'AU'
```

I codici dell'area geografica sono basati sui codici ISO 3166-1 alpha 2. In alcuni casi, una regione corrisponde a un paese, ma non è sempre così. Ad esempio, il codice US include tutti gli stati degli Stati Uniti, un distretto e sei aree periferiche.

Consentire o negare il traffico da un'ASN specifico

Se la tua applicazione web deve essere bloccata per i clienti serviti da un operatore di rete specifico, puoi utilizzare il numero ASN dell'operatore di rete da bloccare.

In una regola di negazione, utilizza la seguente espressione, che corrisponde alle richieste di un ASN specifico:
```
origin.asn == 123
```

In alternativa, se la tua applicazione web deve essere disponibile solo per i clienti dietro un operatore di rete specifico, le richieste di tutti gli altri operatori di rete devono essere bloccate.

In una regola di negazione, utilizza la seguente espressione, che corrisponde a tutti gli altri operatori di rete diversi da quello che vuoi autorizzare.
```
origin.asn != 123
```

Più espressioni

Per includere più condizioni in una singola regola, combina più sottoespressioni.

Nell'esempio seguente, le richieste provenienti da 1.2.3.0/24 (come i tuoi alpha tester) nell'area geografica AU corrispondono alla seguente espressione:
```
origin.region_code == "AU" && inIpRange(origin.ip, '1.2.3.0/24')
```

La seguente espressione corrisponde a richieste da 1.2.3.4 in cui uno user agent contiene la stringa WordPress:

inIpRange(origin.ip, '1.2.3.4/32') &&
has(request.headers['user-agent']) && request.headers['user-agent'].contains('WordPress')

Consenti o nega il traffico per un URI della richiesta che corrisponde a un'espressione regolare

La seguente espressione corrisponde a richieste che contengono la stringa bad_path nell'URI:
```
request.path.matches('/bad_path/')
```
La seguente espressione corrisponde a richieste con Chrome nel campo intestazione User-Agent:
```
request.headers['user-agent'].matches('Chrome')
```
L'espressione seguente mostra una corrispondenza senza distinzione tra maiuscole e minuscole per l'intestazione User-Agent contenente wordpress; corrisponde a User-Agent:WordPress/605.1.15, User-Agent:wordPress e altre varianti di wordpress:
```
request.headers['user-agent'].matches('(?i:wordpress)')
```

Consenti o nega il traffico contenente uno specifico valore decodificato Base64

La seguente espressione corrisponde a richieste con valore Decodificato Base64 myValue per l'intestazione user-id:
```
has(request.headers['user-id']) && request.headers['user-id'].base64Decode().contains('myValue')
```

Consenti o nega il traffico senza `content-length` nel corpo HTTP

La seguente espressione corrisponde a richieste con content-length zero nel corpo HTTP:
```
int(request.headers["content-length"]) == 0
```

Regole preconfigurate

Le regole preconfigurate utilizzano firme statiche preconfigurate, espressioni regolari o entrambe in modo che corrispondano a intestazioni di richieste HTTP e parametri di query. Le regole preconfigurate disponibili si basano sulla OWASP Modsecurity core set set 3.0.2. Google Cloud Armor offre i seguenti set di espressioni predefinite:

xss-<version>: difesa dagli attacchi cross-site scripting (XSS)
sqli-<version>: difesa dagli attacchi di SQL injection
lfi-<version>: difesa dagli attacchi di inclusione di file locali
rfi-<version>: difende dagli attacchi di inclusione di file remoti
rce-<version>: difende dagli attacchi di esecuzione del codice da remoto

Per elencare tutte le regole preconfigurate disponibili, consulta Elencare le regole preconfigurate disponibili.

Per ulteriori informazioni sulle regole preconfigurate, consulta l'articolo sul caso d'uso Ridurre gli attacchi ai livelli delle applicazioni utilizzando regole preconfigurate.

Nomi dei set di espressioni

Il formato dei nomi dei set di espressioni è <attack category>-<version field>. La categoria di attacco specifica il tipo di attacchi da cui eseguire la protezione, ad esempio xss (cross-site scripting) o sqli (SQL injection).

I campi delle versioni supportati sono stable e canary. Le aggiunte e le modifiche alle regole vengono prima rilasciate nella versione canary. Quando aggiunte e modifiche sono considerate sicure e stabili, vengono promosse alla versione stable.

ID membri del set di espressioni

Un set di espressioni contiene più espressioni, ciascuna con il proprio ID set di regole principali (CRS). Ad esempio, il set di espressioni xss-stable include un'espressione chiamata owasp-crs-v020901-id981136-xss, che corrisponde all'ID regola 981136 per version 2.9.1. Puoi utilizzare gli ID CRS per escludere espressioni specifiche dall'utilizzo, utile se una particolare espressione attiva costantemente un falso positivo. Per ulteriori informazioni, consulta le informazioni sulla risoluzione dei falsi positivi.

Per informazioni sul set di regole di base e sull'ottimizzazione a livelli di sensibilità diversi, consulta Ottimizzazione delle regole WAF di Google Cloud Armor.

Operatore per regole preconfigurate

Espressioni Descrizione

Espressioni	Descrizione
`evaluatePreconfiguredExpr(string, LIST)`	Restituisce true se una qualsiasi delle espressioni all'interno del set di espressioni specificato restituisce true. Il primo argomento è il nome dell'insieme di espressioni, ad esempio `xss-stable`. Il secondo argomento (facoltativo) è un elenco di ID separati da virgole che devono essere esclusi dalla valutazione. L'elenco di esclusione è utile quando un dato membro dell'insieme di espressioni attiva un falso positivo.

evaluatePreconfiguredExpr(string, LIST)

Restituisce true se una qualsiasi delle espressioni all'interno del set di espressioni specificato restituisce true.

Il primo argomento è il nome dell'insieme di espressioni, ad esempio xss-stable. Il secondo argomento (facoltativo) è un elenco di ID separati da virgole che devono essere esclusi dalla valutazione. L'elenco di esclusione è utile quando un dato membro dell'insieme di espressioni attiva un falso positivo.

Esempi di regole preconfigurate

L'espressione seguente utilizza la regola preconfigurata xss-stable per attenuare gli attacchi XSS:
```
evaluatePreconfiguredExpr('xss-stable')
```
La seguente espressione utilizza tutte le espressioni della regola preconfigurata xss-stable, ad eccezione degli ID membro 981136 e 981138:
```
evaluatePreconfiguredExpr('xss-stable', ['owasp-crs-v020901-id981136-xss',
'owasp-crs-v020901-id981138-xss'])
```
L'espressione seguente utilizza una regola preconfigurata per ridurre gli attacchi SQLi dall'intervallo di indirizzi IP di 198.51.100.0/24:
```
inIpRange(origin.ip, '198.51.100.0/24') && evaluatePreconfiguredExpr('sqli-stable')
```